@dormer/cli 0.0.0-stage → 0.1.3

package/src/commands/dev.ts

@@ -0,0 +1,128 @@
+// dormer dev: Vite dev server + esbuild watch of the backend + the native host.
+//
+// Restart model: when the backend bundle changes the whole host process is restarted (windows are
+// recreated, renderer state is lost; the Vite page itself keeps HMR). Restarting only the Node
+// sidecar while keeping windows open needs host support (see README "Limitations").
+import net from "node:net";
+import { once } from "node:events";
+import type { ChildProcess } from "node:child_process";
+import { type CommandSpec, type ParsedArgs, flagList, flagNumber, flagString } from "../args.ts";
+import { loadApp } from "../config.ts";
+import { formatMessages, summarizeExternals, watchBackend, type WatchHandle } from "../backend.ts";
+import { resolveHostBinary, spawnHost } from "../host.ts";
+import { findViteConfig, loadVite } from "../resolve.ts";
+import { EXIT, c, log } from "../ui.ts";
+
+export const spec: CommandSpec = {
+  name: "dev",
+  summary: "Run the app with the Vite dev server, backend rebuilds and the native host",
+  usage: "dev [--port <n>] [--host <name>] [--pass-env <VAR>]...",
+  description: `Starts Vite for renderer/ (HMR), bundles the backend with esbuild in watch mode to
+.dormer/dev/main.js and launches dormer-host with --dev --dev-url <vite url>. The backend sees
+DORMER_DEV_URL and should call win.loadURL(process.env.DORMER_DEV_URL) (templates do). When the
+backend bundle changes the host is restarted. Ctrl-C or closing the last window stops everything.`,
+  options: {
+    port: { type: "number", description: "Preferred Vite port (the next free port is used if busy)" },
+    host: { type: "string", description: "Host name Vite listens on", default: "localhost" },
+    "pass-env": { type: "list", description: "Environment variable to forward into the Node sidecar (repeatable)" },
+  },
+  examples: ["dormer dev", "dormer dev --port 3000 --pass-env MY_API_KEY"],
+};
+
+async function portFree(port: number, host: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const s = net.createServer();
+    s.once("error", () => resolve(false));
+    s.listen(port, host, () => s.close(() => resolve(true)));
+  });
+}
+export async function findFreePort(preferred: number, host: string): Promise<number> {
+  for (let p = preferred; p < preferred + 50; p++) if (await portFree(p, host)) return p;
+  throw new Error(`no free port in ${preferred}-${preferred + 49}`);
+}
+
+const alive = (p: ChildProcess | undefined): p is ChildProcess => Boolean(p && p.exitCode === null && p.signalCode === null);
+
+export async function run(args: ParsedArgs): Promise<number> {
+  const app = loadApp();
+  const { config, paths } = app;
+  const host = resolveHostBinary(app.root); // fail before anything is started
+  const hostName = flagString(args.flags, "host") ?? "localhost";
+  const port = await findFreePort(flagNumber(args.flags, "port") ?? config.dev?.port ?? 5173, hostName);
+
+  const { vite, version } = await loadVite(app.root);
+  const configFile = findViteConfig(paths.rendererDir);
+  if (!configFile) log.warn(`no vite.config.* in ${paths.rendererDir}; add one using @dormer/vite-plugin`);
+  const server = await vite.createServer({
+    root: paths.rendererDir,
+    configFile: configFile ?? false,
+    clearScreen: false,
+    logLevel: "info",
+    server: { port, strictPort: true, host: hostName },
+  });
+  await server.listen();
+  const url = server.resolvedUrls?.local[0] ?? `http://${hostName}:${port}/`;
+  log.ok(`vite ${version} dev server ready at ${c.bold(url)}`);
+
+  const passEnv = new Set<string>(["DORMER_DEV_URL", "DORMER_APP_VERSION", ...(config.dev?.passEnv ?? []), ...flagList(args.flags, "pass-env")]);
+  if (process.env.DORMER_SELFTEST !== undefined) passEnv.add("DORMER_SELFTEST");
+
+  let child: ChildProcess | undefined;
+  let generation = 0;
+  let pendingRestart = false;
+  let shuttingDown = false;
+  let watcher: WatchHandle | undefined;
+
+  const shutdown = async (code: number): Promise<never> => {
+    if (shuttingDown) await new Promise(() => {}); // another shutdown is in progress; wait for it to exit
+    shuttingDown = true;
+    if (alive(child)) {
+      child.kill("SIGTERM");
+      await Promise.race([once(child, "exit"), new Promise((r) => setTimeout(r, 3000))]);
+      if (alive(child)) child.kill("SIGKILL");
+    }
+    await watcher?.dispose().catch(() => {});
+    await server.close().catch(() => {});
+    process.exit(code);
+  };
+
+  const launch = () => {
+    const myGeneration = ++generation;
+    const proc = spawnHost({
+      host: host.path, appDir: app.root, entry: paths.devBackendOut, node: process.execPath, name: config.name,
+      dev: true, devUrl: url, passEnv: [...passEnv],
+      env: { DORMER_DEV_URL: url, DORMER_APP_VERSION: config.version },
+    });
+    child = proc;
+    log.ok(`host started (pid ${proc.pid}) from ${host.path} [${host.source}]`);
+    proc.on("error", (e) => { log.error(`failed to start host: ${e.message}`); void shutdown(EXIT.failure); });
+    proc.on("exit", (code, signal) => {
+      if (shuttingDown || myGeneration !== generation) return;
+      if (pendingRestart) { pendingRestart = false; launch(); return; }
+      log.info(`host exited (${signal ?? `code ${code}`}); stopping dev server`);
+      void shutdown(code ?? EXIT.ok);
+    });
+  };
+
+  const restart = () => {
+    if (!alive(child)) { launch(); return; }
+    pendingRestart = true;
+    log.step("backend changed — restarting host (windows are recreated)");
+    const victim = child;
+    victim.kill("SIGTERM");
+    setTimeout(() => { if (alive(victim)) victim.kill("SIGKILL"); }, 3000).unref();
+  };
+
+  let builds = 0;
+  watcher = await watchBackend({ root: app.root, entry: paths.entry, outfile: paths.devBackendOut, sourcemap: true, external: config.backend?.external }, (r) => {
+    builds++;
+    if (r.warnings.length) console.error(formatMessages(r.warnings, "warning"));
+    if (!r.ok) { log.error(`backend bundle failed (${builds === 1 ? "fix the error to start the host" : "keeping the previous host running"})\n${formatMessages(r.errors, "error")}`); return; }
+    if (builds === 1) { log.ok(`backend bundled → ${paths.devBackendOut} (${summarizeExternals(r.externals)})`); launch(); }
+    else restart();
+  });
+
+  process.on("SIGINT", () => { console.log(); void shutdown(130); });
+  process.on("SIGTERM", () => void shutdown(143));
+  return new Promise<number>(() => {}); // runs until shutdown() exits the process
+}

