@mostra/cli 0.0.0-stage → 0.2.0

package/src/commands/interaction.ts

@@ -0,0 +1,288 @@
+/**
+ * Interaction: `wait`, `results`, `push` and `state get|set|patch`, thin clients of `wait`,
+ * `results/get`, `live/push` and `state/*` (INTERFACES §6, D101). `wait` ends with exit 5 when it
+ * times out (`still_waiting`), and a write that meets a conflict with exit 6.
+ */
+import {
+  FieldOp,
+  livePushMethod,
+  MutationId,
+  resultsGetMethod,
+  stateGetMethod,
+  statePatchMethod,
+  type WaitCondition,
+  type WaitResult,
+  waitMethod,
+} from "@mostra/protocol";
+import { type CommandDef, defineCommand } from "../command.ts";
+import { EXIT } from "../exit.ts";
+import { durationMs, usage } from "../parse.ts";
+import { arg, artifactRef, flag, jsonInput, parseJson, pretty } from "./shared.ts";
+
+/** The longest one `wait` request may ask for (INTERFACES §6: 2^31 − 1 ms). */
+const MAX_WAIT_MS = 2 ** 31 - 1;
+
+/** `mostra wait <artifact>`. */
+export const waitCommand: CommandDef = defineCommand({
+  path: ["wait"],
+  summary:
+    "Block until an artifact's submission, signal, state change or event; still_waiting on timeout.",
+  args: [{ name: "artifact", summary: "The artifact: its source path or its ID." }],
+  flags: [
+    {
+      name: "until",
+      kind: "string",
+      value: "<condition>",
+      summary: "submitted, signal:<name>, state:<fieldId> or event:<type>.",
+    },
+    {
+      name: "after",
+      kind: "string",
+      value: "<cursor>",
+      summary: "Wait for what comes after this cursor. Default: the latest publish.",
+    },
+    {
+      name: "timeout",
+      kind: "duration",
+      value: "<d>",
+      summary: "Stop waiting after this long, with still_waiting and exit 5. Default: no limit.",
+    },
+  ],
+  output: { type: "WaitResult", topic: "cli" },
+  exits: [EXIT.failure, EXIT.stillWaiting],
+  example: "wait ./sidebar-review --until submitted --timeout 30m",
+  async run(context) {
+    const until = flag(context, "until");
+    if (until === undefined) throw usage('"mostra wait" needs --until, such as --until submitted.');
+    const timeout = flag(context, "timeout");
+    const deadline = timeout === undefined ? undefined : Date.now() + durationMs(timeout);
+    const artifact = artifactRef(arg(context, "artifact"), context.cwd);
+    let after = flag(context, "after");
+    for (;;) {
+      const remaining = deadline === undefined ? MAX_WAIT_MS : Math.max(0, deadline - Date.now());
+      const result: WaitResult = await context.call(waitMethod, {
+        artifact,
+        until: until as WaitCondition,
+        timeoutMs: Math.min(remaining, MAX_WAIT_MS),
+        ...(after !== undefined ? { after } : {}),
+      });
+      if (result.status === "satisfied") {
+        return { result, human: `${result.event.type} at cursor ${result.cursor}\n` };
+      }
+      // No limit: wait again from the newest cursor examined, so nothing is missed.
+      if (deadline === undefined) {
+        after = result.cursor;
+        continue;
+      }
+      return {
+        result,
+        human: `still waiting; resume with --after ${result.cursor}\n`,
+        exit: EXIT.stillWaiting,
+      };
+    }
+  },
+});
+
+/** `mostra results <artifact>`. */
+export const resultsCommand: CommandDef = defineCommand({
+  path: ["results"],
+  summary:
+    "Print an artifact's submission in full: answers, state, choices, comments, actions and signals.",
+  args: [{ name: "artifact", summary: "The artifact: its source path or its ID." }],
+  flags: [
+    {
+      name: "submission",
+      kind: "string",
+      value: "<id>",
+      summary: "This submission instead of the latest.",
+    },
+    {
+      name: "format",
+      kind: "string",
+      value: "<format>",
+      choices: ["md", "json"],
+      summary: "Markdown or JSON. Default: Markdown, or JSON with --json.",
+    },
+  ],
+  output: { type: "Results", topic: "cli" },
+  exits: [EXIT.failure],
+  example: "results ./sidebar-review",
+  async run(context) {
+    const format = (flag(context, "format") ?? (context.json ? "json" : "md")) as "md" | "json";
+    const submission = flag(context, "submission");
+    const result = await context.call(resultsGetMethod, {
+      artifact: artifactRef(arg(context, "artifact"), context.cwd),
+      format,
+      ...(submission !== undefined ? { submission } : {}),
+    });
+    const markdown =
+      typeof result === "object" && result !== null && "markdown" in result
+        ? (result as { markdown: string }).markdown
+        : undefined;
+    return { result, human: markdown !== undefined ? `${markdown.trimEnd()}\n` : pretty(result) };
+  },
+});
+
+/** `mostra push <artifact> <key>`. */
+export const pushCommand: CommandDef = defineCommand({
+  path: ["push"],
+  summary: "Push a value into an artifact's live source; pages showing it update at once.",
+  args: [
+    { name: "artifact", summary: "The artifact: its source path or its ID." },
+    { name: "key", summary: "The live source's key: its export name in live.ts, or a new one." },
+  ],
+  flags: [
+    { name: "value", kind: "string", value: "<json>", summary: "The value, as JSON." },
+    { name: "file", kind: "string", value: "<path>", summary: "Read the value from a JSON file." },
+    { name: "stdin", kind: "boolean", summary: "Read the value from stdin." },
+    {
+      name: "append",
+      kind: "boolean",
+      summary: "Add the value to the source's ring instead of replacing it.",
+    },
+    {
+      name: "request-id",
+      kind: "string",
+      value: "<id>",
+      summary: "Make a retry return the first attempt's revision.",
+    },
+  ],
+  output: { type: "LivePushResult", topic: "cli" },
+  exits: [EXIT.failure],
+  example: `push ./dashboard prices --value '{"btc": 64000}'`,
+  readsStdin: (flags) => flags["stdin"] === true,
+  async run(context) {
+    const value = await jsonInput(context);
+    const requestId = flag(context, "request-id");
+    const result = await context.call(livePushMethod, {
+      artifact: artifactRef(arg(context, "artifact"), context.cwd),
+      key: arg(context, "key"),
+      value,
+      ...(context.flags["append"] === true ? { mode: "append" as const } : {}),
+      ...(requestId !== undefined ? { requestId } : {}),
+    });
+    return { result, human: `revision ${result.revision}\n` };
+  },
+});
+
+const writeFlags = [
+  {
+    name: "base",
+    kind: "string" as const,
+    value: "<revision>",
+    summary:
+      "Write only if the fields are unchanged since this revision; else a conflict (exit 6).",
+  },
+  {
+    name: "as",
+    kind: "string" as const,
+    value: "<actor>",
+    choices: ["agent", "host"],
+    default: "agent",
+    summary: "Who the change is attributed to.",
+  },
+  {
+    name: "mutation-id",
+    kind: "string" as const,
+    value: "<mut_…>",
+    summary: "Make a retry return the first attempt's result.",
+  },
+];
+
+/** `mostra state get <artifact> [ids…]`. */
+export const stateGetCommand: CommandDef = defineCommand({
+  path: ["state", "get"],
+  summary: "Read an artifact's state: the fields every viewer shares, with their revisions.",
+  args: [
+    { name: "artifact", summary: "The artifact: its source path or its ID." },
+    { name: "id", summary: "Only these field IDs.", optional: true, variadic: true },
+  ],
+  output: { type: "StateGetResult", topic: "cli" },
+  exits: [EXIT.failure],
+  example: "state get ./tasks priorities",
+  async run(context) {
+    const ids = context.args["id"] as readonly string[] | undefined;
+    const result = await context.call(stateGetMethod, {
+      artifact: artifactRef(arg(context, "artifact"), context.cwd),
+      ...(ids !== undefined && ids.length > 0 ? { ids: [...ids] } : {}),
+    });
+    return { result, human: pretty(result) };
+  },
+});
+
+/** Sends one state mutation; a conflict ends with exit 6. */
+async function patch(
+  context: Parameters<(typeof stateGetCommand)["run"]>[0],
+  ops: readonly FieldOp[],
+): Promise<{ result: unknown; human: string; exit?: number }> {
+  const base = flag(context, "base");
+  const as = (flag(context, "as") ?? "agent") as "agent" | "host";
+  const result = await context.call(statePatchMethod, {
+    artifact: artifactRef(arg(context, "artifact"), context.cwd),
+    ops,
+    mutationId: flag(context, "mutation-id") ?? MutationId.create(),
+    as,
+    ...(base !== undefined ? { baseRevision: base } : {}),
+  });
+  const conflicted = result.conflicts.length > 0;
+  return {
+    result,
+    human: conflicted
+      ? `conflict on ${result.conflicts.map((conflict) => conflict.id).join(", ")}; revision ${result.revision}\n`
+      : `revision ${result.revision}\n`,
+    ...(conflicted ? { exit: EXIT.conflict } : {}),
+  };
+}
+
+/** `mostra state set <artifact> <id> <json>`. */
+export const stateSetCommand: CommandDef = defineCommand({
+  path: ["state", "set"],
+  summary: "Set one field of an artifact's state; viewers see it at once.",
+  args: [
+    { name: "artifact", summary: "The artifact: its source path or its ID." },
+    { name: "id", summary: "The field ID." },
+    { name: "value", summary: "The value, as JSON." },
+  ],
+  flags: writeFlags,
+  output: { type: "StatePatchResult", topic: "cli" },
+  exits: [EXIT.failure, EXIT.conflict],
+  example: `state set ./tasks priorities '["Ship the CLI"]'`,
+  async run(context) {
+    return patch(context, [
+      { id: arg(context, "id"), value: parseJson(arg(context, "value"), "<value>") },
+    ]);
+  },
+});
+
+/** `mostra state patch <artifact>`. */
+export const statePatchCommand: CommandDef = defineCommand({
+  path: ["state", "patch"],
+  summary:
+    "Change several fields of an artifact's state in one revision: [{ id, value } | { id, delete: true }].",
+  args: [{ name: "artifact", summary: "The artifact: its source path or its ID." }],
+  flags: [
+    { name: "ops", kind: "string", value: "<json>", summary: "The operations, as JSON." },
+    {
+      name: "file",
+      kind: "string",
+      value: "<path>",
+      summary: "Read the operations from a JSON file.",
+    },
+    { name: "stdin", kind: "boolean", summary: "Read the operations from stdin." },
+    ...writeFlags,
+  ],
+  output: { type: "StatePatchResult", topic: "cli" },
+  exits: [EXIT.failure, EXIT.conflict],
+  example: `state patch ./tasks --file ops.json`,
+  readsStdin: (flags) => flags["stdin"] === true,
+  async run(context) {
+    const ops = await jsonInput(context, "ops");
+    const parsed = FieldOp.array().safeParse(ops);
+    if (!parsed.success || parsed.data.length === 0) {
+      throw usage(
+        "The operations must be a non-empty JSON array of { id, value } or { id, delete: true }.",
+      );
+    }
+    return patch(context, parsed.data);
+  },
+});

