@mostra/cli 0.0.0-stage → 0.2.0

package/dist/run-CMyjOm0Q.js

@@ -0,0 +1,2 @@
+import { t as run } from "./run-BJaRnz-Q.js";
+export { run };

package/dist/telemetry/flush-main.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/telemetry/flush-main.js

@@ -0,0 +1,14 @@
+import { r as TelemetryStore, t as flush } from "../flush-BCuWs0Zh.js";
+//#region src/telemetry/flush-main.ts
+/**
+* The flusher process (D140 item 6): `node flush-main.js <config dir>`, started detached by the
+* CLI. It sends what the queue holds and exits; nothing it does reaches the command that started
+* it.
+*/
+const dir = process.argv[2];
+if (dir !== void 0) await flush(new TelemetryStore(dir), process.env, Date.now).catch(() => {});
+process.exit(0);
+//#endregion
+export {};
+
+//# sourceMappingURL=flush-main.js.map

package/dist/telemetry/flush-main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush-main.js","names":[],"sources":["../../src/telemetry/flush-main.ts"],"sourcesContent":["/**\n * The flusher process (D140 item 6): `node flush-main.js <config dir>`, started detached by the\n * CLI. It sends what the queue holds and exits; nothing it does reaches the command that started\n * it.\n */\nimport { flush } from \"./flush.ts\";\nimport { TelemetryStore } from \"./store.ts\";\n\nconst dir = process.argv[2];\nif (dir !== undefined) {\n  await flush(new TelemetryStore(dir), process.env, Date.now).catch(() => {});\n}\nprocess.exit(0);\n"],"mappings":";;;;;;;AAQA,MAAM,MAAM,QAAQ,KAAK;AACzB,IAAI,QAAQ,KAAA,GACV,MAAM,MAAM,IAAI,eAAe,GAAG,GAAG,QAAQ,KAAK,KAAK,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;AAE5E,QAAQ,KAAK,CAAC"}

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@mostra/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "The mostra command: author, verify, publish, share and wait on agent artifacts, as a thin client of the Mostra host protocol.",
+  "license": "Apache-2.0",
+  "author": "The Mostra Authors",
+  "homepage": "https://github.com/mostra-dev/mostra/tree/main/packages/cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mostra-dev/mostra.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/mostra-dev/mostra/issues",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@mostra/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@mostra/protocol": "0.2.0",
+    "@mostra/sdk": "0.2.0",
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@mostra/runtime": "0.2.0",
+    "@mostra/tools": "0.0.0",
+    "@types/node": "24.19.1",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  },
+  "bin": {
+    "mostra": "./dist/bin.js"
+  },
+  "keywords": [
+    "mostra",
+    "agent",
+    "artifact",
+    "cli"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -b",
+    "test": "vitest run --project unit",
+    "api": "mostra-tools api",
+    "test:integration": "vitest run --project integration"
+  }
 }

package/src/bin.ts

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * `mostra`, the CLI's binary (D60, INTERFACES §9). A copy installed from npm first moves into the
+ * runtime bundle its release pins (`bootstrap.ts`, RT-01); otherwise it runs one command and exits
+ * with its code, after stdout has drained, so a reader never loses the end of the envelope.
+ */
+import { MINIMUM_NODE, nodeTooOld } from "./node-gate.ts";
+
+process.stdout.on("error", () => {});
+process.stderr.on("error", () => {});
+
+/** Refuses a Node.js too old to start Mostra, before anything that needs a newer one loads. */
+async function refuseOldNode(): Promise<number> {
+  const message = `Node.js ${MINIMUM_NODE.join(".")} or later is needed to start Mostra; this is ${process.versions.node}.`;
+  const json = process.argv.includes("--json");
+  try {
+    const { createDiagnostic } = await import("@mostra/protocol");
+    const diagnostic = createDiagnostic("MOSTRA_ENV_NODE_UNSUPPORTED", { message });
+    process.stderr.write(`mostra: ${diagnostic.message}\nmostra: ${diagnostic.hint ?? ""}\n`);
+    if (json)
+      process.stdout.write(`${JSON.stringify({ ok: false, error: diagnostic, warnings: [] })}\n`);
+  } catch {
+    process.stderr.write(`mostra: ${message} (MOSTRA_ENV_NODE_UNSUPPORTED)\n`);
+  }
+  return 3;
+}
+
+const code = nodeTooOld(process.versions.node) ? await refuseOldNode() : await start();
+
+async function start(): Promise<number> {
+  const { bootstrap } = await import("./bootstrap.ts");
+  const booted = await bootstrap({
+    argv: process.argv.slice(2),
+    env: process.env,
+    stdout: (text) => {
+      process.stdout.write(text);
+    },
+    stderr: (text) => {
+      process.stderr.write(text);
+    },
+    stderrTty: process.stderr.isTTY === true,
+    terminal:
+      process.stdin.isTTY === true ||
+      process.stdout.isTTY === true ||
+      process.stderr.isTTY === true,
+  });
+  return (
+    booted ??
+    (await (
+      await import("./run.ts")
+    ).run({
+      argv: process.argv.slice(2),
+      env: process.env,
+      cwd: process.cwd(),
+      stdout: (text) => {
+        process.stdout.write(text);
+      },
+      stderr: (text) => {
+        process.stderr.write(text);
+      },
+      stdin: process.stdin,
+      tty: {
+        stdin: process.stdin.isTTY === true,
+        stdout: process.stdout.isTTY === true,
+        stderr: process.stderr.isTTY === true,
+      },
+    }))
+  );
+}
+process.stdout.write("", () => process.exit(code));