package/src/commands/doctor.ts

@@ -0,0 +1,141 @@
+// dormer doctor: environment checks with fix hints, plus the capability summary of the app.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import type { CommandSpec, ParsedArgs } from "../args.ts";
+import { CONFIG_FILE, type DormerConfig, findAppRoot, loadConfig, resolvePaths } from "../config.ts";
+import { CLI_DIR, hostPackageName, resolveHostBinary } from "../host.ts";
+import { findPackageDir, readJson, which } from "../resolve.ts";
+import { CliError, EXIT, c } from "../ui.ts";
+
+export const spec: CommandSpec = {
+  name: "doctor",
+  summary: "Check the toolchain, the native host and platform prerequisites",
+  usage: "doctor",
+  description: `Exit code 1 when a check fails (warnings do not fail). Windows and macOS checks are
+written from documentation and have not been verified on those platforms yet.`,
+  options: {},
+};
+
+export type Status = "ok" | "warn" | "fail";
+export interface Check { name: string; status: Status; detail: string; hint?: string }
+
+function sh(cmd: string, args: string[]): { ok: boolean; out: string } {
+  const r = spawnSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  return { ok: !r.error && r.status === 0, out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() };
+}
+
+export function nodeCheck(version: string = process.versions.node): Check {
+  const [major, minor] = version.split(".").map(Number);
+  if (major < 22) return { name: "Node.js", status: "fail", detail: `v${version} (22 or newer required)`, hint: "install Node 24 LTS from https://nodejs.org or with your version manager" };
+  if (major === 22 && minor < 18) return { name: "Node.js", status: "warn", detail: `v${version} (type stripping needs --experimental-strip-types before 22.18; the CLI re-executes itself with it)`, hint: "upgrade to Node 22.18+ or 24 to avoid the re-exec" };
+  return { name: "Node.js", status: "ok", detail: `v${version}` };
+}
+
+function hostCheck(root: string): Check {
+  try { const h = resolveHostBinary(root); return { name: "dormer-host", status: "ok", detail: `${h.path} (${h.source === "env" ? "DORMER_HOST_BIN" : h.source === "cargo-target" ? "cargo target dir" : hostPackageName()})` }; }
+  catch (e) { const err = e as CliError; return { name: "dormer-host", status: "fail", detail: err.message, hint: err.hints?.slice(1).join("; ") }; }
+}
+
+function linuxChecks(): Check[] {
+  const checks: Check[] = [];
+  if (sh("pkg-config", ["--exists", "webkit2gtk-4.1"]).ok) checks.push({ name: "WebKitGTK 4.1", status: "ok", detail: `development package present (${sh("pkg-config", ["--modversion", "webkit2gtk-4.1"]).out})` });
+  else {
+    const ld = sh("ldconfig", ["-p"]);
+    if (ld.ok && /libwebkit2gtk-4\.1/.test(ld.out)) checks.push({ name: "WebKitGTK 4.1", status: "ok", detail: "runtime library present (dev headers missing: only needed to build the host)", hint: "to build dormer-host: sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev librsvg2-dev pkg-config" });
+    else checks.push({ name: "WebKitGTK 4.1", status: "fail", detail: "libwebkit2gtk-4.1 not found", hint: "sudo apt install libwebkit2gtk-4.1-0 (runtime) or libwebkit2gtk-4.1-dev (to build the host); Fedora: webkit2gtk4.1" });
+  }
+  const bus = process.env.DBUS_SESSION_BUS_ADDRESS || (process.env.XDG_RUNTIME_DIR && fs.existsSync(path.join(process.env.XDG_RUNTIME_DIR, "bus")) ? `unix:path=${path.join(process.env.XDG_RUNTIME_DIR, "bus")}` : "");
+  checks.push(bus ? { name: "session D-Bus", status: "ok", detail: bus } : { name: "session D-Bus", status: "warn", detail: "no session bus (DBUS_SESSION_BUS_ADDRESS unset, no $XDG_RUNTIME_DIR/bus)", hint: "WebKitGTK and notifications want one: run under dbus-run-session -- <command>" });
+  const display = process.env.WAYLAND_DISPLAY ? `wayland (${process.env.WAYLAND_DISPLAY})` : process.env.DISPLAY ? `x11 (${process.env.DISPLAY})` : "";
+  checks.push(display ? { name: "display", status: "ok", detail: display } : { name: "display", status: "warn", detail: "no DISPLAY or WAYLAND_DISPLAY", hint: 'headless machines: xvfb-run -a -s "-screen 0 1280x800x24" dbus-run-session -- npm run dev' });
+  const nvidia = fs.existsSync("/proc/driver/nvidia/version") || Boolean(which("nvidia-smi"));
+  if (nvidia) checks.push({ name: "GPU driver", status: "warn", detail: "NVIDIA driver detected", hint: "if windows stay blank or crash in the compositor, set WEBKIT_DISABLE_DMABUF_RENDERER=1" });
+  const headless = ["xvfb-run", "dbus-run-session"].filter((t) => !which(t));
+  checks.push(headless.length ? { name: "headless tools", status: "warn", detail: `missing ${headless.join(", ")} (only needed for headless test runs)`, hint: "sudo apt install xvfb dbus" } : { name: "headless tools", status: "ok", detail: "xvfb-run and dbus-run-session available" });
+  return checks;
+}
+
+function macosChecks(): Check[] {
+  // UNVERIFIED on macOS: written from Apple documentation.
+  const clt = sh("xcode-select", ["-p"]);
+  const sw = sh("sw_vers", ["-productVersion"]);
+  const major = Number(sw.out.split(".")[0]);
+  return [
+    clt.ok ? { name: "Xcode command line tools", status: "ok", detail: clt.out } : { name: "Xcode command line tools", status: "fail", detail: "not installed", hint: "run: xcode-select --install" },
+    sw.ok ? (major >= 13 ? { name: "macOS", status: "ok", detail: sw.out } : { name: "macOS", status: "warn", detail: `${sw.out} (13+ recommended for WKWebView features Dormer relies on)` }) : { name: "macOS", status: "warn", detail: "sw_vers unavailable" },
+  ];
+}
+
+function windowsChecks(): Check[] {
+  // UNVERIFIED on Windows: the Evergreen WebView2 runtime registers its version under `pv` at these keys.
+  const keys = [
+    "HKLM\\SOFTWARE\\WOW6432Node\\Microsoft\\EdgeUpdate\\Clients\\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}",
+    "HKLM\\SOFTWARE\\Microsoft\\EdgeUpdate\\Clients\\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}",
+    "HKCU\\SOFTWARE\\Microsoft\\EdgeUpdate\\Clients\\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}",
+  ];
+  for (const k of keys) {
+    const r = sh("reg", ["query", k, "/v", "pv"]);
+    const m = r.ok ? /pv\s+REG_SZ\s+(\S+)/.exec(r.out) : null;
+    if (m && m[1] !== "0.0.0.0") return [{ name: "WebView2 runtime", status: "ok", detail: `version ${m[1]}` }];
+  }
+  return [{ name: "WebView2 runtime", status: "fail", detail: "Evergreen WebView2 runtime not registered", hint: "install it from https://developer.microsoft.com/microsoft-edge/webview2/ (Windows 11 ships it)" }];
+}
+
+function projectChecks(root: string | undefined): Check[] {
+  const checks: Check[] = [];
+  const esb = findPackageDir(CLI_DIR, "esbuild");
+  checks.push(esb ? { name: "esbuild", status: "ok", detail: `v${readJson<{ version: string }>(path.join(esb, "package.json")).version}` } : { name: "esbuild", status: "fail", detail: "not resolvable from @dormer/cli", hint: "reinstall @dormer/cli" });
+  if (!root) return checks;
+  const vite = findPackageDir(root, "vite");
+  checks.push(vite ? { name: "vite", status: "ok", detail: `v${readJson<{ version: string }>(path.join(vite, "package.json")).version} (${vite})` } : { name: "vite", status: "fail", detail: `not installed in ${root}`, hint: "npm install (vite is a devDependency of every template)" });
+  for (const p of ["@dormer/api", "@dormer/renderer", "@dormer/vite-plugin"]) {
+    const dir = findPackageDir(root, p);
+    checks.push(dir ? { name: p, status: "ok", detail: fs.realpathSync(dir) } : { name: p, status: "warn", detail: "not installed", hint: `npm install ${p}` });
+  }
+  return checks;
+}
+
+export function capabilitySummary(config: DormerConfig, root: string): string[] {
+  const paths = resolvePaths(root, config);
+  const lines = [
+    `${c.bold(config.name)} ${config.version} (${config.identifier})${config.description ? ` — ${config.description}` : ""}`,
+    `entry ${path.relative(root, paths.entry)} · renderer ${path.relative(root, paths.rendererDir)}/ · node pin ${config.node?.version ?? c.dim("none")}`,
+  ];
+  const windows = Object.entries(config.windows ?? {});
+  if (windows.length === 0) lines.push(`windows: ${c.dim("none declared (renderers get app-local ipc:*/send:* only)")}`);
+  for (const [name, w] of windows) lines.push(`window ${c.bold(name)}: ${(w.capabilities ?? []).length ? w.capabilities!.join(", ") : c.dim("no capabilities")}`);
+  if (config.backend?.external?.length) lines.push(`backend externals: ${config.backend.external.join(", ")}`);
+  return lines;
+}
+
+export function runChecks(root: string | undefined): Check[] {
+  const checks: Check[] = [nodeCheck(), hostCheck(root ?? process.cwd())];
+  if (process.platform === "linux") checks.push(...linuxChecks());
+  else if (process.platform === "darwin") checks.push(...macosChecks());
+  else if (process.platform === "win32") checks.push(...windowsChecks());
+  checks.push(...projectChecks(root));
+  return checks;
+}
+
+export async function run(_args: ParsedArgs): Promise<number> {
+  const root = findAppRoot(process.cwd());
+  console.log(`${c.bold("dormer doctor")} — ${process.platform} ${process.arch}${root ? `, app at ${root}` : ` (no ${CONFIG_FILE} found from ${process.cwd()})`}`);
+  const checks = runChecks(root);
+  const icon: Record<Status, string> = { ok: c.green("✓"), warn: c.yellow("!"), fail: c.red("✗") };
+  const width = Math.max(...checks.map((k) => k.name.length)) + 2;
+  for (const k of checks) {
+    console.log(`  ${icon[k.status]} ${k.name.padEnd(width)}${k.detail}`);
+    if (k.hint && k.status !== "ok") console.log(`      ${c.dim("hint:")} ${k.hint}`);
+  }
+  if (root) {
+    console.log(`\n${c.bold("App")} (${path.join(root, CONFIG_FILE)})`);
+    try { for (const l of capabilitySummary(loadConfig(root), root)) console.log(`  ${l}`); }
+    catch (e) { console.log(`  ${c.red("✗")} ${(e as Error).message}`); return EXIT.config; }
+  }
+  if (process.platform === "darwin" || process.platform === "win32") console.log(`\n${c.dim("note: platform checks on this OS are unverified; please report false results")}`);
+  const fails = checks.filter((k) => k.status === "fail").length;
+  const warns = checks.filter((k) => k.status === "warn").length;
+  console.log(`\n${fails ? c.red(`${fails} problem(s)`) : c.green("no problems")}${warns ? `, ${warns} warning(s)` : ""}`);
+  return fails ? EXIT.failure : EXIT.ok;
+}

