@cosmicdrift/kumiko-cli 0.2.367 → 0.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cosmicdrift/kumiko-cli",
-  "version": "0.2.367",
-  "description": "Standalone CLI for scaffolding Kumiko apps. `bunx @cosmicdrift/kumiko-cli new app <name>` produces a runnable workspace; `add feature <name>` mounts a feature automatically.",
+  "version": "0.3.0",
+  "description": "CLI for Kumiko apps. `bunx @cosmicdrift/kumiko-cli new app <name>` scaffolds a runnable workspace; `add feature <name>` mounts a feature; `agent lint`, `project` and `consumer` operate on an existing app.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
   "repository": {
@@ -24,10 +24,16 @@
     ".": {
       "types": "./src/index.ts",
       "default": "./src/index.ts"
+    },
+    "./commands": {
+      "types": "./src/commands/index.ts",
+      "default": "./src/commands/index.ts"
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dev-server": "0.243.4"
+    "@cosmicdrift/kumiko-bundled-features": "0.245.0",
+    "@cosmicdrift/kumiko-framework": "0.245.0",
+    "@cosmicdrift/kumiko-dev-server": "0.245.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -36,6 +42,7 @@
   "files": [
     "bin",
     "src",
+    "!src/**/__tests__/**",
     "README.md",
     "LICENSE"
   ]

package/src/commands/agent.ts

@@ -0,0 +1,57 @@
+import { join } from "node:path";
+import type { CliCommand } from "./types";
+
+const LINT_SUBCOMMAND = "lint";
+
+export const agentCommand: CliCommand = {
+  id: "agent",
+  description: "AI-agent tooling (lint)",
+  help: "Reads kumiko.config.ts in cwd and reports handler definitions the AI\nagent can't describe (exposed to the agent without a usable description).\n\nSubcommands:\n  lint                  Report AI-agent-doc gaps in the current config\n",
+  run: async (ctx) => {
+    const sub = ctx.argv[0];
+    if (sub !== LINT_SUBCOMMAND) {
+      ctx.out.err("");
+      ctx.out.err(`  Usage: kumiko agent <${LINT_SUBCOMMAND}>`);
+      ctx.out.err("");
+      return 1;
+    }
+
+    const configPath = join(ctx.cwd, "kumiko.config.ts");
+    if (!(await Bun.file(configPath).exists())) {
+      ctx.out.err("");
+      ctx.out.err(`  kumiko.config.ts not found at: ${configPath}`);
+      ctx.out.err("");
+      ctx.out.err("  Create a file that exports your features:");
+      ctx.out.err("    // kumiko.config.ts");
+      ctx.out.err('    import { myFeature } from "./src/features/my-feature";');
+      ctx.out.err("    export default { features: [myFeature] };");
+      ctx.out.err("");
+      return 1;
+    }
+
+    const config = (await import(configPath)).default as {
+      features: readonly import("@cosmicdrift/kumiko-framework/engine").FeatureDefinition[];
+    };
+    const { findAgentDocGaps, formatAgentDocGap } = await import(
+      "@cosmicdrift/kumiko-bundled-features/agent-tools"
+    );
+
+    const gaps = findAgentDocGaps(config.features);
+
+    if (gaps.length === 0) {
+      ctx.out.log("");
+      ctx.out.log("  ✓ No AI-agent doc gaps found.");
+      ctx.out.log("");
+      return 0;
+    }
+
+    ctx.out.log("");
+    ctx.out.log(`  ${gaps.length} AI-agent doc gap${gaps.length === 1 ? "" : "s"} found:`);
+    ctx.out.log("");
+    for (const gap of gaps) {
+      ctx.out.log(`    ${formatAgentDocGap(gap)}`);
+    }
+    ctx.out.log("");
+    return 1;
+  },
+};

package/src/commands/consumer.ts

@@ -0,0 +1,222 @@
+import { join } from "node:path";
+import type { CliCommand, CliCommandContext } from "./types";
+
+export const consumerCommand: CliCommand = {
+  id: "consumer",
+  description: "Manage event consumers (list | status | restart | disable | enable | skip)",
+  help: "Subcommands:\n  list                 List all consumers and their state\n  status <name>        Show detail state for one consumer\n  restart <name>       Release lock and retry\n  disable <name>       Pause the consumer\n  enable <name>        Reactivate\n  skip <name>          Skip the currently-stuck event\n",
+  run: async (ctx) => {
+    const sub = ctx.argv[0];
+    const arg = ctx.argv[1];
+
+    const configPath = join(ctx.cwd, "kumiko.config.ts");
+    if (!(await Bun.file(configPath).exists())) {
+      ctx.out.err("");
+      ctx.out.err(`  kumiko.config.ts not found at: ${configPath}`);
+      ctx.out.err("");
+      return 1;
+    }
+
+    const databaseUrl = process.env["DATABASE_URL"];
+    if (!databaseUrl) {
+      ctx.out.err("");
+      ctx.out.err("  DATABASE_URL not set.");
+      ctx.out.err("");
+      return 1;
+    }
+
+    const config = (await import(configPath)).default as {
+      features: readonly import("@cosmicdrift/kumiko-framework/engine").FeatureDefinition[];
+    };
+    const { createRegistry } = await import("@cosmicdrift/kumiko-framework/engine");
+    const { createDbConnection } = await import("@cosmicdrift/kumiko-framework/db");
+    const {
+      createEventConsumerStateTable,
+      disableConsumer,
+      enableConsumer,
+      getConsumerState,
+      listConsumersWithState,
+      restartConsumer,
+      skipPoisonEvent,
+      SEARCH_CONSUMER_NAME,
+      SSE_BROADCAST_CONSUMER_NAME,
+    } = await import("@cosmicdrift/kumiko-framework/pipeline");
+
+    const registry = createRegistry(config.features);
+    const { db, close } = createDbConnection(databaseUrl);
+    await createEventConsumerStateTable(db);
+
+    const registeredConsumerNames = [
+      SSE_BROADCAST_CONSUMER_NAME,
+      SEARCH_CONSUMER_NAME,
+      ...registry.getAllMultiStreamProjections().keys(),
+    ];
+
+    const printOutcome = (prefix: string, state: { name: string; status: string }): void => {
+      ctx.out.log("");
+      ctx.out.log(`  ✓ ${prefix} ${state.name} → ${state.status}`);
+      ctx.out.log("");
+    };
+
+    try {
+      switch (sub) {
+        case "list":
+          return await listConsumers(ctx, db, registeredConsumerNames, listConsumersWithState);
+        case "status":
+          return await showConsumerStatus(ctx, db, arg, registeredConsumerNames, getConsumerState);
+        case "restart":
+          return await restartOne(ctx, db, arg, restartConsumer, printOutcome);
+        case "disable":
+          return await disableOne(ctx, db, arg, disableConsumer, printOutcome);
+        case "enable":
+          return await enableOne(ctx, db, arg, enableConsumer, printOutcome);
+        case "skip":
+          return await skipOne(ctx, db, arg, skipPoisonEvent, printOutcome);
+        default:
+          ctx.out.log("");
+          ctx.out.log(
+            "  Usage: kumiko consumer <list | status | restart | disable | enable | skip> <name>",
+          );
+          ctx.out.log("");
+          return 1;
+      }
+    } catch (e) {
+      ctx.out.err("");
+      ctx.out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
+      ctx.out.err("");
+      return 1;
+    } finally {
+      await close();
+    }
+  },
+};
+
+function usage(ctx: CliCommandContext, sub: string): number {
+  ctx.out.err("");
+  ctx.out.err(`  Usage: kumiko consumer ${sub} <consumer-name>`);
+  ctx.out.err("");
+  return 1;
+}
+
+async function listConsumers(
+  ctx: CliCommandContext,
+  db: import("@cosmicdrift/kumiko-framework/db").DbConnection,
+  registeredConsumerNames: readonly string[],
+  listConsumersWithState: typeof import("@cosmicdrift/kumiko-framework/pipeline").listConsumersWithState,
+): Promise<number> {
+  const entries = await listConsumersWithState(db, registeredConsumerNames);
+  if (entries.length === 0) {
+    ctx.out.log("");
+    ctx.out.log("  No event consumers registered.");
+    ctx.out.log("");
+    return 0;
+  }
+  ctx.out.log("");
+  ctx.out.log("  Registered event consumers:");
+  ctx.out.log("");
+  for (const e of entries) {
+    const errHint = e.lastError ? ` error=${e.lastError.slice(0, 60)}` : "";
+    ctx.out.log(
+      `    ${e.name.padEnd(44)} ${e.status.padEnd(15)} cursor=${e.lastProcessedEventId} attempts=${e.attempts}${errHint}`,
+    );
+  }
+  ctx.out.log("");
+  return 0;
+}
+
+async function showConsumerStatus(
+  ctx: CliCommandContext,
+  db: import("@cosmicdrift/kumiko-framework/db").DbConnection,
+  arg: string | undefined,
+  registeredConsumerNames: readonly string[],
+  getConsumerState: typeof import("@cosmicdrift/kumiko-framework/pipeline").getConsumerState,
+): Promise<number> {
+  if (!arg) {
+    ctx.out.err("");
+    ctx.out.err("  Usage: kumiko consumer status <consumer-name>");
+    ctx.out.err("");
+    return 1;
+  }
+  const state = await getConsumerState(db, arg);
+  if (!state) {
+    if (!registeredConsumerNames.includes(arg)) {
+      ctx.out.err("");
+      ctx.out.err(`  Consumer "${arg}" is not registered.`);
+      ctx.out.err("");
+      return 1;
+    }
+    ctx.out.log("");
+    ctx.out.log(`  ${arg}: never-run`);
+    ctx.out.log("");
+    return 0;
+  }
+  ctx.out.log("");
+  ctx.out.log(`  ${state.name}`);
+  ctx.out.log(`    status:        ${state.status}`);
+  ctx.out.log(`    last event id: ${state.lastProcessedEventId}`);
+  ctx.out.log(`    attempts:      ${state.attempts}`);
+  ctx.out.log(`    updated at:    ${String(state.updatedAt)}`);
+  if (state.lastError) {
+    ctx.out.log(`    last error:    ${state.lastError}`);
+  }
+  ctx.out.log("");
+  return 0;
+}
+
+async function restartOne(
+  ctx: CliCommandContext,
+  db: import("@cosmicdrift/kumiko-framework/db").DbConnection,
+  arg: string | undefined,
+  restartConsumer: typeof import("@cosmicdrift/kumiko-framework/pipeline").restartConsumer,
+  printOutcome: (prefix: string, state: { name: string; status: string }) => void,
+): Promise<number> {
+  if (!arg) return usage(ctx, "restart");
+  const state = await restartConsumer(db, arg);
+  printOutcome("restarted", state);
+  return 0;
+}
+
+async function disableOne(
+  ctx: CliCommandContext,
+  db: import("@cosmicdrift/kumiko-framework/db").DbConnection,
+  arg: string | undefined,
+  disableConsumer: typeof import("@cosmicdrift/kumiko-framework/pipeline").disableConsumer,
+  printOutcome: (prefix: string, state: { name: string; status: string }) => void,
+): Promise<number> {
+  if (!arg) return usage(ctx, "disable");
+  const state = await disableConsumer(db, arg);
+  printOutcome("disabled", state);
+  return 0;
+}
+
+async function enableOne(
+  ctx: CliCommandContext,
+  db: import("@cosmicdrift/kumiko-framework/db").DbConnection,
+  arg: string | undefined,
+  enableConsumer: typeof import("@cosmicdrift/kumiko-framework/pipeline").enableConsumer,
+  printOutcome: (prefix: string, state: { name: string; status: string }) => void,
+): Promise<number> {
+  if (!arg) return usage(ctx, "enable");
+  const state = await enableConsumer(db, arg);
+  printOutcome("enabled", state);
+  return 0;
+}
+
+async function skipOne(
+  ctx: CliCommandContext,
+  db: import("@cosmicdrift/kumiko-framework/db").DbConnection,
+  arg: string | undefined,
+  skipPoisonEvent: typeof import("@cosmicdrift/kumiko-framework/pipeline").skipPoisonEvent,
+  printOutcome: (prefix: string, state: { name: string; status: string }) => void,
+): Promise<number> {
+  if (!arg) return usage(ctx, "skip");
+  const state = await skipPoisonEvent(db, arg);
+  if (state.skippedEventId === null) {
+    ctx.out.log("");
+    ctx.out.log(`  ~ ${state.name}: cursor already at head — nothing to skip.`);
+    ctx.out.log("");
+  } else {
+    printOutcome(`skipped event ${state.skippedEventId},`, state);
+  }
+  return 0;
+}

package/src/commands/index.ts

@@ -0,0 +1,17 @@
+import { agentCommand } from "./agent";
+import { consumerCommand } from "./consumer";
+import { projectCommand } from "./project";
+import type { CliCommand } from "./types";
+
+export const APP_COMMANDS: ReadonlyArray<CliCommand> = [
+  agentCommand,
+  projectCommand,
+  consumerCommand,
+];
+
+export function findAppCommand(id: string): CliCommand | undefined {
+  return APP_COMMANDS.find((c) => c.id === id);
+}
+
+export type { CliCommand, CliCommandContext } from "./types";
+export { agentCommand, consumerCommand, projectCommand };

package/src/commands/project.ts

@@ -0,0 +1,164 @@
+import { join } from "node:path";
+import type { CliCommand, CliCommandContext } from "./types";
+
+export const projectCommand: CliCommand = {
+  id: "project",
+  description: "Manage projections (list | status <name> | rebuild <name>)",
+  help: "Reads kumiko.config.ts in cwd, builds the registry, dispatches against the\nprojection-state table in DATABASE_URL.\n\nSubcommands:\n  list                 List all projections and their state\n  status <name>        Show detail state for one projection\n  rebuild <name>       Full rebuild + report",
+  run: async (ctx) => {
+    const sub = ctx.argv[0];
+    const arg = ctx.argv[1];
+
+    const configPath = join(ctx.cwd, "kumiko.config.ts");
+    if (!(await Bun.file(configPath).exists())) {
+      ctx.out.err("");
+      ctx.out.err(`  kumiko.config.ts not found at: ${configPath}`);
+      ctx.out.err("");
+      ctx.out.err("  Create a file that exports your features:");
+      ctx.out.err("    // kumiko.config.ts");
+      ctx.out.err('    import { myFeature } from "./src/features/my-feature";');
+      ctx.out.err("    export default { features: [myFeature] };");
+      ctx.out.err("");
+      return 1;
+    }
+
+    const databaseUrl = process.env["DATABASE_URL"];
+    if (!databaseUrl) {
+      ctx.out.err("");
+      ctx.out.err("  DATABASE_URL not set. Run against a configured env.");
+      ctx.out.err("");
+      return 1;
+    }
+
+    const config = (await import(configPath)).default as {
+      features: readonly import("@cosmicdrift/kumiko-framework/engine").FeatureDefinition[];
+    };
+    const { createRegistry } = await import("@cosmicdrift/kumiko-framework/engine");
+    const { createDbConnection } = await import("@cosmicdrift/kumiko-framework/db");
+    const {
+      listProjectionsWithState,
+      getProjectionState,
+      rebuildProjection,
+      createProjectionStateTable,
+    } = await import("@cosmicdrift/kumiko-framework/pipeline");
+
+    const registry = createRegistry(config.features);
+    const { db, close } = createDbConnection(databaseUrl);
+    await createProjectionStateTable(db);
+
+    try {
+      switch (sub) {
+        case "list":
+          return await listProjections(ctx, db, registry, listProjectionsWithState);
+        case "status":
+          return await showProjectionStatus(ctx, db, arg, registry, getProjectionState);
+        case "rebuild":
+          return await rebuildOne(ctx, db, arg, registry, rebuildProjection);
+        default:
+          ctx.out.log("");
+          ctx.out.log("  Usage: kumiko project <list | status <name> | rebuild <name>>");
+          ctx.out.log("");
+          return 1;
+      }
+    } finally {
+      await close();
+    }
+  },
+};
+
+async function listProjections(
+  ctx: CliCommandContext,
+  db: import("@cosmicdrift/kumiko-framework/db").DbConnection,
+  registry: ReturnType<typeof import("@cosmicdrift/kumiko-framework/engine").createRegistry>,
+  listProjectionsWithState: typeof import("@cosmicdrift/kumiko-framework/pipeline").listProjectionsWithState,
+): Promise<number> {
+  const entries = await listProjectionsWithState(db, registry);
+  if (entries.length === 0) {
+    ctx.out.log("");
+    ctx.out.log("  No projections registered.");
+    ctx.out.log("");
+    return 0;
+  }
+  ctx.out.log("");
+  ctx.out.log("  Registered projections:");
+  ctx.out.log("");
+  for (const e of entries) {
+    const when = e.lastRebuildAt ? e.lastRebuildAt.toString() : "never";
+    ctx.out.log(
+      `    ${e.name.padEnd(40)} ${e.status.padEnd(15)} source=${e.sources.join(",")} last=${when}`,
+    );
+  }
+  ctx.out.log("");
+  return 0;
+}
+
+async function showProjectionStatus(
+  ctx: CliCommandContext,
+  db: import("@cosmicdrift/kumiko-framework/db").DbConnection,
+  arg: string | undefined,
+  registry: ReturnType<typeof import("@cosmicdrift/kumiko-framework/engine").createRegistry>,
+  getProjectionState: typeof import("@cosmicdrift/kumiko-framework/pipeline").getProjectionState,
+): Promise<number> {
+  if (!arg) {
+    ctx.out.err("");
+    ctx.out.err("  Usage: kumiko project status <projection-name>");
+    ctx.out.err("");
+    return 1;
+  }
+  const state = await getProjectionState(db, arg);
+  if (!state) {
+    const registered = registry.getAllProjections().has(arg);
+    if (!registered) {
+      ctx.out.err("");
+      ctx.out.err(`  Projection "${arg}" is not registered.`);
+      ctx.out.err("");
+      return 1;
+    }
+    ctx.out.log("");
+    ctx.out.log(`  ${arg}: never-rebuilt`);
+    ctx.out.log("");
+    return 0;
+  }
+  ctx.out.log("");
+  ctx.out.log(`  ${state.name}`);
+  ctx.out.log(`    status:        ${state.status}`);
+  ctx.out.log(`    last event id: ${state.lastProcessedEventId}`);
+  ctx.out.log(`    last rebuild:  ${state.lastRebuildAt?.toString() ?? "never"}`);
+  ctx.out.log(`    updated at:    ${state.updatedAt.toString()}`);
+  if (state.lastError) {
+    ctx.out.log(`    last error:    ${state.lastError}`);
+  }
+  ctx.out.log("");
+  return 0;
+}
+
+async function rebuildOne(
+  ctx: CliCommandContext,
+  db: import("@cosmicdrift/kumiko-framework/db").DbConnection,
+  arg: string | undefined,
+  registry: ReturnType<typeof import("@cosmicdrift/kumiko-framework/engine").createRegistry>,
+  rebuildProjection: typeof import("@cosmicdrift/kumiko-framework/pipeline").rebuildProjection,
+): Promise<number> {
+  if (!arg) {
+    ctx.out.err("");
+    ctx.out.err("  Usage: kumiko project rebuild <projection-name>");
+    ctx.out.err("");
+    return 1;
+  }
+  ctx.out.log("");
+  ctx.out.log(`  Rebuilding ${arg} ...`);
+  try {
+    const result = await rebuildProjection(arg, { db, registry });
+    ctx.out.log("");
+    ctx.out.log(
+      `  ✓ ${result.projection}: ${result.eventsProcessed} events, ${result.durationMs}ms`,
+    );
+    ctx.out.log("");
+    return 0;
+  } catch (e) {
+    ctx.out.err("");
+    ctx.out.err(`  ✗ Rebuild failed: ${e instanceof Error ? e.message : e}`);
+    ctx.out.err("");
+    return 1;
+  }
+}

package/src/commands/types.ts

@@ -0,0 +1,14 @@
+import type { Output } from "../output";
+
+export type CliCommandContext = {
+  readonly argv: ReadonlyArray<string>;
+  readonly cwd: string;
+  readonly out: Output;
+};
+
+export type CliCommand = {
+  readonly id: string;
+  readonly description: string;
+  readonly help: string;
+  readonly run: (ctx: CliCommandContext) => Promise<number>;
+};

package/src/index.ts

@@ -4,17 +4,17 @@
 // (../bin/cli.ts) is a 3-line wrapper that forwards process.argv. Tests
 // drive runCli directly with a captured Output so no subprocess is needed.
 //
-// Scope (DX-1.2 minimum-viable): `new app <name>` + `add feature <name>`.
-// Other commands (dev, build, check, …) stay in the in-repo bin/kumiko.ts
-// for now — that one operates on the framework workspace, not on a
-// user-app workspace.
+// Scope: scaffolding (`new app <name>`, `add feature <name>`) plus the
+// app-facing ops commands (`agent`, `project`, `consumer`). Framework-
+// maintainer commands (check, ci:guards, dev, build, …) stay in the
+// framework repo's bin/kumiko.ts, which operates on that workspace only.
 
 import { scaffoldApp, scaffoldAppFeature } from "@cosmicdrift/kumiko-dev-server";
+import type { CliCommand } from "./commands";
+import { APP_COMMANDS, findAppCommand } from "./commands";
+import type { Output } from "./output";
 
-export type Output = {
-  readonly log: (line: string) => void;
-  readonly err: (line: string) => void;
-};
+export type { Output } from "./output";
 
 export type RunCliOptions = {
   readonly argv: readonly string[];
@@ -48,6 +48,16 @@ export async function runCli(options: RunCliOptions): Promise<number> {
   if (first === "new") return await runNew(argv.slice(1), out, cwd);
   if (first === "add") return runAdd(argv.slice(1), out, cwd);
 
+  const appCommand = findAppCommand(first);
+  if (appCommand) {
+    const rest = argv.slice(1);
+    if (rest.includes("--help") || rest.includes("-h")) {
+      printCommandHelp(appCommand, out);
+      return 0;
+    }
+    return await appCommand.run({ argv: rest, cwd, out });
+  }
+
   out.err(`kumiko: unknown command "${first}". Run \`kumiko --help\` for usage.`);
   return 1;
 }
@@ -111,8 +121,19 @@ function printHelp(out: Output): void {
   out.log("Commands:");
   out.log("  kumiko new app <name>        Scaffold a new app workspace");
   out.log("  kumiko add feature <name>    Add + auto-mount a feature");
+  for (const cmd of APP_COMMANDS) {
+    out.log(`  kumiko ${cmd.id.padEnd(22)}${cmd.description}`);
+  }
   out.log("  kumiko --version             Print version");
   out.log("  kumiko --help                This help");
   out.log("");
   out.log("Docs: https://docs.kumiko.rocks");
 }
+
+function printCommandHelp(cmd: CliCommand, out: Output): void {
+  out.log("");
+  out.log(`  kumiko ${cmd.id} — ${cmd.description}`);
+  out.log("");
+  for (const line of cmd.help.split("\n")) out.log(`  ${line}`);
+  out.log("");
+}

package/src/output.ts

@@ -0,0 +1,4 @@
+export type Output = {
+  readonly log: (line: string) => void;
+  readonly err: (line: string) => void;
+};

package/src/__tests__/cli.integration.test.ts

@@ -1,122 +0,0 @@
-// Drives runCli in-process — captures stdout/stderr via the injected
-// Output, exercises the 3-command-walkthrough end-to-end (new app +
-// add feature) into a tmp directory.
-
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { runCli } from "../index";
-
-type Captured = { logs: string[]; errs: string[] };
-
-function capture(): {
-  out: { log: (s: string) => void; err: (s: string) => void };
-  captured: Captured;
-} {
-  const captured: Captured = { logs: [], errs: [] };
-  return {
-    captured,
-    out: {
-      log: (s) => captured.logs.push(s),
-      err: (s) => captured.errs.push(s),
-    },
-  };
-}
-
-describe("kumiko cli", () => {
-  let tmp: string;
-
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), "kumiko-cli-"));
-  });
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  test("--help prints commands + docs link", async () => {
-    const { out, captured } = capture();
-    const code = await runCli({ argv: ["--help"], out });
-    expect(code).toBe(0);
-    const joined = captured.logs.join("\n");
-    expect(joined).toContain("kumiko new app");
-    expect(joined).toContain("kumiko add feature");
-    expect(joined).toContain("docs.kumiko.rocks");
-  });
-
-  test("no args prints help", async () => {
-    const { out, captured } = capture();
-    const code = await runCli({ argv: [], out });
-    expect(code).toBe(0);
-    expect(captured.logs.join("\n")).toContain("kumiko new app");
-  });
-
-  test("--version prints semver", async () => {
-    const { out, captured } = capture();
-    const code = await runCli({ argv: ["--version"], out });
-    expect(code).toBe(0);
-    expect(captured.logs[0]).toMatch(/^\d+\.\d+\.\d+$/);
-  });
-
-  test("unknown command exits 1", async () => {
-    const { out, captured } = capture();
-    const code = await runCli({ argv: ["bogus"], out });
-    expect(code).toBe(1);
-    expect(captured.errs.join("\n")).toContain("unknown command");
-  });
-
-  test("new app <name> scaffolds the walkthrough files", async () => {
-    const { out, captured } = capture();
-    const code = await runCli({ argv: ["new", "app", "my-notes"], cwd: tmp, out });
-    expect(code).toBe(0);
-    const appRoot = join(tmp, "my-notes");
-    for (const f of [
-      "package.json",
-      "tsconfig.json",
-      "src/run-config.ts",
-      "bin/main.ts",
-      "bin/dev.ts",
-      ".env.example",
-      "README.md",
-    ]) {
-      expect(() => readFileSync(join(appRoot, f), "utf-8")).not.toThrow();
-    }
-    expect(captured.logs.join("\n")).toContain("Scaffolded my-notes");
-  });
-
-  test("new app rejects bad name", async () => {
-    const { out, captured } = capture();
-    const code = await runCli({ argv: ["new", "app", "My Notes"], cwd: tmp, out });
-    expect(code).toBe(1);
-    expect(captured.errs.join("\n")).toContain("kebab-case");
-  });
-
-  test("new app without name exits 1 with usage hint", async () => {
-    const { out, captured } = capture();
-    const code = await runCli({ argv: ["new", "app"], cwd: tmp, out });
-    expect(code).toBe(1);
-    expect(captured.errs.join("\n")).toContain("missing <name>");
-  });
-
-  test("add feature mounts into scaffolded app", async () => {
-    const { out: out1 } = capture();
-    await runCli({ argv: ["new", "app", "my-notes"], cwd: tmp, out: out1 });
-    const appRoot = join(tmp, "my-notes");
-
-    const { out: out2, captured } = capture();
-    const code = await runCli({ argv: ["add", "feature", "notes"], cwd: appRoot, out: out2 });
-    expect(code).toBe(0);
-
-    const runConfig = readFileSync(join(appRoot, "src/run-config.ts"), "utf-8");
-    expect(runConfig).toContain(`import { notesFeature } from "./features/notes";`);
-    expect(runConfig).toContain("notesFeature");
-    expect(captured.logs.join("\n")).toContain("auto-mounted");
-  });
-
-  test("add feature without name exits 1", async () => {
-    const { out, captured } = capture();
-    const code = await runCli({ argv: ["add", "feature"], cwd: tmp, out });
-    expect(code).toBe(1);
-    expect(captured.errs.join("\n")).toContain("missing <name>");
-  });
-});