@dormer/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,195 @@
-# Temporary Holding Version
+# @dormer/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `dormer` command: scaffold, run, build and package Dormer apps (Node.js backend + system
+WebView renderer). TypeScript executed directly by Node's type stripping (Node 22.18+/24; on Node
+22.6–22.17 the shim re-executes itself with `--experimental-strip-types`). Dependencies: `esbuild`
+(backend bundling); `vite` is resolved from the user's project so their plugins share the instance.
+
+```
+dormer create <dir> --template vanilla|react|vue|svelte [--pm npm] [--link] [--force]
+dormer dev     [--port <n>] [--host <name>] [--pass-env <VAR>]...
+dormer build   [--minify] [--no-sourcemap] [--quiet]
+dormer package [--target deb|rpm|appimage|app|dmg|nsis|msi]... [--out <dir>] [--skip-build] [--dry-run]
+dormer doctor
+```
+
+Every command has `--help`. Errors carry a fix hint; `DORMER_CLI_DEBUG=1` adds stack traces.
+
+## Installing
+
+`npm create dormer my-app -- --template react` (package `create-dormer`) scaffolds an app and installs
+`@dormer/cli`, which carries the compiled CLI (`dist/cli.js`, built by `build.mjs` on `prepare`; Node does
+not type-strip `.ts` under `node_modules`) and the templates (copied in by `prepack`). The native binaries
+come as optional dependencies `@dormer/host-<platform>-<arch>` and `@dormer/bundle-<platform>-<arch>`,
+generated by `scripts/npm-platform-packages.mjs`; `scripts/publish-npm.sh` publishes everything in
+dependency order (rehearse against a local registry with `--registry`).
+
+## App layout and `dormer.config.json`
+
+```
+my-app/
+  dormer.config.json
+  src/main.ts            backend (Node sidecar), uses @dormer/api
+  renderer/              Vite project (index.html, vite.config.ts with @dormer/vite-plugin, src/)
+  dist/                  owned by `dormer build`: renderer/, main.js(.map), dormer.config.json,
+                         dormer-app.json, bundle.json (after `dormer package`)
+  .dormer/dev/main.js    backend bundle used by `dormer dev`
+```
+
+```jsonc
+{
+  "name": "my-app",                      // required: app and package name
+  "identifier": "com.example.my-app",    // required: reverse-DNS bundle identifier
+  "version": "0.1.0",                    // required: semver
+  "description": "…",
+  "entry": "src/main.ts",                // backend entry (default)
+  "renderer": "renderer",                // Vite root (default)
+  "windows": { "main": { "capabilities": ["app:default"] } },   // per-window capability sets (ADR-0006)
+  "firstWindow": { "label": "main", "width": 960, "height": 640, "backgroundColor": "auto" },  // host creates it before Node is ready (RISKS T22); "auto" = system light/dark
+  "csp": { "connectSrc": ["https://api.example.com"], "scriptSrc": ["'wasm-unsafe-eval'"], "workerSrc": ["blob:"] },  // page-side network, WebAssembly, blob workers: off by default
+  "node": { "version": "24", "binary": "/opt/node24/bin/node",  // version pin; binary used by `package`
+            "icu": "small", "compileCache": true },             // icu "full" ships locale data for a small-icu Dormer Node (~31 MB); compile cache: default on when packaged
+  "backend": { "external": ["some-native-addon"] },             // extra bundling externals
+  "dev": { "port": 5173, "passEnv": ["MY_API_KEY"] },
+  "bundle": {
+    "targets": ["deb", "appimage"],
+    "icons": ["icons/icon.png"],
+    "sourceMaps": false,                                        // ship *.map from dist/ (default false)
+    "linux": { "depends": ["libwebkit2gtk-4.1-0", "libgtk-3-0"] },
+    "macos": { "entitlements": "entitlements.plist", "signingIdentity": "Developer ID Application: …", "minimumSystemVersion": "13.0" },
+    "windows": { "signCommand": "signtool sign /fd sha256 /a %1" }
+  }
+}
+```
+
+Commands run from any directory inside the app (the nearest `dormer.config.json` wins). Worked answers to
+"how do I…" questions (caching, server-rendered pages, which web APIs a page gets) live in `docs/RECIPES.md`
+and the `examples/*-probe` and `examples/cache-recipe` directories, each with a `run.sh` that proves them.
+
+## Commands
+
+### `create`
+
+Copies `templates/<name>` (the monorepo's `templates/` directory, or the copy shipped inside the
+package), substitutes `{{name}}`/`{{identifier}}`, renames `_gitignore` and prints next steps.
+Templates depend on `@dormer/api`, `@dormer/renderer`, `@dormer/vite-plugin`, `@dormer/cli` at
+`0.1.0`. `--link` (monorepo only) rewrites those to `file:` paths into the checkout, including the
+transitive `@dormer/node-runtime` and `@dormer/ipc`, so a template installs and builds without
+anything published. Outside the monorepo, `website/public/bootstrap.sh` (served at
+https://dormer-docs.vercel.app/bootstrap.sh) performs the checkout, host build and `create --link` in one
+command.
+
+### `dev`
+
+1. Picks a free port (preferred: `--port`, `dev.port`, 5173) and starts Vite programmatically on
+   `renderer/` with `strictPort`, so the URL handed to the host is exactly the one Vite serves.
+2. Bundles the backend with esbuild in watch mode to `.dormer/dev/main.js`.
+3. Launches `dormer-host --app-dir <app root> --entry .dormer/dev/main.js --node <current node>
+   --name <name> --dev --dev-url <vite url> --pass-env DORMER_DEV_URL --pass-env DORMER_APP_VERSION …`.
+   The backend reads `DORMER_DEV_URL` and calls `win.loadURL(devUrl)` (templates do this; in
+   production they call `win.loadApp("index.html")`).
+4. When the backend bundle changes, the host is restarted. Closing the last window or Ctrl-C stops
+   Vite, the watcher and the host. Extra variables reach the sidecar through `--pass-env` / `dev.passEnv`;
+   `DORMER_SELFTEST` is forwarded automatically when set.
+
+### `build`
+
+`vite build` for the renderer → `dist/renderer`; esbuild for the backend → `dist/main.js` (+ map,
+`--minify` optional); copies `dormer.config.json`; writes `dist/dormer-app.json`:
+
+```json
+{ "manifestVersion": 1, "name": "…", "identifier": "…", "version": "…", "description": "…",
+  "entry": "main.js", "assets": "renderer", "node": { "version": "24" },
+  "externals": [], "windows": { "main": { "capabilities": ["app:default"] } },
+  "builtAt": "…", "cli": "0.1.0" }
+```
+
+Backend bundling rules (see `src/backend.ts`): one ESM file, `platform: node`, target `node22`.
+**`@dormer/*` packages are bundled** (they are published as TypeScript sources, so bundling is what
+makes the output runnable on plain Node without type stripping). Left external and listed in
+`externals`: `node:*` builtins, `*.node` files, packages that look like native addons (`gypfile`,
+`binary`, `napi` fields or a dependency on `node-gyp-build`, `bindings`, `node-pre-gyp`,
+`prebuild-install`, …) and names in `backend.external`. A `createRequire` banner lets bundled
+CommonJS `require()` calls (for example msgpackr's optional native accelerator) resolve from
+`node_modules` next to the output at runtime; when such a package is absent the libraries fall
+back to pure JavaScript.
+
+### `package`
+
+Builds (unless `--skip-build`), writes `dist/bundle.json`, then runs
+`dormer-bundle --config dist/bundle.json --out <dir>` (the Rust tool from `tools/bundler`, found via
+`DORMER_BUNDLE_BIN`, the cargo `target/{release,debug}` directory, then `PATH`). Missing binary:
+instructions are printed and the exit code is 2; `--dry-run` only writes the file.
+
+Interface of `bundle.json` (all paths absolute except `entry`, which is relative to `appDir`):
+
+```json
+{
+  "name": "my-app", "identifier": "com.example.my-app", "version": "0.1.0", "description": "…",
+  "appDir": "/abs/my-app/dist", "entry": "main.js",
+  "hostBinary": "/abs/dormer-host", "nodeBinary": "/abs/node",
+  "targets": ["deb", "appimage"],
+  "icons": ["/abs/my-app/icons/icon.png"],
+  "linux": { "depends": ["libwebkit2gtk-4.1-0", "libgtk-3-0"] },
+  "macos": { "entitlements": null, "signingIdentity": null, "minimumSystemVersion": "13.0" },
+  "windows": { "signCommand": null }
+}
+```
+
+`appDir` contains `renderer/` (served as `dormer://app/`), `main.js`, `dormer.config.json` and
+`dormer-app.json` (whose `externals` lists native packages the bundler must copy from
+`node_modules`). Default targets: Linux `deb, appimage`; macOS `app, dmg`; Windows `nsis`.
+`nodeBinary` defaults to the Node running the CLI (`node.binary` / `DORMER_NODE_BIN` override); a
+warning is printed when its major differs from `node.version`.
+
+### `doctor`
+
+Node ≥ 22; host binary resolution; Linux: `pkg-config --exists webkit2gtk-4.1` or
+`ldconfig -p | grep libwebkit2gtk-4.1`, session D-Bus, display, NVIDIA hint
+(`WEBKIT_DISABLE_DMABUF_RENDERER=1`), headless tools; macOS: Xcode CLT, OS version; Windows:
+WebView2 Evergreen runtime registry key (`…\EdgeUpdate\Clients\{F3017226-…}\pv`). macOS and Windows
+checks are **unverified** on those platforms. Prints the capability summary of `dormer.config.json`
+when run inside an app. Exit 1 if any check fails.
+
+## Host binary resolution
+
+1. `DORMER_HOST_BIN`
+2. `<cargo workspace>/target/{release,debug}/dormer-host`, searching for `Cargo.toml` upward from
+   the app root and from the CLI's own location (`CARGO_TARGET_DIR` honoured)
+3. `node_modules/@dormer/host-<platform>-<arch>/bin/dormer-host` — the planned prebuilt package
+   (downloaded with checksums at install time; not published yet)
+
+## Exit codes
+
+| code | meaning |
+|---|---|
+| 0 | success |
+| 1 | build failed, host/bundler exited non-zero, doctor found a failing check |
+| 2 | required external binary missing (`dormer-host`, `dormer-bundle`) |
+| 64 | usage error |
+| 65 | `dormer.config.json` missing or invalid |
+| 66 | required input missing (template, entry, renderer directory, Node binary) |
+
+## Limitations
+
+* **Dev restart model.** A backend change restarts the whole host process: windows are recreated
+  and renderer state is lost (Vite HMR itself keeps working between restarts). Restarting only the
+  Node sidecar while keeping windows needs host support (a "reload sidecar" control or restart-on-
+  exit with the same entry), which is on the Milestone 2/7 list.
+* The templates still call `loadURL(process.env.DORMER_DEV_URL)` in dev although the host redirects
+  `loadApp()` to `--dev-url` itself; with a `firstWindow` the page is already loading and both calls
+  are no-ops, so the convention is harmless but redundant.
+* `dormer package` ships the Node that runs the CLI unless `node.binary` (or `DORMER_NODE_BIN`) points
+  at another build, such as a small-icu Dormer build from `tools/node-build`; a published Dormer Node
+  dist that the CLI fetches by itself is not wired up yet.
+* **Server-rendered pages (SSR)** work at the runtime level: run the framework's Node server inside the
+  backend, `win.loadURL("http://127.0.0.1:<port>/")`, and declare the origin in a capability
+  (`"origins": ["local", "http://127.0.0.1:*"]`); the page keeps the full bridge (`examples/ssr-probe`,
+  verified 2026-11-08 with plain HTML and with React 19 `renderToPipeableStream` + `hydrateRoot`). `dormer build` only knows the Vite single-page renderer, so a server build has to
+  be placed next to `dist/main.js` by the app's own build step.
+
+## Tests
+
+`npm test -w @dormer/cli` runs unit tests. `npm run test:templates` (root) runs
+`test/e2e-linux.sh`: creates each template with `--link`, installs, builds, runs the built app
+headless (Xvfb + session D-Bus) with `DORMER_SELFTEST=1`, and exercises `dormer dev` once.

package/bin/dormer.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Entry shim: the CLI is TypeScript executed by Node's built-in type stripping (Node 22.18+ / 24+).
+// On Node 22.6–22.17 type stripping exists behind a flag, so re-execute with it once.
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const [major, minor] = process.versions.node.split(".").map(Number);
+if (major < 22 || (major === 22 && minor < 6)) {
+  console.error(`dormer needs Node.js 22.6 or newer (22.18+/24 recommended); found ${process.version}`);
+  process.exit(1);
+}
+// A published copy (installed under node_modules) runs the compiled CLI, dist/cli.js (see build.mjs); a
+// source checkout keeps running src/cli.ts so edits take effect without a rebuild.
+import { existsSync } from "node:fs";
+const dist = new URL("../dist/cli.js", import.meta.url);
+const installed = /[\\/]node_modules[\\/]/.test(fileURLToPath(import.meta.url));
+if (installed && existsSync(dist)) { await import(dist.href); }
+else {
+if (!process.features?.typescript && !process.env.DORMER_CLI_REEXEC) {
+  const r = spawnSync(process.execPath, ["--experimental-strip-types", "--no-warnings", fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+    stdio: "inherit", env: { ...process.env, DORMER_CLI_REEXEC: "1" },
+  });
+  process.exit(r.status ?? 1);
+}
+await import("../src/cli.ts");
+}