package/src/commands/inspect.ts

@@ -0,0 +1,60 @@
+// dormer inspect: build (unless --skip-build), launch the app in inspection mode and print, per
+// window, the element-tree outline plus the snapshot path. Made for agents and CI: the same data a
+// screen reader sees, without opening devtools.
+import fs from "node:fs";
+import path from "node:path";
+import { type CommandSpec, type ParsedArgs, flagBool, flagNumber, flagString } from "../args.ts";
+import { loadApp } from "../config.ts";
+import { resolveHostBinary, spawnHost } from "../host.ts";
+import { CliError, EXIT, c, log } from "../ui.ts";
+import { buildApp } from "./build.ts";
+
+export const spec: CommandSpec = {
+  name: "inspect",
+  summary: "Launch the app, capture each window's element tree (and snapshot), print an outline",
+  usage: "inspect [--out <dir>] [--skip-build] [--json] [--timeout <ms>] [--settle <ms>] [--lines <n>]",
+  description: `Runs the built app with DORMER_INSPECT_OUT set. @dormer/api then captures every window once it
+has loaded: an accessibility-style element tree (roles, names, states, bounds) as JSON and text, and a
+PNG snapshot where the platform supports it (macOS today). The app exits by itself; the outline is
+printed here. Files land in .dormer/inspect/ by default.`,
+  options: {
+    out: { type: "string", description: "Output directory (default .dormer/inspect)" },
+    "skip-build": { type: "boolean", description: "Reuse dist/ instead of rebuilding" },
+    json: { type: "boolean", description: "Print inspect.json instead of the outline" },
+    timeout: { type: "number", description: "Give up after this many milliseconds (default 20000)" },
+    settle: { type: "number", description: "Wait this long after page load before capturing (default 700)" },
+    lines: { type: "number", description: "Outline lines to print per window (default 80)" },
+  },
+  examples: ["dormer inspect", "dormer inspect --skip-build --lines 200", "dormer inspect --json | jq .windows[0].nodes"],
+};
+
+export async function run(args: ParsedArgs): Promise<number> {
+  const app = loadApp();
+  if (!flagBool(args.flags, "skip-build")) await buildApp(app, { quiet: true });
+  const host = resolveHostBinary(app.root);
+  const out = path.resolve(app.root, flagString(args.flags, "out") ?? path.join(".dormer", "inspect"));
+  fs.rmSync(out, { recursive: true, force: true }); fs.mkdirSync(out, { recursive: true });
+  const timeout = flagNumber(args.flags, "timeout") ?? 20000;
+  const proc = spawnHost({
+    host: host.path, appDir: app.paths.rendererOut, entry: app.paths.backendOut, node: process.execPath, name: app.config.name,
+    passEnv: ["DORMER_INSPECT_OUT", "DORMER_INSPECT_SETTLE_MS", "DORMER_INSPECT_TIMEOUT_MS"],
+    env: { DORMER_INSPECT_OUT: out, DORMER_INSPECT_SETTLE_MS: String(flagNumber(args.flags, "settle") ?? 700), DORMER_INSPECT_TIMEOUT_MS: String(timeout), DORMER_APP_VERSION: app.config.version, RUST_LOG: process.env.RUST_LOG ?? "warn" },
+  });
+  const code = await new Promise<number>((res) => { const t = setTimeout(() => { proc.kill("SIGKILL"); res(124); }, timeout + 10000); proc.on("exit", (c) => { clearTimeout(t); res(c ?? 1); }); });
+  const summaryPath = path.join(out, "inspect.json");
+  if (!fs.existsSync(summaryPath)) throw new CliError(`no inspection result (host exited with ${code})`, { exitCode: EXIT.failure, hints: ["does the app create a window on ready?", "run with RUST_LOG=info for the host log"] });
+  const summary = JSON.parse(fs.readFileSync(summaryPath, "utf8")) as { ok: boolean; timedOut: boolean; windows: Array<{ route: number; title: string; url: string; nodes: number; truncated: boolean; outline: string; png: string | null; pngError?: string; error?: string }> };
+  if (flagBool(args.flags, "json")) { process.stdout.write(JSON.stringify(summary, null, 2) + "\n"); return summary.ok ? EXIT.ok : EXIT.failure; }
+  const lines = flagNumber(args.flags, "lines") ?? 80;
+  for (const w of summary.windows) {
+    if (w.error) { log.error(`window ${w.route}: ${w.error}`); continue; }
+    console.log(`${c.bold(`window ${w.route}`)} ${c.dim(w.url)}  ${w.nodes} nodes${w.truncated ? " (truncated)" : ""}`);
+    console.log(`  snapshot: ${w.png ?? c.dim(`none (${w.pngError ?? "not supported here"})`)}`);
+    console.log(`  tree:     ${w.outline.replace(/\.outline\.txt$/, ".tree.json")}`);
+    const outline = fs.readFileSync(w.outline, "utf8").split("\n").filter(Boolean);
+    console.log(outline.slice(0, lines).map((l) => `  ${l}`).join("\n"));
+    if (outline.length > lines) console.log(c.dim(`  … ${outline.length - lines} more lines in ${w.outline}`));
+  }
+  if (summary.timedOut) log.error("timed out before any window could be inspected");
+  return summary.ok ? EXIT.ok : EXIT.failure;
+}

