humanish 0.106.1 → 0.108.0

package/dist/cli/io.js

@@ -3,10 +3,11 @@ import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { loadEnvFile } from "../keys/env-file.js";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
-import { deriveStudyFacts } from "./telemetry.js";
+import { deriveRunFacts } from "./telemetry.js";
+import { withQueuedWarnings } from "./deprecations.js";
 import { forTerminal } from "../routes/terminal/encoding.js";
 export const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
 function readCliVersion() {
@@ -17,11 +18,19 @@ function readCliVersion() {
         : "0.0.0";
 }
 export const CLI_VERSION = readCliVersion();
-// Shared so the ~20 leaf commands that declare their own --json flag cannot drift
-// from each other in wording.
+// One text per shared flag, so the same flag reads the same on every command.
+// tests/cli/shared-options.test.ts walks the program and holds every use to these.
 export const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
-// Transcode ONLY for a terminal. A pipe carries bytes to another program — mangling those would
-// corrupt a JSON payload for a reader that handles UTF-8 perfectly well — while a TTY carries them
+export const CWD_OPTION_DESCRIPTION = "Project directory.";
+export const RUN_OPTION_DESCRIPTION = "Run id, or latest.";
+export const ENV_FILE_OPTION_DESCRIPTION = "Load unset variables from this env file. Values are never printed or saved.";
+export const PORT_OPTION_DESCRIPTION = "Port to listen on at 127.0.0.1.";
+/** `--port` for a loopback server whose default, 0, lets the OS pick a free port. */
+export function freePortOption() {
+    return new Option("--port <port>", PORT_OPTION_DESCRIPTION).default("0", "a free port");
+}
+// Transcode only for a terminal. A pipe carries bytes to another program, and mangling those would
+// corrupt a JSON payload for a reader that handles UTF-8 perfectly well, while a TTY carries them
 // to a font, through a locale that may not decode them. See src/routes/terminal/encoding.ts for what a
 // participant actually read back off the screen.
 const forStream = (stream, text) => stream.isTTY === true ? forTerminal(text) : text;
@@ -37,7 +46,7 @@ export const defaultIo = {
 // of the invocation (a fresh object every createProgram() call) rather than a
 // module-level boolean, so tests that construct multiple `createProgram()`
 // instances in the same process never see one instance's writes bleed into
-// another's, and nothing needs explicit cleanup -- the entry is released once
+// another's, and nothing needs explicit cleanup: the entry is released once
 // that Command tree is garbage collected.
 const invocationEnvelopeWritten = new WeakSet();
 function rootCommandOf(command) {
@@ -77,7 +86,7 @@ export async function applyEnvFileOption(args) {
     return true;
 }
 /**
- * Provider-key discovery (#436): fill still-missing keys from the documented project overlay, the
+ * Provider-key discovery: fill still-missing keys from the documented project overlay, the
  * owning vendors' native stores, and the humanish user store. It is fill-only (an explicit
  * --env-file or process env always wins), and each fill is announced by name and source on
  * stderr, never by value. HUMANISH_STRICT_KEYS=1 restores env-only behavior.
@@ -89,6 +98,7 @@ export async function discoverCliKeys(args) {
             cwd: args.cwd,
             env: args.env ?? process.env,
             announce: (line) => args.io.writeErr(`${line}\n`),
+            ...(args.announced === undefined ? {} : { announced: args.announced }),
         });
         args.onDiscovered?.(discovered.map((fill) => fill.name));
     }
@@ -114,57 +124,98 @@ export function parseParticipantIds(value) {
     }
     return participantIds;
 }
-// Exported so tests/cli/program.test.ts can drive the command-boundary catch-all's
-// post-write guard (invocationEnvelopeAlreadyWritten above) through the same
-// funnel every real command uses, without duplicating its stdout-vs-formatHuman
-// branching. Not re-exported from src/index.ts; this stays an internal seam.
+/**
+ * The command to run next, by code. A code is listed only when its messages do not already name a
+ * command: the run-not-found and lab-less run messages do.
+ */
+const NEXT_COMMAND = {
+    HUMANISH_STUDY_NOT_FOUND: "humanish study list",
+};
+/** `<command> failed: <message>`, then `code: <CODE>`, then `next: <command>` when one is known. */
+export function formatCliError(command, error) {
+    const next = error.code === undefined ? undefined : NEXT_COMMAND[error.code];
+    return ([
+        `${command} failed: ${error.message}`,
+        ...(error.code === undefined ? [] : [`code: ${error.code}`]),
+        ...(next === undefined ? [] : [`next: ${next}`]),
+    ].join("\n") + "\n");
+}
+/** A result whose human output is its message: stdout when it passed, stderr when it failed. */
+export function messageOutput(value) {
+    return value.ok ? `${value.message}\n` : { error: { message: value.message } };
+}
+/** A failed result's human output: its error on stderr and nothing on stdout. */
+export function humanError(error) {
+    return { error: error ?? { message: "the command failed without a recorded error" } };
+}
+/** "humanish study show": the command's path as a person types it. */
+function commandLabel(command) {
+    const names = [];
+    for (let current = command; current !== null; current = current.parent)
+        names.unshift(current.name());
+    return names.join(" ");
+}
+/** Prints a human formatter's output: text to stdout, an error to stderr through formatCliError. */
+export function writeHuman(command, io, human) {
+    if (typeof human === "string") {
+        io.writeOut(human);
+        return;
+    }
+    if (human.stdout)
+        io.writeOut(human.stdout);
+    if (human.error)
+        io.writeErr(formatCliError(commandLabel(command), human.error));
+}
 export function writeResult(command, io, result, formatHuman) {
     const output = automaticAnalysisEnvelope(result);
     if (wantsJson(command)) {
-        io.writeOut(`${JSON.stringify(output, null, 2)}\n`);
+        // Queued warnings are on stderr already; a JSON caller gets them in warnings[] as well.
+        io.writeOut(`${JSON.stringify(withQueuedWarnings(command, output), null, 2)}\n`);
     }
     else {
-        io.writeOut(formatHuman(output));
+        writeHuman(command, io, formatHuman(output));
         if (output !== null && typeof output === "object" && "automaticAnalysis" in output) {
             const analysis = output.automaticAnalysis;
             if (analysis)
-                io.writeOut(`analysis: ${analysis.state}${analysis.reason ? ` (${analysis.reason})` : ""}\n`);
+                io.writeOut(`analysis: ${analysisOutcomeText(analysis)}\n`);
+            const rejected = analysis?.result?.rejectedOutputPath;
+            if (rejected)
+                io.writeOut(`analysis: ${analysis.result?.error?.code ?? "rejected"}; the rejected output is kept locally at ${rejected}\n`);
             if (defaultAnalysisOverBudget(output))
                 io.writeOut(overBudgetAnalysisHint(output));
         }
     }
     markInvocationEnvelopeWritten(command);
     // Every backend's result passes through here, so this is where a study's facts get read for
-    // telemetry — not in each backend, which is how they went unreported for two releases.
-    noteStudyFacts(command, deriveStudyFacts(result));
+    // telemetry. Reading them in each route instead is how they went unreported for two releases.
+    noteRunFacts(command, deriveRunFacts(result));
 }
-const studyFactsByCommand = new WeakMap();
-export function noteStudyFacts(command, facts) {
+const runFactsByCommand = new WeakMap();
+export function noteRunFacts(command, facts) {
     if (Object.keys(facts).length === 0)
         return;
-    studyFactsByCommand.set(command, { ...studyFactsByCommand.get(command), ...facts });
+    runFactsByCommand.set(command, { ...runFactsByCommand.get(command), ...facts });
 }
 /** Exported for tests: the facts writeResult read off a command's result document. */
-export function studyFactsFor(command) {
-    return { ...studyFactsByCommand.get(command) };
+export function runFactsFor(command) {
+    return { ...runFactsByCommand.get(command) };
 }
+/** A run result, or the preview route's study result: they differ only in `schema`. */
 export function formatRunHuman(result) {
-    if (!result.ok) {
-        return `${result.error?.code}: ${result.error?.message}\n`;
-    }
+    if (!result.ok)
+        return humanError(result.error);
     return ([
         `humanish run ${result.mode}`,
         `run: ${result.runId}`,
-        ...(result.simCount === undefined ? [] : [`sims: ${result.simCount}`]),
+        ...(result.simCount === undefined ? [] : [`participants: ${result.simCount}`]),
         `bundle: ${result.bundlePath}`,
         `review: ${result.reviewPath}`,
         ...result.warnings.map((warning) => `warning: ${warning}`),
     ].join("\n") + "\n");
 }
 function formatEnvFileHuman(result) {
-    if (!result.ok) {
-        return `${result.error?.code}: ${result.error?.message}\n`;
-    }
+    if (!result.ok)
+        return humanError(result.error);
     return ([
         "humanish env-file loaded",
         `env-file: ${result.envFile}`,
@@ -201,7 +252,7 @@ export function candidateOption(options) {
         ...(options.finding === undefined ? {} : { finding: options.finding }),
     };
 }
-export function collectRepeated(value, previous) {
+export function collectRepeated(value, previous = []) {
     return [...previous, value];
 }
 export function wantsJson(command) {
@@ -214,6 +265,34 @@ export function wantsJson(command) {
     }
     return false;
 }
+/** What the automatic analysis did, in words; JSON output keeps the reason code. */
+const ANALYSIS_REASON_TEXT = {
+    AUTOMATIC_ANALYSIS_DRY_RUN: "skipped for dry runs",
+    AUTOMATIC_ANALYSIS_KEY_MISSING: "skipped because OPENAI_API_KEY is not set",
+    AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE: "skipped because no participant left evidence",
+    AUTOMATIC_ANALYSIS_ACTOR_CANCELLED: "skipped because the run stopped before its participants finished",
+    AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE: "skipped because the run's evidence could not be read",
+    AUTOMATIC_ANALYSIS_ALREADY_REQUESTED: "skipped because this run's analysis was already requested",
+    AUTOMATIC_ANALYSIS_BUSY: "skipped because another analysis is running",
+    AUTOMATIC_ANALYSIS_ADMISSION_REFUSED: "not started because its configuration or question was refused",
+    AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED: "not started because the run's cleanup was not confirmed",
+    AUTOMATIC_ANALYSIS_REUSED: "complete, reusing an earlier analysis of the same evidence",
+    AUTOMATIC_ANALYSIS_LIMITATIONS: "partial, because it covered only part of the evidence",
+    AUTOMATIC_ANALYSIS_ADMISSION_EXCEEDED: "partial, because it went over its estimated cost or output",
+    AUTOMATIC_ANALYSIS_FAILED: "failed",
+    AUTOMATIC_ANALYSIS_CANCELLED: "cancelled",
+    AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE: "failed because the Codex analyst could not run",
+    AUTOMATIC_ANALYSIS_PUBLICATION_FAILED: "failed because the report could not be saved",
+    AUTOMATIC_ANALYSIS_SOURCE_CHANGED: "failed because the run's evidence changed during analysis",
+    AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE: "outcome unknown: a cancellation could not be recorded",
+    AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE: "outcome unknown: analysis storage is unavailable",
+    AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN: "outcome unknown",
+};
+export function analysisOutcomeText(analysis) {
+    if (analysis.reason === null)
+        return analysis.state;
+    return ANALYSIS_REASON_TEXT[analysis.reason] ?? `${analysis.state} (${analysis.reason})`;
+}
 /** Preserve the run's own result while making requested post-processing failures machine-visible. */
 function overBudgetAnalysisHint(result) {
     const estimate = result.automaticAnalysis?.result?.admission?.estimatedCostUsd ?? null;

package/dist/cli/observer-follow.d.ts

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import type { ObserverResult, ObserverServer } from "../observer/render.js";
 import type { ExposureRequest } from "../observer/exposure.js";
-import { type CliIo, type LabCommandOptions } from "./io.js";
+import { type CliIo, type LabCommandOptions, type HumanOutput } from "./io.js";
 /** How a command shows an Observer, decided before the run it shows starts. */
 export interface ObserverPlan {
     port: number;
@@ -31,7 +31,7 @@ export declare function showObserver(args: {
     rendered: ObserverResult;
 }): Promise<void>;
 export declare function withObserverServer(rendered: ObserverResult, server: ObserverServer): ObserverResult;
-export declare function formatObserverHuman(result: ObserverResult): string;
+export declare function formatObserverHuman(result: ObserverResult): HumanOutput;
 export type WatchStopSignal = "SIGINT" | "SIGTERM" | "SIGHUP";
 interface WatchSignalTarget {
     once(event: WatchStopSignal, listener: () => void): unknown;

package/dist/cli/observer-follow.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { serveObserver } from "../observer/render.js";
-import { formatRunHuman, parseObserverPort, wantsJson, writeResult, } from "./io.js";
+import { formatRunHuman, parseObserverPort, wantsJson, writeResult, humanError, } from "./io.js";
 /**
  * Parse --port and decide open and follow. On an invalid port it writes the failure, sets exit
  * code 2 and returns null, so a caller refuses before starting a run.
@@ -64,9 +64,8 @@ export function withObserverServer(rendered, server) {
     };
 }
 export function formatObserverHuman(result) {
-    if (!result.ok) {
-        return `${result.error?.code}: ${result.error?.message}\n`;
-    }
+    if (!result.ok)
+        return humanError(result.error);
     return ([
         "humanish observer rendered",
         `run: ${result.run}`,
@@ -134,8 +133,8 @@ export function exitCodeForSignal(signal) {
     }
 }
 // True when any tunnel-edge exposure flag is present (not --safe, which is an orthogonal filter).
-// Used to refuse exposure on the non-lab watch path and on non-CUA backends, where there is no live
-// desktop to stream.
+// Callers refuse exposure with it on the non-lab watch path and on non-computer-use routes, where
+// there is no live desktop to stream.
 export function watchExposeRequested(o) {
     return (o.expose === true ||
         o.tunnel !== undefined ||

package/dist/cli/orientation.d.ts

@@ -10,7 +10,7 @@ export interface OrientationState {
     /** Runs already on disk, and the most recent one if there is one. */
     runCount: number;
     latestRunId?: string;
-    /** The commands that make sense from HERE, most useful first. */
+    /** The commands that make sense from here, most useful first. */
     nextCommands: OrientationCommand[];
 }
 interface OrientationCommand {
@@ -19,9 +19,12 @@ interface OrientationCommand {
 }
 /**
  * Read the project's state. Pure-ish: it only reads, never writes, and never touches the network or
- * a provider — bare invocation must not be able to spend money or mutate a repo.
+ * a provider: bare invocation must not be able to spend money or mutate a repo.
  */
-export declare function readOrientation(cwd: string): Promise<OrientationState>;
+export declare function readOrientation(cwd: string, host?: {
+    platform: NodeJS.Platform;
+    arch: string;
+}): Promise<OrientationState>;
 /**
  * The human rendering. Says where you are before it says what to do, because "what should I run"
  * has no answer that is true in every project.

package/dist/cli/orientation.js

@@ -1,9 +1,9 @@
-// What `humanish` says when you run it with no arguments (#367).
+// What `humanish` says when you run it with no arguments.
 //
-// It used to print commander's help: sixteen subcommands before any value, identical whether you
+// Commander's help would print sixteen subcommands before any value, identical whether you
 // had never run the tool or had a finished study sitting on disk. That is a poor first contact for
-// a human, and it is worse for a coding agent, which needs to know WHERE IT IS before it can choose
-// a command — help is a menu, not an orientation.
+// a human, and it is worse for a coding agent, which needs to know where it is before it can choose
+// a command; help is a menu, not an orientation.
 //
 // So bare invocation answers three questions instead: what is this, what state is this project in,
 // and what should I run next. The answer is derived from the project rather than fixed, so it is
@@ -14,24 +14,26 @@
 // or as JSON with `--json`. Neither is a special case of the other bolted on afterwards.
 import { listLabManifests } from "../lab/discover.js";
 import { listRuns } from "../run/stored-runs.js";
+import { supportsLocalBrowser } from "./first-run-path.js";
+import { PRODUCT_SENTENCE } from "./product-sentence.js";
 export const ORIENTATION_SCHEMA = "humanish.orientation.v1";
 /**
  * Read the project's state. Pure-ish: it only reads, never writes, and never touches the network or
- * a provider — bare invocation must not be able to spend money or mutate a repo.
+ * a provider: bare invocation must not be able to spend money or mutate a repo.
  */
-export async function readOrientation(cwd) {
+export async function readOrientation(cwd, host = process) {
     const [labs, runs] = await Promise.all([
         listLabManifests(cwd).catch(() => undefined),
         listRuns(cwd).catch(() => undefined),
     ]);
-    const labIds = (labs?.labs ?? [])
+    const labIds = (labs?.studies ?? [])
         .map((lab) => lab.id)
         .filter((id) => typeof id === "string");
     const runIds = (runs?.runs ?? [])
         .map((run) => run.runId)
         .filter((id) => typeof id === "string");
     const latest = typeof runs?.latest === "string" ? runs.latest : runIds[0];
-    const initialized = (labs?.labs ?? []).some((lab) => lab.origin === "committed") || labIds.length > 0;
+    const initialized = (labs?.studies ?? []).some((lab) => lab.origin === "committed") || labIds.length > 0;
     return {
         schema: ORIENTATION_SCHEMA,
         initialized,
@@ -39,58 +41,60 @@ export async function readOrientation(cwd) {
         labIds: labIds.slice(0, 3),
         runCount: runIds.length,
         ...(latest === undefined ? {} : { latestRunId: latest }),
-        nextCommands: nextCommandsFor({ initialized, labIds, hasRun: runIds.length > 0 }),
+        nextCommands: nextCommandsFor({ initialized, labIds, hasRun: runIds.length > 0, host }),
     };
 }
 /**
  * The two or three commands worth running from this state. Deliberately short: a list of everything
- * is what bare invocation used to print, and it is why nobody read it.
+ * is commander's help, which nobody reads.
  */
 function nextCommandsFor(args) {
+    const dryRun = {
+        command: "humanish run first-run",
+        why: "a dry run: no browser or model runs, no keys, no spend",
+    };
     if (!args.initialized) {
         return [
-            { command: "humanish init", why: "create humanish/ with a starter lab and persona" },
             {
-                command: "humanish run first-run",
-                why: "a synthetic run with no keys and no spend, to see the shape of the evidence",
+                command: "humanish init --yes",
+                why: "write starter labs, personas and an AGENTS.md (--dry-run lists every file first)",
             },
+            dryRun,
+        ];
+    }
+    // The starter live lab this host can run. The other starter labs are templates whose subject
+    // still names your-org/your-app, so they are never suggested.
+    const liveLab = (supportsLocalBrowser(args.host.platform, args.host.arch)
+        ? ["local-browser", "try-live"]
+        : ["try-live"]).find((id) => args.labIds.includes(id));
+    if (!args.hasRun) {
+        return [
+            dryRun,
+            liveLab === undefined
+                ? { command: "humanish study list", why: "see the studies this project declares" }
+                : {
+                    command: `humanish doctor --study ${liveLab}`,
+                    why: `check what the ${liveLab} study still needs before a live run`,
+                },
         ];
     }
-    const suggestedLab = args.labIds[0];
-    const commands = [
+    return [
+        ...(liveLab === undefined
+            ? []
+            : [{ command: `humanish run ${liveLab}`, why: "run a real participant against an app" }]),
         {
-            command: suggestedLab ? `humanish watch ${suggestedLab}` : "humanish watch",
-            why: "run a lab and open the Observer while it goes",
-        },
-    ];
-    if (args.hasRun) {
-        commands.push({
             command: "humanish verify --run latest",
             why: "check the last run's evidence and public-safety gates",
-        });
-        commands.push({
-            command: "humanish observe --run latest",
-            why: "reopen the last run's Observer",
-        });
-    }
-    else {
-        commands.push({ command: "humanish lab list", why: "see the labs this project declares" });
-        commands.push({
-            command: "humanish doctor",
-            why: "check what this project still needs before a live run",
-        });
-    }
-    return commands;
+        },
+        { command: "humanish observe --run latest", why: "reopen the last run's Observer" },
+    ];
 }
 /**
  * The human rendering. Says where you are before it says what to do, because "what should I run"
  * has no answer that is true in every project.
  */
 export function formatOrientationHuman(state) {
-    const lines = [
-        "humanish — run realistic synthetic personas against your app and keep the evidence.",
-        "",
-    ];
+    const lines = [`humanish: ${PRODUCT_SENTENCE}`, ""];
     if (!state.initialized) {
         lines.push("This project is not set up yet.");
     }

package/dist/cli/product-sentence.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The product in one sentence. Line 3 of `README.md`, package.json's description, `humanish --help`,
+ * bare `humanish` and the humanish skill all use it; tests/cli/product-sentence.test.ts holds them
+ * equal.
+ */
+export declare const PRODUCT_SENTENCE = "Synthetic user research for apps, CLIs, and agent-facing product flows.";

package/dist/cli/product-sentence.js

@@ -0,0 +1,6 @@
+/**
+ * The product in one sentence. Line 3 of `README.md`, package.json's description, `humanish --help`,
+ * bare `humanish` and the humanish skill all use it; tests/cli/product-sentence.test.ts holds them
+ * equal.
+ */
+export const PRODUCT_SENTENCE = "Synthetic user research for apps, CLIs, and agent-facing product flows.";

package/dist/cli/program.d.ts

@@ -4,12 +4,17 @@ import { type CliIo } from "./io.js";
 /**
  * Enrich commander's flag rejections with where the flag actually lives. A bare "unknown option"
  * is accurate and unhelpful in the same way `no labs here yet` was: it reports a fact about this
- * command and says nothing the reader can act on. Silence is preserved when no sibling has it —
+ * command and says nothing the reader can act on. Silence is preserved when no sibling has it:
  * inventing a suggestion would be worse than none.
  */
 export declare function withSiblingFlagHint(text: string, root: Command): string;
 /** Drop the literal `--` that `pnpm <script> -- <args>` puts before the CLI's own arguments. */
 export declare function normalizeCliArgv(argv: string[]): string[];
+/**
+ * The root help's examples, in the order a newcomer runs them. Each passes on a freshly
+ * initialized project (tests/cli/root-help-examples.test.ts).
+ */
+export declare const ROOT_HELP_EXAMPLES: readonly ["humanish init --yes", "humanish run first-run", "humanish observe --run latest --open", "humanish doctor --study try-live", "humanish run try-live", "humanish verify --json"];
 export declare function createProgram(io?: Partial<CliIo> & {
     tuiRuntime?: Partial<TuiRuntime>;
 }): Command;