feat(cli): build command (#34)

Author: LemonNekoGH

AGENTS.md

@@ -17,8 +17,9 @@ Do not introduce extra packages, adapters, or broad CLI workflows unless they
 are required to make the current IPC milestone work. The existing
 `@gd-kirie/ipc` package is a thin browser-side transport wrapper; do not expand
 it into an application event or invocation layer unless the user explicitly asks
-for that higher-level work. The planned Kirie CLI v1 exception is limited to
-`kirie dev` for desktop development through Vite and Godot.
+for that higher-level work. The planned Kirie CLI exception is limited to the
+core app workflow described below: development, local build inputs,
+initialization, and diagnostics.
 
 The mobile IPC v1 experiment keeps Kirie core byte-oriented and CBOR-based with
 text, binary, and data lanes. JSON belongs to callers or adapters, not to Kirie
@@ -142,22 +143,47 @@ The planned Kirie app layout is:
 - `addons/kirie/`
 - optional `addons/godot_cef/`
 
-Kirie CLI v1 should only implement `kirie dev` for desktop Godot development.
-It should be installed through npm, call Vite's JavaScript API directly, let
-Vite resolve port conflicts, launch Godot as a child process, and inject
-`KIRIE_DEV=1` and `KIRIE_WEB_URL=<resolved Vite URL>`.
-
-Keep `kirie create`, `kirie export`, addon installation, Godot CEF installation,
-export preset management, and mobile dev targets outside the CLI v1 scope.
-These may be implemented later when explicitly planned. Future mobile dev
-targets should use a unified platform and device selector such as
+Kirie CLI should be installed through npm and expose these planned commands:
+
+- `kirie dev`: start the Vite development server, launch Godot as a child
+  process, and inject `KIRIE_DEV=1` and
+  `KIRIE_WEB_URL=<resolved Vite URL>`.
+- `kirie build`: build every configured local input needed by a runnable or
+  exportable Godot project, without exporting platform packages.
+- `kirie build web`: build only the Vite web output for Godot resource loading.
+- `kirie build dotnet`: build only the Godot C#/.NET project when one is
+  configured or discovered.
+- `kirie init`: explicitly initialize a Kirie project and write required
+  project configuration.
+- `kirie doctor`: diagnose project configuration without writing files.
+- `kirie doctor --fix`: explicitly repair supported configuration problems.
+
+Keep `kirie create`, `kirie export`, and mobile dev targets outside the current
+CLI scope. These may be implemented later when explicitly planned. Future
+mobile dev targets should use a unified platform and device selector such as
 `kirie dev ios --device <selector>` or
 `kirie dev android --device <selector>`; do not expose simulator and real device
 as separate user-facing target names.
 
 Kirie enforces Vite for user web source. Advanced Vite options belong in
 `kirie.config.ts` under `web.vite`, but Kirie owns `root`, `base`,
-`server.host`, `server.port`, `server.open`, and `build.outDir`.
+`server.host`, `server.port`, `server.open`, and `build.outDir`. Explicit CLI
+flags may override runtime server values for a single command invocation.
+Planned `kirie dev` flags include `--config <path>` for the Kirie config,
+`--project <dir>` for the Godot project, `--godot <path>` for a Godot executable
+override, and Vite-shaped flags such as `--host <host>`, `--port <number>`,
+`--strict-port`, `--mode <mode>`, `--force`, `--log-level <level>`,
+`--clear-screen`, and `--no-clear-screen`. Kirie must either parse and map
+Vite-shaped flags explicitly to Vite's public JavaScript API or proxy them to
+the real Vite CLI; unknown flags must not be silently ignored. Arguments after
+`--` on `kirie dev` belong to Godot.
+
+Only explicit setup and repair commands may write Godot configuration.
+`kirie init` and `kirie doctor --fix` may modify `project.godot` or
+`export_presets.cfg`, but those writes must go through Godot itself, for
+example a headless Godot helper using `ProjectSettings` or `ConfigFile`. Runtime
+commands such as `kirie dev`, `kirie build`, and future `kirie export` should
+fail on wrong configuration and point users to `kirie doctor`.
 
 Kirie user projects should not contain Capacitor-style `ios/` or `android/`
 native project directories. Native features belong in Godot plugins.
@@ -191,6 +217,10 @@ For the current milestone, iOS should be owned by the standard addon tree:
 
 - Keep changes aligned with the current milestone.
 - When a same-session temporary decision is replaced, converge on the latest decision directly; do not add compatibility unless explicitly requested.
+- Do not add regression tests solely to prevent an implementation pattern that
+  is already known to be invalid or contrary to the chosen API. Remove or
+  correct the invalid usage instead; keep tests focused on supported behavior
+  and realistic regressions.
 - Use English only for agent-facing communication, project-maintenance notes,
   AGENTS updates, and project documentation unless the user explicitly requests
   a non-English artifact.

docs/architecture.md

@@ -147,21 +147,28 @@ Directory responsibilities are:
 - `src-web`: Vite web UI source and production build output.
 - `addons`: Godot plugins. Kirie remains installed as `addons/kirie`, and Godot
   CEF remains installed as `addons/godot_cef`.
-- `kirie.config.ts`: Kirie CLI development-time configuration.
+- `kirie.config.ts`: Kirie CLI configuration for coordinating Godot, Vite, and
+  local build inputs.
 
 Kirie does not own native platform project directories. Do not introduce
 Capacitor-style `ios/` or `android/` project trees into Kirie user projects.
 Native capabilities should be provided by Godot plugins.
 
-Kirie CLI v1 is scoped to one command:
+The planned Kirie CLI surface is intentionally small but covers the full local
+app workflow:
 
 ```sh
 kirie dev
+kirie build
+kirie build web
+kirie build dotnet
+kirie init
+kirie doctor
+kirie doctor --fix
 ```
 
-`kirie dev` targets desktop Godot only in v1. It starts a Vite development
-server through Vite's JavaScript API, reads the actual resolved URL after Vite
-listens, launches Godot as a child process, and injects:
+`kirie dev` starts a Vite development server, reads the actual resolved URL
+after Vite listens, launches Godot as a child process, and injects:
 
 ```text
 KIRIE_DEV=1
@@ -182,15 +189,27 @@ named-class references.
 The CLI does not support Finder, Dock, or other non-CLI launched macOS app
 processes. It only supports development sessions that the CLI starts and owns.
 
-Kirie CLI v1 does not implement:
-
-- `kirie create`
-- `kirie build`
-- `kirie export`
-- addon installation
-- Godot CEF installation
-- export preset management
-- BrowserWindow APIs
+`kirie build` builds local intermediate artifacts needed by a runnable or
+exportable Godot project, but it does not produce platform application packages.
+It should build every configured or clearly discovered input. `kirie build web`
+builds only the Vite web output, and `kirie build dotnet` builds only the
+Godot C#/.NET project when one is configured or discovered. If no C# project is
+configured or discovered, the aggregate `kirie build` command may skip the
+`.NET` step; if a C# project is present, C# build failure must fail the command.
+
+`kirie export` remains future work. When it exists, it should mean a complete
+platform export workflow: build local inputs first, then call Godot's export
+flow for the selected platform or preset. It should not silently create or
+repair project configuration as part of export.
+
+`kirie init` and `kirie doctor --fix` are the explicit commands allowed to
+write configuration. `kirie init` initializes Kirie-owned files and may register
+required Godot project settings. `kirie doctor` is read-only diagnostics.
+`kirie doctor --fix` may apply supported repairs. Any writes to Godot-owned
+configuration files, including `project.godot` and `export_presets.cfg`, must
+go through Godot itself, for example a headless helper script using
+`ProjectSettings` or `ConfigFile`. JavaScript code must not patch
+Godot configuration text directly.
 
 Kirie enforces Vite as the web toolchain. Users should not hand-write a fixed
 development URL. The CLI should let Vite handle port conflicts, then pass the
@@ -211,17 +230,54 @@ User-supplied `web.vite` may extend Vite for plugins, aliases, defines, CSS,
 JSON, extra assets, proxying, headers, HMR details, Rollup options, and
 dependency optimization. It must not override Kirie-owned invariants such as
 `root`, `base`, `server.host`, `server.port`, `server.open`, or
-`build.outDir`.
+`build.outDir`. Explicit command-line flags may override runtime server values
+for a single invocation.
+
+Kirie command-line flags are Kirie API, not an implicit promise to support the
+entire Vite CLI surface. The planned `kirie dev` flags are:
+
+```text
+--config <path>       Kirie config file path, not a Vite config path.
+--project <dir>       Godot project directory, defaulting to the current project.
+--godot <path>        Godot executable override.
+--host <host>         Vite dev server host override.
+--port <number>       Vite dev server port override.
+--strict-port         Fail if the requested Vite port is unavailable.
+--mode <mode>         Vite mode.
+--force               Force Vite dependency pre-bundling.
+--log-level <level>   Vite log level: info, warn, error, or silent.
+--clear-screen        Allow Vite to clear the terminal.
+--no-clear-screen     Prevent Vite from clearing the terminal.
+```
+
+Kirie must either parse and map Vite-shaped flags explicitly to Vite's public
+JavaScript API or proxy them to the real Vite CLI. Unknown flags must fail
+instead of being silently ignored. Arguments after `--` on `kirie dev` are
+reserved for Godot:
+
+```sh
+kirie dev --host 0.0.0.0 --port 5173 --mode staging -- --verbose
+```
+
+`--open` is intentionally not part of `kirie dev` because Kirie launches Godot
+instead of opening a browser. `--base`, `--outDir`, and Vite's own `--config`
+are also not part of the `kirie dev` surface because Kirie owns those values
+through `kirie.config.ts` and the app layout.
+
+The current CLI plan does not implement:
+
+- `kirie create`
+- `kirie export`
+- mobile dev targets
+- BrowserWindow APIs
 
 Future mobile development targets should use one platform command with unified
 device selection, for example `kirie dev ios --device <selector>` and
 `kirie dev android --device <selector>`. The user-facing API should not split
 iOS simulator and iOS device into separate target names. Kirie may still use
 different launch backends internally for simulators, real devices, Android
 emulators, and Android devices. Mobile development targets are explicitly out
-of scope for CLI v1. Future export support should own the production web build
-and Godot export as one workflow, instead of exposing a separate `kirie build`
-command that only wraps Vite.
+of scope for the current CLI plan.
 
 ## Packaged web resource loading
 
@@ -242,8 +298,10 @@ default production entry. When that migration is implemented, the addon export
 plugin should package `res://src-web/dist` for Android and iOS exports, fail
 export when `res://src-web/dist/index.html` is missing, and drop the previous
 `res://web` behavior instead of preserving a compatibility layer. Users should
-continue to use Godot's official export preset flow; Kirie should not create or
-manage export presets.
+continue to use Godot's official export preset flow by default. Kirie may
+diagnose export preset issues, and explicit setup or repair commands may write
+supported preset changes through Godot, but normal run, build, and export
+commands must not silently mutate export presets.
 
 ## Desktop Godot CEF direction
 

docs/dreams/browser-window.md

@@ -48,7 +48,7 @@ Until that resolver exists, users can manually compose Godot `Window` nodes and
 
 ## Out of scope
 
-Keep BrowserWindow separate from the current CLI v1 work. Do not combine it
+Keep BrowserWindow separate from the current CLI work. Do not combine it
 with:
 
 - `kirie dev`

docs/references.md

@@ -16,8 +16,14 @@ packaging, or platform WebView bridge details.
 - [Godot Android plugins (stable)](https://docs.godotengine.org/en/stable/tutorials/platform/android/android_plugin.html)
   Main reference for Godot Android plugin v2 packaging and export flow.
 - [Command line tutorial (stable)](https://docs.godotengine.org/en/stable/tutorials/editor/command_line_tutorial.html)
-  Reference for `--import`, `--path`, `--remote-debug`, command-line running,
-  and export behavior.
+  Reference for `--import`, `--path`, `--remote-debug`, `--script`,
+  `--build-solutions`, command-line running, and export behavior.
+- [ProjectSettings (stable)](https://docs.godotengine.org/en/stable/classes/class_projectsettings.html)
+  Reference for reading and saving `project.godot` through Godot instead of
+  hand-editing the file from JavaScript.
+- [ConfigFile (stable)](https://docs.godotengine.org/en/stable/classes/class_configfile.html)
+  Reference for Godot's INI-like configuration file API and Variant-aware
+  reading and writing.
 - [GDScript reference: registering named classes](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript_basics.html#registering-named-classes)
   Reference for `class_name` scripts such as `GdKirie` and `KirieNode`, which
   Godot exposes as named/global script classes after project scanning.
@@ -146,6 +152,8 @@ packaging, or platform WebView bridge details.
   Reference for source files included in PackageReference-based NuGet packages.
 - [dotnet pack](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-pack)
   Reference for creating NuGet packages from .NET projects.
+- [dotnet build](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-build)
+  Reference for compiling .NET projects without publishing or packaging them.
 - [dotnet nuget push](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-push)
   Reference for publishing NuGet packages.
 
@@ -164,6 +172,9 @@ packaging, or platform WebView bridge details.
 - [Vite JavaScript API](https://vite.dev/guide/api-javascript.html)
   Reference for `createServer()`, `build()`, `mergeConfig()`, and dev server
   `resolvedUrls`, which underpin the planned `kirie dev` implementation.
+- [Vite CLI](https://vite.dev/guide/cli)
+  Reference for Vite command-line flags when Kirie chooses to expose or proxy
+  Vite-shaped arguments.
 - [Vite server options](https://vite.dev/config/server-options.html)
   Reference for development server host, port, strict port behavior, and related
   options owned by Kirie CLI defaults.

packages/cli/src/build.test.ts

@@ -0,0 +1,84 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { runBuild, runBuildDotnet, runBuildWeb } from "./build.ts";
+import { createBasicKirieCliProjectTracker, installKirieConfigFixture } from "./test-project.ts";
+
+const projects = createBasicKirieCliProjectTracker("kirie-cli-build-");
+
+afterEach(async () => {
+  await projects.cleanup();
+});
+
+describe("runBuildWeb", () => {
+  it("builds the Vite web output into src-web/dist", async () => {
+    const project = await projects.copy();
+
+    await runBuildWeb({ cwd: project });
+
+    await expect(fs.access(path.join(project, "src-web", "dist", "index.html"))).resolves.toBe(
+      undefined,
+    );
+  });
+
+  it("rejects Kirie-owned Vite build options", async () => {
+    const project = await projects.copy();
+    await installKirieConfigFixture(project, "build-owned-out-dir.kirie.config.ts");
+
+    // TODO: Revisit whether `build.outDir` should be configurable once the
+    // packaged resource layout is settled.
+    await expect(runBuildWeb({ cwd: project })).rejects.toThrow(
+      "web.vite.build.outDir is owned by Kirie",
+    );
+  });
+
+  it("loads kirie.config.ts with Vite build command context", async () => {
+    const project = await projects.copy();
+    await installKirieConfigFixture(project, "build-context.kirie.config.ts");
+
+    await runBuildWeb({ cwd: project });
+
+    const assets = await fs.readdir(path.join(project, "src-web", "dist", "assets"));
+
+    expect(assets.some((asset) => asset.endsWith(".js.map"))).toBe(true);
+  });
+});
+
+describe("runBuild", () => {
+  it("skips dotnet when dotnet reports no project or solution", async () => {
+    const project = await projects.copy();
+
+    await runBuild({ cwd: project });
+
+    await expect(fs.access(path.join(project, "src-web", "dist", "index.html"))).resolves.toBe(
+      undefined,
+    );
+  });
+});
+
+describe("runBuildDotnet", () => {
+  it("builds a discovered .NET project", async () => {
+    const project = await projects.copy();
+    await fs.writeFile(
+      path.join(project, "Example.csproj"),
+      `<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
+    <TargetFramework>net10.0</TargetFramework>
+  </PropertyGroup>
+</Project>
+`,
+    );
+
+    await runBuildDotnet({ cwd: project });
+
+    await expect(fs.access(path.join(project, "bin", "Debug", "net10.0"))).resolves.toBe(undefined);
+  });
+
+  it("fails when dotnet reports no project or solution", async () => {
+    const project = await projects.copy();
+
+    await expect(runBuildDotnet({ cwd: project })).rejects.toThrow("dotnet build failed");
+  });
+});