@mostra/cli 0.0.0-stage → 0.2.0

package/src/exit.ts

@@ -0,0 +1,89 @@
+/**
+ * The exit codes (INTERFACES §9, D140 item 16): one table keyed by diagnostic code, so every
+ * command ends the same way for the same failure. Each area has a code, and a few codes differ
+ * from their area; the table is total over the catalog by construction, and a test checks every
+ * catalog code against it.
+ */
+import type { DiagnosticArea } from "@mostra/protocol";
+
+/** The exit codes of INTERFACES §9. */
+export const EXIT = {
+  /** Success, or `verify` passed. */
+  ok: 0,
+  /** Artifact failure: verify failed, publish refused, a request the artifact's state refused. */
+  failure: 1,
+  /** Usage error. */
+  usage: 2,
+  /** Environment error: no runtime, browser or socket; the home; an unsupported platform. */
+  environment: 3,
+  /** Timeout: `--timeout` passed before the instance answered. */
+  timeout: 4,
+  /** `wait` ended `still_waiting`: not an error, the status is in the result. */
+  stillWaiting: 5,
+  /** Conflict: `once` already submitted, a compare-and-set mismatch, a reused request ID. */
+  conflict: 6,
+} as const;
+
+/** One of {@link EXIT}'s codes. */
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+
+/** Each area's exit code. Every area is here: a new one fails the type check until it is. */
+const BY_AREA: Readonly<Record<DiagnosticArea, ExitCode>> = {
+  MANIFEST: EXIT.failure,
+  BUILD: EXIT.failure,
+  TYPE: EXIT.failure,
+  LINT: EXIT.failure,
+  DEP: EXIT.failure,
+  KIT: EXIT.failure,
+  FIELD: EXIT.failure,
+  ACTION: EXIT.failure,
+  LIVE: EXIT.failure,
+  RUNTIME: EXIT.failure,
+  CONSOLE: EXIT.failure,
+  NETWORK: EXIT.failure,
+  A11Y: EXIT.failure,
+  VISUAL: EXIT.failure,
+  SMOKE: EXIT.failure,
+  REGRESSION: EXIT.failure,
+  TERM: EXIT.failure,
+  PUBLISH: EXIT.failure,
+  SUBMIT: EXIT.failure,
+  HOST: EXIT.environment,
+  HOME: EXIT.environment,
+  HYGIENE: EXIT.failure,
+  SECRET: EXIT.failure,
+  SHARE: EXIT.environment,
+  VERIFY: EXIT.failure,
+  TARGET: EXIT.failure,
+  ENV: EXIT.environment,
+  PLATFORM: EXIT.environment,
+  ARTIFACT: EXIT.failure,
+  CLI: EXIT.usage,
+};
+
+/** Codes whose exit code isn't their area's. */
+const BY_CODE: Readonly<Record<string, ExitCode>> = {
+  MOSTRA_HOST_TIMEOUT: EXIT.timeout,
+  // The CLI can't record a choice: its environment, not its command line.
+  MOSTRA_CLI_CONFIG_UNWRITABLE: EXIT.environment,
+  MOSTRA_HOST_INVALID_PARAMS: EXIT.usage,
+  MOSTRA_HOST_REQUEST_ID_REUSED: EXIT.conflict,
+  MOSTRA_HOST_CURSOR_COMPACTED: EXIT.failure,
+  MOSTRA_HOST_SUBSCRIPTION_UNKNOWN: EXIT.usage,
+  MOSTRA_SUBMIT_ALREADY: EXIT.conflict,
+  MOSTRA_SUBMIT_REVISION_MOVED: EXIT.conflict,
+  MOSTRA_FIELD_CONFLICT: EXIT.conflict,
+  MOSTRA_FIELD_MUTATION_ID_REUSED: EXIT.conflict,
+  MOSTRA_PUBLISH_ID_CONFLICT: EXIT.failure,
+  MOSTRA_HOME_INTEGRITY: EXIT.failure,
+  MOSTRA_HOME_NOT_ALWAYS_ON: EXIT.ok,
+  MOSTRA_VERIFY_CRASHED: EXIT.environment,
+};
+
+/** The exit code a diagnostic ends a command with. An unknown area is an environment error. */
+export function exitCodeFor(code: string): ExitCode {
+  const exact = BY_CODE[code];
+  if (exact !== undefined) return exact;
+  const area = /^MOSTRA_([A-Z0-9]+)_/.exec(code)?.[1];
+  return (area !== undefined ? BY_AREA[area as DiagnosticArea] : undefined) ?? EXIT.environment;
+}

