humanish 0.112.0 → 0.113.0

package/dist/cli/doctor.d.ts

@@ -12,6 +12,8 @@ export interface DoctorResult {
     schema: typeof DOCTOR_SCHEMA;
     ok: boolean;
     cwd: string;
+    /** The step to take first, such as preparing a local study's runtime. */
+    next?: string;
     checks: Array<{
         name: string;
         ok: boolean;

package/dist/cli/doctor.js

@@ -11,6 +11,8 @@ import { studySetupChecks, studiesByRequiredKey, } from "../study/doctor.js";
 import { prepareSelectedOutputDirectory, } from "../run/contained-output.js";
 import { implicitProjectDirectoryExists, readImplicitProjectFile, validateCwd, } from "../run/project.js";
 import { cli } from "./invocation.js";
+import { recordedVersion } from "./update-check.js";
+import { CLI_VERSION } from "./version.js";
 const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
 /**
  * Version 2.3.1 stopped holding a launched background command's event stream open. Version 2.3.2
@@ -94,6 +96,7 @@ export async function doctor(cwdInput, options = {}) {
         ...(await projectChecks(projectRoot)),
         await desktopSdkCheck(setup),
         terminalSurfaceCheck(),
+        ...versionCheck(env),
         ...localAgentChecks(agents),
         await claudeTranscriptCheck(env),
         ...keyChecks(probes, receivingKey, setup, keyUsers),
@@ -109,6 +112,7 @@ export async function doctor(cwdInput, options = {}) {
         schema: DOCTOR_SCHEMA,
         ok: checks.every((check) => check.ok),
         cwd,
+        ...(setup?.next === undefined ? {} : { next: setup.next }),
         checks: withStatus(checks),
     };
 }
@@ -246,6 +250,20 @@ function terminalSurfaceCheck() {
         }),
     };
 }
+/** The latest version the update check recorded on this machine; no row before a check. */
+function versionCheck(env) {
+    const recorded = recordedVersion(CLI_VERSION, env, env.HOME ?? homedir());
+    if (recorded === undefined)
+        return [];
+    return [
+        {
+            name: "humanish version",
+            ok: true,
+            ...(recorded.newer ? { status: "note" } : {}),
+            message: recorded.message,
+        },
+    ];
+}
 /** Probes the live-run keys, plus the receiving-email key a real-comms study names. */
 async function probeDoctorKeys(cwd, env, study, keyDeps, dotenv) {
     const keyNames = new Set(["OPENAI_API_KEY", "E2B_API_KEY", "GH_TOKEN", "CODEX_API_KEY"]);

package/dist/cli/io.d.ts

@@ -1,6 +1,7 @@
 import { Command, Option } from "commander";
 import { discoverProviderKeys, type DotenvLoad } from "../keys/key-resolution.js";
 import { type TelemetryProperties } from "./telemetry.js";
+import type { UpdateCheckContext } from "./update-check.js";
 import type { RunResult } from "../run/results.js";
 export declare const CLI_RESPONSE_SCHEMA = "humanish.cli-response.v1";
 export { CLI_VERSION } from "./version.js";
@@ -9,6 +10,7 @@ export interface CliIo {
     writeErr(text: string): void;
     setExitCode(code: number): void;
     keyDiscovery?: typeof discoverProviderKeys;
+    updateCheck?: Partial<UpdateCheckContext>;
 }
 export declare const JSON_OPTION_DESCRIPTION = "Print a machine-readable JSON response.";
 export declare const CWD_OPTION_DESCRIPTION = "Project directory.";

package/dist/cli/program.js

@@ -2,10 +2,11 @@ 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 { Command, Help } 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 { checkForUpdate, startRefreshWorker } from "./update-check.js";
 import { registerAnalyzeCommand } from "./commands/analyze.js";
 import { registerCodexCommands } from "./commands/codex.js";
 import { registerCommsCommands } from "./commands/comms.js";
@@ -95,6 +96,29 @@ async function recordCommandTelemetry(command, ok, durationMs, exitCode) {
         // Metrics are our problem, never the operator's.
     }
 }
+/**
+ * After a command, one line on stderr when a newer humanish is published. It reads only the cache;
+ * the registry request runs detached (see update-check.ts), so nothing here waits on the network.
+ */
+function noticeNewerVersion(command, io) {
+    try {
+        const notice = checkForUpdate({
+            installed: CLI_VERSION,
+            env: process.env,
+            terminal: process.stderr.isTTY === true,
+            json: wantsJson(command),
+            ownCheckout: isOwnCheckoutRun(process.cwd(), dirname(fileURLToPath(import.meta.url)), (p) => readFileSync(p, "utf8")),
+            now: Date.now(),
+            startRefresh: startRefreshWorker,
+            ...io.updateCheck,
+        });
+        if (notice !== undefined)
+            io.writeErr(`${notice}\n`);
+    }
+    catch {
+        // An update notice is never a reason for a command to fail.
+    }
+}
 /**
  * HUMANISH_DEBUG_HANDLES=1: after a command's handler settles, name what is still keeping the
  * process alive. A live terminal run wrote its result 64 s in and the CLI stayed up for
@@ -165,6 +189,7 @@ class HumanishCommand extends Command {
             const noticed = announceTelemetryOnce(this, cliIo);
             const finish = (ok) => {
                 void recordCommandTelemetry(this, ok, Date.now() - startedAt, lastExitCode);
+                noticeNewerVersion(this, cliIo);
                 reportActiveHandles(this, cliIo);
             };
             try {
@@ -326,6 +351,15 @@ export function createProgram(io = {}) {
         // each subcommand when it is created.
         .helpOption("-h, --help", "Show help for this command.")
         .helpCommand("help [command]", "Show help for a command.")
+        // `help <command>` and `<command> help` keep working; a command's listing names only the
+        // commands that do something, so `help` is left out of every Commands section.
+        .configureHelp({
+        visibleCommands(command) {
+            return Help.prototype.visibleCommands
+                .call(this, command)
+                .filter((child) => child.name() !== "help");
+        },
+    })
         .showHelpAfterError()
         .option("--json", "Print machine-readable JSON responses where supported.")
         .configureOutput({

package/dist/cli/secret-prompt.d.ts

@@ -1,2 +1,6 @@
-/** Host-owned entry: no secret crosses the TUI view contract or reaches a writable terminal. */
+/**
+ * Host-owned entry: no secret crosses the TUI view contract or reaches a writable terminal.
+ * Resolves to the trimmed line, an empty string when Enter was pressed alone, or null when the
+ * person cancelled or there is no terminal.
+ */
 export declare function promptSecret(label: string, stdin: NodeJS.ReadStream, stdout: NodeJS.WriteStream): Promise<string | null>;

package/dist/cli/secret-prompt.js

@@ -1,6 +1,10 @@
 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. */
+/**
+ * Host-owned entry: no secret crosses the TUI view contract or reaches a writable terminal.
+ * Resolves to the trimmed line, an empty string when Enter was pressed alone, or null when the
+ * person cancelled or there is no terminal.
+ */
 export async function promptSecret(label, stdin, stdout) {
     if (!stdin.isTTY || !stdout.isTTY)
         return null;
@@ -27,7 +31,7 @@ export async function promptSecret(label, stdin, stdout) {
             stdout.write("\n");
             resolve(value);
         };
-        reader.once("line", (line) => finish(line.trim() || null));
+        reader.once("line", (line) => finish(line.trim()));
         reader.once("SIGINT", () => finish(null));
         reader.once("close", () => finish(null));
         reader.once("error", () => finish(null));

package/dist/cli/update-check-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/update-check-worker.js

@@ -0,0 +1,5 @@
+// Started detached by startRefreshWorker in update-check.ts, with the cache path as its argument.
+import { refreshUpdateCache } from "./update-check.js";
+const cachePath = process.argv[2];
+if (cachePath !== undefined)
+    await refreshUpdateCache({ cachePath });

package/dist/cli/update-check.d.ts

@@ -0,0 +1,46 @@
+export interface UpdateCheckContext {
+    /** The running CLI's version. */
+    installed: string;
+    env: NodeJS.ProcessEnv;
+    /** Whether stderr is a terminal. */
+    terminal: boolean;
+    /** Whether the command prints a JSON document. */
+    json: boolean;
+    /** Whether this CLI runs from humanish's own source checkout. */
+    ownCheckout: boolean;
+    /** The clock, in epoch milliseconds. */
+    now: number;
+    home?: string;
+    /** Starts the background registry request that writes the cache. Never awaited. */
+    startRefresh: (cachePath: string) => void;
+}
+/**
+ * The one line to print after a command when the cache names a newer humanish, at most once a day.
+ * Records that it was shown. Every failure inside is swallowed: an update notice is never a reason
+ * for a command to fail.
+ */
+export declare function checkForUpdate(context: UpdateCheckContext): string | undefined;
+/**
+ * The version the last successful check recorded, compared with `installed`, for `doctor`. Reads the
+ * cache only; undefined until a check has succeeded on this machine.
+ */
+export declare function recordedVersion(installed: string, env: NodeJS.ProcessEnv, home?: string): {
+    newer: boolean;
+    message: string;
+} | undefined;
+/**
+ * Ask the npm registry for humanish's `latest` dist-tag and record it in the cache. The detached
+ * worker runs this. The request is a GET with an Accept header and nothing else: no machine id,
+ * installed version, command or path. A failed or malformed answer leaves the cache as it was.
+ */
+export declare function refreshUpdateCache(args: {
+    cachePath: string;
+    fetchFn?: (url: string, init: RequestInit) => Promise<Response>;
+    now?: () => number;
+    timeoutMs?: number;
+}): Promise<void>;
+/**
+ * Start the worker that runs refreshUpdateCache, detached and unreferenced so this process exits
+ * without waiting for it. A source checkout has no built worker, and nothing starts.
+ */
+export declare function startRefreshWorker(cachePath: string): void;

package/dist/cli/update-check.js

@@ -0,0 +1,203 @@
+// Tells a person when a newer humanish is published, as npm, gh and the Vercel CLI do. A command
+// only reads a small cache and prints at most one line from it; the registry request runs in a
+// detached process that writes the cache for a later command, so the check never delays or fails
+// the command that started it.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { disabledByEnvironment } from "./telemetry.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const REGISTRY_DIST_TAGS = "https://registry.npmjs.org/-/package/humanish/dist-tags";
+/** Next to telemetry.json, under the same XDG rule the key store uses. */
+function updateCachePath(env, home = homedir()) {
+    const declared = env.XDG_CONFIG_HOME?.trim();
+    const configHome = declared !== undefined && declared !== "" && path.isAbsolute(declared)
+        ? declared
+        : path.join(home, ".config");
+    return path.join(configHome, "humanish", "update-check.json");
+}
+function readUpdateCache(cachePath) {
+    try {
+        const parsed = JSON.parse(readFileSync(cachePath, "utf8"));
+        if (parsed === null || typeof parsed !== "object")
+            return {};
+        const record = parsed;
+        const text = (field) => typeof record[field] === "string" ? record[field] : undefined;
+        const cache = {};
+        const checkedAt = text("checkedAt");
+        const latest = text("latest");
+        const notifiedAt = text("notifiedAt");
+        if (checkedAt !== undefined)
+            cache.checkedAt = checkedAt;
+        if (latest !== undefined && parseVersion(latest) !== undefined)
+            cache.latest = latest;
+        if (notifiedAt !== undefined)
+            cache.notifiedAt = notifiedAt;
+        return cache;
+    }
+    catch {
+        return {};
+    }
+}
+function writeUpdateCache(cachePath, cache) {
+    mkdirSync(path.dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+}
+function parseVersion(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+    return match === null ? undefined : [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** True when `candidate` is a higher release than `installed`. */
+function isNewer(candidate, installed) {
+    const a = parseVersion(candidate);
+    const b = parseVersion(installed);
+    if (a === undefined || b === undefined)
+        return false;
+    for (let index = 0; index < 3; index += 1)
+        if (a[index] !== b[index])
+            return a[index] > b[index];
+    return false;
+}
+/** True when `timestamp` is missing, unreadable, or at least a day before `now`. */
+function dayPassed(timestamp, now) {
+    const then = timestamp === undefined ? Number.NaN : Date.parse(timestamp);
+    return Number.isNaN(then) || now - then >= DAY_MS;
+}
+const truthy = (value) => value !== undefined &&
+    value.trim() !== "" &&
+    value.trim() !== "0" &&
+    value.trim().toLowerCase() !== "false";
+/**
+ * Only a person at a terminal is told, and only when nothing has switched the check off. A pipe,
+ * CI and a JSON document have a program reading them. A study participant runs the version the
+ * study chose, and a notice would send it to another. The telemetry switches turn this off too:
+ * someone who opted out of telemetry expects no unprompted requests.
+ */
+function checkAllowed(context) {
+    const env = context.env;
+    return (context.terminal &&
+        !context.json &&
+        !context.ownCheckout &&
+        !truthy(env.CI) &&
+        !truthy(env.HUMANISH_NO_UPDATE_CHECK) &&
+        !truthy(env.HUMANISH_STUDY_PARTICIPANT) &&
+        !disabledByEnvironment(env));
+}
+/**
+ * The one line to print after a command when the cache names a newer humanish, at most once a day.
+ * Records that it was shown. Every failure inside is swallowed: an update notice is never a reason
+ * for a command to fail.
+ */
+export function checkForUpdate(context) {
+    try {
+        if (!checkAllowed(context))
+            return undefined;
+        const cachePath = updateCachePath(context.env, context.home);
+        const cache = readUpdateCache(cachePath);
+        const stamp = new Date(context.now).toISOString();
+        const next = { ...cache };
+        // Stamped before the request starts, so an offline machine asks once a day rather than on
+        // every command. The request writes `latest` when it succeeds.
+        const refresh = dayPassed(cache.checkedAt, context.now);
+        if (refresh)
+            next.checkedAt = stamp;
+        const latest = cache.latest;
+        const notice = latest !== undefined &&
+            isNewer(latest, context.installed) &&
+            dayPassed(cache.notifiedAt, context.now)
+            ? `humanish ${context.installed} is out of date; the latest is ${latest}. Run npx humanish@latest to use it.`
+            : undefined;
+        if (notice !== undefined)
+            next.notifiedAt = stamp;
+        if (refresh || notice !== undefined)
+            writeUpdateCache(cachePath, next);
+        if (refresh)
+            context.startRefresh(cachePath);
+        return notice;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The version the last successful check recorded, compared with `installed`, for `doctor`. Reads the
+ * cache only; undefined until a check has succeeded on this machine.
+ */
+export function recordedVersion(installed, env, home) {
+    const cache = readUpdateCache(updateCachePath(env, home));
+    if (cache.latest === undefined)
+        return undefined;
+    const checked = cache.checkedAt === undefined ? "" : ` (checked ${cache.checkedAt.slice(0, 10)})`;
+    return isNewer(cache.latest, installed)
+        ? {
+            newer: true,
+            message: `${installed} installed; ${cache.latest} is the latest${checked}. Run npx humanish@latest to use it.`,
+        }
+        : { newer: false, message: `${installed} installed, the latest published${checked}` };
+}
+/**
+ * Ask the npm registry for humanish's `latest` dist-tag and record it in the cache. The detached
+ * worker runs this. The request is a GET with an Accept header and nothing else: no machine id,
+ * installed version, command or path. A failed or malformed answer leaves the cache as it was.
+ */
+export async function refreshUpdateCache(args) {
+    try {
+        const fetchFn = args.fetchFn ?? globalThis.fetch;
+        const response = await fetchFn(REGISTRY_DIST_TAGS, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(args.timeoutMs ?? 3_000),
+        });
+        if (!response.ok)
+            return;
+        const body = await response.json();
+        const latest = body !== null && typeof body === "object"
+            ? body.latest
+            : undefined;
+        if (typeof latest !== "string" || parseVersion(latest) === undefined)
+            return;
+        const now = (args.now ?? Date.now)();
+        writeUpdateCache(args.cachePath, {
+            ...readUpdateCache(args.cachePath),
+            checkedAt: new Date(now).toISOString(),
+            latest,
+        });
+    }
+    catch {
+        // Offline, slow or refused: the next check is a day away either way.
+    }
+}
+/** What the worker's environment keeps: how this machine reaches the network, and no credentials. */
+const WORKER_ENV_NAMES = [
+    "HTTPS_PROXY",
+    "HTTP_PROXY",
+    "NO_PROXY",
+    "https_proxy",
+    "http_proxy",
+    "no_proxy",
+    "NODE_USE_ENV_PROXY",
+    "NODE_EXTRA_CA_CERTS",
+    "SYSTEMROOT",
+];
+/**
+ * Start the worker that runs refreshUpdateCache, detached and unreferenced so this process exits
+ * without waiting for it. A source checkout has no built worker, and nothing starts.
+ */
+export function startRefreshWorker(cachePath) {
+    const worker = fileURLToPath(new URL("./update-check-worker.js", import.meta.url));
+    if (!existsSync(worker))
+        return;
+    const env = Object.fromEntries(WORKER_ENV_NAMES.flatMap((name) => {
+        const value = process.env[name];
+        return value === undefined ? [] : [[name, value]];
+    }));
+    const child = spawn(process.execPath, [worker, cachePath], {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+        env,
+    });
+    child.on("error", () => { });
+    child.unref();
+}

package/dist/feedback/draft.js

@@ -161,6 +161,7 @@ export async function buildAnalysisDraft(context, options) {
             `Impact: ${finding.impact}. ${finding.affectedStreamIds.length} affected / ${finding.exposedStreamIds.length} observed exposed participants. ${finding.exposureReason}`,
             `Recovery: ${finding.recovery}. Confidence: ${finding.confidence}.`,
             ...finding.observations.map((item) => `${item.basis}: ${item.claim}${item.limitation ? ` Limitation: ${item.limitation}` : ""}`),
+            ...citedImpressions(bundle, evidence).map(({ streamId, kind, text }) => `Participant ${streamId} said at the end (${kind.replaceAll("_", " ")}): ${text}`),
             `Next check: ${finding.nextStep}`,
             correction
                 ? `Human review: ${correction.status}. ${correction.reason}`
@@ -206,6 +207,23 @@ export async function buildAnalysisDraft(context, options) {
         ],
     };
 }
+/**
+ * The participant impressions among a finding's cited evidence. Only an impression whose text the
+ * cited entry carries whole is quoted, so the draft repeats nothing the analysis share check did
+ * not read.
+ */
+function citedImpressions(bundle, evidence) {
+    return evidence.flatMap((item) => {
+        const impressions = bundle.streams.find((stream) => stream.id === item.streamId)?.actor
+            ?.impressions;
+        const impression = impressions?.status === "collected"
+            ? impressions.items.find((entry) => entry.messageId === item.eventId)
+            : undefined;
+        return impression === undefined || !item.text.includes(impression.text)
+            ? []
+            : [{ streamId: item.streamId, kind: impression.kind, text: impression.text }];
+    });
+}
 export function isUsableFeedbackCandidate(candidate) {
     if (!isRecord(candidate) ||
         candidate.schema !== "humanish.feedback-candidate.v1" ||

package/dist/keys/key-resolution.js

@@ -245,6 +245,8 @@ export function missingKeyHint(name) {
             return `run \`${cli("keys set openai")}\``;
         case "ANTHROPIC_API_KEY":
             return `run \`${cli("keys set anthropic")}\``;
+        case "AGENTMAIL_API_KEY":
+            return `run \`${cli("keys set agentmail")}\``;
         default:
             return `run \`${cli(`keys set ${name}`)}\``;
     }

package/dist/keys/key-status.d.ts

@@ -0,0 +1,37 @@
+import { type KeyResolutionDeps, type KeySourceProbe } from "./key-resolution.js";
+interface KeyStatusRow extends KeySourceProbe {
+    /** What humanish uses the key for, in a few words. */
+    use: string;
+}
+export declare function keyStatus(args: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    deps?: KeyResolutionDeps;
+}): Promise<KeyStatusRow[]>;
+/** Names in the user store that the status does not list, such as ANTHROPIC_API_KEY. */
+export declare function otherStoredKeys(env: NodeJS.ProcessEnv, deps?: KeyResolutionDeps): string[];
+export declare function formatKeyStatus(rows: readonly KeyStatusRow[], otherStored?: readonly string[]): string;
+interface MissingKeysOutcome {
+    stored: string[];
+    /** Keys left unset because the person pressed Enter without a value. */
+    skipped: string[];
+    /** Keys whose value the store refused, with the reason. */
+    rejected?: Array<{
+        name: string;
+        message: string;
+    }>;
+    /** The key whose prompt was cancelled. No later key was asked for. */
+    stoppedAt?: string;
+}
+/**
+ * `humanish keys set` with no key named: ask for each missing key in turn and store each answer in
+ * the user store. An empty answer skips that key; a cancelled prompt (null) stops the walk and
+ * keeps what was already stored.
+ */
+export declare function askForMissingKeys(args: {
+    rows: readonly KeyStatusRow[];
+    env: NodeJS.ProcessEnv;
+    deps?: KeyResolutionDeps;
+    prompt: (label: string) => Promise<string | null>;
+}): Promise<MissingKeysOutcome>;
+export {};

package/dist/keys/key-status.js

@@ -0,0 +1,68 @@
+// `humanish keys`: which provider keys are set and where each comes from, through the same chain a
+// live command resolves. Never a value.
+import { cli } from "../cli/invocation.js";
+import { listUserKeys, probeKeySources, setUserKey, } from "./key-resolution.js";
+/**
+ * The keys a person sets for humanish, in the order the status lists them and `keys set` asks for
+ * them. ANTHROPIC_API_KEY is left out: a Claude Code participant runs on its own login and never
+ * receives it. CODEX_API_KEY is an alternative spelling of the OpenAI key for terminal studies.
+ */
+const STATUS_KEYS = [
+    { name: "E2B_API_KEY", use: "hosted desktops" },
+    { name: "OPENAI_API_KEY", use: "participant model and analysis" },
+    { name: "GH_TOKEN", use: "private repository subjects" },
+    { name: "AGENTMAIL_API_KEY", use: "email in studies" },
+];
+export async function keyStatus(args) {
+    const probes = await probeKeySources(STATUS_KEYS.map((key) => key.name), {
+        cwd: args.cwd,
+        env: args.env,
+        ...(args.deps === undefined ? {} : { deps: args.deps }),
+    });
+    return probes.map((probe, index) => ({ ...probe, use: STATUS_KEYS[index].use }));
+}
+/** Names in the user store that the status does not list, such as ANTHROPIC_API_KEY. */
+export function otherStoredKeys(env, deps = {}) {
+    const listed = new Set(STATUS_KEYS.map((key) => key.name));
+    return listUserKeys(env, deps).filter((name) => !listed.has(name));
+}
+export function formatKeyStatus(rows, otherStored = []) {
+    const lines = rows.map((row) => `${row.name} (${row.use}): ${row.source === null ? `missing; ${row.hint}` : `set, from ${row.source}`}`);
+    if (otherStored.length > 0)
+        lines.push(`Also in the user store: ${otherStored.join(", ")}. humanish does not use ${otherStored.length === 1 ? "it" : "them"} today.`);
+    const missing = rows.some((row) => row.source === null);
+    lines.push("", missing
+        ? `Values are never printed. \`${cli("keys set")}\` asks for each missing key in turn.`
+        : "Values are never printed.");
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * `humanish keys set` with no key named: ask for each missing key in turn and store each answer in
+ * the user store. An empty answer skips that key; a cancelled prompt (null) stops the walk and
+ * keeps what was already stored.
+ */
+export async function askForMissingKeys(args) {
+    const outcome = { stored: [], skipped: [] };
+    for (const row of args.rows) {
+        if (row.source !== null)
+            continue;
+        const value = await args.prompt(`${row.name} for ${row.use}`);
+        if (value === null)
+            return { ...outcome, stoppedAt: row.name };
+        if (value === "") {
+            outcome.skipped.push(row.name);
+            continue;
+        }
+        try {
+            setUserKey(row.name, value, args.env, args.deps);
+            outcome.stored.push(row.name);
+        }
+        catch (error) {
+            (outcome.rejected ??= []).push({
+                name: row.name,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return outcome;
+}