@dormer/cli 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@dormer/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "dormer CLI: create, dev, build, package and doctor for Dormer desktop apps",
+  "type": "module",
+  "license": "Apache-2.0 OR MIT",
+  "bin": {
+    "dormer": "bin/dormer.mjs"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "test:e2e-linux": "test/e2e-linux.sh",
+    "prepack": "node ../../scripts/sync-templates.mjs && node build.mjs",
+    "postpack": "node ../../scripts/sync-templates.mjs --clean",
+    "build": "node build.mjs",
+    "prepare": "node build.mjs"
+  },
+  "dependencies": {
+    "esbuild": "^0.28.0"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.6"
+  },
+  "optionalDependencies": {
+    "@dormer/host-darwin-arm64": "0.1.0",
+    "@dormer/bundle-darwin-arm64": "0.1.0",
+    "@dormer/host-darwin-x64": "0.1.0",
+    "@dormer/bundle-darwin-x64": "0.1.0",
+    "@dormer/host-linux-x64": "0.1.0",
+    "@dormer/bundle-linux-x64": "0.1.0",
+    "@dormer/host-win32-x64": "0.1.0",
+    "@dormer/bundle-win32-x64": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/veerareddyvishal144/dormer.git",
+    "directory": "packages/cli"
+  }
+}

package/src/args.ts

@@ -0,0 +1,68 @@
+// Minimal argument parser driven by a per-command option spec (also used to render --help).
+import { CliError, EXIT, c } from "./ui.ts";
+
+export type OptionType = "string" | "boolean" | "list" | "number";
+export interface OptionSpec { type: OptionType; description: string; alias?: string; values?: readonly string[]; default?: string | number | boolean }
+export interface CommandSpec {
+  name: string;
+  summary: string;
+  usage: string;
+  description?: string;
+  options: Record<string, OptionSpec>;
+  examples?: string[];
+}
+export type FlagValue = string | number | boolean | string[];
+export interface ParsedArgs { positionals: string[]; flags: Record<string, FlagValue> }
+
+const GLOBAL_OPTIONS: Record<string, OptionSpec> = { help: { type: "boolean", description: "Show help for this command", alias: "h" } };
+
+export function parseArgs(argv: string[], spec: CommandSpec): ParsedArgs {
+  const options = { ...GLOBAL_OPTIONS, ...spec.options };
+  const aliases = new Map<string, string>();
+  for (const [name, o] of Object.entries(options)) if (o.alias) aliases.set(o.alias, name);
+  const flags: Record<string, FlagValue> = {};
+  const positionals: string[] = [];
+  const usage = (msg: string) => new CliError(msg, { exitCode: EXIT.usage, hints: [`run ${c.bold(`dormer ${spec.name} --help`)} for usage`] });
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") { positionals.push(...argv.slice(i + 1)); break; }
+    if (!a.startsWith("-") || a === "-") { positionals.push(a); continue; }
+    let name: string; let inline: string | undefined;
+    if (a.startsWith("--")) { const eq = a.indexOf("="); name = eq === -1 ? a.slice(2) : a.slice(2, eq); if (eq !== -1) inline = a.slice(eq + 1); }
+    else { const short = a.slice(1); const full = aliases.get(short); if (!full) throw usage(`unknown option ${a}`); name = full; }
+    let negated = false;
+    if (!options[name] && name.startsWith("no-") && options[name.slice(3)]?.type === "boolean") { name = name.slice(3); negated = true; }
+    const o = options[name];
+    if (!o) throw usage(`unknown option --${name}`);
+    if (o.type === "boolean") { if (inline !== undefined) throw usage(`--${name} does not take a value`); flags[name] = !negated; continue; }
+    const value = inline ?? argv[++i];
+    if (value === undefined) throw usage(`--${name} requires a value`);
+    if (o.values && !o.values.includes(value)) throw usage(`--${name} must be one of: ${o.values.join(", ")} (got "${value}")`);
+    if (o.type === "number") { const n = Number(value); if (!Number.isFinite(n)) throw usage(`--${name} must be a number`); flags[name] = n; continue; }
+    if (o.type === "list") { (flags[name] = (flags[name] as string[] | undefined) ?? []); (flags[name] as string[]).push(value); continue; }
+    flags[name] = value;
+  }
+  for (const [name, o] of Object.entries(spec.options)) if (o.default !== undefined && flags[name] === undefined) flags[name] = o.default;
+  return { positionals, flags };
+}
+
+export function renderHelp(spec: CommandSpec): string {
+  const lines = [`${c.bold(`dormer ${spec.name}`)} — ${spec.summary}`, "", `Usage: dormer ${spec.usage}`];
+  if (spec.description) lines.push("", spec.description.trim());
+  const options = { ...spec.options, ...GLOBAL_OPTIONS };
+  const names = Object.entries(options).map(([n, o]) => [`--${n}${o.alias ? `, -${o.alias}` : ""}${o.type === "boolean" ? "" : o.type === "list" ? " <value>…" : " <value>"}`, o] as const);
+  const width = Math.max(...names.map(([n]) => n.length)) + 2;
+  lines.push("", "Options:");
+  for (const [n, o] of names) {
+    const extras = [o.values ? `one of ${o.values.join("|")}` : "", o.default !== undefined ? `default ${String(o.default)}` : ""].filter(Boolean).join(", ");
+    lines.push(`  ${n.padEnd(width)}${o.description}${extras ? c.dim(` (${extras})`) : ""}`);
+  }
+  if (spec.examples?.length) { lines.push("", "Examples:"); for (const e of spec.examples) lines.push(`  ${e}`); }
+  return lines.join("\n");
+}
+
+export const flagString = (flags: Record<string, FlagValue>, name: string): string | undefined => (typeof flags[name] === "string" ? (flags[name] as string) : undefined);
+export const flagBool = (flags: Record<string, FlagValue>, name: string): boolean => flags[name] === true;
+export const flagNumber = (flags: Record<string, FlagValue>, name: string): number | undefined => (typeof flags[name] === "number" ? (flags[name] as number) : undefined);
+export const flagList = (flags: Record<string, FlagValue>, name: string): string[] => (Array.isArray(flags[name]) ? (flags[name] as string[]) : []);