package/src/commands/shared.ts

@@ -0,0 +1,71 @@
+/**
+ * What commands share: naming artifacts and sources on the command line, and reading JSON values.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { ArtifactRef, SourceRef } from "@mostra/protocol";
+import type { CommandContext } from "../command.ts";
+import { usage } from "../parse.ts";
+
+const ARTIFACT_ID = /^art_[0-9A-HJKMNP-TV-Z]{26}$/;
+
+/** An artifact named by its ID (`art_…`) or by a path, relative ones from `--cwd`. */
+export function artifactRef(value: string, cwd: string): ArtifactRef {
+  return ARTIFACT_ID.test(value) ? { artifactId: value } : { path: resolve(cwd, value) };
+}
+
+/** A source named the same way: a path, or the ID of an artifact (the path it was published from). */
+export function sourceRef(value: string, cwd: string): SourceRef {
+  return ARTIFACT_ID.test(value) ? { artifactId: value } : { path: resolve(cwd, value) };
+}
+
+/** A string argument the parser guaranteed. */
+export function arg(context: CommandContext, name: string): string {
+  const value = context.args[name];
+  if (typeof value !== "string") throw usage(`<${name}> is missing.`);
+  return value;
+}
+
+/** An optional string flag. */
+export function flag(context: CommandContext, name: string): string | undefined {
+  const value = context.flags[name];
+  return typeof value === "string" ? value : undefined;
+}
+
+/** Parses a JSON value given on the command line, in a file or on stdin. */
+export function parseJson(text: string, where: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw usage(`${where} isn't JSON: ${(error as Error).message}`);
+  }
+}
+
+/** Reads a JSON value from `--value`, `--file` or `--stdin`, exactly one of them. */
+export async function jsonInput(context: CommandContext, valueFlag = "value"): Promise<unknown> {
+  const given = [valueFlag, "file", "stdin"].filter(
+    (name) => context.flags[name] !== undefined && context.flags[name] !== false,
+  );
+  if (given.length !== 1) {
+    throw usage(`Give the value with exactly one of --${valueFlag}, --file or --stdin.`);
+  }
+  if (context.flags["stdin"] === true) return parseJson(await context.readStdin(), "stdin");
+  const file = flag(context, "file");
+  if (file !== undefined) {
+    let text: string;
+    try {
+      text = readFileSync(resolve(context.cwd, file), "utf8");
+    } catch (error) {
+      throw usage(
+        `--file ${file} can't be read (${(error as NodeJS.ErrnoException).code ?? "error"}).`,
+      );
+    }
+    return parseJson(text, file);
+  }
+  return parseJson(flag(context, valueFlag) ?? "", `--${valueFlag}`);
+}
+
+/** Indented JSON, for human output of structured results. */
+export function pretty(value: unknown): string {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}

