humanish 0.107.0 → 0.109.0

package/dist/cli/commands/observe.js

@@ -3,19 +3,20 @@ import { openTarget, renderObserver, serveObserver } from "../../observer/render
 import { SERVE_SCHEMA, serveObserverLibrary } from "../../observer/serve.js";
 import { startExposedObserver, validateExposure } from "../../observer/exposure.js";
 import { ServeTunnelError } from "../../observer/tunnel.js";
-import { collectRepeated, formatRunHuman, JSON_OPTION_DESCRIPTION, parseObserverPort, wantsJson, writeResult, } from "../io.js";
+import { collectRepeated, CWD_OPTION_DESCRIPTION, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parseObserverPort, RUN_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
 import { exitCodeForSignal, formatObserverHuman, } from "../observer-follow.js";
 export function registerObserveCommand(parent, io) {
-    parent
+    addLibraryOptions(parent
         .command("observe")
-        .description("Follow a run's saved evidence in Observer over loopback http://127.0.0.1.")
-        .summary("Follow a run's saved evidence over loopback http.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--port <port>", "Loopback port to bind on 127.0.0.1. Defaults to an ephemeral port.", "0")
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--open", "Open the observer in the default browser.")
+        .description("Open a saved run in the Observer, served on http://127.0.0.1; without --run, the latest. With --all, serve the run library, opening on --run when given.")
+        .summary("Open a saved run in the Observer.")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION)
+        .option("--all", "Serve the whole run library, with optional tunnel-edge exposure.")
+        .addOption(freePortOption())
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--open", "Open the Observer in the default browser.")
         .option("--no-open", "Serve without opening a browser.")
-        .option("--json", JSON_OPTION_DESCRIPTION)
+        .option("--json", JSON_OPTION_DESCRIPTION))
         .addHelpText("after", [
         "",
         "Examples:",
@@ -23,62 +24,128 @@ export function registerObserveCommand(parent, io) {
         "  humanish observe --run latest",
         "  humanish observe --run <runId> --port 8732",
         "  humanish observe --no-open --json",
+        "  humanish observe --all",
+        "  humanish observe --all --expose --tunnel ngrok --oauth google --allow-email you@example.com",
+        "  humanish observe --all --safe --expose --tunnel ngrok",
+        "  humanish observe --all --expose --public-url https://observer.example.com",
         "",
-        "The server binds 127.0.0.1 only and exposes just the run's bundle directory.",
-        "It stays attached until Ctrl-C; file:// security policy and live refresh are why",
-        "loopback http is preferred over opening the index.html path directly.",
+        "The server binds 127.0.0.1 only. One run exposes just that run's bundle directory; --all",
+        "serves the run library. It stays attached until Ctrl-C; file:// security policy and live",
+        "refresh are why loopback http is preferred over opening the index.html path directly.",
+        "",
+        "--safe, --expose, --tunnel, --tunnel-domain, --oauth, --allow-email, --allow-domain and",
+        "--public-url need --all. Exposure only ever happens through an authenticated edge (ngrok",
+        "--oauth google, or an operator --public-url you secure) forwarding to the loopback port;",
+        "the server carries no in-process auth. Live desktop stream URLs are never served; remote",
+        "viewers see persisted evidence only. --safe composes with any exposure.",
     ].join("\n"))
-        .action(async (options, command) => {
-        const port = parseObserverPort(options.port);
-        if (port === null) {
-            const result = {
-                schema: "humanish.run-result.v1",
-                ok: false,
-                cwd: options.cwd,
-                warnings: [],
-                error: {
-                    code: "HUMANISH_INVALID_PORT",
-                    message: "--port must be an integer between 0 and 65535.",
-                },
-            };
-            writeResult(command, io, result, formatRunHuman);
-            io.setExitCode(2);
-            return;
-        }
-        const rendered = await renderObserver(options.cwd, options.run, { open: false });
-        if (!rendered.ok || !rendered.observerPath) {
-            writeResult(command, io, rendered, formatObserverHuman);
-            io.setExitCode(2);
-            return;
-        }
-        // Reuse the contained current-data projection, scoped to this run. A raw static
-        // server would miss runtime status and could replay stored iframe grants.
-        const wantsMachine = wantsJson(command);
-        const shouldOpen = options.open === false
-            ? false
-            : options.open === true
-                ? true
-                : !wantsMachine && process.stdout.isTTY === true;
-        const server = await serveObserver(rendered, { open: false, port, scope: "run" });
-        const openResult = shouldOpen
-            ? openTarget(server.url)
-            : { opened: false };
+        .action((options, command) => handleObserve(io, options, command));
+}
+/** The run library's flags, on `observe --all` and the hidden `serve` alias. */
+function addLibraryOptions(command) {
+    return command
+        .option("--safe", "Serve only runs whose verify shareSafety is share_ready; other runs are not served at all.")
+        .option("--expose", "Share the library beyond this machine. Requires --oauth or --public-url, or --safe.")
+        .addOption(new Option("--tunnel <provider>", "Spawn the external tunnel binary against the loopback port.").choices(["ngrok"]))
+        .option("--tunnel-domain <domain>", "Reserved domain passed to ngrok as --url (e.g. observer.example.com). Requires --tunnel.")
+        .addOption(new Option("--oauth <provider>", "Turn on ngrok edge OAuth. Requires --tunnel.").choices([
+        "google",
+    ]))
+        .option("--allow-email <addr>", "Edge OAuth allow rule: permit this email. Repeatable. Requires --oauth.", collectRepeated)
+        .option("--allow-domain <domain>", "Edge OAuth allow rule: permit this domain. Repeatable. Requires --oauth.", collectRepeated)
+        .option("--public-url <origin>", "Bring-your-own authed edge (e.g. https://observer.example.com). Requires --expose; never affects binding.");
+}
+/** The library flags set on a one-run observe, as typed on the command line. */
+function libraryOnlyFlags(options) {
+    return [
+        options.safe === true ? ["--safe"] : [],
+        options.expose === true ? ["--expose"] : [],
+        options.tunnel === undefined ? [] : ["--tunnel"],
+        options.tunnelDomain === undefined ? [] : ["--tunnel-domain"],
+        options.oauth === undefined ? [] : ["--oauth"],
+        (options.allowEmail?.length ?? 0) === 0 ? [] : ["--allow-email"],
+        (options.allowDomain?.length ?? 0) === 0 ? [] : ["--allow-domain"],
+        options.publicUrl === undefined ? [] : ["--public-url"],
+    ].flat();
+}
+function refuseObserve(command, io, cwd, error) {
+    const result = {
+        schema: "humanish.run-result.v1",
+        ok: false,
+        cwd,
+        warnings: [],
+        ...(error === undefined ? {} : { error }),
+    };
+    writeResult(command, io, result, formatRunHuman);
+    io.setExitCode(2);
+}
+/** `observe` shows one run (default latest); `observe --all` serves the run library. */
+async function handleObserve(io, options, command) {
+    if (options.all === true) {
+        await handleServe(io, options, command);
+        return;
+    }
+    const libraryOnly = libraryOnlyFlags(options);
+    if (libraryOnly.length > 0) {
+        refuseObserve(command, io, options.cwd, {
+            code: "HUMANISH_OBSERVE_OPTION_CONFLICT",
+            message: `${libraryOnly.join(", ")} ${libraryOnly.length === 1 ? "needs" : "need"} --all: humanish observe --all ${libraryOnly.join(" ")}.`,
+        });
+        return;
+    }
+    await observeRun(io, { ...options, run: options.run ?? "latest" }, command);
+}
+/** One run's Observer over loopback, until a signal stops it. */
+async function observeRun(io, options, command) {
+    const port = parseObserverPort(options.port);
+    if (port === null) {
         const result = {
-            ...rendered,
-            observerUrl: server.url,
-            serverUrl: server.url,
-            opened: openResult.opened,
-            ...(openResult.command ? { openCommand: openResult.command } : {}),
-            warnings: [
-                ...rendered.warnings,
-                "Observer is served read-only over loopback http on 127.0.0.1; only this run's bundle directory is exposed.",
-                ...(openResult.warning ? [openResult.warning] : []),
-            ],
+            schema: "humanish.run-result.v1",
+            ok: false,
+            cwd: options.cwd,
+            warnings: [],
+            error: {
+                code: "HUMANISH_INVALID_PORT",
+                message: "--port must be an integer between 0 and 65535.",
+            },
         };
-        writeResult(command, io, result, formatObserverHuman);
-        io.setExitCode(0);
-        await serveObserveUntilSignal(io, server, { json: wantsMachine });
-    });
+        writeResult(command, io, result, formatRunHuman);
+        io.setExitCode(2);
+        return;
+    }
+    const rendered = await renderObserver(options.cwd, options.run, { open: false });
+    if (!rendered.ok || !rendered.observerPath) {
+        writeResult(command, io, rendered, formatObserverHuman);
+        io.setExitCode(2);
+        return;
+    }
+    // Reuse the contained current-data projection, scoped to this run. A raw static
+    // server would miss runtime status and could replay stored iframe grants.
+    const wantsMachine = wantsJson(command);
+    const shouldOpen = options.open === false
+        ? false
+        : options.open === true
+            ? true
+            : !wantsMachine && process.stdout.isTTY === true;
+    const server = await serveObserver(rendered, { open: false, port, scope: "run" });
+    const openResult = shouldOpen
+        ? openTarget(server.url)
+        : { opened: false };
+    const result = {
+        ...rendered,
+        observerUrl: server.url,
+        serverUrl: server.url,
+        opened: openResult.opened,
+        ...(openResult.command ? { openCommand: openResult.command } : {}),
+        warnings: [
+            ...rendered.warnings,
+            "Observer is served read-only over loopback http on 127.0.0.1; only this run's bundle directory is exposed.",
+            ...(openResult.warning ? [openResult.warning] : []),
+        ],
+    };
+    writeResult(command, io, result, formatObserverHuman);
+    io.setExitCode(0);
+    await serveObserveUntilSignal(io, server, { json: wantsMachine });
 }
 async function serveObserveUntilSignal(io, server, options) {
     // Keep the JSON envelope on stdout clean: route attach/stop chatter to stderr
@@ -117,46 +184,6 @@ async function serveObserveUntilSignal(io, server, options) {
         }
     });
 }