package/src/bootstrap.ts

@@ -0,0 +1,156 @@
+/**
+ * The npm bootstrap (RT-01, D142): a `mostra` installed from npm runs on whatever Node.js the
+ * system has, so before anything else it finds the runtime bundle its release pins (from the
+ * cache, or downloaded once, with progress on stderr) and runs the bundle's own `mostra` with the
+ * same arguments on the bundle's private Node.js. Every command, telemetry included, then runs in
+ * the bundle, and this process only waits and passes the exit code on.
+ *
+ * Inside a bundle, in a development checkout, or with `MOSTRA_BUNDLE`/`MOSTRA_RUNTIME_BIN` set,
+ * there is nothing to bootstrap and the CLI runs in this process.
+ *
+ * This module runs on the system's Node.js, so it uses nothing newer than Node.js 22.19 and loads
+ * none of the CLI's commands.
+ */
+import { spawn } from "node:child_process";
+import { constants } from "node:os";
+import { createDiagnostic, type Diagnostic, RpcError } from "@mostra/protocol";
+import { enclosingBundle, type InstallProgress, readPins, resolveRuntime } from "@mostra/sdk";
+import { exitCodeFor } from "./exit.ts";
+import type { Environment } from "./home.ts";
+
+/** How the bootstrap talks to the terminal. */
+export interface BootstrapIo {
+  readonly argv: readonly string[];
+  readonly env: Environment;
+  readonly stdout: (text: string) => void;
+  readonly stderr: (text: string) => void;
+  /** Whether stderr is a terminal: progress then rewrites one line. */
+  readonly stderrTty: boolean;
+  /**
+   * Whether a terminal is attached (stdin, stdout or stderr is one). Ctrl-C there signals the
+   * whole foreground process group, the bundle's `mostra` included, so SIGINT isn't forwarded:
+   * a second one would cut short a command that stops gracefully on the first (`mostra dev`).
+   */
+  readonly terminal: boolean;
+}
+
+/** Whether this CLI should move into its pinned bundle before running a command. */
+export function needsBootstrap(env: Environment): boolean {
+  if (env["MOSTRA_BUNDLE"] || env["MOSTRA_RUNTIME_BIN"]) return false;
+  if (enclosingBundle() !== undefined) return false;
+  return readPins(env) !== undefined;
+}
+
+/** Progress lines for a person waiting on the first download. */
+function progressReporter(io: BootstrapIo): (progress: InstallProgress) => void {
+  let lastPercent = -1;
+  let lastStep = "";
+  return (progress) => {
+    if (progress.step === "download") {
+      const percent = Math.floor((progress.received / progress.total) * 100);
+      const mb = (bytes: number): string => `${Math.round(bytes / 1e6)} MB`;
+      if (io.stderrTty) {
+        if (percent !== lastPercent)
+          io.stderr(
+            `\rmostra: downloading the Mostra runtime, ${mb(progress.received)} of ${mb(progress.total)} (${percent}%)`,
+          );
+      } else if (
+        lastStep !== "download" ||
+        Math.floor(percent / 25) > Math.floor(lastPercent / 25)
+      ) {
+        io.stderr(`mostra: downloading the Mostra runtime (${mb(progress.total)}): ${percent}%\n`);
+      }
+      lastPercent = percent;
+      lastStep = "download";
+      return;
+    }
+    if (progress.step === lastStep) return;
+    if (lastStep === "download" && io.stderrTty) io.stderr("\n");
+    lastStep = progress.step;
+    const words: Partial<Record<InstallProgress["step"], string>> = {
+      files: "checking the runtime's files",
+      browser: "fetching the browser verify uses",
+    };
+    const said = words[progress.step];
+    if (said !== undefined) io.stderr(`mostra: ${said}…\n`);
+  };
+}
+
+/** The envelope `--json` promises, for a bootstrap that fails before any command runs. */
+function failed(io: BootstrapIo, diagnostic: Diagnostic): number {
+  io.stderr(`mostra: ${diagnostic.message}\n`);
+  if (diagnostic.hint) io.stderr(`mostra: ${diagnostic.hint}\n`);
+  if (io.argv.includes("--json")) {
+    io.stdout(`${JSON.stringify({ ok: false, error: diagnostic, warnings: [] })}\n`);
+  }
+  return exitCodeFor(diagnostic.code);
+}
+
+/**
+ * When this copy needs the bundle its release pins (`needsBootstrap`), runs the bundle's
+ * `mostra` with `io.argv` and resolves with its exit code; otherwise resolves `undefined`, and the
+ * caller runs the command itself. Any failure, deciding included, is a diagnostic (one envelope
+ * with `--json`) and its exit code. Signals this process gets are passed on to the child.
+ */
+export async function bootstrap(io: BootstrapIo): Promise<number | undefined> {
+  try {
+    // Deciding is inside the boundary too: pins that can't be read are a diagnostic, never a
+    // stack trace (GPT review finding 3).
+    if (!needsBootstrap(io.env)) return undefined;
+    return await runInBundle(io);
+  } catch (error) {
+    // Whatever goes wrong, `--json` still gets exactly one envelope (D140 item 16).
+    if (error instanceof RpcError) return failed(io, error.diagnostic);
+    return failed(
+      io,
+      createDiagnostic("MOSTRA_HOST_INTERNAL_ERROR", {
+        message: `The npm bootstrap failed: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  }
+}
+
+async function runInBundle(io: BootstrapIo): Promise<number> {
+  const runtime = await resolveRuntime({ env: io.env, onProgress: progressReporter(io) });
+  if (runtime.cliEntry === undefined) {
+    throw new RpcError(
+      createDiagnostic("MOSTRA_ENV_RUNTIME_MISSING", {
+        message: "The runtime the bootstrap found has no CLI entry.",
+      }),
+    );
+  }
+  const cli = runtime.cliEntry;
+  return new Promise((resolve) => {
+    const child = spawn(runtime.node, [cli, ...io.argv], {
+      stdio: "inherit",
+      env: io.env as NodeJS.ProcessEnv,
+    });
+    const forward = (signal: NodeJS.Signals): void => {
+      if (signal === "SIGINT" && io.terminal) return; // the child got the terminal's own
+      child.kill(signal);
+    };
+    const signals: NodeJS.Signals[] = ["SIGINT", "SIGTERM", "SIGHUP"];
+    for (const signal of signals) process.on(signal, forward);
+    let settled = false;
+    const settle = (code: number): void => {
+      if (settled) return;
+      settled = true;
+      for (const signal of signals) process.off(signal, forward);
+      resolve(code);
+    };
+    child.on("error", (error) =>
+      settle(
+        failed(
+          io,
+          createDiagnostic("MOSTRA_ENV_RUNTIME_MISSING", {
+            message: `The runtime bundle's CLI couldn't be started (${runtime.node}): ${error.message}`,
+          }),
+        ),
+      ),
+    );
+    // A child ended by a signal exits as a shell reports it: 128 plus the signal's number.
+    child.on("exit", (code, signal) =>
+      settle(code ?? 128 + (signal ? (constants.signals[signal] ?? 0) : 0)),
+    );
+  });
+}

package/src/browser.ts

@@ -0,0 +1,186 @@
+/**
+ * Opening a browser on a launch URL without putting it on a command line (D140 item 15, Opus
+ * review finding 4). A program's arguments are readable by every local user (`ps`,
+ * `/proc/<pid>/cmdline`), so the opener gets the path of a page that redirects to the launch URL,
+ * written mode 0600 in a fresh directory of mode 0700, as Jupyter's server does for its token.
+ * The launch ticket in the page is single-use and lives a minute, so a page left behind is
+ * harmless; each launch removes the ones older than that.
+ */
+import { spawn } from "node:child_process";
+import { lstatSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Environment } from "./home.ts";
+
+/** The prefix of the directories launch pages live in. */
+const PREFIX = "mostra-open-";
+/** A launch page older than this holds a ticket that expired: it goes on the next launch. */
+const STALE_MS = 2 * 60_000;
+
+/** Escapes text for an HTML attribute or element. */
+const html = (text: string): string =>
+  text
+    .replaceAll("&", "&amp;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+
+/** The page that sends the browser on to `url`. */
+export function launchPage(url: string): string {
+  // JSON in a script, with `<` escaped so nothing in it ends the script element.
+  const script = JSON.stringify(url).replaceAll("<", "\\u003c");
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="referrer" content="no-referrer">
+<meta http-equiv="refresh" content="0;url=${html(url)}">
+<title>Opening Mostra</title>
+<script>location.replace(${script});</script>
+</head>
+<body>
+<p>Opening the artifact. If nothing happens, <a href="${html(url)}">open it here</a>.</p>
+</body>
+</html>
+`;
+}
+
+/** Removes launch pages of earlier launches that are this user's and older than a minute or two. */
+function sweep(base: string, now: number): void {
+  const uid = process.getuid?.();
+  let names: string[];
+  try {
+    names = readdirSync(base);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (!name.startsWith(PREFIX)) continue;
+    const dir = join(base, name);
+    try {
+      const stats = lstatSync(dir);
+      if (!stats.isDirectory() || (uid !== undefined && stats.uid !== uid)) continue;
+      if (now - stats.mtimeMs < STALE_MS) continue;
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // Gone already, or not ours to remove.
+    }
+  }
+}
+
+/** Writes the launch page for `url`; its path. */
+export function writeLaunchPage(
+  url: string,
+  base: string = tmpdir(),
+  now: number = Date.now(),
+): string {
+  sweep(base, now);
+  // mkdtemp makes the directory with a random name and mode 0700.
+  const dir = mkdtempSync(join(base, PREFIX));
+  const file = join(dir, "open.html");
+  writeFileSync(file, launchPage(url), { mode: 0o600, flag: "wx" });
+  return file;
+}
+
+/**
+ * Splits a command the way a shell would split plain words and quotes, without running one:
+ * `firefox --new-window %s` or `"/Applications/My Browser" %s`.
+ */
+export function splitCommand(command: string): string[] {
+  const words: string[] = [];
+  let word = "";
+  let inWord = false;
+  let quote: '"' | "'" | undefined;
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index] as string;
+    if (quote) {
+      if (char === quote) quote = undefined;
+      else if (char === "\\" && quote === '"' && index + 1 < command.length) {
+        index += 1;
+        word += command[index];
+      } else word += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      inWord = true;
+    } else if (char === "\\" && index + 1 < command.length) {
+      index += 1;
+      word += command[index];
+      inWord = true;
+    } else if (/\s/.test(char)) {
+      if (inWord) words.push(word);
+      word = "";
+      inWord = false;
+    } else {
+      word += char;
+      inWord = true;
+    }
+  }
+  if (inWord) words.push(word);
+  return words;
+}
+
+/**
+ * The commands that may open `target`, in order: each entry of `$BROWSER` (separated by `:`, its
+ * `%s` replaced by the target, else the target appended, `%%` a literal `%`, as `xdg-open` and
+ * Python's `webbrowser` read it), else the platform's opener.
+ */
+export function browserCommands(
+  target: string,
+  env: Environment,
+  platform: string = process.platform,
+): string[][] {
+  const chosen = env["BROWSER"];
+  const entries =
+    chosen !== undefined && chosen.trim() !== ""
+      ? chosen.split(":").filter((entry) => entry.trim() !== "")
+      : [platform === "darwin" ? "open" : "xdg-open"];
+  const commands: string[][] = [];
+  for (const entry of entries) {
+    const words = splitCommand(entry);
+    if (words.length === 0) continue;
+    let substituted = false;
+    const argv = words.map((word) =>
+      word.replaceAll(/%%|%s/g, (match) => {
+        if (match === "%%") return "%";
+        substituted = true;
+        return target;
+      }),
+    );
+    commands.push(substituted ? argv : [...argv, target]);
+  }
+  return commands;
+}
+
+/** Starts one command, detached; whether it started (its program was found and could run). */
+function start(argv: readonly string[]): Promise<boolean> {
+  const [program, ...args] = argv;
+  if (program === undefined) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    try {
+      const child = spawn(program, args, { detached: true, stdio: "ignore" });
+      child.once("spawn", () => {
+        child.unref();
+        resolve(true);
+      });
+      child.once("error", () => resolve(false));
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+/** Opens `url` in a browser through a launch page; whether a browser command started. */
+export async function openInBrowser(url: string, env: Environment): Promise<boolean> {
+  let page: string;
+  try {
+    page = writeLaunchPage(url);
+  } catch {
+    return false;
+  }
+  for (const command of browserCommands(page, env)) {
+    if (await start(command)) return true;
+  }
+  return false;
+}