package/src/commands/package.ts

@@ -0,0 +1,159 @@
+// dormer package: writes dist/bundle.json and shells out to the Rust `dormer-bundle` tool.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { type CommandSpec, type ParsedArgs, flagBool, flagList, flagString } from "../args.ts";
+import { BUNDLE_TARGETS, type BundleTarget, type DormerConfig, loadApp } from "../config.ts";
+import { CLI_DIR, isExecutable, resolveHostBinary } from "../host.ts";
+import { findPackageDir, findUp, which } from "../resolve.ts";
+import { CliError, EXIT, c, log } from "../ui.ts";
+import { buildApp } from "./build.ts";
+
+export const spec: CommandSpec = {
+  name: "package",
+  summary: "Produce installers for the current platform with dormer-bundle",
+  usage: "package [--target <t>]... [--out <dir>] [--skip-build] [--dry-run]",
+  description: `Builds the app (unless --skip-build), writes dist/bundle.json describing it, then runs
+\`dormer-bundle --config dist/bundle.json --out <dir>\`. The bundler binary is looked up in
+$DORMER_BUNDLE_BIN, the cargo target directory and PATH; when missing, instructions are printed
+and the exit code is 2. --dry-run stops after writing bundle.json.`,
+  options: {
+    target: { type: "list", alias: "t", description: "Installer format (repeatable)", values: BUNDLE_TARGETS },
+    out: { type: "string", description: "Output directory", default: "dist/bundle" },
+    "skip-build": { type: "boolean", description: "Reuse the existing dist/ instead of rebuilding" },
+    "dry-run": { type: "boolean", description: "Only write dist/bundle.json" },
+  },
+};
+
+/** Interface agreed with tools/bundler (`dormer-bundle --config <file> --out <dir>`). */
+export interface BundleSpec {
+  name: string;
+  identifier: string;
+  version: string;
+  description: string;
+  /** Absolute path of the built app (dist/): contains renderer/, main.js, dormer-app.json. */
+  appDir: string;
+  /** Backend entry relative to appDir. */
+  entry: string;
+  hostBinary: string;
+  nodeBinary: string;
+  targets: BundleTarget[];
+  icons: string[];
+  linux: { depends: string[] };
+  macos: { entitlements: string | null; signingIdentity: string | null; minimumSystemVersion: string | null };
+  windows: { signCommand: string | null };
+  /** Ship `*.map` files from dist/ (off by default: they are build artefacts, 1 MB for the PoC). */
+  sourceMaps: boolean;
+  /** Full ICU data file to ship next to a small-icu Node (`node.icu: "full"`), else null. */
+  nodeIcuData: string | null;
+}
+
+/** `icudt<N>l.dat` next to the Node binary (placed there by `dormer-bundle fetch-node` from a Dormer dist). */
+export function findIcuData(nodeBinary: string): string | undefined {
+  const dir = path.dirname(nodeBinary);
+  try { const f = fs.readdirSync(dir).find((n) => /^icudt\d+l\.dat$/.test(n)); return f ? path.join(dir, f) : undefined; } catch { return undefined; }
+}
+
+export function defaultTargets(platform: NodeJS.Platform = process.platform): BundleTarget[] {
+  if (platform === "darwin") return ["app", "dmg"];
+  if (platform === "win32") return ["nsis"];
+  return ["deb", "appimage"];
+}
+
+const DEFAULT_LINUX_DEPENDS = ["libwebkit2gtk-4.1-0", "libgtk-3-0"];
+
+export function makeBundleSpec(config: DormerConfig, o: { root: string; appDir: string; hostBinary: string; nodeBinary: string; targets: BundleTarget[] }): BundleSpec {
+  const b = config.bundle ?? {};
+  let icons = (b.icons ?? []).map((p) => path.resolve(o.root, p));
+  if (icons.length === 0 && fs.existsSync(path.join(o.root, "icons"))) {
+    icons = fs.readdirSync(path.join(o.root, "icons")).filter((f) => /\.(png|icns|ico|svg)$/i.test(f)).map((f) => path.join(o.root, "icons", f));
+  }
+  return {
+    name: config.name,
+    identifier: config.identifier,
+    version: config.version,
+    description: config.description ?? "",
+    appDir: o.appDir,
+    entry: "main.js",
+    hostBinary: o.hostBinary,
+    nodeBinary: o.nodeBinary,
+    targets: o.targets,
+    icons,
+    linux: { depends: b.linux?.depends ?? DEFAULT_LINUX_DEPENDS },
+    macos: { entitlements: b.macos?.entitlements ? path.resolve(o.root, b.macos.entitlements) : null, signingIdentity: b.macos?.signingIdentity ?? null, minimumSystemVersion: b.macos?.minimumSystemVersion ?? "13.0" },
+    windows: { signCommand: b.windows?.signCommand ?? null },
+    sourceMaps: b.sourceMaps ?? false,
+    nodeIcuData: config.node?.icu === "full" ? (findIcuData(o.nodeBinary) ?? null) : null,
+  };
+}
+
+export function resolveBundlerBinary(appRoot: string): { path?: string; tried: string[] } {
+  const exe = process.platform === "win32" ? "dormer-bundle.exe" : "dormer-bundle";
+  const tried: string[] = [];
+  if (process.env.DORMER_BUNDLE_BIN) { tried.push(process.env.DORMER_BUNDLE_BIN); if (isExecutable(process.env.DORMER_BUNDLE_BIN)) return { path: process.env.DORMER_BUNDLE_BIN, tried }; }
+  const workspaces = new Set<string>();
+  for (const start of [appRoot, CLI_DIR]) { const ws = findUp(start, "Cargo.toml"); if (ws) workspaces.add(ws); }
+  for (const ws of workspaces) {
+    for (const profile of ["release", "debug"]) {
+      const candidate = path.join(process.env.CARGO_TARGET_DIR ?? path.join(ws, "target"), profile, exe);
+      tried.push(candidate);
+      if (isExecutable(candidate)) return { path: candidate, tried };
+    }
+  }
+  // Prebuilt package for this platform (optional dependency of @dormer/cli), then $PATH.
+  const pkg = findPackageDir(appRoot, bundlePackageName()) ?? findPackageDir(CLI_DIR, bundlePackageName());
+  const fromPkg = pkg ? path.join(pkg, "bin", exe) : path.join(appRoot, "node_modules", bundlePackageName(), "bin", exe);
+  tried.push(fromPkg);
+  if (isExecutable(fromPkg)) return { path: fromPkg, tried };
+  const onPath = which("dormer-bundle");
+  tried.push("$PATH");
+  return { path: onPath, tried };
+}
+
+/** The npm package that carries the prebuilt packaging tool for this platform. */
+export function bundlePackageName(): string { return `@dormer/bundle-${process.platform}-${process.arch}`; }
+
+export function resolveNodeBinary(config: DormerConfig): string {
+  const candidate = config.node?.binary ?? process.env.DORMER_NODE_BIN ?? process.execPath;
+  if (!isExecutable(candidate)) throw new CliError(`Node binary not found: ${candidate}`, { exitCode: EXIT.noInput, hints: ['set "node.binary" in dormer.config.json or DORMER_NODE_BIN'] });
+  return candidate;
+}
+
+export async function run(args: ParsedArgs): Promise<number> {
+  const app = loadApp();
+  const { config, paths } = app;
+  if (!flagBool(args.flags, "skip-build")) await buildApp(app, { quiet: true });
+  else if (!fs.existsSync(path.join(paths.distDir, "dormer-app.json"))) throw new CliError("--skip-build given but dist/dormer-app.json does not exist", { exitCode: EXIT.noInput, hints: [`run ${c.bold("dormer build")} first`] });
+
+  const requested = flagList(args.flags, "target") as BundleTarget[];
+  const targets = requested.length ? requested : config.bundle?.targets ?? defaultTargets();
+  const host = resolveHostBinary(app.root);
+  const nodeBinary = resolveNodeBinary(config);
+  const pinned = config.node?.version;
+  if (pinned && pinned.split(".")[0] !== process.versions.node.split(".")[0] && nodeBinary === process.execPath) {
+    log.warn(`dormer.config.json pins Node ${pinned} but the app is packaged with the running Node ${process.versions.node}; set "node.binary" to a Node ${pinned} executable to ship that one`);
+  }
+  const bundle = makeBundleSpec(config, { root: app.root, appDir: paths.distDir, hostBinary: host.path, nodeBinary, targets });
+  const specPath = path.join(paths.distDir, "bundle.json");
+  fs.writeFileSync(specPath, JSON.stringify(bundle, null, 2) + "\n");
+  log.ok(`wrote ${specPath} (targets: ${targets.join(", ")})`);
+  if (flagBool(args.flags, "dry-run")) return EXIT.ok;
+
+  const outDir = path.resolve(app.root, flagString(args.flags, "out") ?? "dist/bundle");
+  const bundler = resolveBundlerBinary(app.root);
+  if (!bundler.path) {
+    log.error("dormer-bundle (the Rust packaging tool from tools/bundler) was not found");
+    log.hint(`looked at: ${bundler.tried.join(", ")}`);
+    log.hint(`inside the Dormer repository: ${c.bold("cargo build --release -p dormer-bundle")}`);
+    log.hint(`or set ${c.bold("DORMER_BUNDLE_BIN=/path/to/dormer-bundle")}`);
+    log.hint(`the generated ${specPath} can be passed to it manually: dormer-bundle --config ${specPath} --out ${outDir}`);
+    return EXIT.missingTool;
+  }
+  log.step(`running ${bundler.path} --config ${specPath} --out ${outDir}`);
+  fs.mkdirSync(outDir, { recursive: true });
+  const r = spawnSync(bundler.path, ["--config", specPath, "--out", outDir], { stdio: "inherit" });
+  if (r.error) throw new CliError(`failed to run dormer-bundle: ${r.error.message}`);
+  if (r.status !== 0) { log.error(`dormer-bundle exited with ${r.status ?? r.signal}`); return r.status ?? EXIT.failure; }
+  log.ok(`installers written to ${outDir}`);
+  return EXIT.ok;
+}