package/src/backend.ts

@@ -0,0 +1,142 @@
+// Bundling the Node backend with esbuild.
+//
+// Output is one ESM file (plus source map) for `platform: node`. Everything the entry imports is
+// bundled, including the `@dormer/*` packages, which are published as TypeScript sources (their
+// `exports` point at `src/index.ts`): bundling them here is what lets the output run on any Node
+// 22+ without type stripping and without the app's node_modules at runtime. Left external:
+//   - `node:*` and bare builtins;
+//   - `*.node` files and packages that look like native addons (gypfile/binary/napi fields, or a
+//     dependency on node-gyp-build, bindings, node-pre-gyp, prebuild-install...): they are
+//     reported in `externals` so `dormer package` can ship them from node_modules;
+//   - names listed in dormer.config.json `backend.external`.
+// A `createRequire` banner makes `require()` calls inside bundled CommonJS (e.g. msgpackr's
+// optional native accelerator lookup) resolve relative to the output file at runtime.
+import fs from "node:fs";
+import path from "node:path";
+import { isBuiltin } from "node:module";
+import * as esbuild from "esbuild";
+import { CliError, EXIT, c } from "./ui.ts";
+
+export interface BundleOptions {
+  root: string;
+  entry: string;
+  outfile: string;
+  minify?: boolean;
+  sourcemap?: boolean;
+  external?: string[];
+  define?: Record<string, string>;
+}
+export interface BundleResult { outfile: string; bytes: number; externals: string[]; warnings: esbuild.Message[] }
+
+const NATIVE_DEP_RE = /^(node-gyp-build|node-gyp-build-optional-packages|bindings|prebuild-install|prebuildify|@mapbox\/node-pre-gyp|node-pre-gyp|node-addon-api|cmake-js|nan|napi-build-utils|pkg-prebuilds)$/;
+
+export function packageName(specifier: string): string | undefined {
+  if (specifier.startsWith(".") || specifier.startsWith("/") || specifier.startsWith("node:")) return undefined;
+  const parts = specifier.split("/");
+  return specifier.startsWith("@") ? (parts.length >= 2 ? `${parts[0]}/${parts[1]}` : undefined) : parts[0];
+}
+
+function findPackageJson(fromDir: string, name: string): Record<string, unknown> | undefined {
+  let dir = fromDir;
+  for (;;) {
+    const f = path.join(dir, "node_modules", name, "package.json");
+    if (fs.existsSync(f)) { try { return JSON.parse(fs.readFileSync(f, "utf8")); } catch { return undefined; } }
+    const parent = path.dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+export function looksNative(pkg: Record<string, unknown>): boolean {
+  if (pkg.gypfile || pkg.binary || pkg.napi) return true;
+  for (const k of ["dependencies", "optionalDependencies", "peerDependencies"]) {
+    const deps = pkg[k];
+    if (deps && typeof deps === "object" && Object.keys(deps as object).some((d) => NATIVE_DEP_RE.test(d))) return true;
+  }
+  return false;
+}
+
+function externalsPlugin(externals: Set<string>, explicit: string[]): esbuild.Plugin {
+  return {
+    name: "dormer-externals",
+    setup(build) {
+      build.onResolve({ filter: /\.node$/ }, (args) => ({ path: args.path, external: true }));
+      build.onResolve({ filter: /^[^./]/ }, (args) => {
+        if (args.kind === "entry-point") return undefined;
+        const name = packageName(args.path);
+        if (!name) return undefined;
+        if (isBuiltin(name)) return { path: args.path, external: true };
+        if (explicit.includes(name)) { externals.add(name); return { path: args.path, external: true }; }
+        if (name.startsWith("@dormer/")) return undefined; // always bundled (TypeScript sources)
+        const pkg = findPackageJson(args.resolveDir, name);
+        if (pkg && looksNative(pkg)) { externals.add(name); return { path: args.path, external: true }; }
+        return undefined;
+      });
+    },
+  };
+}
+
+const BANNER = `import { createRequire as __dormerCreateRequire } from "node:module";\nconst require = __dormerCreateRequire(import.meta.url);\n`;
+
+export function buildOptions(o: BundleOptions, externals: Set<string>): esbuild.BuildOptions {
+  return {
+    entryPoints: [o.entry],
+    outfile: o.outfile,
+    bundle: true,
+    platform: "node",
+    format: "esm",
+    target: "node22",
+    conditions: ["node", "import", "module", "default"],
+    mainFields: ["module", "main"],
+    sourcemap: o.sourcemap === false ? false : true,
+    minify: o.minify === true,
+    legalComments: "none",
+    logLevel: "silent",
+    absWorkingDir: o.root,
+    banner: { js: BANNER },
+    define: { "process.env.DORMER_BUNDLED": '"1"', ...o.define },
+    plugins: [externalsPlugin(externals, o.external ?? [])],
+    metafile: true,
+  };
+}
+
+export function formatMessages(messages: esbuild.Message[], kind: "error" | "warning"): string {
+  return esbuild.formatMessagesSync(messages, { kind, color: Boolean(process.stdout.isTTY) }).join("");
+}
+
+export async function bundleBackend(o: BundleOptions): Promise<BundleResult> {
+  if (!fs.existsSync(o.entry)) throw new CliError(`backend entry not found: ${o.entry}`, { exitCode: EXIT.noInput, hints: [`set "entry" in dormer.config.json (default src/main.ts)`] });
+  const externals = new Set<string>();
+  fs.mkdirSync(path.dirname(o.outfile), { recursive: true });
+  let result: esbuild.BuildResult;
+  try { result = await esbuild.build(buildOptions(o, externals)); }
+  catch (e) {
+    const err = e as { errors?: esbuild.Message[] };
+    if (err.errors?.length) throw new CliError(`backend bundle failed:\n${formatMessages(err.errors, "error")}`, { hints: [`entry: ${o.entry}`] });
+    throw e;
+  }
+  const bytes = fs.statSync(o.outfile).size;
+  return { outfile: o.outfile, bytes, externals: [...externals].sort(), warnings: result.warnings };
+}
+
+export interface WatchHandle { dispose(): Promise<void> }
+export type WatchCallback = (r: { ok: boolean; errors: esbuild.Message[]; warnings: esbuild.Message[]; externals: string[] }) => void;
+
+/** Rebuilds `outfile` whenever the backend sources change; `onBuild` fires after every attempt (first included). */
+export async function watchBackend(o: BundleOptions, onBuild: WatchCallback): Promise<WatchHandle> {
+  if (!fs.existsSync(o.entry)) throw new CliError(`backend entry not found: ${o.entry}`, { exitCode: EXIT.noInput, hints: [`set "entry" in dormer.config.json (default src/main.ts)`] });
+  const externals = new Set<string>();
+  fs.mkdirSync(path.dirname(o.outfile), { recursive: true });
+  const options = buildOptions(o, externals);
+  options.plugins!.push({
+    name: "dormer-watch-notify",
+    setup(build) { build.onEnd((r) => onBuild({ ok: r.errors.length === 0, errors: r.errors, warnings: r.warnings, externals: [...externals].sort() })); },
+  });
+  const ctx = await esbuild.context(options);
+  await ctx.watch();
+  return { dispose: () => ctx.dispose() };
+}
+
+export function summarizeExternals(externals: string[]): string {
+  return externals.length ? `${externals.length} native/external package(s) kept out of the bundle: ${c.bold(externals.join(", "))}` : "no external packages (everything bundled)";
+}

package/src/cli.ts

@@ -0,0 +1,45 @@
+// `dormer` command dispatcher. Each command module exports `spec` (options, help) and `run`.
+import path from "node:path";
+import { type CommandSpec, type ParsedArgs, parseArgs, renderHelp } from "./args.ts";
+import { CLI_DIR } from "./host.ts";
+import { readJson } from "./resolve.ts";
+import { CliError, EXIT, c, reportError } from "./ui.ts";
+import * as create from "./commands/create.ts";
+import * as dev from "./commands/dev.ts";
+import * as build from "./commands/build.ts";
+import * as pkg from "./commands/package.ts";
+import * as doctor from "./commands/doctor.ts";
+import * as inspect from "./commands/inspect.ts";
+
+interface Command { spec: CommandSpec; run(args: ParsedArgs): Promise<number> }
+const COMMANDS: Record<string, Command> = { create, dev, build, package: pkg, doctor, inspect };
+
+function version(): string { try { return readJson<{ version: string }>(path.join(CLI_DIR, "package.json")).version; } catch { return "0.0.0"; } }
+
+function globalHelp(): string {
+  const width = Math.max(...Object.keys(COMMANDS).map((n) => n.length)) + 2;
+  return [
+    `${c.bold("dormer")} ${version()} — build desktop apps with Node.js and the system WebView`,
+    "",
+    "Usage: dormer <command> [options]",
+    "",
+    "Commands:",
+    ...Object.values(COMMANDS).map((cmd) => `  ${cmd.spec.name.padEnd(width)}${cmd.spec.summary}`),
+    "",
+    "Run `dormer <command> --help` for the options of a command.",
+    "Environment: DORMER_HOST_BIN (host binary), DORMER_BUNDLE_BIN (packaging tool), DORMER_CLI_DEBUG=1 (stack traces).",
+  ].join("\n");
+}
+
+export async function main(argv: string[]): Promise<number> {
+  const [name, ...rest] = argv;
+  if (!name || name === "--help" || name === "-h" || name === "help") { console.log(globalHelp()); return EXIT.ok; }
+  if (name === "--version" || name === "-v") { console.log(version()); return EXIT.ok; }
+  const cmd = COMMANDS[name];
+  if (!cmd) throw new CliError(`unknown command "${name}"`, { exitCode: EXIT.usage, hints: [`commands: ${Object.keys(COMMANDS).join(", ")}`, "run `dormer --help`"] });
+  const args = parseArgs(rest, cmd.spec);
+  if (args.flags.help) { console.log(renderHelp(cmd.spec)); return EXIT.ok; }
+  return cmd.run(args);
+}
+
+main(process.argv.slice(2)).then((code) => process.exit(code), (err) => process.exit(reportError(err)));

package/src/commands/build.ts

@@ -0,0 +1,105 @@
+// dormer build: vite build (renderer) + esbuild (backend) + manifest.
+import fs from "node:fs";
+import path from "node:path";
+import { type CommandSpec, type ParsedArgs, flagBool } from "../args.ts";
+import { CONFIG_FILE, type AppPaths, type DormerConfig, loadApp } from "../config.ts";
+import { bundleBackend, formatMessages, summarizeExternals, type BundleResult } from "../backend.ts";
+import { findViteConfig, loadVite, readJson } from "../resolve.ts";
+import { CLI_DIR } from "../host.ts";
+import { CliError, EXIT, c, formatBytes, log } from "../ui.ts";
+
+export const spec: CommandSpec = {
+  name: "build",
+  summary: "Build the renderer and the backend into dist/",
+  usage: "build [--minify] [--no-sourcemap] [--quiet]",
+  description: `Runs \`vite build\` for the renderer (→ dist/renderer), bundles the backend with esbuild
+(→ dist/main.js + .map), copies ${CONFIG_FILE} and writes dist/dormer-app.json. dist/ is owned by
+this command and is recreated on every run.`,
+  options: {
+    minify: { type: "boolean", description: "Minify the backend bundle" },
+    sourcemap: { type: "boolean", description: "Emit dist/main.js.map (use --no-sourcemap to disable)", default: true },
+    quiet: { type: "boolean", description: "Only print warnings and errors from Vite" },
+  },
+};
+
+export interface AppManifest {
+  manifestVersion: 1;
+  name: string;
+  identifier: string;
+  version: string;
+  description?: string;
+  /** Backend entry, relative to the manifest's directory. */
+  entry: string;
+  /** Renderer assets directory, relative to the manifest's directory (served as dormer://app/). */
+  assets: string;
+  node: { version?: string };
+  /** Packages left outside the bundle (native addons); must be shipped from node_modules. */
+  externals: string[];
+  windows?: DormerConfig["windows"];
+  builtAt: string;
+  cli: string;
+}
+
+export function cliVersion(): string {
+  try { return readJson<{ version: string }>(path.join(CLI_DIR, "package.json")).version; } catch { return "0.0.0"; }
+}
+
+export function makeManifest(config: DormerConfig, externals: string[]): AppManifest {
+  return {
+    manifestVersion: 1,
+    name: config.name,
+    identifier: config.identifier,
+    version: config.version,
+    description: config.description,
+    entry: "main.js",
+    assets: "renderer",
+    node: { version: config.node?.version },
+    externals,
+    windows: config.windows,
+    builtAt: new Date().toISOString(),
+    cli: cliVersion(),
+  };
+}
+
+export interface BuildOutput { manifest: AppManifest; backend: BundleResult; manifestPath: string }
+
+export async function buildApp(app: { root: string; config: DormerConfig; paths: AppPaths }, opts: { minify?: boolean; sourcemap?: boolean; quiet?: boolean } = {}): Promise<BuildOutput> {
+  const { config, paths } = app;
+  if (!fs.existsSync(paths.rendererDir)) throw new CliError(`renderer directory not found: ${paths.rendererDir}`, { exitCode: EXIT.noInput, hints: [`set "renderer" in ${CONFIG_FILE} (default "renderer")`] });
+  if (!fs.existsSync(paths.entry)) throw new CliError(`backend entry not found: ${paths.entry}`, { exitCode: EXIT.noInput, hints: [`set "entry" in ${CONFIG_FILE} (default "src/main.ts")`] });
+
+  fs.rmSync(paths.distDir, { recursive: true, force: true });
+  fs.mkdirSync(paths.distDir, { recursive: true });
+
+  const { vite, version } = await loadVite(app.root);
+  log.step(`building renderer with vite ${version} → ${path.relative(app.root, paths.rendererOut)}`);
+  const configFile = findViteConfig(paths.rendererDir);
+  if (!configFile) log.warn(`no vite.config.* in ${paths.rendererDir}; add one using @dormer/vite-plugin`);
+  await vite.build({
+    root: paths.rendererDir,
+    configFile: configFile ?? false,
+    logLevel: opts.quiet ? "warn" : "info",
+    build: { outDir: paths.rendererOut, emptyOutDir: true },
+  });
+  if (!fs.existsSync(path.join(paths.rendererOut, "index.html"))) {
+    throw new CliError(`vite build produced no ${path.join(paths.rendererOut, "index.html")}`, { hints: ["the renderer must have an index.html at its root; check build.outDir is not overridden"] });
+  }
+
+  log.step(`bundling backend ${path.relative(app.root, paths.entry)} → ${path.relative(app.root, paths.backendOut)}`);
+  const backend = await bundleBackend({ root: app.root, entry: paths.entry, outfile: paths.backendOut, minify: opts.minify, sourcemap: opts.sourcemap !== false, external: config.backend?.external });
+  if (backend.warnings.length) console.error(formatMessages(backend.warnings, "warning"));
+  log.info(`backend ${formatBytes(backend.bytes)}; ${summarizeExternals(backend.externals)}`);
+
+  fs.copyFileSync(paths.configPath, path.join(paths.distDir, CONFIG_FILE));
+  const manifest = makeManifest(config, backend.externals);
+  const manifestPath = path.join(paths.distDir, "dormer-app.json");
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+  log.ok(`built ${c.bold(`${config.name} ${config.version}`)} → ${paths.distDir}`);
+  return { manifest, backend, manifestPath };
+}
+
+export async function run(args: ParsedArgs): Promise<number> {
+  const app = loadApp();
+  await buildApp(app, { minify: flagBool(args.flags, "minify"), sourcemap: args.flags.sourcemap !== false, quiet: flagBool(args.flags, "quiet") });
+  return EXIT.ok;
+}

package/src/commands/create.ts

@@ -0,0 +1,132 @@
+// dormer create <dir> --template <name>
+import fs from "node:fs";
+import path from "node:path";
+import { type CommandSpec, type ParsedArgs, flagBool, flagString } from "../args.ts";
+import { CLI_DIR } from "../host.ts";
+import { CliError, EXIT, c, log } from "../ui.ts";
+
+export const TEMPLATES = ["vanilla", "react", "vue", "svelte"] as const;
+const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
+
+export const spec: CommandSpec = {
+  name: "create",
+  summary: "Scaffold a new Dormer app from a template",
+  usage: "create <dir> --template <name> [--pm npm] [--link] [--force]",
+  description: `Copies templates/<name> into <dir>, sets the package name and bundle identifier
+(com.example.<name>) and prints the next steps. Templates depend on the published @dormer/*
+packages; inside the Dormer monorepo pass --link to reference the local packages instead.`,
+  options: {
+    template: { type: "string", alias: "t", description: "Template to copy", values: TEMPLATES },
+    pm: { type: "string", description: "Package manager used in the printed next steps", values: PACKAGE_MANAGERS, default: "npm" },
+    link: { type: "boolean", description: "Write file: paths to this monorepo's @dormer/* packages (no publishing needed)" },
+    force: { type: "boolean", description: "Allow writing into a non-empty directory" },
+  },
+  examples: ["dormer create my-app --template react", "dormer create ../scratch/app --template svelte --link"],
+};
+
+/** Packages a template may reference, with their locations inside the monorepo (used by --link). */
+export const MONOREPO_PACKAGES: Record<string, string> = {
+  "@dormer/api": "packages/api",
+  "@dormer/renderer": "packages/renderer",
+  "@dormer/vite-plugin": "packages/vite-plugin",
+  "@dormer/cli": "packages/cli",
+  // transitive dependencies of @dormer/api, linked too so npm can satisfy them without a registry
+  "@dormer/node-runtime": "runtime/node-runtime",
+  "@dormer/ipc": "runtime/ipc/ts",
+};
+
+export function templatesDir(): string {
+  for (const d of [path.join(CLI_DIR, "templates"), path.resolve(CLI_DIR, "..", "..", "templates")]) {
+    if (fs.existsSync(path.join(d, "vanilla", "package.json"))) return d;
+  }
+  throw new CliError("templates directory not found", { exitCode: EXIT.noInput, hints: [`expected ${path.join(CLI_DIR, "templates")} or ${path.resolve(CLI_DIR, "..", "..", "templates")}`] });
+}
+
+export function monorepoRoot(): string | undefined {
+  const root = path.resolve(CLI_DIR, "..", "..");
+  return fs.existsSync(path.join(root, "packages", "api", "package.json")) && fs.existsSync(path.join(root, "runtime", "ipc", "ts", "package.json")) ? root : undefined;
+}
+
+export function packageNameFor(dir: string): string {
+  const base = path.basename(path.resolve(dir)).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+|[._-]+$/g, "");
+  return base || "dormer-app";
+}
+export function identifierFor(name: string): string {
+  const seg = name.replace(/[^a-z0-9-]+/gi, "-").replace(/^-+|-+$/g, "").toLowerCase() || "app";
+  return `com.example.${/^[a-z]/.test(seg) ? seg : `app-${seg}`}`;
+}
+
+const TEXT_EXT = new Set([".json", ".md", ".html", ".ts", ".tsx", ".vue", ".svelte", ".js", ".mjs", ".cjs", ".css", ".txt", ".yml", ".yaml"]);
+
+/** Recursively copies a template; `_gitignore` becomes `.gitignore` (npm would drop a real one). */
+export function copyTemplate(src: string, dest: string, vars: Record<string, string>): string[] {
+  const written: string[] = [];
+  const walk = (from: string, to: string) => {
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+      if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".dormer") continue;
+      const target = path.join(to, entry.name === "_gitignore" ? ".gitignore" : entry.name);
+      const source = path.join(from, entry.name);
+      if (entry.isDirectory()) { walk(source, target); continue; }
+      if (TEXT_EXT.has(path.extname(entry.name)) || entry.name === "_gitignore") {
+        let text = fs.readFileSync(source, "utf8");
+        for (const [k, v] of Object.entries(vars)) text = text.replaceAll(`{{${k}}}`, v);
+        fs.writeFileSync(target, text);
+      } else fs.copyFileSync(source, target);
+      written.push(target);
+    }
+  };
+  walk(src, dest);
+  return written;
+}
+
+/** Rewrites @dormer/* dependency ranges to file: links into the monorepo. */
+export function linkMonorepoPackages(pkgJsonPath: string, repoRoot: string): string[] {
+  const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8")) as Record<string, Record<string, string> | undefined>;
+  const linked: string[] = [];
+  for (const field of ["dependencies", "devDependencies"]) {
+    const deps = pkg[field]; if (!deps) continue;
+    for (const name of Object.keys(deps)) {
+      const rel = MONOREPO_PACKAGES[name];
+      if (rel) { deps[name] = `file:${path.join(repoRoot, rel)}`; linked.push(name); }
+    }
+  }
+  // Transitive @dormer/* dependencies must be visible to npm's resolver as well.
+  pkg.devDependencies ??= {};
+  for (const [name, rel] of Object.entries(MONOREPO_PACKAGES)) {
+    if (!pkg.dependencies?.[name] && !pkg.devDependencies[name]) { pkg.devDependencies[name] = `file:${path.join(repoRoot, rel)}`; linked.push(name); }
+  }
+  fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + "\n");
+  return linked;
+}
+
+export async function run(args: ParsedArgs): Promise<number> {
+  const target = args.positionals[0];
+  const template = flagString(args.flags, "template");
+  if (!target) throw new CliError("missing <dir>", { exitCode: EXIT.usage, hints: [`example: ${c.bold("dormer create my-app --template vanilla")}`] });
+  if (!template) throw new CliError("missing --template", { exitCode: EXIT.usage, hints: [`choose one of: ${TEMPLATES.join(", ")}`] });
+  const dest = path.resolve(target);
+  const src = path.join(templatesDir(), template);
+  if (!fs.existsSync(path.join(src, "package.json"))) throw new CliError(`template "${template}" not found at ${src}`, { exitCode: EXIT.noInput });
+  if (fs.existsSync(dest) && fs.readdirSync(dest).length > 0 && !flagBool(args.flags, "force")) {
+    throw new CliError(`${dest} exists and is not empty`, { exitCode: EXIT.usage, hints: ["choose another directory or pass --force"] });
+  }
+  const name = packageNameFor(dest);
+  const vars = { name, identifier: identifierFor(name), template };
+  log.step(`creating ${c.bold(name)} from the ${template} template in ${dest}`);
+  const files = copyTemplate(src, dest, vars);
+  log.info(`${files.length} files written`);
+
+  if (flagBool(args.flags, "link")) {
+    const repo = monorepoRoot();
+    if (!repo) throw new CliError("--link requires running the CLI from a checkout of the Dormer monorepo", { exitCode: EXIT.usage, hints: ["without --link the templates reference the published @dormer/* packages"] });
+    const linked = linkMonorepoPackages(path.join(dest, "package.json"), repo);
+    log.info(`linked ${linked.length} @dormer packages to ${repo} via file: paths`);
+  }
+
+  const pm = flagString(args.flags, "pm") ?? "npm";
+  const runCmd = (s: string) => (pm === "npm" ? `npm run ${s}` : `${pm} ${s}`);
+  const rel = path.relative(process.cwd(), dest) || ".";
+  console.log(`\n${c.green("Done.")} Next steps:\n\n  cd ${rel}\n  ${pm} install\n  ${runCmd("dev")}        ${c.dim("# Vite dev server + native window with live backend rebuilds")}\n  ${runCmd("build")}      ${c.dim("# dist/renderer + dist/main.js + dist/dormer-app.json")}\n  ${runCmd("package")}    ${c.dim("# installers via dormer-bundle")}\n\nRun ${c.bold("npx dormer doctor")} if the window does not open.\n`);
+  return EXIT.ok;
+}