-export function registerServeCommand(parent, io) {
-    parent
-        .command("serve")
-        .description("Serve the local run library over loopback http, with optional tunnel-edge authenticated exposure.")
-        .summary("Serve the run library; optional tunnel-edge exposure.")
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--port <port>", "Loopback port to bind on 127.0.0.1. Defaults to an ephemeral port.", "0")
-        .option("--run <id>", "Land on this run id (or latest) instead of the library index.")
-        .option("--safe", "Serve only runs whose verify shareSafety is share_ready; everything else is absent (fail-closed).")
-        .option("--expose", "Declare exposure intent. Requires edge auth (--oauth or --public-url) OR --safe.")
-        .addOption(new Option("--tunnel <provider>", "Spawn the external tunnel binary against the loopback port.").choices(["ngrok"]))
-        .option("--tunnel-domain <domain>", "Reserved domain passed to ngrok as --url (e.g. observer.example.com). Requires --tunnel.")
-        .addOption(new Option("--oauth <provider>", "Turn on ngrok edge OAuth. Requires --tunnel.").choices([
-        "google",
-    ]))
-        .option("--allow-email <addr>", "Edge OAuth allow rule: permit this email. Repeatable. Requires --oauth.", collectRepeated, [])
-        .option("--allow-domain <domain>", "Edge OAuth allow rule: permit this domain. Repeatable. Requires --oauth.", collectRepeated, [])
-        .option("--public-url <origin>", "Bring-your-own authed edge (e.g. https://observer.example.com). Requires --expose; never affects binding.")
-        .option("--open", "Open the library in the default browser.")
-        .option("--no-open", "Serve without opening a browser.")
-        .option("--json", JSON_OPTION_DESCRIPTION)
-        .addHelpText("after", [
-        "",
-        "Happy path:",
-        "  humanish serve",
-        "  humanish serve --expose --tunnel ngrok --oauth google --allow-email you@example.com",
-        "  humanish serve --safe --expose --tunnel ngrok",
-        "  humanish serve --expose --public-url https://observer.example.com",
-        "",
-        "Agent/CI path:",
-        "  humanish serve --json --no-open",
-        "",
-        "The server always binds 127.0.0.1; exposure only ever happens through an authenticated",
-        "edge (ngrok --oauth google, or an operator --public-url you secure) forwarding to the",
-        "loopback port. The server carries no in-process auth; the gate lives at the edge. Live",
-        "desktop stream URLs are never served here; remote viewers see persisted evidence only.",
-        "--safe composes with any exposure for defense in depth.",
-    ].join("\n"))
-        .action((options, command) => handleServe(io, options, command));
-}
 async function handleServe(io, options, command) {
     const fail = (code, message) => refuseServe(command, io, options, code, message);
     const port = parseObserverPort(options.port);
@@ -171,8 +198,8 @@ async function handleServe(io, options, command) {
         ...(options.tunnel === undefined ? {} : { tunnel: options.tunnel }),
         ...(options.tunnelDomain === undefined ? {} : { tunnelDomain: options.tunnelDomain }),
         ...(options.oauth === undefined ? {} : { oauth: options.oauth }),
-        allowEmails: options.allowEmail,
-        allowDomains: options.allowDomain,
+        allowEmails: options.allowEmail ?? [],
+        allowDomains: options.allowDomain ?? [],
         ...(options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl }),
         safe: options.safe === true,
     });
