humanish 0.104.3 → 0.106.0

package/dist/cli/program.js

@@ -0,0 +1,338 @@
+import { readFileSync } from "node:fs";
+import { formatOrientationHuman, readOrientation } from "./orientation.js";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { redactText } from "../evidence/redaction.js";
+import { PortInUseError } from "../observer/listen.js";
+import { buildPayload, disabledByEnvironment, durationBucket, readTelemetryState, sendTelemetry, TELEMETRY_NOTICE, writeTelemetryState, isOwnCheckoutRun, } from "./telemetry.js";
+import { registerAnalyzeCommand } from "./commands/analyze.js";
+import { registerCodexCommands } from "./commands/codex.js";
+import { registerCommsCommands } from "./commands/comms.js";
+import { registerFeedbackCommands } from "./commands/feedback.js";
+import { registerLabCommands } from "./commands/lab.js";
+import { registerObserveCommand, registerServeCommand } from "./commands/observe.js";
+import { registerCleanupCommand, registerExportCommand, registerReclaimCommand, registerReviewCommand, registerRunCommand, registerRunsCommand, registerRuntimeCommands, registerStatsCommand, registerVerifyCommand, } from "./commands/runs.js";
+import { registerDoctorCommand, registerInitCommand, registerKeysCommand, registerTelemetryCommand, } from "./commands/setup.js";
+import { defaultTuiRuntime, registerTuiCommand } from "./commands/tui.js";
+import { registerWatchCommand } from "./commands/watch.js";
+import { CLI_RESPONSE_SCHEMA, CLI_VERSION, defaultIo, invocationEnvelopeAlreadyWritten, studyFactsFor, wantsJson, } from "./io.js";
+// Command boundary catch-all (fix set point 1): every leaf command is created
+// through HumanishCommand.createCommand, and HumanishCommand.action wraps the caller's
+// handler so an uncaught throw or promise rejection can never escape as a raw
+// Node crash. On failure it emits the same structured envelope --json commands
+// already promise (schema humanish.cli-response.v1, ok: false, error.code
+// HUMANISH_UNEXPECTED) or a single concise stderr line otherwise, then sets exit
+// code 2 through the existing CliIo.setExitCode seam. This is the single seam:
+// none of the ~20 .action() handlers below need their own try/catch for this.
+/**
+ * Print the disclosure the first time humanish would collect anything, and remember that it was
+ * shown. AWAITED by the caller: if this loses the race with process exit, a default-on collector
+ * becomes a silent one.
+ */
+async function announceTelemetryOnce(command, io) {
+    try {
+        if (commandPath(command).startsWith("telemetry"))
+            return;
+        if (disabledByEnvironment(process.env))
+            return;
+        const state = await readTelemetryState();
+        if (!state.enabled || state.noticed)
+            return;
+        io.writeErr(`${TELEMETRY_NOTICE}\n`);
+        await writeTelemetryState({ ...state, noticed: true });
+    }
+    catch {
+        // Never blocks the command.
+    }
+}
+/** The exit code the most recent command chose through CliIo.setExitCode; 0 until it says otherwise. */
+let lastExitCode = 0;
+/**
+ * Record that a command ran. Anonymous, allowlisted, and unable to affect the command: it is not
+ * awaited, it is bounded by its own timeout, and every failure inside it is swallowed.
+ */
+async function recordCommandTelemetry(command, ok, durationMs, exitCode) {
+    try {
+        // `telemetry` itself is never measured: instrumenting the opt-out would be indecent.
+        const name = commandPath(command);
+        if (name.startsWith("telemetry"))
+            return;
+        if (disabledByEnvironment(process.env))
+            return;
+        // Our own checkout never reports, from whichever directory the command was started: see
+        // isOwnCheckoutRun for the measured reason both walks exist.
+        if (isOwnCheckoutRun(process.cwd(), dirname(fileURLToPath(import.meta.url)), (p) => readFileSync(p, "utf8")))
+            return;
+        const state = await readTelemetryState();
+        if (!state.enabled)
+            return;
+        const payload = buildPayload({
+            event: "cli_command",
+            anonymousId: state.anonymousId,
+            version: CLI_VERSION,
+            // The study facts (mode, outcome, starter lab, brain, our own error code) were read off the
+            // result document when it was written; see writeResult. Without them every `run` event
+            // looked the same whether it was a dry run or the first live study that ever worked.
+            properties: {
+                ...studyFactsFor(command),
+                command: name,
+                ok: ok && exitCode === 0,
+                exitCode,
+                durationBucket: durationBucket(durationMs),
+            },
+        });
+        if (process.env.HUMANISH_TELEMETRY_DEBUG !== undefined &&
+            process.env.HUMANISH_TELEMETRY_DEBUG !== "") {
+            process.stderr.write(`humanish telemetry (debug, not sent): ${JSON.stringify(payload)}\n`);
+            return;
+        }
+        await sendTelemetry(payload);
+    }
+    catch {
+        // Metrics are our problem, never the operator's.
+    }
+}
+/**
+ * HUMANISH_DEBUG_HANDLES=1: after a command's handler settles, name what is still keeping the
+ * process alive (#581). A live terminal run wrote its result 64 s in and the CLI stayed up for
+ * sixteen more minutes; nothing in the bundle could say what held it, and an in-process probe of
+ * the lane found nothing of ours. This is the one line that answers it next time: the resource
+ * types Node reports, once, to stderr, after one macrotask so settled work has cleared.
+ */
+function reportActiveHandles(command, io) {
+    const flag = process.env.HUMANISH_DEBUG_HANDLES;
+    if (flag === undefined || flag === "" || flag === "0")
+        return;
+    setImmediate(() => {
+        const proc = process;
+        const resources = proc.getActiveResourcesInfo?.() ?? [];
+        const counts = new Map();
+        for (const resource of resources)
+            counts.set(resource, (counts.get(resource) ?? 0) + 1);
+        const summary = [...counts.entries()].map(([type, count]) => `${type}×${count}`).join(", ") || "none";
+        io.writeErr(`humanish debug: active resources after \`${commandPath(command) || "humanish"}\` settled: ${summary}\n`);
+    }).unref?.();
+}
+/** `lab run`, not `run`, so the two are distinguishable — and nothing else from the invocation. */
+function commandPath(command) {
+    const parts = [];
+    let current = command;
+    while (current && current.name() !== "humanish") {
+        parts.unshift(current.name());
+        current = current.parent;
+    }
+    return parts.join(" ");
+}
+class HumanishCommand extends Command {
+    cliIo;
+    constructor(name, cliIo) {
+        super(name);
+        this.cliIo = cliIo;
+    }
+    createCommand(name) {
+        return new HumanishCommand(name, this.cliIo);
+    }
+    action(fn) {
+        const cliIo = this.cliIo;
+        const wrapped = function (...args) {
+            // ONE emission point for every command, at the same seam that already catches every throw.
+            // Twenty .action() handlers each remembering to record a metric is twenty chances to forget
+            // one, and a funnel with a hole in it is worse than no funnel.
+            const startedAt = Date.now();
+            lastExitCode = 0;
+            // The NOTICE is awaited; the SEND is not. They have opposite requirements: disclosure must
+            // never be lost (a silent default-on collector is indefensible), and a metric must never
+            // make anyone wait. The first version put both in the fire-and-forget path, and the notice
+            // lost the race with process exit — a real participant ran this build and never saw it.
+            const noticed = announceTelemetryOnce(this, cliIo);
+            const finish = (ok) => {
+                void recordCommandTelemetry(this, ok, Date.now() - startedAt, lastExitCode);
+                reportActiveHandles(this, cliIo);
+            };
+            try {
+                // Reflect.apply (not fn.apply) sidesteps TS's special CallableFunction
+                // overload for functions typed with an explicit `this` parameter, which
+                // would otherwise reject the plain `Command` thisArg below.
+                const result = Reflect.apply(fn, this, args);
+                if (result && typeof result.then === "function") {
+                    return Promise.all([result, noticed]).then(() => {
+                        finish(true);
+                    }, (error) => {
+                        reportUnexpectedActionError(this, cliIo, error);
+                        finish(false);
+                    });
+                }
+                // A synchronous action still has to let the disclosure land before the process exits.
+                return noticed.then(() => {
+                    finish(true);
+                });
+            }
+            catch (error) {
+                reportUnexpectedActionError(this, cliIo, error);
+                return undefined;
+            }
+        };
+        return super.action(wrapped);
+    }
+}
+function reportUnexpectedActionError(command, io, error) {
+    const message = redactText(error instanceof Error ? error.message : String(error));
+    // A taken port is the most expected thing a serving command meets; it gets its own code rather
+    // than the catch-all's (#484). The message already names the port and whose it is.
+    const code = error instanceof PortInUseError ? "HUMANISH_PORT_IN_USE" : "HUMANISH_UNEXPECTED";
+    if (wantsJson(command)) {
+        if (invocationEnvelopeAlreadyWritten(command)) {
+            // Some result already went to stdout for this invocation before the
+            // failure landed -- e.g. `codex app-server --keep-open --json` writes its
+            // "running" envelope via writeResult, then a later `await` can still
+            // reject (src/actors/codex/app-server-ui.ts's persistState() write can fail on
+            // either branch of that command's completion handling). Appending a
+            // second JSON document to stdout would break every JSON.parse(stdout)
+            // consumer, so this failure goes to stderr instead, same as the non-json
+            // branch below.
+            io.writeErr(`${code}: ${message}\n`);
+            io.setExitCode(2);
+            return;
+        }
+        const envelope = {
+            schema: CLI_RESPONSE_SCHEMA,
+            ok: false,
+            error: {
+                code,
+                message,
+            },
+        };
+        io.writeOut(`${JSON.stringify(envelope, null, 2)}\n`);
+    }
+    else {
+        io.writeErr(`${code}: ${message}\n`);
+    }
+    io.setExitCode(2);
+}
+/** `unknown option '--x'` -> the sibling commands that DO declare `--x`. */
+function commandsDeclaring(root, flag) {
+    const found = [];
+    const walk = (command, trail) => {
+        const names = [...trail, command.name()];
+        if (trail.length > 0 &&
+            command.options.some((option) => option.long === flag || option.short === flag)) {
+            found.push(names.slice(1).join(" "));
+        }
+        for (const child of command.commands)
+            walk(child, names);
+    };
+    walk(root, []);
+    return found;
+}
+/**
+ * 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 —
+ * inventing a suggestion would be worse than none.
+ */
+export function withSiblingFlagHint(text, root) {
+    const match = /unknown option '([^']+)'/.exec(text);
+    if (match === null)
+        return text;
+    const owners = commandsDeclaring(root, match[1]);
+    if (owners.length === 0)
+        return text;
+    // Truncation is REPORTED, never silent: a list that quietly drops owners would send a reader
+    // looking in the wrong place and think it had answered them.
+    const shown = owners.slice(0, 3);
+    const list = shown.map((owner) => `\`humanish ${owner}\``).join(", ");
+    const rest = owners.length - shown.length;
+    const tail = rest > 0 ? ` (and ${rest} more)` : "";
+    return `${text.replace(/\n+$/, "")}\n${match[1]} is an option of ${list}${tail}, not of this command.\n`;
+}
+/** Drop the literal `--` that `pnpm <script> -- <args>` puts before the CLI's own arguments. */
+export function normalizeCliArgv(argv) {
+    const [runtime, entrypoint, separator, ...rest] = argv;
+    if (runtime && entrypoint && separator === "--") {
+        return [runtime, entrypoint, ...rest];
+    }
+    return argv;
+}
+export function createProgram(io = {}) {
+    const given = { ...defaultIo, ...io };
+    // Telemetry's `ok` used to mean "the handler did not throw", which is true of nearly every
+    // failure: commands report failure through their envelope and setExitCode(2), not by throwing.
+    // 1,359 study events in two days and every one said ok. Record the exit code the command chose.
+    const cliIo = {
+        ...given,
+        setExitCode: (code) => {
+            lastExitCode = code;
+            given.setExitCode(code);
+        },
+    };
+    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.
+    program.action(async (options) => {
+        const state = await readOrientation(".");
+        if (options.json === true) {
+            cliIo.writeOut(`${JSON.stringify(state, null, 2)}\n`);
+        }
+        else {
+            cliIo.writeOut(formatOrientationHuman(state));
+        }
+        cliIo.setExitCode(0);
+    });
+    program
+        .name("humanish")
+        .description("Open-source-safe persona simulation CLI and proof harness.")
+        .version(CLI_VERSION)
+        .showHelpAfterError()
+        .option("--json", "Print machine-readable JSON responses where supported.")
+        .configureOutput({
+        writeOut: (text) => cliIo.writeOut(text),
+        writeErr: (text) => cliIo.writeErr(text),
+        // A rejected flag should name the command that WOULD have taken it. Found by a real
+        // first-contact study (labs/first-contact.yaml): a participant reached for
+        // `humanish run --no-open` by analogy with `lab run`, got a bare "unknown option", and
+        // filed it as a documentation mismatch. The flag is genuinely absent — `run` opens
+        // nothing — but "unknown" says that badly, because the reader's actual question is
+        // "then where does it live?".
+        outputError: (text, write) => write(withSiblingFlagHint(text, program)),
+    })
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  humanish watch",
+        "  humanish watch first-run",
+        "  humanish watch --lab .humanish/labs/local.yaml",
+        "  humanish watch --run latest --detach",
+        "  humanish watch --json --no-open",
+        "  humanish lab list",
+        "  humanish lab run first-run --json --no-open",
+        "  humanish verify --run latest --json",
+        "",
+        "Public-safety boundary:",
+        "  humanish must not commit or emit PII, PHI, secrets, keys, raw private transcripts,",
+        "  private screenshots, or private upstream artifacts.",
+    ].join("\n"));
+    registerInitCommand(program, cliIo);
+    registerDoctorCommand(program, cliIo);
+    registerTuiCommand(program, cliIo, { ...defaultTuiRuntime, ...io.tuiRuntime });
+    registerTelemetryCommand(program, cliIo);
+    registerKeysCommand(program, cliIo);
+    registerRunCommand(program, cliIo);
+    registerVerifyCommand(program, cliIo);
+    registerCleanupCommand(program, cliIo);
+    registerReviewCommand(program, cliIo);
+    registerAnalyzeCommand(program, cliIo);
+    registerRunsCommand(program, cliIo);
+    registerStatsCommand(program, cliIo);
+    registerExportCommand(program, cliIo);
+    registerCommsCommands(program, cliIo);
+    registerRuntimeCommands(program, cliIo);
+    registerReclaimCommand(program, cliIo);
+    registerWatchCommand(program, cliIo);
+    registerObserveCommand(program, cliIo);
+    registerServeCommand(program, cliIo);
+    registerCodexCommands(program, cliIo);
+    registerLabCommands(program, cliIo);
+    registerFeedbackCommands(program, cliIo);
+    return program;
+}

