humanish 0.48.0 → 0.50.0

package/dist/program.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { formatOrientationHuman, readOrientation } from "./orientation.js";
 import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import { Command, Option } from "commander";
 import { startCodexAppServerUi } from "./codex-app-server-ui.js";
 import { loadEnvFile } from "./env-file.js";
+import { discoverProviderKeys, listUserKeys, resolveKeyName, setUserKey, unsetUserKey, userKeyStorePath } from "./key-resolution.js";
 import { redactText } from "./redaction.js";
 import { draftFeedback, listFeedback, renderIssueMarkdown, renderIssueUrl, verifyFeedback } from "./feedback.js";
 import { runInit } from "./init.js";
@@ -23,6 +24,10 @@ import { DEFAULT_OSS_REPOS, runOssLab } from "./oss-lab.js";
 import { cleanupOssMetaLabSandboxes, cleanupStaleOssMetaLabSandboxes, runOssMetaLab, startOssMetaLabLiveRefresh } from "./oss-meta-lab.js";
 import { cleanupRun, doctor, listRuns, readReview, runDryRun, verifyRun } from "./run.js";
 import { reclaimRunSandboxes } from "./reclaim.js";
+import { RunIndexCache, readRunIndex } from "./run-index.js";
+import { readRunDetail } from "./run-detail.js";
+import { launchRun, readLaunchLogTail } from "./tui-launch.js";
+import { TUI_MIN_NODE_MAJOR, nodeSupportsTui, tuiBundleUrl } from "./tui-contract.js";
 import { runCommsCatchHost } from "./comms-catch-host.js";
 import { DEFAULT_SANDBOX_CATCH_PORT } from "./comms-sandbox-catch.js";
 export const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
@@ -136,6 +141,8 @@ function reportUnexpectedActionError(command, io, error) {
 }
 export function createProgram(io = {}) {
     const cliIo = { ...defaultIo, ...io };
+    keyDiscoveryFn = io.keyDiscovery ?? discoverProviderKeys;
+    tuiRuntime = { ...defaultTuiRuntime, ...io.tuiRuntime };
     const program = new HumanishCommand(undefined, cliIo);
     // Bare `humanish` orients instead of printing sixteen subcommands (#367). --help is untouched;
     // this is only what happens when no command was chosen at all.
@@ -177,6 +184,8 @@ export function createProgram(io = {}) {
     ].join("\n"));
     registerInitCommand(program, cliIo);
     registerDoctorCommand(program, cliIo);
+    registerTuiCommand(program, cliIo);
+    registerKeysCommand(program, cliIo);
     registerRunCommand(program, cliIo);
     registerVerifyCommand(program, cliIo);
     registerCleanupCommand(program, cliIo);
@@ -234,6 +243,244 @@ function registerDoctorCommand(parent, io) {
         io.setExitCode(result.ok ? 0 : 2);
     });
 }