@@ -257,7 +284,7 @@ async function reportServe(io, command, options, server, plan, edge) {
         ...serveExposureWarnings(server, options.safe === true, publicUrl),
     ];
     // Auto-open is suppressed under --expose so the public URL is not shoved into a local opener's
-    // argv unasked — the exposure target is a remote device anyway. Explicit --open still honors
+    // argv unasked; the exposure target is a remote device anyway. Explicit --open still honors
     // intent and opens the loopback library.
     const shouldOpen = options.open === false
         ? false
@@ -326,21 +353,18 @@ function hiddenRunLines(groups) {
         lines.push(`  ${runs(group.runs)} ${group.status}${reasons}`);
     }
     if (groups.some((group) => group.reasons.join(",") === "RAW_SCREENSHOTS"))
-        lines.push("share: a run held back only for RAW_SCREENSHOTS can be copied with blurred screenshots: `humanish export --run <id> --format bundle --redact-screenshots --out <dir>`, then `humanish serve --safe --cwd <dir>`");
+        lines.push("share: a run held back only for RAW_SCREENSHOTS can be copied with blurred screenshots: `humanish export --run <id> --format bundle --redact-screenshots --out <dir>`, then `humanish observe --all --safe --cwd <dir>`");
     lines.push("why: `humanish verify --run <id>` explains each reason");
     return lines;
 }
 function formatServeHuman(result) {
     if (!result.ok) {
-        return ([
-            "humanish serve failed",
-            ...(result.error ? [`error: ${result.error.code} ${result.error.message}`] : []),
-            ...result.warnings.map((warning) => `warning: ${warning}`),
-        ].join("\n") + "\n");
+        const warnings = result.warnings.map((warning) => `warning: ${warning}\n`).join("");
+        return { ...(warnings ? { stdout: warnings } : {}), error: result.error };
     }
     const modeSuffix = result.safe ? " (share_ready only)" : "";
     const lines = [
-        "humanish serve",
+        "humanish observe --all",
         `mode: ${result.mode}${modeSuffix}`,
         `library: ${result.url ?? ""}`,
         `runs: ${result.runsListed}`,
@@ -354,7 +378,7 @@ function formatServeHuman(result) {
     }
     if (result.oauth) {
         const rules = [...result.oauth.allowEmails, ...result.oauth.allowDomains];
-        lines.push(`edge auth: ${result.oauth.provider} oauth${rules.length > 0 ? ` (allow: ${rules.join(", ")})` : " (no allow rule — any Google account)"}`);
+        lines.push(`edge auth: ${result.oauth.provider} oauth${rules.length > 0 ? ` (allow: ${rules.join(", ")})` : " (no allow rule: any Google account can sign in)"}`);
     }
     if (result.entryRunId) {
         lines.push(`entry: ${result.entryRunId}`);

package/dist/cli/commands/run-command.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import { type CliIo, type StudyCommandOptions as RunOptions } from "../io.js";
+/** The parsed flags of `run` and `watch`. */
+export type { RunOptions };
+/** The flags a run takes, whichever command starts it. */
+export declare function addRunOptions(command: Command): Command;
+/** The flags that only a study file can use, as typed on the command line, when they are set. */
+export declare function studyOnlyFlags(options: RunOptions): string[];
+/** `humanish run [study]`: the named study, or the synthetic preview when no study is given. */
+export declare function handleRun(io: CliIo, named: string | undefined, options: RunOptions, command: Command): Promise<void>;

package/dist/cli/commands/run-command.js

@@ -0,0 +1,85 @@
+import { runDryRun } from "../../run/dry-run.js";
+import { runStudyCommand } from "./study-run.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, } from "../io.js";
+/** The flags a run takes, whichever command starts it. */
+export function addRunOptions(command) {
+    return command
+        .option("--dry-run", "Do a dry run: a synthetic run with no browser, keys or provider spend.")
+        .option("--open", "Open the Observer in the default browser.")
+        .option("--no-open", "Render without opening a browser.")
+        .option("--detach", "Render/open once and exit without an attached watch server.")
+        .addOption(freePortOption())
+        .option("--count <count>", "Override the participant count of a preview or computer-use study, or of the synthetic run without a study.")
+        .option("--rerun-failed-from <run>", "Computer-use studies only: start a new run for the failed participants of a prior run.")
+        .option("--participants <ids>", "With --rerun-failed-from: comma-separated ids of the participants to rerun. The study's participants decide who takes part; ids are their id, or lane-01, lane-02, … by position.")
+        .option("--scorer <path>", "Score with this .mjs module, a path inside the repo, in place of review.scorer.ref. It runs as code, so review it first. Terminal, computer-use and shared-world studies only.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--run-id <id>", "Explicit run id for deterministic fixture tests; refused when that run already exists.")
+        .option("--json", JSON_OPTION_DESCRIPTION);
+}
+/** The flags that only a study file can use, as typed on the command line, when they are set. */
+export function studyOnlyFlags(options) {
+    return [
+        options.scorer === undefined ? [] : ["--scorer"],
+        options.rerunFailedFrom === undefined ? [] : ["--rerun-failed-from"],
+        options.participants === undefined ? [] : ["--participants"],
+    ].flat();
+}
+function refuseRun(command, io, cwd, error) {
+    const result = {
+        schema: "humanish.run-result.v1",
+        ok: false,
+        cwd,
+        warnings: [],
+        ...(error === undefined ? {} : { error }),
+    };
+    writeResult(command, io, result, formatRunHuman);
+    io.setExitCode(2);
+}
+/** `humanish run [study]`: the named study, or the synthetic preview when no study is given. */
+export async function handleRun(io, named, options, command) {
+    // An empty argument, as from a script passing an unset variable, is the synthetic run.
+    const study = named === "" ? undefined : named;
+    const studyOnly = studyOnlyFlags(options);
+    if (study === undefined && studyOnly.length > 0) {
+        refuseRun(command, io, options.cwd, {
+            code: "HUMANISH_RUN_OPTION_CONFLICT",
+            message: `${studyOnly.join(", ")} ${studyOnly.length === 1 ? "needs" : "need"} a study: humanish run <study>.`,
+        });
+        return;
+    }
+    const loaded = await applyEnvFileOption({
+        command,
+        cwd: options.cwd,
+        envFile: options.envFile,
+        io,
+        // runStudyCommand discovers keys for a live study; a preview without a study needs none.
+        discoverKeys: false,
+    });
+    if (!loaded)
+        return;
+    if (study !== undefined) {
+        await runStudyCommand({ command, io, study, mode: "run", options });
+        return;
+    }
+    const participantCount = options.count === undefined ? undefined : parsePositiveInteger(options.count);
+    if (participantCount === null) {
+        refuseRun(command, io, options.cwd, {
+            code: "HUMANISH_INVALID_PARTICIPANT_COUNT",
+            message: "--count must be a positive integer.",
+        });
+        return;
+    }
+    const result = await runDryRun({
+        cwd: options.cwd,
+        ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+        ...(options.runId === undefined ? {} : { runId: options.runId }),
+        ...(participantCount === undefined ? {} : { participantCount }),
+        // Rendered the way `watch` renders it, so a bundle is the same bundle whichever command
+        // produced it. A render failure is a warning on the result.
+        observer: { open: false },
+    });
+    writeResult(command, io, result, formatRunHuman);
+    io.setExitCode(result.ok ? 0 : 2);
+}