package/src/help.ts

@@ -0,0 +1,170 @@
+/**
+ * Help, generated from the command definitions (D140 items 8 and 16): `--help` for people,
+ * `--help --json` for agents (the definition itself), and `docs/reference/cli.md`, which CI
+ * checks is current. The wording lives in the definitions; this module only lays it out.
+ */
+import { type CommandDef, commandName, type FlagDef } from "./command.ts";
+import { EXIT } from "./exit.ts";
+import { GLOBAL_FLAGS, topWords } from "./parse.ts";
+
+const EXIT_MEANING: Readonly<Record<number, string>> = {
+  [EXIT.ok]: "success",
+  [EXIT.failure]:
+    "artifact failure (verify failed, publish refused, the artifact's state refused the request)",
+  [EXIT.usage]: "usage error",
+  [EXIT.environment]:
+    "environment error (no runtime, browser or socket; the home; an unsupported platform)",
+  [EXIT.timeout]: "timeout (--timeout passed)",
+  [EXIT.stillWaiting]: "still waiting (the wait timed out; the result says where to resume)",
+  [EXIT.conflict]: "conflict (already submitted, a compare-and-set mismatch, a reused request ID)",
+};
+
+/** The usage line: `mostra open <artifact> [flags]`. */
+export function usageLine(command: CommandDef): string {
+  const args = (command.args ?? []).map((arg) => {
+    const name = arg.variadic ? `<${arg.name}…>` : `<${arg.name}>`;
+    return arg.optional ? `[${name}]` : name;
+  });
+  return [
+    "mostra",
+    ...command.path,
+    ...args,
+    ...((command.flags ?? []).length > 0 ? ["[flags]"] : []),
+  ].join(" ");
+}
+
+function flagLine(flag: FlagDef): string {
+  const name = `--${flag.name}${flag.kind === "boolean" ? "" : ` ${flag.value ?? `<${flag.kind}>`}`}`;
+  const choices = flag.choices ? ` (${flag.choices.join(", ")})` : "";
+  const fallback = flag.default !== undefined ? ` Default: ${flag.default}.` : "";
+  return `  ${name.padEnd(28)} ${flag.summary}${choices}${fallback}`;
+}
+
+/** Commands that run until their connection or Ctrl-C ends them: `--timeout` doesn't bound them. */
+export const UNBOUNDED: ReadonlySet<string> = new Set(["host", "dev"]);
+
+/**
+ * The global flags a command doesn't define again (`wait --timeout` is the wait's own); a command
+ * `--timeout` doesn't bound has no `--timeout`.
+ */
+function globalFlagsOf(command: CommandDef): FlagDef[] {
+  const own = new Set((command.flags ?? []).map((flag) => flag.name));
+  if (UNBOUNDED.has(command.path[0] ?? "")) own.add("timeout");
+  return GLOBAL_FLAGS.filter((flag) => !own.has(flag.name));
+}
+
+/** Every exit code a command can end with, sorted: `--timeout` can end any it bounds with 4. */
+export function exitCodes(command: CommandDef): number[] {
+  const bounded = !UNBOUNDED.has(command.path[0] ?? "") && command.path[0] !== "wait";
+  return [
+    ...new Set([
+      EXIT.ok,
+      ...command.exits,
+      EXIT.usage,
+      EXIT.environment,
+      ...(bounded ? [EXIT.timeout] : []),
+    ]),
+  ].sort((a, b) => a - b);
+}
+
+/** One command's help, for people. */
+export function commandHelp(command: CommandDef): string {
+  const lines = [command.summary, "", "Usage:", `  ${usageLine(command)}`];
+  if ((command.args ?? []).length > 0) {
+    lines.push("", "Arguments:");
+    for (const arg of command.args ?? [])
+      lines.push(`  ${`<${arg.name}>`.padEnd(28)} ${arg.summary}`);
+  }
+  if ((command.flags ?? []).length > 0) {
+    lines.push("", "Flags:");
+    for (const flag of command.flags ?? []) lines.push(flagLine(flag));
+  }
+  lines.push("", "Global flags:");
+  for (const flag of globalFlagsOf(command)) lines.push(flagLine(flag));
+  lines.push("", `Output: ${command.output.type} (mostra docs ${command.output.topic})`);
+  lines.push("", "Exit codes:");
+  for (const code of exitCodes(command)) lines.push(`  ${code}  ${EXIT_MEANING[code] ?? ""}`);
+  lines.push("", "Example:", `  mostra ${command.example}`, "");
+  return lines.join("\n");
+}
+
+/** A group's help (`mostra daemon --help`): its commands. */
+export function groupHelp(commands: readonly CommandDef[], group: string): string {
+  const members = commands.filter((command) => command.path[0] === group);
+  return [
+    `mostra ${group}: ${members.length} commands.`,
+    "",
+    ...members.map((command) => `  ${commandName(command).padEnd(22)} ${command.summary}`),
+    "",
+    `Run "mostra ${group} <command> --help" for one of them.`,
+    "",
+  ].join("\n");
+}
+
+/** The top-level help: every command. */
+export function topHelp(commands: readonly CommandDef[]): string {
+  return [
+    "Mostra, the agent artifact runtime: write ordinary React, verify it, publish it, share the link, wait for answers.",
+    "",
+    "Usage:",
+    "  mostra <command> [arguments] [flags]",
+    "",
+    "Commands:",
+    ...commands.map((command) => `  ${commandName(command).padEnd(22)} ${command.summary}`),
+    "",
+    "Global flags:",
+    ...GLOBAL_FLAGS.map(flagLine),
+    "",
+    'Run "mostra <command> --help" for a command, and "mostra docs" for the reference.',
+    "",
+  ].join("\n");
+}
+
+/** One command's machine-readable definition (`--help --json`). */
+export function commandDefinition(command: CommandDef): Record<string, unknown> {
+  return {
+    command: commandName(command),
+    summary: command.summary,
+    usage: usageLine(command),
+    args: (command.args ?? []).map((arg) => ({
+      name: arg.name,
+      summary: arg.summary,
+      optional: arg.optional === true,
+      variadic: arg.variadic === true,
+    })),
+    flags: [...(command.flags ?? []), ...globalFlagsOf(command)].map((flag) => ({
+      name: flag.name,
+      type: flag.kind,
+      summary: flag.summary,
+      ...(flag.choices ? { choices: flag.choices } : {}),
+      ...(flag.default !== undefined ? { default: flag.default } : {}),
+      global: GLOBAL_FLAGS.includes(flag),
+    })),
+    output: command.output,
+    exitCodes: exitCodes(command).map((code) => ({ code, meaning: EXIT_MEANING[code] ?? "" })),
+    stdin: typeof command.readsStdin === "function" ? "sometimes" : command.readsStdin === true,
+    streams: command.streams === true,
+    example: `mostra ${command.example}`,
+  };
+}
+
+/** `docs/reference/cli.md`: every command's help as one page. */
+export function referenceMarkdown(commands: readonly CommandDef[]): string {
+  const sections = commands.map(
+    (command) =>
+      `## mostra ${commandName(command)}\n\n\`\`\`text\n${commandHelp(command).trimEnd()}\n\`\`\`\n`,
+  );
+  return [
+    "# The mostra CLI",
+    "",
+    "<!-- Generated from the command definitions in packages/cli/src/commands/. Don't edit; run `pnpm fix`. -->",
+    "",
+    'Every command takes `--json`, which prints one envelope on stdout: `{ "ok": true, "result", "instance", "warnings" }` or `{ "ok": false, "error", "warnings" }`. Streaming commands print one envelope per line, the last one carrying `result` or `error`. Logs and progress go to stderr. Without a terminal, or with `--json`, no command asks a question.',
+    "",
+    `Commands: ${topWords(commands)
+      .map((word) => `\`${word}\``)
+      .join(", ")}.`,
+    "",
+    ...sections,
+  ].join("\n");
+}

package/src/home.ts

@@ -0,0 +1,111 @@
+/**
+ * Where the CLI's things are: the home (D84's order), the runtime it starts, the home's settings
+ * it reads, and the CLI's own config directory (D140 item 5). Resolving a path never touches the
+ * file system; the runtime owns everything inside the home.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { resolveRuntime } from "@mostra/sdk";
+
+/** The environment the CLI reads. */
+export type Environment = Readonly<Record<string, string | undefined>>;
+
+const nonEmpty = (value: string | undefined): string | undefined =>
+  value === undefined || value === "" ? undefined : value;
+
+/**
+ * The home, in D84's order: `--home`, then `MOSTRA_HOME`, then the platform default (`~/.mostra`
+ * on macOS, `${XDG_DATA_HOME:-~/.local/share}/mostra` on Linux), the same order the runtime uses.
+ */
+export function resolveHome(options: {
+  readonly home?: string | undefined;
+  readonly env: Environment;
+  readonly cwd: string;
+  readonly platform?: string;
+}): string {
+  const chosen = nonEmpty(options.home) ?? nonEmpty(options.env["MOSTRA_HOME"]);
+  if (chosen !== undefined) return resolve(options.cwd, chosen);
+  const user = nonEmpty(options.env["HOME"]) ?? homedir();
+  if ((options.platform ?? process.platform) === "darwin") return join(user, ".mostra");
+  const data = nonEmpty(options.env["XDG_DATA_HOME"]);
+  return join(
+    data !== undefined && isAbsolute(data) ? data : join(user, ".local", "share"),
+    "mostra",
+  );
+}
+
+/**
+ * The CLI's config directory (D140 item 5): `MOSTRA_CONFIG_DIR`, else
+ * `${XDG_CONFIG_HOME:-~/.config}/mostra`, on both platforms. It holds telemetry's choice and
+ * queue, per operating-system user, never per home.
+ */
+export function configDir(env: Environment, cwd: string): string {
+  const override = nonEmpty(env["MOSTRA_CONFIG_DIR"]);
+  if (override !== undefined) return resolve(cwd, override);
+  const xdg = nonEmpty(env["XDG_CONFIG_HOME"]);
+  const base =
+    xdg !== undefined && isAbsolute(xdg)
+      ? xdg
+      : join(nonEmpty(env["HOME"]) ?? homedir(), ".config");
+  return join(base, "mostra");
+}
+
+/** The runtime the CLI starts: its Node.js and its `mostra-runtime` entry. */
+export interface RuntimeLocation {
+  /** The Node.js to run it with: the runtime bundle's own, or this process's for a checkout. */
+  readonly node: string;
+  /** `mostra-runtime`'s entry. */
+  readonly entry: string;
+}
+
+/**
+ * The runtime the CLI starts (D85, RT-01), found as the SDK finds it: `MOSTRA_BUNDLE`,
+ * `MOSTRA_RUNTIME_BIN`, the runtime bundle this CLI sits in, or a development checkout's built
+ * runtime beside it. The bootstrap (`bootstrap.ts`) has already moved a CLI installed from npm
+ * into its pinned bundle, so this never downloads. Throws the SDK's diagnostic when there is none.
+ */
+export async function locateRuntime(env: Environment): Promise<RuntimeLocation> {
+  const runtime = await resolveRuntime({ env });
+  return { node: runtime.node, entry: runtime.runtimeEntry };
+}
+
+/** What the CLI reads of a home's `config.json` (DATA_MODEL §1). */
+export interface HomeMarks {
+  /** The first host that configured the home (D140 item 4), if any. */
+  readonly hostConfigured?: { readonly client: string; readonly at: string };
+  /** Whether the file couldn't be read as settings: the CLI then treats the home as a host's. */
+  readonly unreadable?: true;
+}
+
+/**
+ * Whether the CLI treats the home as a host's, which sends no telemetry (D140 item 4): a host
+ * marked it, or its `config.json` can't be read as settings (fail closed). One rule for the
+ * runner and for `mostra telemetry` (Opus review finding 6).
+ */
+export function embeddedHome(marks: HomeMarks): boolean {
+  return marks.hostConfigured !== undefined || marks.unreadable === true;
+}
+
+/**
+ * The home's host mark, read from `config.json` without the instance, for commands that never
+ * reach one. A file that can't be read as JSON counts as a host's home, so telemetry fails closed.
+ */
+export function readHomeMarks(home: string): HomeMarks {
+  let text: string;
+  try {
+    text = readFileSync(join(home, "config.json"), "utf8");
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT" ? {} : { unreadable: true };
+  }
+  try {
+    const data = JSON.parse(text) as { hostConfigured?: { client?: unknown; at?: unknown } };
+    const mark = data.hostConfigured;
+    if (mark === undefined) return {};
+    return typeof mark.client === "string" && typeof mark.at === "string"
+      ? { hostConfigured: { client: mark.client, at: mark.at } }
+      : { unreadable: true };
+  } catch {
+    return { unreadable: true };
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * `@mostra/cli`: the `mostra` command (D60, INTERFACES §9), a thin client of the host protocol
+ * that agents and people run. Its binary is `mostra`; this entry exposes the runner and the
+ * command definitions, for the generated reference and for tools that embed the CLI's surface.
+ *
+ * @packageDocumentation
+ */
+
+export type { InstanceConnection, InstanceSummary } from "./client.ts";
+export type {
+  ArgDef,
+  CommandContext,
+  CommandDef,
+  CommandOutcome,
+  FlagDef,
+  FlagKind,
+  TelemetryEventInput,
+} from "./command.ts";
+export { COMMANDS } from "./commands/index.ts";
+export { EXIT, type ExitCode, exitCodeFor } from "./exit.ts";
+export { commandDefinition, commandHelp, referenceMarkdown } from "./help.ts";
+export type { Environment } from "./home.ts";
+export { type RunnerIo, run } from "./run.ts";

package/src/node-gate.ts

@@ -0,0 +1,15 @@
+/**
+ * The first thing `mostra` does (RT-01, D142): a copy installed from npm starts on the machine's
+ * Node.js, which must be 22.19 or later to find and start the runtime bundle (the SDK's download
+ * and extraction need it). An older one fails closed with `MOSTRA_ENV_NODE_UNSUPPORTED` before
+ * anything else loads, so nothing breaks half-way on an API it lacks. This module imports nothing.
+ */
+
+/** The oldest Node.js `mostra` starts on, as `[major, minor]`. */
+export const MINIMUM_NODE: readonly [number, number] = [22, 19];
+
+/** Whether `version` (`process.versions.node`, `22.18.0`) is older than {@link MINIMUM_NODE}. */
+export function nodeTooOld(version: string): boolean {
+  const [major = 0, minor = 0] = version.split(".").map((part) => Number.parseInt(part, 10));
+  return major < MINIMUM_NODE[0] || (major === MINIMUM_NODE[0] && minor < MINIMUM_NODE[1]);
+}

package/src/parse.ts

@@ -0,0 +1,246 @@
+/**
+ * The command line, read against the command definitions (D140 item 13): the global flags, the
+ * command path, its arguments and flags. Every failure is `MOSTRA_CLI_USAGE` or
+ * `MOSTRA_CLI_UNKNOWN_COMMAND`, so `--json` mode reports it like any other error.
+ */
+import { parseArgs } from "node:util";
+import { createDiagnostic, RpcError } from "@mostra/protocol";
+import { type CommandDef, commandName, type FlagDef } from "./command.ts";
+
+/** The flags every command takes (INTERFACES §9). */
+export const GLOBAL_FLAGS: readonly FlagDef[] = [
+  {
+    name: "json",
+    kind: "boolean",
+    summary: "Print one JSON envelope on stdout (NDJSON for streams).",
+  },
+  {
+    name: "home",
+    kind: "string",
+    value: "<dir>",
+    summary: "Use this Mostra home instead of MOSTRA_HOME or the default.",
+  },
+  {
+    name: "cwd",
+    kind: "string",
+    value: "<dir>",
+    summary: "Resolve relative paths from this directory.",
+  },
+  {
+    name: "timeout",
+    kind: "duration",
+    value: "<d>",
+    summary: "Give up on the instance after this long (exit 4), such as 30s or 5m.",
+  },
+  {
+    name: "help",
+    kind: "boolean",
+    summary: "Show this command's help; with --json, its definition.",
+  },
+];
+
+/** What the command line asks for. */
+export type Parsed =
+  | { readonly kind: "version" }
+  | { readonly kind: "help"; readonly command?: CommandDef; readonly group?: string }
+  | {
+      readonly kind: "run";
+      readonly command: CommandDef;
+      readonly args: Record<string, string | readonly string[] | undefined>;
+      readonly flags: Record<string, string | number | boolean | readonly string[] | undefined>;
+    };
+
+/** The global flags' values, read before anything else so a usage error still honors them. */
+export interface GlobalFlags {
+  readonly json: boolean;
+  readonly home?: string;
+  readonly cwd?: string;
+  readonly timeoutMs?: number;
+}
+
+/** A usage error. */
+export function usage(message: string): RpcError {
+  return new RpcError(createDiagnostic("MOSTRA_CLI_USAGE", { message }));
+}
+
+const DURATION = /^([1-9][0-9]*)(ms|s|m|h|d)$/;
+const UNIT_MS: Readonly<Record<string, number>> = {
+  ms: 1,
+  s: 1000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};
+
+/** A duration flag's milliseconds: `30s`, `5m`, `2h`, `7d`, `500ms`. */
+export function durationMs(value: string): number {
+  const match = DURATION.exec(value);
+  if (!match)
+    throw usage(`"${value}" isn't a duration; use a number with ms, s, m, h or d, such as 30s.`);
+  return Number(match[1]) * (UNIT_MS[match[2] as string] as number);
+}
+
+/**
+ * Reads the global flags wherever they stand, before the command is known: `--json` anywhere
+ * before `--` makes even a usage error a JSON envelope (D140 item 16).
+ */
+export function globalFlags(argv: readonly string[]): GlobalFlags {
+  const end = argv.indexOf("--");
+  const words = end === -1 ? argv : argv.slice(0, end);
+  const value = (name: string): string | undefined => {
+    for (let index = 0; index < words.length; index += 1) {
+      const word = words[index] as string;
+      if (word === `--${name}`) return words[index + 1];
+      if (word.startsWith(`--${name}=`)) return word.slice(name.length + 3);
+    }
+    return undefined;
+  };
+  const timeout = value("timeout");
+  let timeoutMs: number | undefined;
+  try {
+    timeoutMs = timeout === undefined ? undefined : durationMs(timeout);
+  } catch {
+    timeoutMs = undefined;
+  }
+  const home = value("home");
+  const cwd = value("cwd");
+  return {
+    json: words.includes("--json"),
+    ...(home !== undefined ? { home } : {}),
+    ...(cwd !== undefined ? { cwd } : {}),
+    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+  };
+}
+
+/** The command that names `words`' longest prefix. */
+function findCommand(
+  commands: readonly CommandDef[],
+  words: readonly string[],
+): { command: CommandDef; used: number } | undefined {
+  let best: { command: CommandDef; used: number } | undefined;
+  for (const command of commands) {
+    const { path } = command;
+    if (path.length <= words.length && path.every((word, index) => words[index] === word)) {
+      if (!best || path.length > best.used) best = { command, used: path.length };
+    }
+  }
+  return best;
+}
+
+/** The first words of every command: the groups and the single-word commands. */
+export function topWords(commands: readonly CommandDef[]): string[] {
+  return [...new Set(commands.map((command) => command.path[0] as string))].sort();
+}
+
+/** Parses the command line against the definitions. Throws a usage diagnostic. */
+export function parseCommandLine(commands: readonly CommandDef[], argv: readonly string[]): Parsed {
+  const bare = argv.filter((word) => word !== "--json");
+  if (bare.length === 1 && (bare[0] === "--version" || bare[0] === "-v"))
+    return { kind: "version" };
+  // The command path is the leading words that aren't flags; global flags may stand before it.
+  const words: string[] = [];
+  const pathAt: number[] = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const word = argv[index] as string;
+    if (word === "--json" || word === "--help" || word === "-h") continue;
+    if (word === "--home" || word === "--cwd" || word === "--timeout") {
+      index += 1;
+      continue;
+    }
+    if (/^--(home|cwd|timeout)=/.test(word)) continue;
+    if (word.startsWith("-")) break;
+    words.push(word);
+    pathAt.push(index);
+  }
+  const helpAsked = argv.includes("--help") || argv.includes("-h");
+  if (words.length === 0) {
+    if (helpAsked || argv.every((word) => word === "--json")) return { kind: "help" };
+    throw usage(`Name a command first; ${argv[0]} isn't one.`);
+  }
+  const found = findCommand(commands, words);
+  if (!found) {
+    const group = commands.filter((command) => command.path[0] === words[0]);
+    if (group.length > 0) {
+      if (helpAsked) return { kind: "help", group: words[0] as string };
+      throw usage(
+        `"mostra ${words[0]}" needs one of: ${group.map((command) => command.path.slice(1).join(" ")).join(", ")}.`,
+      );
+    }
+    throw new RpcError(
+      createDiagnostic("MOSTRA_CLI_UNKNOWN_COMMAND", {
+        message: `"${words[0]}" isn't a mostra command. The commands are: ${topWords(commands).join(", ")}.`,
+      }),
+    );
+  }
+  const { command } = found;
+  if (helpAsked) return { kind: "help", command };
+  const used = new Set(pathAt.slice(0, found.used));
+  const rest = argv.filter((_, index) => !used.has(index));
+  const flagDefs = [...GLOBAL_FLAGS, ...(command.flags ?? [])];
+  let parsed: ReturnType<typeof parseArgs>;
+  try {
+    parsed = parseArgs({
+      args: [...rest],
+      allowPositionals: true,
+      strict: true,
+      options: Object.fromEntries(
+        flagDefs.map((flag) => [
+          flag.name,
+          { type: flag.kind === "boolean" ? "boolean" : "string" },
+        ]),
+      ) as Parameters<typeof parseArgs>[0] extends { options?: infer O } ? NonNullable<O> : never,
+    });
+  } catch (error) {
+    throw usage(
+      `${(error as Error).message.split(". To specify")[0]}. Run "mostra ${commandName(command)} --help".`,
+    );
+  }
+  const flags: Record<string, string | number | boolean | readonly string[] | undefined> = {};
+  for (const flag of command.flags ?? []) {
+    const raw = parsed.values[flag.name];
+    if (raw === undefined) continue;
+    if (flag.kind === "boolean") {
+      flags[flag.name] = raw === true;
+      continue;
+    }
+    const text = String(raw);
+    if (flag.choices && !flag.choices.includes(text)) {
+      throw usage(`--${flag.name} takes one of ${flag.choices.join(", ")}; "${text}" isn't one.`);
+    }
+    if (flag.kind === "number") {
+      const number = Number(text);
+      if (!Number.isInteger(number) || number < 0)
+        throw usage(`--${flag.name} takes a whole number; "${text}" isn't one.`);
+      flags[flag.name] = number;
+    } else if (flag.kind === "duration") {
+      durationMs(text);
+      flags[flag.name] = text;
+    } else if (flag.kind === "list") {
+      flags[flag.name] = text
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+    } else flags[flag.name] = text;
+  }
+  const positionals = [...parsed.positionals];
+  const args: Record<string, string | readonly string[] | undefined> = {};
+  for (const arg of command.args ?? []) {
+    if (arg.variadic) {
+      if (positionals.length === 0 && !arg.optional)
+        throw usage(`"mostra ${commandName(command)}" needs <${arg.name}…>.`);
+      args[arg.name] = positionals.splice(0);
+      continue;
+    }
+    const value = positionals.shift();
+    if (value === undefined && !arg.optional)
+      throw usage(`"mostra ${commandName(command)}" needs <${arg.name}>.`);
+    args[arg.name] = value;
+  }
+  if (positionals.length > 0) {
+    throw usage(
+      `"mostra ${commandName(command)}" takes no argument "${positionals[0]}". Run "mostra ${commandName(command)} --help".`,
+    );
+  }
+  if (typeof parsed.values["timeout"] === "string") durationMs(parsed.values["timeout"]);
+  return { kind: "run", command, args, flags };
+}