package/src/commands/viewing.ts

@@ -0,0 +1,153 @@
+/**
+ * `mostra open`: the artifact's link on stdout, and a browser opened on a one-time launch URL that
+ * never carries the link's secret (D140 item 15), handed over in a page, never on a command line
+ * (`browser.ts`). A client of `view/default`, `view/url`,
+ * `view/rotate`, `view/revoke` and `view/launch`.
+ */
+import {
+  type CapabilityLink,
+  type CapabilityScope,
+  viewDefaultMethod,
+  viewLaunchMethod,
+  viewRevokeMethod,
+  viewRotateMethod,
+  viewUrlMethod,
+} from "@mostra/protocol";
+import { openInBrowser } from "../browser.ts";
+import { type CommandContext, type CommandDef, defineCommand } from "../command.ts";
+import { EXIT } from "../exit.ts";
+import type { Environment } from "../home.ts";
+import { usage } from "../parse.ts";
+import { arg, artifactRef, flag } from "./shared.ts";
+
+/** Whether this session can show a browser: not over SSH without a display. */
+export function hasDisplay(env: Environment, platform: string = process.platform): boolean {
+  const ssh = env["SSH_CONNECTION"] !== undefined || env["SSH_TTY"] !== undefined;
+  if (platform === "darwin") return !ssh;
+  return env["DISPLAY"] !== undefined || env["WAYLAND_DISPLAY"] !== undefined;
+}
+
+/** Whether `open` should launch a browser: a terminal without `--json`, or `--browser`. */
+function wantsBrowser(context: CommandContext): boolean {
+  if (context.flags["no-browser"] === true) return false;
+  if (context.flags["browser"] === true) return true;
+  return context.tty.stdout && !context.json && hasDisplay(context.env);
+}
+
+/** The link, opened in a browser when wanted. */
+async function show(
+  context: CommandContext,
+  link: CapabilityLink,
+): Promise<{ result: CapabilityLink & { readonly opened: boolean }; human: string }> {
+  let opened = false;
+  if (wantsBrowser(context)) {
+    const launch = await context.call(viewLaunchMethod, { tokenId: link.tokenId });
+    // The launch URL reaches the browser through a 0600 page, never its arguments.
+    opened = await openInBrowser(launch.url, context.env);
+  }
+  return { result: { ...link, opened }, human: `${link.url}\n` };
+}
+
+/** `mostra open <artifact>`. */
+export const openCommand: CommandDef = defineCommand({
+  path: ["open"],
+  summary:
+    "Print an artifact's capability link and open it in a browser; or mint, rotate or revoke a link.",
+  args: [{ name: "artifact", summary: "The artifact: its source path or its ID." }],
+  flags: [
+    {
+      name: "new",
+      kind: "boolean",
+      summary: "Mint a separate link instead of the artifact's default one.",
+    },
+    {
+      name: "version",
+      kind: "string",
+      value: "<n|id>",
+      summary: "A new link that opens only this version.",
+    },
+    {
+      name: "scope",
+      kind: "list",
+      value: "<a,b>",
+      summary: "A new link's scopes: view, draft, submit, review, signal, action:*. Default: all.",
+    },
+    {
+      name: "ttl",
+      kind: "duration",
+      value: "<d>",
+      summary: "A new link that expires after this long, such as 24h.",
+    },
+    {
+      name: "viewer",
+      kind: "string",
+      value: "<ref>",
+      summary: "A new link that acts for this person, by your own stable key for them.",
+    },
+    {
+      name: "viewer-name",
+      kind: "string",
+      value: "<name>",
+      summary: "The display name of --viewer.",
+    },
+    {
+      name: "rotate",
+      kind: "string",
+      value: "<tokenId>",
+      summary: "Replace this link with a new one; the old one stops working.",
+    },
+    { name: "revoke", kind: "string", value: "<tokenId>", summary: "Stop this link from working." },
+    { name: "browser", kind: "boolean", summary: "Open a browser even without a terminal." },
+    { name: "no-browser", kind: "boolean", summary: "Only print the link." },
+    {
+      name: "request-id",
+      kind: "string",
+      value: "<id>",
+      summary: "Make a retried --new return the same link.",
+    },
+  ],
+  output: { type: "CapabilityLink", topic: "cli" },
+  exits: [EXIT.failure],
+  example: "open ./sidebar-review",
+  async run(context) {
+    const artifact = artifactRef(arg(context, "artifact"), context.cwd);
+    const revoke = flag(context, "revoke");
+    const rotate = flag(context, "rotate");
+    if (revoke !== undefined && rotate !== undefined)
+      throw usage("Give --rotate or --revoke, not both.");
+    if (revoke !== undefined) {
+      await context.call(viewRevokeMethod, { tokenId: revoke });
+      return { result: { tokenId: revoke, revoked: true }, human: `Revoked ${revoke}\n` };
+    }
+    if (rotate !== undefined)
+      return show(context, await context.call(viewRotateMethod, { tokenId: rotate }));
+    const version = flag(context, "version");
+    const scopes = context.flags["scope"] as readonly string[] | undefined;
+    const ttl = flag(context, "ttl");
+    const viewerRef = flag(context, "viewer");
+    const viewerName = flag(context, "viewer-name");
+    const requestId = flag(context, "request-id");
+    if (viewerName !== undefined && viewerRef === undefined)
+      throw usage("--viewer-name needs --viewer.");
+    const fresh =
+      context.flags["new"] === true ||
+      version !== undefined ||
+      scopes !== undefined ||
+      ttl !== undefined ||
+      viewerRef !== undefined;
+    if (!fresh) return show(context, await context.call(viewDefaultMethod, { artifact }));
+    const link = await context.call(viewUrlMethod, {
+      artifact,
+      ...(version !== undefined
+        ? { version: /^[0-9]+$/.test(version) ? Number(version) : version }
+        : {}),
+      ...(scopes !== undefined ? { scopes: scopes as CapabilityScope[] } : {}),
+      ...(ttl !== undefined ? { ttl: ttl as `${number}${"s" | "m" | "h" | "d"}` } : {}),
+      ...(viewerRef !== undefined
+        ? { viewer: { ref: viewerRef, ...(viewerName !== undefined ? { name: viewerName } : {}) } }
+        : {}),
+      ...(requestId !== undefined ? { requestId } : {}),
+    });
+    return show(context, link);
+  },
+});

