humanish 0.104.3 → 0.106.0

package/dist/cli/io.js

@@ -0,0 +1,232 @@
+import { automaticAnalysisSucceeded, defaultAnalysisOverBudget, } from "../analysis/automatic-completion.js";
+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 { loadEnvFile } from "../keys/env-file.js";
+import { discoverProviderKeys } from "../keys/key-resolution.js";
+import { deriveStudyFacts } from "./telemetry.js";
+import { forTerminal } from "../routes/terminal/encoding.js";
+export const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
+function readCliVersion() {
+    const packageJsonPath = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+    return typeof packageJson.version === "string" && packageJson.version.trim()
+        ? packageJson.version
+        : "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.
+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
+// 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;
+export const defaultIo = {
+    writeOut: (text) => process.stdout.write(forStream(process.stdout, text)),
+    writeErr: (text) => process.stderr.write(forStream(process.stderr, text)),
+    setExitCode: (code) => {
+        process.exitCode = code;
+    },
+};
+// Fix set point 1 (general guard): writeResult marks its own invocation's root
+// command the moment it flushes a result to stdout. Keyed by the root Command
+// 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
+// that Command tree is garbage collected.
+const invocationEnvelopeWritten = new WeakSet();
+function rootCommandOf(command) {
+    let current = command;
+    while (current.parent) {
+        current = current.parent;
+    }
+    return current;
+}
+export function markInvocationEnvelopeWritten(command) {
+    invocationEnvelopeWritten.add(rootCommandOf(command));
+}
+export function invocationEnvelopeAlreadyWritten(command) {
+    return invocationEnvelopeWritten.has(rootCommandOf(command));
+}
+export async function applyEnvFileOption(args) {
+    const env = args.env ?? process.env;
+    if (args.envFile) {
+        const stagedEnv = { ...env };
+        const result = await loadEnvFile(args.cwd, args.envFile, stagedEnv);
+        if (!result.ok) {
+            writeResult(args.command, args.io, result, formatEnvFileHuman);
+            args.io.setExitCode(2);
+            return false;
+        }
+        for (const name of result.loaded)
+            env[name] = stagedEnv[name];
+    }
+    if (args.discoverKeys !== false) {
+        await discoverCliKeys({
+            io: args.io,
+            cwd: args.cwd,
+            env,
+            ...(args.onDiscovered === undefined ? {} : { onDiscovered: args.onDiscovered }),
+        });
+    }
+    return true;
+}
+/**
+ * Provider-key discovery (#436): 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.
+ */
+export async function discoverCliKeys(args) {
+    try {
+        const discover = args.io.keyDiscovery ?? discoverProviderKeys;
+        const discovered = await discover({
+            cwd: args.cwd,
+            env: args.env ?? process.env,
+            announce: (line) => args.io.writeErr(`${line}\n`),
+        });
+        args.onDiscovered?.(discovered.map((fill) => fill.name));
+    }
+    catch {
+        // Discovery must never break a command; a rung that fails to read is a miss, not an error.
+    }
+}
+export function parseLabCount(value, fallback) {
+    return value === undefined ? fallback : parsePositiveInteger(value);
+}
+export function parseParticipantIds(value) {
+    if (value === undefined) {
+        return [];
+    }
+    const seen = new Set();
+    const participantIds = [];
+    for (const raw of value.split(",")) {
+        const participantId = raw.trim();
+        if (!participantId || seen.has(participantId))
+            continue;
+        seen.add(participantId);
+        participantIds.push(participantId);
+    }
+    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.
+export function writeResult(command, io, result, formatHuman) {
+    const output = automaticAnalysisEnvelope(result);
+    if (wantsJson(command)) {
+        io.writeOut(`${JSON.stringify(output, null, 2)}\n`);
+    }
+    else {
+        io.writeOut(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`);
+            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));
+}
+const studyFactsByCommand = new WeakMap();
+export function noteStudyFacts(command, facts) {
+    if (Object.keys(facts).length === 0)
+        return;
+    studyFactsByCommand.set(command, { ...studyFactsByCommand.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 formatRunHuman(result) {
+    if (!result.ok) {
+        return `${result.error?.code}: ${result.error?.message}\n`;
+    }
+    return ([
+        `humanish run ${result.mode}`,
+        `run: ${result.runId}`,
+        ...(result.simCount === undefined ? [] : [`sims: ${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`;
+    }
+    return ([
+        "humanish env-file loaded",
+        `env-file: ${result.envFile}`,
+        `loaded: ${result.loaded.length ? result.loaded.join(", ") : "none"}`,
+        `skipped-existing: ${result.skipped.length ? result.skipped.join(", ") : "none"}`,
+    ].join("\n") + "\n");
+}
+export function parsePositiveInteger(value) {
+    if (!/^\d+$/.test(value)) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isSafeInteger(parsed) && parsed >= 1 ? parsed : null;
+}
+export function parseTimeoutMs(value) {
+    if (!/^\d+$/.test(value)) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return parsed >= 1 && parsed <= 3_600_000 ? parsed : null;
+}
+export function parseObserverPort(value) {
+    if (!/^\d+$/.test(value)) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return parsed >= 0 && parsed <= 65535 ? parsed : null;
+}
+/** `--candidate` as the module option, absent when not given (exactOptionalPropertyTypes). */
+export function candidateOption(options) {
+    return {
+        ...(options.candidate === undefined ? {} : { candidate: options.candidate }),
+        ...(options.analysis === undefined ? {} : { analysis: options.analysis }),
+        ...(options.finding === undefined ? {} : { finding: options.finding }),
+    };
+}
+export function collectRepeated(value, previous) {
+    return [...previous, value];
+}
+export function wantsJson(command) {
+    let current = command;
+    while (current) {
+        if (current.opts().json === true) {
+            return true;
+        }
+        current = current.parent ?? null;
+    }
+    return false;
+}
+/** 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;
+    const suggested = Math.ceil(estimate ?? DEFAULT_ANALYSIS_MAX_COST_USD + 1);
+    const shown = estimate === null ? "" : ` ($${estimate.toFixed(2)})`;
+    return `analysis: its estimate${shown} is over the default $${DEFAULT_ANALYSIS_MAX_COST_USD} cap, so no request was sent. To analyze this run: humanish analyze --run ${result.runId ?? "latest"} --max-cost ${suggested}\n`;
+}
+export function automaticAnalysisEnvelope(result) {
+    if (result === null ||
+        typeof result !== "object" ||
+        !("automaticAnalysis" in result) ||
+        !("ok" in result))
+        return result;
+    const run = result;
+    return { ...run, runOk: run.ok, ok: run.ok && automaticAnalysisSucceeded(run) };
+}

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

@@ -0,0 +1,56 @@
+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";
+/** How a command shows an Observer, decided before the run it shows starts. */
+export interface ObserverPlan {
+    port: number;
+    /** Open the page: the served URL when following, the static file otherwise. */
+    shouldOpen: boolean;
+    wantsFollow: boolean;
+}
+/**
+ * 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.
+ */
+export declare function planObserver(args: {
+    command: Command;
+    cwd: string;
+    detach?: boolean | undefined;
+    io: CliIo;
+    open?: boolean | undefined;
+    port: string;
+}): ObserverPlan | null;
+/** The `open` a run's static Observer render takes: a followed Observer opens its served URL. */
+export declare function staticObserverOpen(plan: ObserverPlan): boolean;
+/** Write a rendered Observer's result, then serve and follow it when the plan says so. */
+export declare function showObserver(args: {
+    command: Command;
+    io: CliIo;
+    plan: ObserverPlan;
+    rendered: ObserverResult;
+}): Promise<void>;
+export declare function withObserverServer(rendered: ObserverResult, server: ObserverServer): ObserverResult;
+export declare function formatObserverHuman(result: ObserverResult): string;
+export type WatchStopSignal = "SIGINT" | "SIGTERM" | "SIGHUP";
+interface WatchSignalTarget {
+    once(event: WatchStopSignal, listener: () => void): unknown;
+    removeListener(event: WatchStopSignal, listener: () => void): unknown;
+}
+export declare function followObserver(io: CliIo, result: ObserverResult, server: ObserverServer, options?: {
+    onStop?: () => Promise<string[]>;
+    signalTarget?: WatchSignalTarget;
+    signals?: WatchStopSignal[];
+}): Promise<void>;
+export declare function exitCodeForSignal(signal: WatchStopSignal): number;
+export declare function watchExposeRequested(o: {
+    expose?: boolean | undefined;
+    tunnel?: string | undefined;
+    tunnelDomain?: string | undefined;
+    oauth?: string | undefined;
+    allowEmail?: string[] | undefined;
+    allowDomain?: string[] | undefined;
+    publicUrl?: string | undefined;
+}): boolean;
+export declare function exposureRequestFromOptions(options: LabCommandOptions): ExposureRequest;
+export {};

package/dist/cli/observer-follow.js

@@ -0,0 +1,160 @@
+import { Command } from "commander";
+import { serveObserver } from "../observer/render.js";
+import { formatRunHuman, parseObserverPort, wantsJson, writeResult, } 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.
+ */
+export function planObserver(args) {
+    const port = parseObserverPort(args.port);
+    if (port === null) {
+        const result = {
+            schema: "humanish.run-result.v1",
+            ok: false,
+            cwd: args.cwd,
+            warnings: [],
+            error: {
+                code: "HUMANISH_INVALID_PORT",
+                message: "--port must be an integer between 0 and 65535.",
+            },
+        };
+        writeResult(args.command, args.io, result, formatRunHuman);
+        args.io.setExitCode(2);
+        return null;
+    }
+    const wantsMachine = wantsJson(args.command);
+    const shouldOpen = args.open === false
+        ? false
+        : args.open === true
+            ? true
+            : !wantsMachine && process.stdout.isTTY === true;
+    return { port, shouldOpen, wantsFollow: !wantsMachine && args.detach !== true };
+}
+/** The `open` a run's static Observer render takes: a followed Observer opens its served URL. */
+export function staticObserverOpen(plan) {
+    return plan.wantsFollow ? false : plan.shouldOpen;
+}
+/** Write a rendered Observer's result, then serve and follow it when the plan says so. */
+export async function showObserver(args) {
+    const { plan, rendered } = args;
+    let server = null;
+    let result = rendered;
+    if (rendered.ok && plan.wantsFollow) {
+        server = await serveObserver(rendered, { open: plan.shouldOpen, port: plan.port });
+        result = withObserverServer(rendered, server);
+    }
+    writeResult(args.command, args.io, result, formatObserverHuman);
+    args.io.setExitCode(result.ok ? 0 : 2);
+    if (result.ok && server) {
+        await followObserver(args.io, result, server);
+    }
+}
+export function withObserverServer(rendered, server) {
+    return {
+        ...rendered,
+        observerUrl: server.url,
+        serverUrl: server.url,
+        opened: server.opened,
+        ...(server.openCommand ? { openCommand: server.openCommand } : {}),
+        warnings: [
+            ...rendered.warnings,
+            "Live observer server is polling observer-data.json with no-store caching.",
+            ...(server.warning ? [server.warning] : []),
+        ],
+    };
+}
+export function formatObserverHuman(result) {
+    if (!result.ok) {
+        return `${result.error?.code}: ${result.error?.message}\n`;
+    }
+    return ([
+        "humanish observer rendered",
+        `run: ${result.run}`,
+        `observer: ${result.observerPath}`,
+        ...(result.observerUrl ? [`url: ${result.observerUrl}`] : []),
+        ...(result.opened === undefined ? [] : [`opened: ${result.opened ? "yes" : "no"}`]),
+        `bundle: ${result.bundlePath}`,
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n");
+}
+export async function followObserver(io, result, server, options = {}) {
+    io.writeOut(`watching: ${result.serverUrl ?? result.observerUrl ?? result.observerPath}\n`);
+    io.writeOut("watching: press Ctrl-C to stop\n");
+    await new Promise((resolve) => {
+        const signalTarget = options.signalTarget ?? process;
+        const signals = options.signals ?? ["SIGINT", "SIGTERM", "SIGHUP"];
+        const handlers = new Map();
+        let stopping = false;
+        const stop = (signal) => {
+            if (stopping) {
+                return;
+            }
+            stopping = true;
+            for (const [registeredSignal, handler] of handlers.entries()) {
+                signalTarget.removeListener(registeredSignal, handler);
+            }
+            io.setExitCode(exitCodeForSignal(signal));
+            void (async () => {
+                try {
+                    await server.close();
+                }
+                catch (error) {
+                    io.writeErr(`watch cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`);
+                }
+                if (options.onStop) {
+                    try {
+                        const messages = await options.onStop();
+                        for (const message of messages) {
+                            io.writeOut(`watch cleanup: ${message}\n`);
+                        }
+                    }
+                    catch (error) {
+                        io.writeErr(`watch cleanup failed: ${error instanceof Error ? error.message : String(error)}\n`);
+                    }
+                }
+                io.writeOut("watch stopped\n");
+                resolve();
+            })();
+        };
+        for (const signal of signals) {
+            const handler = () => stop(signal);
+            handlers.set(signal, handler);
+            signalTarget.once(signal, handler);
+        }
+    });
+}
+export function exitCodeForSignal(signal) {
+    switch (signal) {
+        case "SIGINT":
+            return 130;
+        case "SIGTERM":
+            return 143;
+        case "SIGHUP":
+            return 129;
+    }
+}
+// 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.
+export function watchExposeRequested(o) {
+    return (o.expose === true ||
+        o.tunnel !== undefined ||
+        o.tunnelDomain !== undefined ||
+        o.oauth !== undefined ||
+        (o.allowEmail?.length ?? 0) > 0 ||
+        (o.allowDomain?.length ?? 0) > 0 ||
+        o.publicUrl !== undefined);
+}
+// Map LabCommandOptions onto the shared exposure validator input.
+export function exposureRequestFromOptions(options) {
+    return {
+        expose: options.expose === true,
+        ...(options.tunnel === undefined ? {} : { tunnel: options.tunnel }),
+        ...(options.tunnelDomain === undefined ? {} : { tunnelDomain: options.tunnelDomain }),
+        ...(options.oauth === undefined ? {} : { oauth: options.oauth }),
+        allowEmails: options.allowEmail ?? [],
+        allowDomains: options.allowDomain ?? [],
+        ...(options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl }),
+        safe: options.safe === true,
+    };
+}

package/dist/cli/orientation.d.ts

@@ -0,0 +1,30 @@
+export declare const ORIENTATION_SCHEMA: "humanish.orientation.v1";
+export interface OrientationState {
+    schema: typeof ORIENTATION_SCHEMA;
+    /** Whether this project has a committed `humanish/` source plane. */
+    initialized: boolean;
+    /** Committed + gitignored lab manifests discovered in this project. */
+    labCount: number;
+    /** Ids of a few labs worth naming in a suggestion. */
+    labIds: string[];
+    /** 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. */
+    nextCommands: OrientationCommand[];
+}
+interface OrientationCommand {
+    command: string;
+    why: string;
+}
+/**
+ * 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.
+ */
+export declare function readOrientation(cwd: 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.
+ */
+export declare function formatOrientationHuman(state: OrientationState): string;
+export {};

package/dist/cli/orientation.js

@@ -0,0 +1,114 @@
+// What `humanish` says when you run it with no arguments (#367).
+//
+// It used to print commander's help: 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.
+//
+// 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
+// useful on first contact and still useful on the hundredth run.
+//
+// Both audiences are served by the same data (docs/principles/three-roles.md). A human on a
+// terminal gets prose and an offer to set things up; an agent gets the same facts as stable text,
+// 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";
+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.
+ */
+export async function readOrientation(cwd) {
+    const [labs, runs] = await Promise.all([
+        listLabManifests(cwd).catch(() => undefined),
+        listRuns(cwd).catch(() => undefined),
+    ]);
+    const labIds = (labs?.labs ?? [])
+        .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;
+    return {
+        schema: ORIENTATION_SCHEMA,
+        initialized,
+        labCount: labIds.length,
+        labIds: labIds.slice(0, 3),
+        runCount: runIds.length,
+        ...(latest === undefined ? {} : { latestRunId: latest }),
+        nextCommands: nextCommandsFor({ initialized, labIds, hasRun: runIds.length > 0 }),
+    };
+}
+/**
+ * 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.
+ */
+function nextCommandsFor(args) {
+    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",
+            },
+        ];
+    }
+    const suggestedLab = args.labIds[0];
+    const commands = [
+        {
+            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;
+}
+/**
+ * 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.",
+        "",
+    ];
+    if (!state.initialized) {
+        lines.push("This project is not set up yet.");
+    }
+    else {
+        const labs = state.labCount === 1 ? "1 lab" : `${state.labCount} labs`;
+        const runs = state.runCount === 0
+            ? "no runs yet"
+            : state.runCount === 1
+                ? "1 run"
+                : `${state.runCount} runs`;
+        lines.push(`This project has ${labs} and ${runs}${state.latestRunId ? ` (latest: ${state.latestRunId})` : ""}.`);
+    }
+    lines.push("");
+    for (const next of state.nextCommands) {
+        lines.push(`  ${next.command}`);
+        lines.push(`      ${next.why}`);
+    }
+    lines.push("");
+    lines.push("`humanish --help` lists every command.");
+    return `${lines.join("\n")}\n`;
+}

package/dist/cli/program.d.ts

@@ -0,0 +1,15 @@
+import { Command } from "commander";
+import { type TuiRuntime } from "./commands/tui.js";
+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 —
+ * 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[];
+export declare function createProgram(io?: Partial<CliIo> & {
+    tuiRuntime?: Partial<TuiRuntime>;
+}): Command;