package/src/config.ts

@@ -0,0 +1,151 @@
+// dormer.config.json: schema, loading, validation and derived paths.
+import fs from "node:fs";
+import path from "node:path";
+import { CliError, EXIT, c } from "./ui.ts";
+
+export const CONFIG_FILE = "dormer.config.json";
+export const BUNDLE_TARGETS = ["deb", "rpm", "appimage", "app", "dmg", "nsis", "msi"] as const;
+export type BundleTarget = (typeof BUNDLE_TARGETS)[number];
+
+export interface WindowConfig { capabilities?: string[] }
+export interface DormerConfig {
+  name: string;
+  identifier: string;
+  version: string;
+  description?: string;
+  /** Backend entry, relative to the app root. Default `src/main.ts`. */
+  entry?: string;
+  /** Vite root of the renderer, relative to the app root. Default `renderer`. */
+  renderer?: string;
+  /** Per-window capability sets (ADR-0006); `main` is the first window. */
+  windows?: Record<string, WindowConfig>;
+  node?: {
+    /** Node.js major (or full) version the packaged app ships with, e.g. "24". */
+    version?: string;
+    /** Explicit Node binary for `dormer package`; default: the Node running the CLI. */
+    binary?: string;
+    /**
+     * `"full"` ships the complete ICU locale data next to a small-icu Dormer Node build (about 31 MB);
+     * default `"small"` keeps the embedded English-only data. Official full-icu binaries ignore this.
+     */
+    icu?: "small" | "full";
+  };
+  backend?: {
+    /** Extra package names to leave out of the backend bundle (native addons are detected automatically). */
+    external?: string[];
+  };
+  dev?: { port?: number; passEnv?: string[] };
+  bundle?: {
+    targets?: BundleTarget[];
+    icons?: string[];
+    linux?: { depends?: string[] };
+    macos?: { entitlements?: string; signingIdentity?: string; minimumSystemVersion?: string };
+    windows?: { signCommand?: string };
+    /** Ship source maps found under dist/ (default false). */
+    sourceMaps?: boolean;
+  };
+}
+
+export interface AppPaths {
+  root: string;
+  configPath: string;
+  entry: string;
+  rendererDir: string;
+  distDir: string;
+  rendererOut: string;
+  backendOut: string;
+  devDir: string;
+  devBackendOut: string;
+}
+
+/** Walks up from `start` to find the directory holding dormer.config.json. */
+export function findAppRoot(start: string = process.cwd()): string | undefined {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, CONFIG_FILE))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+const IDENTIFIER_RE = /^[A-Za-z][A-Za-z0-9-]*(\.[A-Za-z0-9-]+)+$/;
+const VERSION_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
+
+/** Validates a parsed config object; returns a list of problems (empty when valid). */
+export function validateConfig(cfg: unknown): string[] {
+  const problems: string[] = [];
+  if (!cfg || typeof cfg !== "object" || Array.isArray(cfg)) return ["top level must be an object"];
+  const o = cfg as Record<string, unknown>;
+  const str = (k: string, required: boolean) => {
+    if (o[k] === undefined) { if (required) problems.push(`"${k}" is required`); return; }
+    if (typeof o[k] !== "string" || (o[k] as string).length === 0) problems.push(`"${k}" must be a non-empty string`);
+  };
+  str("name", true); str("identifier", true); str("version", true); str("description", false); str("entry", false); str("renderer", false);
+  if (typeof o.identifier === "string" && !IDENTIFIER_RE.test(o.identifier)) problems.push(`"identifier" must be reverse-DNS like com.example.myapp (got "${o.identifier}")`);
+  if (typeof o.version === "string" && !VERSION_RE.test(o.version)) problems.push(`"version" must be semver like 1.2.3 (got "${o.version}")`);
+  if (o.windows !== undefined) {
+    if (!o.windows || typeof o.windows !== "object" || Array.isArray(o.windows)) problems.push(`"windows" must be an object keyed by window name`);
+    else for (const [name, w] of Object.entries(o.windows as Record<string, unknown>)) {
+      const caps = (w as { capabilities?: unknown })?.capabilities;
+      if (caps !== undefined && (!Array.isArray(caps) || caps.some((x) => typeof x !== "string"))) problems.push(`"windows.${name}.capabilities" must be an array of strings`);
+    }
+  }
+  const node = o.node as { version?: unknown; binary?: unknown } | undefined;
+  if (node !== undefined) {
+    if (!node || typeof node !== "object") problems.push(`"node" must be an object`);
+    else {
+      if (node.version !== undefined && (typeof node.version !== "string" || !/^\d+(\.\d+){0,2}$/.test(node.version))) problems.push(`"node.version" must be a version like "24" or "24.4.0"`);
+      if (node.binary !== undefined && typeof node.binary !== "string") problems.push(`"node.binary" must be a path string`);
+    }
+  }
+  const bundle = o.bundle as { targets?: unknown } | undefined;
+  if (bundle?.targets !== undefined) {
+    if (!Array.isArray(bundle.targets)) problems.push(`"bundle.targets" must be an array`);
+    else for (const t of bundle.targets) if (!(BUNDLE_TARGETS as readonly string[]).includes(String(t))) problems.push(`"bundle.targets" contains unknown target "${String(t)}" (known: ${BUNDLE_TARGETS.join(", ")})`);
+  }
+  return problems;
+}
+
+export function loadConfig(root: string): DormerConfig {
+  const file = path.join(root, CONFIG_FILE);
+  if (!fs.existsSync(file)) {
+    throw new CliError(`no ${CONFIG_FILE} found in ${root} (or any parent directory)`, {
+      exitCode: EXIT.config,
+      hints: [`run this command inside a Dormer app, or create one with ${c.bold("dormer create my-app --template vanilla")}`],
+    });
+  }
+  let parsed: unknown;
+  try { parsed = JSON.parse(fs.readFileSync(file, "utf8")); }
+  catch (e) { throw new CliError(`${file} is not valid JSON: ${(e as Error).message}`, { exitCode: EXIT.config }); }
+  const problems = validateConfig(parsed);
+  if (problems.length) throw new CliError(`${file} is invalid:\n  - ${problems.join("\n  - ")}`, { exitCode: EXIT.config, hints: ["see packages/cli/README.md for the config schema"] });
+  return parsed as DormerConfig;
+}
+
+export function resolvePaths(root: string, config: DormerConfig): AppPaths {
+  const distDir = path.join(root, "dist");
+  const devDir = path.join(root, ".dormer", "dev");
+  return {
+    root,
+    configPath: path.join(root, CONFIG_FILE),
+    entry: path.resolve(root, config.entry ?? "src/main.ts"),
+    rendererDir: path.resolve(root, config.renderer ?? "renderer"),
+    distDir,
+    rendererOut: path.join(distDir, "renderer"),
+    backendOut: path.join(distDir, "main.js"),
+    devDir,
+    devBackendOut: path.join(devDir, "main.js"),
+  };
+}
+
+/** Loads config from the nearest app root (cwd upwards) and derives paths. */
+export function loadApp(cwd: string = process.cwd()): { root: string; config: DormerConfig; paths: AppPaths } {
+  const root = findAppRoot(cwd) ?? cwd;
+  const config = loadConfig(root);
+  return { root, config, paths: resolvePaths(root, config) };
+}
+
+export function assertExists(file: string, what: string, hint?: string): void {
+  if (!fs.existsSync(file)) throw new CliError(`${what} not found: ${file}`, { exitCode: EXIT.noInput, hints: hint ? [hint] : [] });
+}