package/src/docs.ts

@@ -0,0 +1,111 @@
+/**
+ * `mostra docs` (D140 item 17): the reference that ships with the CLI, by stable slug. The
+ * diagnostic pages are keyed by code (`mostra docs MOSTRA_DEP_MISSING`, as hints say), beside the
+ * CLI reference and the telemetry page. This index is the one source WP-15's `docs_search` and
+ * WP-26's site read.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_DOCS_BASE } from "@mostra/protocol";
+import { fromSource, packageRoot } from "./version.ts";
+
+/** One topic of the reference. */
+export interface DocsTopic {
+  /** Its stable slug: `cli`, `telemetry`, `errors`, or a diagnostic code. */
+  readonly topic: string;
+  /** Its title, from the page's first heading. */
+  readonly title: string;
+  /** Where the docs site serves it. */
+  readonly url: string;
+  /** Its Markdown file. */
+  readonly file: string;
+}
+
+/** Where the reference is: bundled in the build (`dist/reference`), or the repository's. */
+export function referenceDir(): string {
+  const bundled = join(packageRoot(), "dist", "reference");
+  return !fromSource() && existsSync(bundled)
+    ? bundled
+    : join(packageRoot(), "..", "..", "docs", "reference");
+}
+
+function titleOf(file: string): string {
+  const first = readFileSync(file, "utf8")
+    .split("\n")
+    .find((line) => line.startsWith("# "));
+  return first ? first.slice(2).trim() : "";
+}
+
+/** Every topic, the pages first and then the codes, sorted. */
+export function docsIndex(dir: string = referenceDir()): DocsTopic[] {
+  const base = DEFAULT_DOCS_BASE.replace(/\/+$/, "");
+  const pages: DocsTopic[] = [];
+  for (const topic of ["cli", "telemetry"]) {
+    const file = join(dir, `${topic}.md`);
+    if (existsSync(file))
+      pages.push({ topic, title: titleOf(file), url: `${base}/${topic}`, file });
+  }
+  const errorsDir = join(dir, "errors");
+  const codes = existsSync(errorsDir)
+    ? readdirSync(errorsDir)
+        .filter((name) => /^MOSTRA_[A-Z0-9_]+\.md$/.test(name))
+        .sort()
+    : [];
+  const errors: DocsTopic[] = codes.map((name) => {
+    const code = name.slice(0, -3);
+    const file = join(errorsDir, name);
+    return { topic: code, title: titleOf(file), url: `${base}/errors/${code}`, file };
+  });
+  return [...pages, ...errors];
+}
+
+/** The index as Markdown: what `mostra docs` prints without a topic. */
+export function indexMarkdown(topics: readonly DocsTopic[]): string {
+  const pages = topics.filter((topic) => !topic.topic.startsWith("MOSTRA_"));
+  const codes = topics.filter((topic) => topic.topic.startsWith("MOSTRA_"));
+  return [
+    "# Mostra reference",
+    "",
+    "Run `mostra docs <topic>` to read one. Diagnostic codes are topics too.",
+    "",
+    ...pages.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
+    "",
+    "## Diagnostic codes",
+    "",
+    ...codes.map((topic) => `- \`${topic.topic}\`: ${topic.title}`),
+    "",
+  ].join("\n");
+}
+
+/** The topics nearest an unknown one, for its usage error. */
+export function nearestTopics(wanted: string, topics: readonly DocsTopic[], count = 3): string[] {
+  const target = wanted.toUpperCase();
+  const scored = topics.map((topic) => {
+    const name = topic.topic.toUpperCase();
+    const contains = name.includes(target) || target.includes(name) ? 0 : 1;
+    return { topic: topic.topic, score: contains * 100 + distance(name, target) };
+  });
+  return scored
+    .sort((a, b) => a.score - b.score || (a.topic < b.topic ? -1 : 1))
+    .slice(0, count)
+    .map((item) => item.topic);
+}
+
+/** Levenshtein distance. */
+function distance(a: string, b: string): number {
+  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i += 1) {
+    let previous = row[0] as number;
+    row[0] = i;
+    for (let j = 1; j <= b.length; j += 1) {
+      const current = row[j] as number;
+      row[j] = Math.min(
+        (row[j] as number) + 1,
+        (row[j - 1] as number) + 1,
+        previous + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+      previous = current;
+    }
+  }
+  return row[b.length] as number;
+}