@ultimat3/cli 1.0.0

package/src/cmd-mcp.ts

@@ -0,0 +1,176 @@
+// `x mcp serve` — the framework's dev MCP server over stdio or HTTP. The 13 tools, the JSON-RPC
+// dispatch, both transports and the structural SQL refusals all come from `@ultimat3/mcp`; the CLI
+// supplies only the app, the caller and the socket. A tool answered here would be a second answer
+// to a question the framework already answers.
+
+import { markListening, nanoid } from '@ultimat3/core';
+import { mcpHttpRoute, serveStdio } from '@ultimat3/mcp';
+import { requireAppRoot } from './app-root';
+import type { CliCommand, CommandContext } from './command';
+import { BadFlagError } from './errors';
+import { holdUntilShutdown } from './hold';
+import type { CliMcpServer } from './mcp-host';
+import { createDevMcpServer, DEV_TOOL_SCOPES } from './mcp-host';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { flagString } from './parse';
+
+const DEFAULT_PORT = 9229;
+const TRANSPORTS = ['stdio', 'http'] as const;
+type Transport = (typeof TRANSPORTS)[number];
+
+/** One reading of the entitlement, so `--json` and the terminal can never disagree about it. */
+const scopes = (): readonly string[] => [...DEV_TOOL_SCOPES].sort();
+
+const scopeLine = (): string => msg('cli.mcp.scopes', { scopes: scopes().join(' ') });
+
+const isTransport = (value: string): value is Transport =>
+  (TRANSPORTS as readonly string[]).includes(value);
+
+/** The catalog, from the server's own registry — never a list kept here. */
+async function catalog(host: CliMcpServer): Promise<CommandResult> {
+  const tools = host.server.list(host.caller);
+  await host.close();
+  return {
+    ok: true,
+    command: 'mcp',
+    summary: msg('cli.mcp.serving', { transport: 'none', tools: tools.length }),
+    // `scopes` rides in `data` because it rides in `lines`: every fact the terminal prints is a
+    // fact `--json` carries, or the two renderers have drifted.
+    data: {
+      tools: tools.map((tool) => ({ name: tool.name, description: tool.description })),
+      scopes: scopes(),
+    },
+    lines: [...tools.map((tool) => `  ${tool.name.padEnd(20)} ${tool.description}`), scopeLine()],
+  };
+}
+
+const notFound = (path: string): Response =>
+  new Response(
+    JSON.stringify({
+      code: 'X_MCP_PROTOCOL',
+      cause: 'the MCP server answers exactly one route',
+      fix: `POST ${path} with an Authorization: Bearer header`,
+    }),
+    { status: 404, headers: { 'content-type': 'application/json' } },
+  );
+
+/** A running HTTP transport. `stop()` releases the socket AND the host's lazily booted services. */
+export interface McpHttpServer {
+  readonly result: CommandResult;
+  stop(): Promise<void>;
+}
+
+/**
+ * HTTP demands a bearer token, and a token in a config file is one more thing to keep in sync — so
+ * it is minted per process and returned in `data`, where `--json` puts it one read away.
+ *
+ * Exported with its stop handle rather than swallowing it: the socket and the host's PGlite data
+ * directory outlive `run()` otherwise, and nothing — a test, an embedding caller, or a signal —
+ * could ever release them.
+ */
+export function startMcpHttp(host: CliMcpServer, port: number): McpHttpServer {
+  const token = nanoid(32);
+  const route = mcpHttpRoute({
+    server: host.server,
+    resolveToken: (candidate) =>
+      candidate === token ? { actor: host.caller.actor, scopes: DEV_TOOL_SCOPES } : null,
+  });
+  const handle = Bun.serve({
+    port,
+    hostname: 'localhost',
+    fetch: (request: Request): Response | Promise<Response> => {
+      const url = new URL(request.url);
+      if (request.method !== route.method || url.pathname !== route.path) {
+        return notFound(route.path);
+      }
+      return route.handle(request);
+    },
+  });
+  // Announces the socket as this process's own, so a caller on it is never mistaken for egress.
+  const stopListening = markListening(handle.url.origin);
+  const url = `${handle.url.origin}${route.path}`;
+  return {
+    result: {
+      ok: true,
+      command: 'mcp',
+      summary: msg('cli.mcp.serving', { transport: 'http', tools: host.tools.length }),
+      data: { url, token, tools: host.tools.length, scopes: scopes() },
+      lines: [`  POST ${url}`, `  authorization: Bearer ${token}`, scopeLine()],
+    },
+    async stop() {
+      await handle.stop(true);
+      stopListening();
+      await host.close();
+    },
+  };
+}
+
+/**
+ * stdout is the WIRE. `dispatch.ts` renders a `CommandResult` only after `run` resolves, and this
+ * resolves when the peer closes stdin — so the command's own output cannot reach stdout while a
+ * session is live, and nothing here writes to it directly.
+ */
+async function serveOverStdio(host: CliMcpServer): Promise<CommandResult> {
+  await serveStdio({ server: host.server, caller: host.caller });
+  await host.close();
+  return {
+    ok: true,
+    command: 'mcp',
+    summary: msg('cli.mcp.serving', { transport: 'stdio', tools: host.tools.length }),
+    data: { transport: 'stdio', tools: host.tools.length },
+  };
+}
+
+function readPort(ctx: CommandContext): number {
+  const raw = flagString(ctx.args, 'port') ?? String(DEFAULT_PORT);
+  const port = Number.parseInt(raw, 10);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new BadFlagError({
+      flag: 'port',
+      command: 'mcp serve',
+      reason: `expects a port in 0..65535, got "${raw}"`,
+      fix: `x mcp serve --transport http --port ${DEFAULT_PORT}`,
+    });
+  }
+  return port;
+}
+
+export const mcpCommand: CliCommand = {
+  spec: {
+    name: 'mcp',
+    summary: 'serve the dev tools: routes, schema, policies, db, queues, logs, tests, verify',
+    usage: 'x mcp tools | x mcp serve [--transport stdio|http] [--port 9229] [--json]',
+    requiresApp: true,
+    subcommands: ['serve', 'tools'],
+    flags: [
+      { name: 'transport', type: 'string', summary: 'stdio | http', default: 'stdio' },
+      { name: 'port', type: 'string', summary: 'HTTP port', default: String(DEFAULT_PORT) },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('mcp', ctx.cwd).dir;
+    const transport = flagString(ctx.args, 'transport') ?? 'stdio';
+    // Validated before the app is loaded: a typo must not cost a boot to report.
+    if (!isTransport(transport)) {
+      throw new BadFlagError({
+        flag: 'transport',
+        command: 'mcp serve',
+        reason: `expects ${TRANSPORTS.join(' or ')}, got "${transport}"`,
+        fix: 'x mcp serve --transport stdio',
+      });
+    }
+    const port = readPort(ctx);
+    const host = await createDevMcpServer({ root, env: ctx.env, runner: ctx.runner });
+    if (ctx.args.subcommand === 'tools') return catalog(host);
+    if (transport !== 'http') return serveOverStdio(host);
+    // Long-running: the process stays alive on the server handle. The stop handle goes to the
+    // shutdown registry so a signal releases the socket and the database, not the exit code alone.
+    // Long-running, exactly as `x dev` is: `dispatch` awaits the hold, and the drain a signal
+    // starts is what releases the socket and the database. Registering a shutdown hook and
+    // returning was the older shape — nothing installed a signal handler, so the hook was never
+    // reached and the exit code closed the socket the line above had just announced.
+    const served = startMcpHttp(host, port);
+    return { ...served.result, hold: holdUntilShutdown('mcp', () => served.stop()) };
+  },
+};

package/src/cmd-new.ts

@@ -0,0 +1,133 @@
+// `x new <name>` — a monorepo that already runs: auth, a seeded database, a 0kb landing page, a
+// streaming dashboard, an admin app with MCP on, and an example feature slice with passing tests.
+// Interactive-free: every choice is a flag with a default, because an agent cannot answer prompts.
+
+import { existsSync } from 'node:fs';
+import { chmod } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+import { dedupe } from './cmd-generate';
+import type { CliCommand, CommandContext } from './command';
+import { writeSchemaHash } from './drift';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { flagBool, flagString } from './parse';
+import type { GeneratedFile } from './templates';
+import { appFiles, EXECUTABLE_FILES, names, repoFiles, resourceFiles } from './templates';
+import { loadVersion } from './version-loader';
+
+export interface NewAppOptions {
+  readonly name: string;
+  /** The example feature slice. `--no-example` gives the same shape with an empty app/. */
+  readonly example: boolean;
+}
+
+/** Pure: the complete file list for a new app, so `--dry-run` and the test see the same thing. */
+export function planNewApp(options: NewAppOptions): readonly GeneratedFile[] {
+  const app = names(options.name);
+  const files: GeneratedFile[] = [
+    ...repoFiles(app, loadVersion(), options.example),
+    ...appFiles(app),
+  ];
+  if (options.example) {
+    files.push(...resourceFiles('post', { surfaceDir: 'apps/web/app', feature: 'post' }));
+  }
+  // `repoFiles`' own catalog entry and the example resource's both target the same flat catalog
+  // file, so this has to be the merge-aware dedupe — the one `cmd-generate.ts` uses for `x g` —
+  // or the second contributor's keys would silently vanish instead of landing in the one file.
+  return dedupe(files);
+}
+
+export interface WrittenApp {
+  readonly dir: string;
+  readonly files: readonly string[];
+  readonly schemaHash: string;
+}
+
+export async function writeNewApp(target: string, options: NewAppOptions): Promise<WrittenApp> {
+  const files = planNewApp(options);
+  for (const file of files) await Bun.write(join(target, file.path), file.contents);
+  for (const path of EXECUTABLE_FILES) await chmod(join(target, path), 0o755);
+  // Record the schema hash beside the initial migration so `x verify` sees no drift on run one.
+  const hash = await writeSchemaHash(target, '0000_initial');
+  return { dir: target, files: files.map((file) => file.path), schemaHash: hash };
+}
+
+function parentDir(cwd: string, dirFlag: string | undefined): string {
+  if (dirFlag === undefined) return cwd;
+  return isAbsolute(dirFlag) ? dirFlag : join(cwd, dirFlag);
+}
+
+export const newCommand: CliCommand = {
+  spec: {
+    name: 'new',
+    summary: 'scaffold a new Ultimate monorepo that already runs',
+    usage: 'x new <name> [--dir path] [--no-example] [--dry-run] [--json]',
+    flags: [
+      { name: 'dir', type: 'string', summary: 'parent directory (default: cwd)' },
+      {
+        name: 'example',
+        type: 'boolean',
+        summary: 'include the example feature slice',
+        default: true,
+      },
+      { name: 'dry-run', type: 'boolean', summary: 'print the file list, write nothing' },
+      { name: 'force', type: 'boolean', summary: 'write into a directory that already exists' },
+    ],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const raw = ctx.args.positionals[0];
+    if (raw === undefined) {
+      return {
+        ok: false,
+        command: 'new',
+        summary: msg('cli.usage'),
+        findings: [
+          {
+            code: 'X_CLI_BAD_FLAG',
+            cause: 'x new needs a name',
+            fix: 'x new myapp',
+            docs: 'https://ultimate.dev/errors/X_CLI_BAD_FLAG',
+          },
+        ],
+      };
+    }
+    const app = names(raw);
+    const target = resolve(parentDir(ctx.cwd, flagString(ctx.args, 'dir')), app.kebab);
+    const options: NewAppOptions = { name: raw, example: ctx.args.flags.get('example') !== false };
+
+    if (flagBool(ctx.args, 'dry-run')) {
+      const files = planNewApp(options);
+      return {
+        ok: true,
+        command: 'new',
+        summary: msg('cli.new.done', { name: app.kebab }),
+        data: { dir: target, files: files.map((file) => file.path), dryRun: true },
+        lines: files.map((file) => `  + ${app.kebab}/${file.path}`),
+      };
+    }
+    if (existsSync(target) && !flagBool(ctx.args, 'force')) {
+      return {
+        ok: false,
+        command: 'new',
+        summary: msg('cli.usage'),
+        findings: [
+          {
+            code: 'X_GENERATE_CONFLICT',
+            cause: `${target} already exists`,
+            fix: `x new ${app.kebab} --force, or choose another name`,
+            docs: 'https://ultimate.dev/errors/X_GENERATE_CONFLICT',
+            at: target,
+          },
+        ],
+      };
+    }
+    const written = await writeNewApp(target, options);
+    return {
+      ok: true,
+      command: 'new',
+      summary: msg('cli.new.done', { name: app.kebab }),
+      data: { dir: written.dir, files: written.files, schemaHash: written.schemaHash },
+      lines: [`  ${written.files.length} files in ${target}`],
+    };
+  },
+};

package/src/cmd-planned.ts

@@ -0,0 +1,119 @@
+// The commands the design docs specify and this build does not yet implement. They are in the
+// registry on purpose: `x cache bust` exiting X_CLI_UNKNOWN_COMMAND says "you typed something that
+// does not exist", which is false and sends an agent looking for a typo. X_NOT_IMPLEMENTED plus a
+// fix naming the closest shipped command says the true thing, and `x help` lists them honestly.
+
+import type { CliCommand } from './command';
+import { CliNotImplementedError } from './errors';
+import type { CommandResult } from './output';
+import type { CommandSpec } from './parse';
+
+export interface PlannedCommand {
+  readonly name: string;
+  readonly summary: string;
+  readonly usage: string;
+  readonly subcommands?: readonly string[];
+  /** Runnable today, and closer to the answer than nothing. Never a doc link. */
+  readonly fix: string;
+}
+
+/**
+ * `wiki/CLI-Reference.md`'s planned table, verbatim in shape. Every `fix` names a command this
+ * build actually ships — a fix line pointing at another unbuilt command is the failure mode this
+ * table exists to close, and `cmd-planned.test.ts` asserts the whole set against the registry.
+ */
+export const PLANNED_COMMANDS: readonly PlannedCommand[] = [
+  {
+    name: 'cache',
+    summary: 'the tag graph, targeted eviction, hit stats',
+    usage: 'x cache [graph|bust <tag>|clear|stats] [--json]',
+    subcommands: ['graph', 'bust', 'clear', 'stats'],
+    fix: 'x dev   # then the cache panel at /_x',
+  },
+  {
+    name: 'branch',
+    summary: 'copy-on-write branch environments with a preview URL',
+    usage: 'x branch [<name>|rm <name>] [--json]',
+    fix: 'x db branch <name>   # the database half, shipped today',
+  },
+  {
+    name: 'status',
+    summary: 'role health and the build-ID distribution of connected clients',
+    usage: 'x status [--json]',
+    fix: 'x doctor --json',
+  },
+  {
+    name: 'upgrade',
+    summary: 'move every @ultimat3/* in lockstep, with codemods',
+    usage: 'x upgrade [--dry-run] [--json]',
+    fix: 'bun update --latest && x verify',
+  },
+  {
+    name: 'env',
+    summary: 'validate the typed env; --fix writes the missing keys',
+    usage: 'x env check [--fix] [--json]',
+    subcommands: ['check'],
+    fix: 'x doctor --json   # reports the env problems it can already see',
+  },
+  {
+    name: 'logs',
+    summary: 'structured logs and OTel spans, filterable',
+    usage: 'x logs tail [--json]',
+    subcommands: ['tail'],
+    fix: 'x dev   # then the timeline panel at /_x',
+  },
+  {
+    name: 'token',
+    summary: 'create MCP tokens and grant scopes',
+    usage: 'x token [create --scopes <s>|grant <scope>] [--json]',
+    subcommands: ['create', 'grant'],
+    fix: 'x mcp serve --help   # the scopes this build serves',
+  },
+  {
+    name: 'ai',
+    summary: 'eval scores, semantic-cache stats, vector reindex',
+    usage: 'x ai [eval <name>|cache|reindex] [--json]',
+    subcommands: ['eval', 'cache', 'reindex'],
+    fix: 'x test eval --json   # every eval, scored against its committed baseline',
+  },
+  {
+    name: 'money',
+    summary: 'extend the currency table',
+    usage: 'x money add-currency <ISO> --exponent <n> [--json]',
+    subcommands: ['add-currency'],
+    fix: 'x manifest --json   # currencies ship in @ultimat3/money; add yours in app.config.ts',
+  },
+  {
+    name: 'config',
+    summary: 'the resolved app.config.ts, defaults included',
+    usage: 'x config show [--json]',
+    subcommands: ['show'],
+    fix: 'x manifest --json   # the facts the resolved config produced',
+  },
+];
+
+const specFor = (planned: PlannedCommand): CommandSpec => ({
+  name: planned.name,
+  summary: `${planned.summary} (planned)`,
+  usage: planned.usage,
+  ...(planned.subcommands === undefined ? {} : { subcommands: planned.subcommands }),
+});
+
+/**
+ * Throws rather than returning a failed `CommandResult`: `dispatch` renders a thrown
+ * `UltimateError` through the same 3-line contract and the same `--json` shape, so a planned
+ * command reads byte-identically to any other typed failure.
+ */
+const toCommand = (planned: PlannedCommand): CliCommand => ({
+  spec: specFor(planned),
+  // `async` is load-bearing: a synchronous throw would escape every caller that awaits the
+  // promise this signature promises, including the dispatcher's own error path.
+  async run(): Promise<CommandResult> {
+    throw new CliNotImplementedError({
+      feature: `x ${planned.name}`,
+      fix: planned.fix,
+    });
+  },
+});
+
+export const plannedCommands = (): readonly CliCommand[] => PLANNED_COMMANDS.map(toCommand);

package/src/cmd-policy.ts

@@ -0,0 +1,136 @@
+// `x policy list|explain` — which clause decided a permission, and why. This file is CLI wiring
+// only: the fact-gathering (registries, matrix rows) lives in `policy-facts.ts`, so the matrix
+// logic is testable without an app — same split as `cmd-jobs.ts` / `jobs-report.ts`.
+
+import { loadApp } from './app-load';
+import { requireAppRoot } from './app-root';
+import type { CliCommand, CommandContext } from './command';
+import { BadFlagError, DeclarationUnknownError } from './errors';
+import { msg } from './messages';
+import type { CommandResult, Finding, JsonValue } from './output';
+import { nearest } from './parse';
+import type { DeclarationExplanation } from './policy-facts';
+import { explainPolicy, knownPolicySubjects, listPolicy } from './policy-facts';
+import { renderTable } from './table';
+
+/** A descriptor is plain JSON by construction — same idiom as `cmd-registries.ts`'s `asJson`. */
+const asJson = (value: object): Record<string, JsonValue> => value as Record<string, JsonValue>;
+
+const joinOrDash = (values: readonly string[]): string =>
+  values.length === 0 ? msg('cli.policy.none') : values.join(',');
+
+function runList(findings: readonly Finding[]): CommandResult {
+  const facts = listPolicy();
+  const header = ['permission', 'roles', 'actions', 'queries'];
+  const rows = facts.rows.map((row) => [
+    row.permission,
+    joinOrDash(row.roles),
+    joinOrDash(row.actions),
+    joinOrDash(row.queries),
+  ]);
+  const lines: string[] =
+    facts.rows.length === 0 ? [] : renderTable(header, rows).map((line) => `  ${line}`);
+  if (facts.unenforced.length > 0) {
+    lines.push(`  ${msg('cli.policy.unenforced', { count: facts.unenforced.length })}`);
+    for (const permission of facts.unenforced) lines.push(`    ${permission}`);
+  }
+  return {
+    ok: findings.length === 0,
+    command: 'policy',
+    summary: msg('cli.policy.count', {
+      permissions: facts.rows.length,
+      roles: facts.roleCount,
+      enforced: facts.enforcedCount,
+    }),
+    lines,
+    findings,
+    data: facts.rows.map((row) => asJson(row)),
+  };
+}
+
+/** A header naming the declaration and its policy label, then the actor/verdict/deciding table. */
+function declarationLines(declaration: DeclarationExplanation): readonly string[] {
+  const header = `  ${msg('cli.policy.declaration', {
+    kind: declaration.kind,
+    name: declaration.name,
+    label: declaration.label,
+  })}`;
+  // Both notes say the same thing `dev-policy.ts` writes into the `/_x` trace: this ran outside a
+  // request. A policy that merely reads input gets its table plus the caveat; one that cannot be
+  // evaluated at all gets the caveat instead of a table, never a synthetic deny dressed as one.
+  if (!declaration.decidable) return [header, `    ${msg('cli.policy.undecidable')}`];
+  const rows = declaration.rows.map((row) => [
+    row.actor,
+    msg(row.allowed ? 'cli.policy.allow' : 'cli.policy.deny'),
+    row.deciding ?? msg('cli.policy.none'),
+    row.reason ?? msg('cli.policy.none'),
+  ]);
+  const table = renderTable(['actor', 'verdict', 'deciding', 'reason'], rows).map(
+    (line) => `  ${line}`,
+  );
+  return [header, ...table, `    ${msg('cli.policy.noInput')}`];
+}
+
+function requireSubject(ctx: CommandContext): string {
+  const name = ctx.args.positionals[0];
+  if (name === undefined) {
+    throw new BadFlagError({
+      flag: 'subject',
+      command: 'policy',
+      reason: 'x policy explain <subject> needs a permission, action, query or route path',
+      fix: 'x policy list --json',
+    });
+  }
+  return name;
+}
+
+function runExplain(ctx: CommandContext, findings: readonly Finding[]): CommandResult {
+  const name = requireSubject(ctx);
+  const explanation = explainPolicy(name);
+  if (explanation === undefined) {
+    const known = knownPolicySubjects();
+    const suggestion = nearest(name, known);
+    throw new DeclarationUnknownError(
+      suggestion === undefined
+        ? { kind: 'policy', singular: 'policy subject', name, known, verb: 'explain' }
+        : { kind: 'policy', singular: 'policy subject', name, known, suggestion, verb: 'explain' },
+    );
+  }
+  // One row per (declaration, actor) pair — a permission two declarations enforce evaluates every
+  // actor twice, so this counts evaluations and never roles.
+  const rows = explanation.declarations.flatMap((declaration) => declaration.rows);
+  const allowed = rows.filter((row) => row.allowed).length;
+  return {
+    ok: findings.length === 0,
+    command: 'policy',
+    summary: msg('cli.policy.explained', {
+      subject: explanation.subject,
+      allowed,
+      evaluations: rows.length,
+    }),
+    lines: explanation.declarations.flatMap(declarationLines),
+    findings,
+    data: asJson({
+      subject: explanation.subject,
+      kind: explanation.kind,
+      grantingRoles: explanation.grantingRoles,
+      declarations: explanation.declarations.map((declaration) => asJson(declaration)),
+    }),
+  };
+}
+
+export const policyCommand: CliCommand = {
+  spec: {
+    name: 'policy',
+    summary: 'which clause decided a permission, and why',
+    usage: 'x policy [list|explain <subject>] [--json]',
+    requiresApp: true,
+    subcommands: ['list', 'explain'],
+  },
+  async run(ctx: CommandContext): Promise<CommandResult> {
+    const root = requireAppRoot('policy', ctx.cwd).dir;
+    const { findings } = await loadApp(root);
+    const sub = ctx.args.subcommand ?? 'list';
+    return sub === 'explain' ? runExplain(ctx, findings) : runList(findings);
+  },
+};