+const defaultTuiRuntime = {
+    stdin: process.stdin,
+    stdout: process.stdout,
+    nodeVersion: process.version,
+    loadTui: async (bundle) => {
+        if (!existsSync(bundle))
+            return null;
+        return (await import(bundle.href));
+    }
+};
+let tuiRuntime = defaultTuiRuntime;
+const TUI_RESULT_SCHEMA = "humanish.tui-result.v1";
+function refuseTui(command, io, refusal) {
+    if (wantsJson(command)) {
+        io.writeOut(`${JSON.stringify(refusal, null, 2)}\n`);
+    }
+    else {
+        io.writeErr(`${refusal.error.message}\n`);
+    }
+    markInvocationEnvelopeWritten(command);
+    io.setExitCode(2);
+}
+/**
+ * The stakeholder surface (#455). Every other command is written so an agent can drive it; this one
+ * is the opposite — it takes the screen and waits for a person.
+ *
+ * That inversion is why it refuses rather than degrades. An agent that runs `humanish tui` with a
+ * piped stdout has asked for something that cannot exist, and the useful answer is a structured
+ * error naming the command that WOULD have answered the question. A TUI that quietly rendered
+ * frames into a pipe would poison a transcript with escape codes and look like a hang.
+ */
+function registerTuiCommand(parent, io) {
+    parent
+        .command("tui")
+        .description("Open the interactive terminal surface for browsing labs and runs (humans only).")
+        .summary("Open the interactive terminal surface.")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const { stdin, stdout } = tuiRuntime;
+        if (stdin.isTTY !== true || stdout.isTTY !== true) {
+            refuseTui(command, io, {
+                schema: TUI_RESULT_SCHEMA,
+                ok: false,
+                error: {
+                    code: "HUMANISH_TUI_REQUIRES_TTY",
+                    message: "humanish tui needs an interactive terminal. For scripted or agent use, `humanish runs --json` lists the same runs and `humanish lab run --json` starts one."
+                }
+            });
+            return;
+        }
+        if (!nodeSupportsTui(tuiRuntime.nodeVersion)) {
+            refuseTui(command, io, {
+                schema: TUI_RESULT_SCHEMA,
+                ok: false,
+                error: {
+                    code: "HUMANISH_TUI_UNSUPPORTED_NODE",
+                    message: `humanish tui needs Node ${TUI_MIN_NODE_MAJOR} or newer (this is ${tuiRuntime.nodeVersion}). Every other humanish command still works on this runtime.`
+                }
+            });
+            return;
+        }
+        // The Ink app ships as a pre-built bundle beside the compiled CLI and is loaded ONLY here, so
+        // no agent-facing command pays its parse cost.
+        const bundle = tuiBundleUrl(import.meta.url);
+        const runIndexCache = new RunIndexCache();
+        const loaded = await tuiRuntime.loadTui(bundle);
+        if (loaded === null) {
+            refuseTui(command, io, {
+                schema: TUI_RESULT_SCHEMA,
+                ok: false,
+                error: {
+                    code: "HUMANISH_TUI_BUNDLE_MISSING",
+                    message: `The terminal surface bundle is missing at ${bundle.pathname}. In a checkout, run \`pnpm build\`; in an install, this package is incomplete — please report it.`
+                }
+            });
+            return;
+        }
+        const exitCode = await loaded.startTui({
+            cwd: resolve(options.cwd),
+            version: { cli: CLI_VERSION },
+            capabilities: {
+                // One cache for the life of the surface: it refreshes on a cadence, and re-walking every
+                // run tree each tick is the cost this index exists to avoid.
+                readRunIndex: (target, readOptions) => readRunIndex(target, { ...readOptions, cache: runIndexCache }),
+                listLabs: listLabManifests,
+                startRun: launchRun,
+                readLaunchLog: readLaunchLogTail,
+                readRunDetail
+            },
+            stdin,
+            stdout
+        });
+        // The surface owned the screen; it has already told the operator whatever there was to say.
+        markInvocationEnvelopeWritten(command);
+        io.setExitCode(exitCode);
+    });
+}
+// The discovery fn the env seam calls; injectable via createProgram for hermetic CLI tests.
+let keyDiscoveryFn = discoverProviderKeys;
+const KEYS_RESULT_SCHEMA = "humanish.keys-result.v1";
+function formatKeysHuman(result) {
+    const lines = [`humanish keys ${result.ok ? "ok" : "failed"}`, `store: ${result.store}`, result.message];
+    if (result.action === "list" && result.names.length > 0) {
+        for (const name of result.names)
+            lines.push(`- ${name}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** Read one secret line: from a piped stdin when --stdin, else a hidden TTY prompt. */
+async function readSecretValue(useStdin, promptLabel, io) {
+    if (useStdin || !process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        const text = Buffer.concat(chunks).toString("utf8").trim();
+        return text.length > 0 ? text : null;
+    }
+    io.writeErr(`${promptLabel} (input hidden): `);
+    return await new Promise((resolve) => {
+        const stdin = process.stdin;
+        let value = "";
+        stdin.setRawMode?.(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+        const onData = (key) => {
+            if (key === "\u0003") {
+                cleanup();
+                resolve(null);
+                return;
+            }
+            if (key === "\r" || key === "\n") {
+                cleanup();
+                io.writeErr("\n");
+                resolve(value.trim().length > 0 ? value.trim() : null);
+                return;
+            }
+            if (key === "\u007f" || key === "\b") {
+                value = value.slice(0, -1);
+                return;
+            }
+            value += key;
+        };
+        const cleanup = () => {
+            stdin.off("data", onData);
+            stdin.setRawMode?.(false);
+            stdin.pause();
+        };
+        stdin.on("data", onData);
+    });
+}
+function registerKeysCommand(parent, io) {
+    const keys = parent
+        .command("keys")
+        .description("Manage the humanish user-level key store used by provider-key discovery (#436).")
+        .summary("Manage the user-level provider key store.");
+    keys
+        .command("set")
+        .argument("<vendor-or-name>", "A vendor alias (openai, e2b, anthropic, github) or a raw ENV_NAME.")
+        .description("Store one provider key in the user store (0600), prompted with hidden input.")
+        .option("--stdin", "Read the value from stdin instead of prompting (for agents/pipes).")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (vendorOrName, options, command) => {
+        const name = resolveKeyName(vendorOrName);
+        const storePath = userKeyStorePath(process.env);
+        if (name === null) {
+            const result = {
+                schema: KEYS_RESULT_SCHEMA, ok: false, action: "set", store: storePath, names: [],
+                message: `Not a vendor alias or valid env name: ${vendorOrName}. Vendors: openai, e2b, anthropic, github.`
+            };
+            writeResult(command, io, result, formatKeysHuman);
+            io.setExitCode(2);
+            return;
+        }
+        const value = await readSecretValue(options.stdin === true, `Value for ${name}`, io);
+        if (value === null) {
+            const result = {
+                schema: KEYS_RESULT_SCHEMA, ok: false, action: "set", store: storePath, names: [name],
+                message: "No value provided; nothing written."
+            };
+            writeResult(command, io, result, formatKeysHuman);
+            io.setExitCode(2);
+            return;
+        }
+        try {
+            const written = setUserKey(name, value, process.env);
+            const result = {
+                schema: KEYS_RESULT_SCHEMA, ok: true, action: "set", store: written.path, names: [name],
+                message: `${name} stored (0600). Live commands resolve it automatically; remove with "humanish keys unset ${name}".`
+            };
+            writeResult(command, io, result, formatKeysHuman);
+            io.setExitCode(0);
+        }
+        catch (error) {
+            const result = {
+                schema: KEYS_RESULT_SCHEMA, ok: false, action: "set", store: storePath, names: [name],
+                message: error instanceof Error ? error.message : "Failed to write the key store."
+            };
+            writeResult(command, io, result, formatKeysHuman);
+            io.setExitCode(2);
+        }
+    });
+    keys
+        .command("unset")
+        .argument("<vendor-or-name>", "A vendor alias or raw ENV_NAME to remove from the store.")
+        .description("Remove one key from the user store.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (vendorOrName, _options, command) => {
+        const name = resolveKeyName(vendorOrName);
+        const storePath = userKeyStorePath(process.env);
+        const had = name !== null && unsetUserKey(name, process.env);
+        const result = {
+            schema: KEYS_RESULT_SCHEMA, ok: name !== null, action: "unset", store: storePath,
+            names: name === null ? [] : [name],
+            message: name === null
+                ? `Not a vendor alias or valid env name: ${vendorOrName}.`
+                : had ? `${name} removed from the store.` : `${name} was not in the store; nothing changed.`
+        };
+        writeResult(command, io, result, formatKeysHuman);
+        io.setExitCode(name === null ? 2 : 0);
+    });
+    keys
+        .command("list")
+        .description("List the NAMES stored in the user store. Values are never printed.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (_options, command) => {
+        const storePath = userKeyStorePath(process.env);
+        const names = listUserKeys(process.env);
+        const result = {
+            schema: KEYS_RESULT_SCHEMA, ok: true, action: "list", store: storePath, names,
+            message: names.length === 0
+                ? "The store is empty. Add a key with `humanish keys set <vendor>`."
+                : `${names.length} key name(s) stored. Values are never printed.`
+        };
+        writeResult(command, io, result, formatKeysHuman);
+        io.setExitCode(0);
+    });
+}
 function registerRunCommand(parent, io) {
     parent
         .command("run")
@@ -1612,6 +1859,11 @@ async function runLabCommand(args) {
         args.io.writeErr(`warning: ${warning}\n`);
     }
     const config = resolved.config;
+    // The run's identity (#455): which manifest, where it lives, and whether it is committed, a
+    // local overlay, or an explicit path. Resolved once here — the only place that knows all three —
+    // and carried into the run's status record and bundle so the filesystem can answer "which lab
+    // produced this run" without the old `persona.source = "lab:<id>"` string convention.
+    const lab = { id: config.id, path: resolved.path, origin: resolved.origin };
     const backend = selectLabBackend(config);
     if (backend !== "cua" && labRerunFlagsRequested(args.options)) {
         writeUnsupportedRerunFlagsResult(args, backend);
@@ -1663,28 +1915,28 @@ async function runLabCommand(args) {
     }
     switch (backend) {
         case "synthetic":
-            await runSyntheticBackend({ ...args, config });
+            await runSyntheticBackend({ ...args, config, labProvenance: lab });
             return;
         case "meta":
-            await runMetaBackend({ ...args, config });
+            await runMetaBackend({ ...args, config, labProvenance: lab });
             return;
         case "smoke":
-            await runSmokeBackend({ ...args, config });
+            await runSmokeBackend({ ...args, config, labProvenance: lab });
             return;
         case "cua":
-            await runCuaBackend({ ...args, config, ...(scorer ? { scorer } : {}) });
+            await runCuaBackend({ ...args, config, labProvenance: lab, ...(scorer ? { scorer } : {}) });
             return;
         case "scripted":
-            await runScriptedBackend({ ...args, config });
+            await runScriptedBackend({ ...args, config, labProvenance: lab });
             return;
         case "terminal":
-            await runTerminalBackend({ ...args, config, ...(scorer ? { scorer } : {}) });
+            await runTerminalBackend({ ...args, config, labProvenance: lab, ...(scorer ? { scorer } : {}) });
             return;
         case "shared-world":
-            await runSharedWorldBackend({ ...args, config, ...(scorer ? { scorer } : {}) });
+            await runSharedWorldBackend({ ...args, config, labProvenance: lab, ...(scorer ? { scorer } : {}) });
             return;
         case "concurrent-shared-world":
-            await runConcurrentSharedWorldBackend({ ...args, config, ...(scorer ? { scorer } : {}) });
+            await runConcurrentSharedWorldBackend({ ...args, config, labProvenance: lab, ...(scorer ? { scorer } : {}) });
             return;
         default:
             // Compile-time exhaustiveness: a future backend must be handled here, not silently no-op.
@@ -1727,6 +1979,7 @@ async function runSyntheticBackend(args) {
     }
     const outcome = await runLab(args.config, {
         cwd: args.options.cwd,
+        ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
         count: simCount,
         ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
         ...(args.options.runId === undefined ? {} : { runId: args.options.runId })
@@ -1834,6 +2087,7 @@ async function runCuaBackend(args) {
     try {
         outcome = await runLab(args.config, {
             cwd: args.options.cwd,
+            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             // Watch mode opens the served Observer below (or prints the phone target under --expose)
             // instead of the static render — preserved byte-for-byte from the pre-0.18 open policy so a
             // non-follow watch (dry-run/--json) does not double-open. Run mode keeps the static open.
@@ -1969,6 +2223,7 @@ async function runScriptedBackend(args) {
     });
     const outcome = await runLab(args.config, {
         cwd: args.options.cwd,
+        ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
         // Watch mode opens the served Observer below instead of the static render.
         open: args.mode === "watch" ? false : shouldOpen,
         ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
@@ -2005,6 +2260,7 @@ async function runTerminalBackend(args) {
     });
     const outcome = await runLab(args.config, {
         cwd: args.options.cwd,
+        ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
         open: args.mode === "watch" ? false : shouldOpen,
         ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
         ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
@@ -2038,6 +2294,7 @@ async function runSharedWorldBackend(args) {
     });
     const outcome = await runLab(args.config, {
         cwd: args.options.cwd,
+        ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
         open: args.mode === "watch" ? false : shouldOpen,
         ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
         ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
@@ -2119,6 +2376,7 @@ async function runConcurrentSharedWorldBackend(args) {
     try {
         outcome = await runLab(args.config, {
             cwd: args.options.cwd,
+            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             open: wantsFollow ? false : shouldOpen,
             dryRun,
             ...(wantsFollow
@@ -2280,6 +2538,7 @@ async function runSmokeBackend(args) {
     const repos = labReposOverride(args.options);
     const outcome = await runLab(args.config, {
         cwd: args.options.cwd,
+        ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
         count: limit,
         ...(repos === undefined ? {} : { repos }),
         ...(args.options.keep === undefined ? {} : { keep: args.options.keep }),
@@ -2336,6 +2595,8 @@ async function runMetaBackend(args) {
     try {
         const outcome = await runLab(args.config, {
             cwd: args.options.cwd,
+            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
+            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
             ...(wantsFollow ? { completionTimeoutMs: 0 } : {}),
             ...(codexAppServer === undefined ? {} : { codexAppServer }),
             ...(wantsFollow
@@ -2440,16 +2701,29 @@ async function renderAndMaybeFollowObserver(args) {
     }
 }
 async function applyEnvFileOption(args) {
-    if (!args.envFile) {
-        return true;
+    if (args.envFile) {
+        const result = await loadEnvFile(args.cwd, args.envFile);
+        if (!result.ok) {
+            writeResult(args.command, args.io, result, formatEnvFileHuman);
+            args.io.setExitCode(2);
+            return false;
+        }
+    }
+    // Provider-key discovery (#436): fill still-missing keys from the documented project
+    // overlay, the owning vendors' native stores, and the humanish user store — fill-only
+    // (an explicit --env-file or process env always wins), each fill announced by name and
+    // source on stderr, never by value. HUMANISH_STRICT_KEYS=1 restores env-only behavior.
+    try {
+        await keyDiscoveryFn({
+            cwd: args.cwd,
+            env: process.env,
+            announce: (line) => args.io.writeErr(`${line}\n`)
+        });
     }
-    const result = await loadEnvFile(args.cwd, args.envFile);
-    if (result.ok) {
-        return true;
+    catch {
+        // Discovery must never break a command; a rung that fails to read is a miss, not an error.
     }
-    writeResult(args.command, args.io, result, formatEnvFileHuman);
-    args.io.setExitCode(2);
-    return false;
+    return true;
 }
 function labReposOverride(options) {
     const override = [