@monster-orange/den 0.4.4 → 0.4.6

package/src/shared/secrets/onepassword.ts

@@ -52,11 +52,34 @@ export class OnePasswordProvider implements SecretsProvider {
     }
   }
 
+  /** Overwrite the field; an item that isn't there yet is created (a Password item). */
   async set(ref: SecretRef, value: string): Promise<void> {
-    const args = ["item", "edit", ref.item];
-    if (ref.vault) args.push("--vault", ref.vault);
-    args.push(`${ref.field}[password]=${value}`);
-    await execFileAsync("op", args, { timeout: this.timeout });
+    const vault = ref.vault ? ["--vault", ref.vault] : [];
+    const field = `${ref.field}[password]=${value}`;
+    try {
+      await execFileAsync("op", ["item", "edit", ref.item, ...vault, field], {
+        timeout: this.timeout,
+      });
+    } catch (err) {
+      try {
+        await execFileAsync(
+          "op",
+          [
+            "item",
+            "create",
+            "--category",
+            "password",
+            "--title",
+            ref.item,
+            ...vault,
+            field,
+          ],
+          { timeout: this.timeout },
+        );
+      } catch {
+        throw err;
+      }
+    }
   }
 
   async preflight(): Promise<PreflightResult> {

package/src/shared/web-owner.ts

@@ -0,0 +1,91 @@
+/**
+ * SEC-2a: the owner's GitHub identity. `<state dir>/web-owner.json`, mode
+ * 0600: `{ v: 1, owner: "github:<numeric id>", login, linkedAt }`. The id
+ * is what sign-in compares; the login is for display only (a login can be
+ * renamed, the id can't). No token is ever stored: the device flow's token
+ * is dropped right after `GET /user`.
+ *
+ * Written by `<cli> web owner link` and Settings › Access; removed by
+ * `web owner unlink`. Re-read whenever it changes on disk.
+ */
+import { randomBytes } from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import { getStateDir } from "./paths.js";
+
+export const WEB_OWNER_FILE = "web-owner.json";
+
+export interface WebOwner {
+  /** `github:<numeric id>`. */
+  owner: `github:${number}`;
+  /** The GitHub login at link time, for display. */
+  login: string;
+  /** ISO time it was linked. */
+  linkedAt: string;
+}
+
+export function webOwnerPath(stateDir: string = getStateDir()): string {
+  return path.join(stateDir, WEB_OWNER_FILE);
+}
+
+const LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+
+/** The linked owner, or null (none, or a file that isn't one). */
+export function readWebOwner(
+  stateDir: string = getStateDir(),
+): WebOwner | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(fs.readFileSync(webOwnerPath(stateDir), "utf-8"));
+  } catch {
+    return null;
+  }
+  const o = raw as Partial<WebOwner> | null;
+  if (
+    !o ||
+    typeof o.owner !== "string" ||
+    !/^github:[1-9][0-9]{0,15}$/.test(o.owner) ||
+    typeof o.login !== "string" ||
+    !LOGIN.test(o.login)
+  )
+    return null;
+  return {
+    owner: o.owner,
+    login: o.login,
+    linkedAt: typeof o.linkedAt === "string" ? o.linkedAt : "",
+  };
+}
+
+/** Link `id` (`login` for display) as the owner: atomic, 0600. */
+export function writeWebOwner(
+  identity: { id: number; login: string },
+  stateDir: string = getStateDir(),
+  now: Date = new Date(),
+): WebOwner {
+  if (!Number.isSafeInteger(identity.id) || identity.id <= 0)
+    throw new Error("a GitHub account id is a positive integer");
+  if (!LOGIN.test(identity.login))
+    throw new Error("that is not a GitHub login");
+  const rec: WebOwner = {
+    owner: `github:${identity.id}`,
+    login: identity.login,
+    linkedAt: now.toISOString(),
+  };
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const file = webOwnerPath(stateDir);
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify({ v: 1, ...rec })}\n`, {
+    mode: 0o600,
+  });
+  fs.renameSync(tmp, file);
+  return rec;
+}
+
+/** Unlink the owner; the one it was, or null when none was linked. */
+export function clearWebOwner(
+  stateDir: string = getStateDir(),
+): WebOwner | null {
+  const was = readWebOwner(stateDir);
+  fs.rmSync(webOwnerPath(stateDir), { force: true });
+  return was;
+}

package/src/shared/web-session.ts

@@ -21,6 +21,7 @@ import { createHash, createHmac, randomBytes, timingSafeEqual } from "crypto";
 import * as fs from "fs";
 import * as path from "path";
 import * as yaml from "yaml";
+import { parseMachineName } from "./cli-command.js";
 import { getStateDir } from "./paths.js";
 
 export const LOGIN_CODE_TTL_MS = 60_000;
@@ -98,6 +99,14 @@ export function checkLoginCode(
   return { ok: true, nonce: m[2], expiresAt };
 }
 
+/** A login code's nonce, from its shape alone (unverified), or null. */
+export function loginCodeNonce(code: string): string | null {
+  const m = /^v1\.([A-Za-z0-9_-]{22})\.[0-9a-z]{1,11}\.[A-Za-z0-9_-]{43}$/.exec(
+    code,
+  );
+  return m ? m[1] : null;
+}
+
 /**
  * Where a sign-in may send the browser: a same-origin relative path, else
  * `/`. `//evil`, `/\evil`, `http://evil`, a control character or a path back