package/dist/cli/secret-prompt.js

@@ -0,0 +1,39 @@
+import { createInterface } from "node:readline/promises";
+import { Writable } from "node:stream";
+/** Host-owned entry: no secret crosses the TUI view contract or reaches a writable terminal. */
+export async function promptSecret(label, stdin, stdout) {
+    if (!stdin.isTTY || !stdout.isTTY)
+        return null;
+    const wasRaw = stdin.isRaw;
+    // readline owns editing, paste and raw-mode lifecycle; all of its echo goes to this sink.
+    const sink = new Writable({
+        write(_chunk, _encoding, done) {
+            done();
+        },
+    });
+    const reader = createInterface({ input: stdin, output: sink, terminal: true, historySize: 0 });
+    // Ink unrefs stdin on unmount. A pending promise alone does not keep Node alive.
+    stdin.ref?.();
+    return await new Promise((resolve) => {
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            reader.close();
+            stdin.setRawMode?.(wasRaw === true);
+            stdin.pause();
+            stdin.unref?.();
+            stdout.write("\n");
+            resolve(value);
+        };
+        reader.once("line", (line) => finish(line.trim() || null));
+        reader.once("SIGINT", () => finish(null));
+        reader.once("close", () => finish(null));
+        reader.once("error", () => finish(null));
+        // Advertise readiness only after raw mode and handlers are active. Printing this first lets
+        // fast paste race terminal echo and exposes the very value this prompt exists to hide.
+        stdin.resume();
+        stdout.write(`${label} (input hidden; Ctrl+C cancels): `);
+    });
+}