@@ -167,8 +176,30 @@ export interface WebAuthConfig {
    * never the distribution's), and warned about at start.
    */
   plainHttpInDistribution?: string;
+  /**
+   * `web.github_client_id` (SEC-2a): the GitHub App whose device flow signs
+   * the owner in. user.yml over the distribution config; unset: the MO Den
+   * app's (github-app.ts).
+   */
+  githubClientId?: string;
+  /**
+   * `web.edge_unattested` (SEC-2a, user.yml only): what an edge request
+   * whose client Den can't place gets. `signin` (the default): it signs in;
+   * `local`: it is treated as this machine (0.4.4's allow).
+   */
+  edgeUnattested: EdgeUnattested;
+  /** The distribution config's file when it sets `web.edge_unattested`: ignored there. */
+  edgeUnattestedInDistribution?: string;
+  /**
+   * `web.machine_name` (SEC-2a, user.yml only): the name the signed-out
+   * page gives this machine ("runs on <name>"). Unset: the short hostname.
+   */
+  machineName?: string;
 }
 
+/** `web.edge_unattested`'s values. */
+export type EdgeUnattested = "local" | "signin";
+
 function readYaml(file: string): Record<string, unknown> {
   try {
     const v = yaml.parse(fs.readFileSync(file, "utf-8")) as unknown;
@@ -210,6 +241,12 @@ export function ignoredConfigWarning(cfg: WebAuthConfig): string | null {
       `${cfg.ignored.join(", ")}: ignored. A browser session never expires; ` +
         "it ends at sign-out or `web logout`. Remove the key to silence this.",
     );
+  if (cfg.edgeUnattestedInDistribution)
+    lines.push(
+      `web.edge_unattested (${cfg.edgeUnattestedInDistribution}): ignored. ` +
+        "It is a choice for one machine, read only from config/local/user.yml; " +
+        "move it there on the machine that needs it, and remove it here.",
+    );
   if (cfg.plainHttpInDistribution)
     lines.push(
       `web.allow_plain_http_remote (${cfg.plainHttpInDistribution}): ignored. ` +
@@ -241,15 +278,47 @@ export function readWebAuthConfig(
     throw new Error(
       `web.allow_plain_http_remote must be true or false, got ${JSON.stringify(plain)}`,
     );
+  const unattested = user.edge_unattested;
+  if (
+    unattested !== undefined &&
+    unattested !== "local" &&
+    unattested !== "signin"
+  )
+    throw new Error(
+      `web.edge_unattested must be local or signin, got ${JSON.stringify(unattested)}`,
+    );
+  const clientId =
+    clientIdOf(user, "config/local/user.yml") ?? clientIdOf(team, configFile);
+  const machineName = parseMachineName(user.machine_name);
   return {
+    ...(machineName ? { machineName } : {}),
     allowPlainHttpRemote: plain === true,
     ignored,
+    edgeUnattested: unattested ?? "signin",
+    ...(clientId !== undefined ? { githubClientId: clientId } : {}),
     ...(team.allow_plain_http_remote !== undefined
       ? { plainHttpInDistribution: configFile }
       : {}),
+    ...(team.edge_unattested !== undefined
+      ? { edgeUnattestedInDistribution: configFile }
+      : {}),
   };
 }
 
+/** `web.github_client_id` in one file: a GitHub App client id, or unset. */
+function clientIdOf(
+  w: Record<string, unknown>,
+  file: string,
+): string | undefined {
+  const v = w.github_client_id;
+  if (v === undefined || v === null) return undefined;
+  if (typeof v !== "string" || !/^[A-Za-z0-9._-]{0,64}$/.test(v.trim()))
+    throw new Error(
+      `web.github_client_id (${file}) must be a GitHub App client id (letters, digits, dots, dashes), got ${JSON.stringify(v)}`,
+    );
+  return v.trim();
+}
+
 // ── The session store ──────────────────────────────────────────────────────
 
 export interface SessionRecord {
@@ -260,6 +329,14 @@ export interface SessionRecord {
   csrf: string;
   /** The Host it was issued on. */
   host: string;
+  /** SEC-2a: how it signed in: a GitHub sign-in, or a one-time link (pairing). Unset: a link (before 0.4.5). */
+  via?: "github" | "link" | "code";
+  /** SEC-2a: the client's address when Den could attest it. */
+  client?: string;
+  /** SEC-2a: a GitHub sign-in's login (the chip's "@login"). */
+  login?: string;
+  /** SEC-2a: not yet greeted ("This device is signed in…", once). */
+  welcome?: true;
 }
 
 interface StoreFile {
@@ -384,7 +461,13 @@ export class WebSessionStore {
   }
 
   /** A new session: its id (the cookie's value) and record. */
-  create(meta: { userAgent?: string; host?: string }): {
+  create(meta: {
+    userAgent?: string;
+    host?: string;
+    via?: "github" | "link" | "code";
+    client?: string;
+    login?: string;
+  }): {
     id: string;
     session: SessionView;
   } {
@@ -400,6 +483,10 @@ export class WebSessionStore {
       host: String(meta.host ?? "")
         .toLowerCase()
         .slice(0, 255),
+      ...(meta.via ? { via: meta.via } : {}),
+      ...(meta.client ? { client: String(meta.client).slice(0, 64) } : {}),
+      ...(meta.login ? { login: String(meta.login).slice(0, 64) } : {}),
+      welcome: true,
     };
     const data = structuredClone(this.load());
     this.prune(data, now);
@@ -438,6 +525,19 @@ export class WebSessionStore {
     }
   }
 
+  /**
+   * Whether this session is yet to be greeted, once: true the first time
+   * after its sign-in, and never again (the flag is cleared).
+   */
+  takeWelcome(key: string): boolean {
+    const data = this.load();
+    if (!data.sessions[key]?.welcome) return false;
+    const next = structuredClone(data);
+    delete next.sessions[key].welcome;
+    this.trySave(next);
+    return true;
+  }
+
   /** Every session, newest first. */
   list(): SessionView[] {
     return Object.entries(this.load().sessions)
@@ -489,3 +589,37 @@ export class WebSessionStore {
 export function sessionIdPrefix(key: string): string {
   return key.slice(0, 8);
 }
+
+/**
+ * A linked device's name from its User-Agent (SEC-2a: "Chrome on macOS"),
+ * or "Unknown browser".
+ */
+export function deviceName(userAgent: string | undefined): string {
+  const ua = String(userAgent ?? "");
+  const browser = /Edg\//.test(ua)
+    ? "Edge"
+    : /Firefox\//.test(ua)
+      ? "Firefox"
+      : /(Chrome|CriOS)\//.test(ua)
+        ? "Chrome"
+        : /Safari\//.test(ua)
+          ? "Safari"
+          : /curl\//.test(ua)
+            ? "curl"
+            : null;
+  const os = /iPhone|iPad|iPod/.test(ua)
+    ? "iOS"
+    : /Android/.test(ua)
+      ? "Android"
+      : /Mac OS X|Macintosh/.test(ua)
+        ? "macOS"
+        : /Windows/.test(ua)
+          ? "Windows"
+          : /CrOS/.test(ua)
+            ? "ChromeOS"
+            : /Linux/.test(ua)
+              ? "Linux"
+              : null;
+  if (browser && os) return `${browser} on ${os}`;
+  return browser ?? (os ? `A browser on ${os}` : "Unknown browser");
+}

package/src/ui/cli/create-main.ts

@@ -6,4 +6,4 @@
 import { runCreate } from "./create.js";
 
 const cwd = process.env.DEN_INVOKE_CWD?.trim() || process.cwd();
-process.exit(runCreate(process.argv.slice(2), cwd));
+process.exit(await runCreate(process.argv.slice(2), cwd));

package/src/ui/cli/create.ts

@@ -15,7 +15,10 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { ENGINE_PACKAGE, getEngineRoot } from "../../shared/paths.js";
 import { profileFrom } from "../../shared/profile.js";
+import { parse as parseYaml } from "yaml";
 import { plural } from "../../shared/plural.js";
+import { DEFAULT_PORT } from "../../shared/constants.js";
+import { pickFreePort } from "../../shared/port-pick.js";
 
 export interface CreateOptions {
   /** Product name: lower-case `[a-z][a-z0-9-]*`. */
@@ -296,18 +299,34 @@ export function writeDistribution(dir: string, opts: CreateOptions): string[] {
 
 export interface ParsedCreateArgs extends Omit<CreateOptions, "denVersion"> {
   dir: string;
+  /** `--yes`: never prompt (create never does; accepted so agents can say so). */
+  yes: boolean;
+  /** `--json`: print one JSON object on stdout, nothing else. */
+  json: boolean;
+  /** `--port <n>`: the web UI's port, taken as given (no search). */
+  port?: number;
 }
 
 const CREATE_USAGE =
-  "usage: den create <name> [dir] [--title <title>] [--cli <cli>] [--env-prefix <PREFIX>]";
+  "usage: den create <name> [dir] [--title <title>] [--cli <cli>] [--env-prefix <PREFIX>] [--port <n>] [--yes] [--json]";
 
 /** Parse `create` argv (after the word `create`). `cwd` resolves the dir. */
 export function parseCreateArgs(argv: string[], cwd: string): ParsedCreateArgs {
   const positional: string[] = [];
   const flags: Record<string, string> = {};
+  let yes = false;
+  let json = false;
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    const m = /^--(title|cli|env-prefix)(?:=(.*))?$/.exec(a);
+    if (a === "--yes" || a === "-y") {
+      yes = true;
+      continue;
+    }
+    if (a === "--json") {
+      json = true;
+      continue;
+    }
+    const m = /^--(title|cli|env-prefix|port)(?:=(.*))?$/.exec(a);
     if (m) {
       const value = m[2] ?? argv[++i];
       if (value === undefined)
@@ -326,9 +345,19 @@ export function parseCreateArgs(argv: string[], cwd: string): ParsedCreateArgs {
     title: flags.title,
     cli: flags.cli,
     envPrefix: flags["env-prefix"],
+    yes,
+    json,
+    ...(flags.port !== undefined ? { port: parsePortFlag(flags.port) } : {}),
   };
 }
 
+function parsePortFlag(v: string): number {
+  const n = Number(v);
+  if (!/^\d+$/.test(v) || n < 1 || n > 65535)
+    throw new Error(`--port must be a port number\n${CREATE_USAGE}`);
+  return n;
+}
+
 export const CREATE_HELP = `${CREATE_USAGE}
 
 Scaffold a new Den distribution in [dir] (default ./<name>):
@@ -338,41 +367,245 @@ config/environments/local.json, manifests/ and tests/pillars/.
 
   --title <title>        brand name shown to people (default: <Name>)
   --cli <cli>            the command people type (default: <name>)
-  --env-prefix <PREFIX>  env-var prefix (default: <NAME>)`;
+  --env-prefix <PREFIX>  env-var prefix (default: <NAME>)
+  --port <n>             the web UI's port (default: ${DEFAULT_PORT}, or the next
+                         free one above it when that is in use)
+  --yes, -y              never prompt (create never does; for agents)
+  --json                 print one JSON object: { ok, dir, cli, existed, port, next }
+
+Safe to re-run: a [dir] that already holds this distribution answers ok
+(existed: true) and writes nothing.`;
+
+/**
+ * Whether `dir` already holds the distribution `create` would make: its
+ * den.yml names this product (and this cli, when one was given).
+ */
+export function existingDistribution(
+  dir: string,
+  opts: { name: string; cli?: string },
+): boolean {
+  let text: string;
+  try {
+    text = fs.readFileSync(path.join(dir, "den.yml"), "utf-8");
+  } catch {
+    return false;
+  }
+  const name = /^\s+name:\s*(\S+)\s*$/m.exec(text)?.[1];
+  if (name !== opts.name) return false;
+  const cli = /^\s+cli:\s*(\S+)\s*$/m.exec(text)?.[1] ?? opts.name;
+  return cli === (opts.cli ?? opts.name);
+}
+
+/** What `create --json` prints. */
+export interface CreateJson {
+  ok: boolean;
+  dir?: string;
+  cli?: string;
+  existed?: boolean;
+  files?: number;
+  /** The web UI's port for this distribution. */
+  port?: number;
+  /** Set when DEFAULT_PORT was in use and `port` was picked instead. */
+  portPicked?: { wanted: number; file: string };
+  next?: string[];
+  error?: string;
+  fix?: string;
+  ask?: string;
+}
+
+function cdPathFor(cwd: string, dir: string): string {
+  // Relative only when the new directory is under the caller's cwd; a
+  // path that climbs out (../../..) is harder to read than the absolute one.
+  const rel = path.relative(cwd, dir);
+  return rel === ""
+    ? "."
+    : rel.startsWith("..") || path.isAbsolute(rel)
+      ? dir
+      : rel;
+}
+
+/** The web port a distribution at `dir` is set to (user, then team, config). */
+export function configuredWebPort(dir: string, name: string): number {
+  for (const rel of [
+    path.join("config", "local", "user.yml"),
+    path.join("config", `${name}.yml`),
+  ]) {
+    try {
+      const doc = parseYaml(fs.readFileSync(path.join(dir, rel), "utf-8")) as {
+        web?: { port?: unknown };
+      } | null;
+      const p = doc?.web?.port;
+      if (typeof p === "number" && Number.isInteger(p)) return p;
+    } catch {
+      /* absent or unreadable: next layer */
+    }
+  }
+  return DEFAULT_PORT;
+}
+
+export interface CreatePortOptions {
+  /**
+   * The port to start from: DEFAULT_PORT unless a test passes a port of its
+   * own (so no test probes the real default). The CLI reads it from
+   * DEN_WEB_PORT_START.
+   */
+  startPort?: number;
+  inUse?: (port: number) => Promise<boolean>;
+}
 
-/** Run `create` end to end; returns the process exit code. */
-export function runCreate(argv: string[], cwd: string): number {
+/** DEN_WEB_PORT_START, for tests and CI: never probe the real default. */
+export function startPortFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): number | undefined {
+  const v = env.DEN_WEB_PORT_START?.trim();
+  if (!v) return undefined;
+  const n = Number(v);
+  return Number.isInteger(n) && n > 0 && n < 65536 ? n : undefined;
+}
+
+/**
+ * `create` as data: never prompts, never throws. A dir that already holds
+ * this distribution is ok (existed); any other non-empty dir is an error
+ * that names a fix.
+ *
+ * The web port: `--port` as given; else the default when it is free, else
+ * the next free port above it (never a reserved Den port), written to the
+ * new distribution's config/local/user.yml as `web.port`. Checking a port
+ * sends nothing to whoever holds it (port-pick.ts). A re-run reports the
+ * port the distribution is set to and picks nothing.
+ */
+export async function createResult(
+  args: ParsedCreateArgs,
+  cwd: string,
+  denVersion: string = runningDenVersion(),
+  portOpts: CreatePortOptions = {},
+): Promise<CreateJson> {
+  const cli = args.cli ?? args.name;
+  const next = (dir: string): string[] => [
+    `cd ${cdPathFor(cwd, dir)}`,
+    "npm install",
+    `./bin/${cli} repo add <path|git-url> --json`,
+  ];
+  try {
+    validateCreateOptions({ ...args, denVersion });
+    if (existingDistribution(args.dir, args))
+      return {
+        ok: true,
+        dir: args.dir,
+        cli,
+        existed: true,
+        port: configuredWebPort(args.dir, args.name),
+        next: next(args.dir),
+      };
+    // Refuse a busy dir before looking for a port.
+    if (
+      fs.existsSync(args.dir) &&
+      fs.statSync(args.dir).isDirectory() &&
+      fs.readdirSync(args.dir).length > 0
+    )
+      writeDistribution(args.dir, { ...args, denVersion }); // throws "not empty"
+    const wanted = args.port ?? portOpts.startPort ?? DEFAULT_PORT;
+    const port =
+      args.port ??
+      (await pickFreePort({ start: wanted, inUse: portOpts.inUse })) ??
+      wanted;
+    const written = writeDistribution(args.dir, { ...args, denVersion });
+    let portPicked: CreateJson["portPicked"];
+    // Written when the port differs from what the distribution would use
+    // anyway (an explicit --port that isn't the default, or a picked one).
+    if (port !== (args.port !== undefined ? DEFAULT_PORT : wanted)) {
+      const rel = path.join("config", "local", "user.yml");
+      const file = path.join(args.dir, rel);
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(
+        file,
+        `# Yours, not the team's (gitignored). Set by create: ${
+          args.port !== undefined
+            ? "--port"
+            : `port ${wanted} was in use on this machine`
+        }.\nweb:\n  port: ${port}\n`,
+        { encoding: "utf-8", flag: "wx" },
+      );
+      written.push(rel);
+      if (args.port === undefined) portPicked = { wanted, file: rel };
+    }
+    return {
+      ok: true,
+      dir: args.dir,
+      cli,
+      existed: false,
+      files: written.length,
+      port,
+      ...(portPicked ? { portPicked } : {}),
+      next: next(args.dir),
+    };
+  } catch (e) {
+    const error = (e as Error).message;
+    if (/is not empty/.test(error))
+      return {
+        ok: false,
+        error,
+        fix: `npx ${ENGINE_PACKAGE} create ${args.name} ${path.join(path.dirname(args.dir), `${args.name}-den`)} --yes --json`,
+        ask: `${args.dir} already has files that are not a ${args.name} distribution. Which new or empty folder should the distribution go in?`,
+      };
+    return {
+      ok: false,
+      error,
+      ask: "Which name should the distribution have? Lower-case letters, digits and dashes, starting with a letter.",
+    };
+  }
+}
+
+/** Run `create` end to end; resolves to the process exit code. */
+export async function runCreate(
+  argv: string[],
+  cwd: string,
+  portOpts: CreatePortOptions = { startPort: startPortFromEnv() },
+): Promise<number> {
   if (argv.includes("-h") || argv.includes("--help")) {
     console.log(CREATE_HELP);
     return 0;
   }
+  const json = argv.includes("--json");
+  let args: ParsedCreateArgs;
   try {
-    const args = parseCreateArgs(argv, cwd);
-    const written = writeDistribution(args.dir, {
-      ...args,
-      denVersion: runningDenVersion(),
-    });
-    const cli = args.cli ?? args.name;
-    // Relative only when the new directory is under the caller's cwd; a
-    // path that climbs out (../../..) is harder to read than the absolute one.
-    const rel = path.relative(cwd, args.dir);
-    const cdPath =
-      rel === ""
-        ? "."
-        : rel.startsWith("..") || path.isAbsolute(rel)
-          ? args.dir
-          : rel;
-    console.log(
-      `Created ${args.name} in ${args.dir} (${plural(written.length, "file")}).`,
-    );
-    console.log("");
-    console.log("Next:");
-    console.log(`  cd ${cdPath}`);
-    console.log("  npm install");
-    console.log(`  ./bin/${cli} --help`);
-    return 0;
+    args = parseCreateArgs(argv, cwd);
   } catch (e) {
-    console.error(`create: ${(e as Error).message}`);
+    if (json) {
+      console.log(
+        JSON.stringify({
+          ok: false,
+          error: (e as Error).message.split("\n")[0],
+          fix: `npx ${ENGINE_PACKAGE} create <name> [dir] --yes --json`,
+        } satisfies CreateJson),
+      );
+    } else console.error(`create: ${(e as Error).message}`);
+    return 1;
+  }
+  const r = await createResult(args, cwd, runningDenVersion(), portOpts);
+  if (json) {
+    console.log(JSON.stringify(r));
+    return r.ok ? 0 : 1;
+  }
+  if (!r.ok) {
+    console.error(`create: ${r.error}`);
     return 1;
   }
+  const dir = r.dir ?? args.dir;
+  console.log(
+    r.existed
+      ? `${args.name} is already in ${dir}: nothing to do.`
+      : `Created ${args.name} in ${dir} (${plural(r.files ?? 0, "file")}).`,
+  );
+  console.log(
+    r.portPicked
+      ? `Web UI port: ${r.port} (${r.portPicked.wanted} is in use here; set in ${r.portPicked.file}).`
+      : `Web UI port: ${r.port}.`,
+  );
+  console.log("");
+  console.log("Next:");
+  console.log(`  cd ${cdPathFor(cwd, dir)}`);
+  console.log("  npm install");
+  console.log(`  ./bin/${r.cli} --help`);
+  return 0;
 }