@fastagent-sh/fastagent 0.29.0 → 0.30.0

package/dist/deploy/railway/run.d.ts

@@ -1,9 +1,12 @@
 /** `fastagent deploy railway --run` — drive the Railway CLI to completion. */
 import type { BoxLoginStep } from "../box-shell.ts";
-import { type PublicHealthProbe, type Registrars } from "../channel-ingress.ts";
+import { type BoxWebhooksProbe, type UrlRecorder, type PublicHealthProbe, type Registrars } from "../channel-ingress.ts";
 import type { DeclaredChannel } from "../../channels/discover.ts";
 import { type CliRunner } from "../runner.ts";
+import type { SecretStore } from "../secret-store.ts";
 export interface RailwayRunPlan {
+    /** At a terminal with a `--config` file: record each URL a person set once the box confirms it. */
+    recordUrl?: UrlRecorder;
     /** Names both the project (`railway init --name`) and the service (`railway add --service`). */
     name: string;
     /**
@@ -11,12 +14,11 @@ export interface RailwayRunPlan {
      * in lockstep).
      */
     mountPath: string;
-    /** `KEY=value` secrets set one-per-`variable set --stdin`: the value file's variables. */
-    secrets: Record<string, string>;
-    /** Declared names the value file supplies no value for — the run gates on these before any side effect. */
-    missingSecrets: string[];
-    /** That value file, agent-dir-relative, so the gate names the file this deploy actually read. */
-    valueFile: string;
+    /**
+     * Make sure the service holds a value for every name the deployment needs, through whoever can supply one
+     * (secret-store.ts): resolves a gate line, or undefined. It runs once the service exists.
+     */
+    provideSecrets: (store: SecretStore) => Promise<string | undefined>;
     /** Every declared channel and its ingress — the driver asks which of them have a webhook. */
     channels: readonly DeclaredChannel[];
     /** Opt-in (CLI `--into-linked`) to provision INTO the project this directory is already linked to. */
@@ -33,6 +35,12 @@ export interface RailwayRunPlan {
     hostLogin?: () => Promise<string | undefined>;
     /** The command a coding agent runs to deploy this, its person's steps handed to its user (`--run --json`). */
     forAgent: string;
+    /**
+     * Put the service's domain into the configuration the image delivers (`http.publicUrl`), before `railway up` uploads
+     * it, so the box points its own channels there. Resolves the URL the configuration then names, the operator's own
+     * when it had one.
+     */
+    deliverPublicUrl: (url: string) => Promise<string>;
 }
 /**
  * Done (with the live URL), or a gate the operator must clear before re-running (printed + non-zero exit by the CLI).
@@ -44,13 +52,6 @@ export type RailwayRunOutcome = {
     ok: false;
     gate: string;
 };
-/** Whether `railway status --json` shows a linked project: non-empty stdout. */
-export declare function isLinked(stdout: string): boolean;
-/**
- * The linked project's name for the gate message, or undefined if it can't be read (still linked — `railway status
- * --json` puts `name` at the top level on 5.15.0).
- */
-export declare function linkedName(stdout: string): string | undefined;
 /** The first Railway-provided domain as an https URL, or undefined if none is present. */
 export declare function parseDomainUrl(stdout: string): string | undefined;
 /**
@@ -61,4 +62,9 @@ export declare function parseDomainUrl(stdout: string): string | undefined;
  * that is not JSON throws: read as "no volume", it would add a second one.
  */
 export declare function volumeOn(stdout: string, service: string, mountPath: string): string | undefined;
-export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registrars: Registrars, healthProbe?: PublicHealthProbe, sleep?: (ms: number) => Promise<void>): Promise<RailwayRunOutcome>;
+export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, 
+/** Slack's, which this machine still sets (its Request URL no credential on the box can change). */
+registrars: Pick<Registrars, "leave">, healthProbe?: PublicHealthProbe, sleep?: (ms: number) => Promise<void>, boxWebhooks?: {
+    probe: BoxWebhooksProbe;
+    intervalMs?: number;
+}): Promise<RailwayRunOutcome>;

package/dist/deploy/railway/run.js

@@ -1,25 +1,7 @@
-import { loginGate, publicHealthGate, registerWebhooks, } from "../channel-ingress.js";
+import { confirmWebhooks, loginGate, publicHealthGate, } from "../channel-ingress.js";
 import { readOutput } from "../runner.js";
-import { hostSignedOutGate, missingValuesGate } from "../secrets.js";
-/** Whether `railway status --json` shows a linked project: non-empty stdout. */
-export function isLinked(stdout) {
-    return stdout.trim() !== "";
-}
-/**
- * The linked project's name for the gate message, or undefined if it can't be read (still linked — `railway status
- * --json` puts `name` at the top level on 5.15.0).
- */
-export function linkedName(stdout) {
-    try {
-        const v = JSON.parse(stdout);
-        if (typeof v.name === "string")
-            return v.name;
-    }
-    catch {
-        // non-JSON but non-empty → still linked, just no name to show
-    }
-    return undefined;
-}
+import { hostSignedOutGate } from "../secrets.js";
+import { ensureRailwayService, railwayStore } from "./store.js";
 /** Every string leaf of a parsed JSON value. */
 function jsonStrings(stdout) {
     const walk = (v) => typeof v === "string"
@@ -72,16 +54,13 @@ export function volumeOn(stdout, service, mountPath) {
  */
 const VOLUME_ATTACH_TIMEOUT_MS = 60_000;
 const VOLUME_POLL_MS = 2_000;
-export async function deployRailwayRun(plan, railway, log, registrars, healthProbe, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))) {
+export async function deployRailwayRun(plan, railway, log, 
+/** Slack's, which this machine still sets (its Request URL no credential on the box can change). */
+registrars, healthProbe, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), boxWebhooks) {
     const gate = (g) => ({ ok: false, gate: g });
     // Every --service below targets plan.name — the name this tool gives BOTH the project and the service (`init
     // --name` + `add --service`).
     const svc = ["--service", plan.name];
-    // 1. Gate missing required secret VALUES before any side effect (no half-created infra), and before asking a
-    // person to sign in for a deploy that would stop here anyway.
-    const missingValues = missingValuesGate(plan.missingSecrets, plan.valueFile);
-    if (missingValues)
-        return gate(missingValues);
     // 2.
     if ((await railway(["whoami"], { capture: true })).code !== 0) {
         const failed = plan.hostLogin
@@ -91,58 +70,22 @@ export async function deployRailwayRun(plan, railway, log, registrars, healthPro
             return gate(failed);
     }
     // 3.
-    const status = await railway(["status", "--json"], { capture: true });
-    if (isLinked(status.stdout)) {
-        if (!plan.intoLinked) {
-            const name = linkedName(status.stdout);
-            return gate(`this directory is already linked to Railway project ${name ? `"${name}"` : "(name unreadable)"}. ` +
-                "`--run` provisions a NEW project and only runs on an unlinked directory — it won't deploy into an " +
-                "unrelated one. To redeploy an already-provisioned agent, run `railway up`. To provision the agent " +
-                "INTO this project, re-run with --into-linked. To start fresh, `railway unlink` first.");
-        }
-        log(`provisioning into linked project ${linkedName(status.stdout) ?? plan.name} (--into-linked)`);
-    }
-    else {
-        // --into-linked means "provision into the project this dir is linked to" — but it isn't linked.
-        if (plan.intoLinked) {
-            log("warn: --into-linked was passed but this directory isn't linked to any project — creating a fresh one");
-        }
-        log(`creating project ${plan.name}…`);
-        if ((await railway(["init", "--name", plan.name])).code !== 0) {
-            return gate("`railway init` failed — if you have multiple workspaces, run it once interactively (or pass --workspace) to pick one, then re-run");
-        }
-        // Create + link the service (init makes only a project); it precedes the volume, which has no --service flag and
-        // rides the linked service.
-        log(`creating service ${plan.name}…`);
-        // `--variables` with one of the machinery variables set just below: in a terminal, a bare `railway add` stops at
-        // "Enter a variable <esc to skip>" (5.62.1) and waits for a key nobody was told to press.
-        const addArgs = ["add", "--service", plan.name, "--variables", `FASTAGENT_STATE_DIR=${plan.mountPath}/.state`];
-        if ((await railway(addArgs)).code !== 0) {
-            // Precise recovery, not "fix and re-run": init already created + linked the project, so a plain re-run hits the
-            // linked-gate, and --into-linked SKIPS `add` and then fails at the volume (no service to ride).
-            return gate(`\`railway add --service\` failed — \`railway init\` already created the project (this directory is now ` +
-                `linked) but not the service. Finish with \`railway add --service ${plan.name}\` here, then re-run with ` +
-                `--into-linked; or \`railway unlink\` to detach and start fresh.`);
-        }
-    }
+    const projectGate = await ensureRailwayService(railway, { name: plan.name, mountPath: plan.mountPath, intoLinked: plan.intoLinked }, log);
+    if (projectGate !== undefined)
+        return gate(projectGate);
+    // 3a. The names the service holds, the gaps filled.
+    const secretsGate = await plan.provideSecrets(railwayStore(railway, plan.name, log, { redeploy: false }));
+    if (secretsGate !== undefined)
+        return gate(secretsGate);
     // 3b.
     const machineryVars = [
         `FASTAGENT_STATE_DIR=${plan.mountPath}/.state`,
         `FASTAGENT_SECRETS_DIR=${plan.mountPath}/.secrets`,
     ];
-    // The secret NAMES, not a count: `--run` uploads the whole value file, so the operator has to be able to see the
-    // list on every host.
-    const secretNames = Object.keys(plan.secrets);
-    log(`setting ${machineryVars.map((v) => v.split("=")[0]).join("/")} + ${secretNames.length} secret(s)` +
-        `${secretNames.length > 0 ? `: ${secretNames.join(", ")}` : ""}…`);
+    log(`setting ${machineryVars.map((v) => v.split("=")[0]).join("/")}…`);
     if ((await railway(["variables", "set", ...machineryVars, ...svc])).code !== 0) {
         return gate("`railway variables set` failed — see the railway output above");
     }
-    for (const [k, v] of Object.entries(plan.secrets)) {
-        if ((await railway(["variables", "set", k, "--stdin", ...svc], { input: v })).code !== 0) {
-            return gate(`\`railway variables set ${k}\` failed — see the railway output above`);
-        }
-    }
     // 3c.
     const volumeStatus = () => readOutput(railway, "railway", ["volume", "list", "--json"], (out) => volumeOn(out, plan.name, plan.mountPath));
     const existing = await volumeStatus();
@@ -174,17 +117,19 @@ export async function deployRailwayRun(plan, railway, log, registrars, healthPro
                 "check `railway volume list`, then re-run with --into-linked once it shows Ready");
         }
     }
-    // 5. Deploy — CI mode streams build logs then exits (no interactive attach). Build runs on Railway.
-    log("deploying (railway up)…");
-    if ((await railway(["up", "--ci", ...svc])).code !== 0) {
-        return gate("`railway up` failed — see the railway output above; fix and re-run");
-    }
-    // 6.
+    // 5. The domain before the upload: `railway domain` creates the service's on a service never deployed, and answers
+    // the existing one when run again, so the image the upload builds names it as its `http.publicUrl`.
     log("getting the public domain…");
     const url = parseDomainUrl((await railway(["domain", "--json", ...svc], { capture: true })).stdout);
     if (!url) {
         return gate("couldn't read a domain from `railway domain` — run `railway domain` manually, then set any webhook");
     }
+    const publicUrl = await plan.deliverPublicUrl(url);
+    // 6. Deploy — CI mode streams build logs then exits (no interactive attach). Build runs on Railway.
+    log("deploying (railway up)…");
+    if ((await railway(["up", "--ci", ...svc])).code !== 0) {
+        return gate("`railway up` failed — see the railway output above; fix and re-run");
+    }
     // 6b. `railway up --ci` exits 0 once the build is accepted, so readiness is asked here and not inferred.
     const healthGate = await publicHealthGate({
         baseUrl: url,
@@ -207,12 +152,21 @@ export async function deployRailwayRun(plan, railway, log, registrars, healthPro
         }));
     }
     // 7.
-    const registrationGateMsg = await registerWebhooks({
+    // The box points its own channels at the `http.publicUrl` delivered above; this reads what it made of them.
+    const registrationGateMsg = await confirmWebhooks({
         baseUrl: url,
+        publicUrl,
         channels: plan.channels,
         registrars,
         log,
+        ...(plan.recordUrl === undefined ? {} : { record: plan.recordUrl }),
         retryHint: "re-run with --into-linked to retry registration",
+        ...(boxWebhooks === undefined
+            ? {}
+            : {
+                probe: boxWebhooks.probe,
+                ...(boxWebhooks.intervalMs === undefined ? {} : { intervalMs: boxWebhooks.intervalMs }),
+            }),
     });
     if (registrationGateMsg)
         return gate(registrationGateMsg);

package/dist/deploy/railway/store.d.ts

@@ -0,0 +1,29 @@
+/** Railway's service variables as a deployment's store: `railway variable list` for the names, `variables set` for values. */
+import type { SecretStore } from "../secret-store.ts";
+import { type CliRunner } from "../runner.ts";
+/** Whether `railway status --json` shows a linked project: non-empty stdout. */
+export declare function isLinked(stdout: string): boolean;
+/**
+ * The linked project's name for the gate message, or undefined if it can't be read (still linked — `railway status
+ * --json` puts `name` at the top level on 5.15.0).
+ */
+export declare function linkedName(stdout: string): string | undefined;
+/**
+ * The project and service a deployment's values and image belong to. The project named for the agent (`secrets set` or
+ * an earlier `--run` made and linked it) is continued, and given the service when it lacks one. A directory linked to
+ * any other project is refused unless `intoLinked` says to provision into it, whatever that project holds: a service of
+ * the same name does not make it the agent's. An unlinked directory is given a new project. Resolves the gate line when
+ * it cannot be done.
+ */
+export declare function ensureRailwayService(railway: CliRunner, plan: {
+    name: string;
+    mountPath: string;
+    intoLinked: boolean;
+}, log: (message: string) => void): Promise<string | undefined>;
+/**
+ * `service`'s variables, in the project and environment this directory is linked to. `redeploy`: the service restarts on
+ * what is written, once, after the last; off, for a deploy that follows and applies them.
+ */
+export declare function railwayStore(railway: CliRunner, service: string, log: (message: string) => void, options: {
+    redeploy: boolean;
+}): SecretStore;

package/dist/deploy/railway/store.js

@@ -0,0 +1,143 @@
+import { readOutput } from "../runner.js";
+/** Whether `railway status --json` shows a linked project: non-empty stdout. */
+export function isLinked(stdout) {
+    return stdout.trim() !== "";
+}
+/**
+ * The linked project's name for the gate message, or undefined if it can't be read (still linked — `railway status
+ * --json` puts `name` at the top level on 5.15.0).
+ */
+export function linkedName(stdout) {
+    try {
+        const v = JSON.parse(stdout);
+        if (typeof v.name === "string")
+            return v.name;
+    }
+    catch {
+        // non-JSON but non-empty → still linked, just no name to show
+    }
+    return undefined;
+}
+function unrelatedProject(name, agent) {
+    return (`this directory is already linked to Railway project ${name ? `"${name}"` : "(name unreadable)"}, not to ` +
+        `this agent's own (${agent}). \`--run\` won't deploy into an unrelated project. To provision the agent ` +
+        "INTO this project, re-run with --into-linked. To start fresh, `railway unlink` first.");
+}
+/** Whether `railway status --json` lists a service called `name`. */
+function hasService(stdout, name) {
+    const walk = (value) => {
+        if (value === null || typeof value !== "object")
+            return false;
+        const object = value;
+        if (object.serviceName === name)
+            return true;
+        return Object.values(object).some(walk);
+    };
+    try {
+        return walk(JSON.parse(stdout));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The project and service a deployment's values and image belong to. The project named for the agent (`secrets set` or
+ * an earlier `--run` made and linked it) is continued, and given the service when it lacks one. A directory linked to
+ * any other project is refused unless `intoLinked` says to provision into it, whatever that project holds: a service of
+ * the same name does not make it the agent's. An unlinked directory is given a new project. Resolves the gate line when
+ * it cannot be done.
+ */
+export async function ensureRailwayService(railway, plan, log) {
+    const status = await railway(["status", "--json"], { capture: true });
+    if (isLinked(status.stdout)) {
+        const name = linkedName(status.stdout);
+        if (!plan.intoLinked && name !== plan.name)
+            return unrelatedProject(name, plan.name);
+        if (plan.intoLinked)
+            log(`provisioning into linked project ${name ?? plan.name} (--into-linked)`);
+        if (hasService(status.stdout, plan.name))
+            return undefined;
+        return addService(railway, plan, log);
+    }
+    else {
+        // --into-linked means "provision into the project this dir is linked to" — but it isn't linked.
+        if (plan.intoLinked) {
+            log("warn: --into-linked was passed but this directory isn't linked to any project — creating a fresh one");
+        }
+        log(`creating project ${plan.name}…`);
+        if ((await railway(["init", "--name", plan.name])).code !== 0) {
+            return "`railway init` failed — if you have multiple workspaces, run it once interactively (or pass --workspace) to pick one, then re-run";
+        }
+        return addService(railway, plan, log);
+    }
+}
+async function addService(railway, plan, log) {
+    // `init` makes only a project; the service precedes the volume, which has no --service flag and rides the linked one.
+    log(`creating service ${plan.name}…`);
+    // `--variables` with one of the machinery variables set just below: in a terminal, a bare `railway add` stops at
+    // "Enter a variable <esc to skip>" (5.62.1) and waits for a key nobody was told to press.
+    const addArgs = ["add", "--service", plan.name, "--variables", `FASTAGENT_STATE_DIR=${plan.mountPath}/.state`];
+    if ((await railway(addArgs)).code !== 0) {
+        return (`\`railway add --service\` failed — the project ${plan.name} exists and this directory is linked to it, but ` +
+            `it has no service. Run \`railway add --service ${plan.name}\` here, then re-run; or \`railway unlink\` to ` +
+            `detach and start fresh.`);
+    }
+    return undefined;
+}
+/** The names `railway variable list --json` shows: the keys of an object. Its values are never read. */
+function variableNames(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        // Not the parser's message: it quotes the text around the error, and this output holds every value.
+        throw new Error("the output was not JSON");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`expected a JSON object of variables, got ${Array.isArray(parsed) ? "an array" : typeof parsed}`);
+    }
+    return new Set(Object.keys(parsed));
+}
+/**
+ * `service`'s variables, in the project and environment this directory is linked to. `redeploy`: the service restarts on
+ * what is written, once, after the last; off, for a deploy that follows and applies them.
+ */
+export function railwayStore(railway, service, log, options) {
+    const svc = ["--service", service];
+    return {
+        async exists() {
+            const status = (await railway(["status", "--json"], { capture: true })).stdout;
+            if (!isLinked(status))
+                return false;
+            const name = linkedName(status);
+            if (name !== service)
+                throw new Error(unrelatedProject(name, service));
+            return true;
+        },
+        async ensure() {
+            const gate = await ensureRailwayService(railway, { name: service, mountPath: "/data", intoLinked: false }, log);
+            if (gate !== undefined)
+                throw new Error(gate);
+        },
+        async names() {
+            const listed = await readOutput(railway, "railway", ["variable", "list", "--json", ...svc], variableNames);
+            if ("gate" in listed)
+                throw new Error(listed.gate);
+            return listed.value;
+        },
+        async write(values) {
+            const names = Object.keys(values);
+            log(`setting ${names.length} variable(s) on ${service}: ${names.join(", ")}`);
+            // One value per call over stdin, never argv. `--skip-deploys` on all but the last of a write that is to take effect.
+            for (const [index, name] of names.entries()) {
+                const skip = options.redeploy && index === names.length - 1 ? [] : ["--skip-deploys"];
+                const result = await railway(["variables", "set", name, "--stdin", ...skip, ...svc], {
+                    input: values[name],
+                });
+                if (result.code !== 0)
+                    throw new Error(`\`railway variables set ${name}\` failed — see the railway output above`);
+            }
+        },
+    };
+}

package/dist/deploy/runner.d.ts

@@ -30,9 +30,12 @@ export declare function readOutput<T>(run: CliRunner, bin: string, args: string[
 }>;
 /**
  * Production {@link CliRunner}: spawn `bin` in `cwd` (the agent directory, which is the build/upload context). stderr
- * is always inherited to the terminal.
+ * is always inherited to the terminal. `stdoutToStderr`: what the CLI prints is not this command's result (a command
+ * whose stdout is data, `secrets set --generate`), so it goes to this process's stderr, still on the terminal.
  */
-export declare function spawnRunner(bin: string, cwd: string): CliRunner;
+export declare function spawnRunner(bin: string, cwd: string, options?: {
+    stdoutToStderr?: boolean;
+}): CliRunner;
 /**
  * The AWS CLI, as every command here runs it: with its pager off. Given a terminal, AWS CLI v2 pipes any output it
  * prints through `less`, so `deploy agentcore --run` stopped at `(END)` after `ecr create-repository` until someone

package/dist/deploy/runner.js

@@ -25,16 +25,17 @@ export async function readOutput(run, bin, args, read) {
 }
 /**
  * Production {@link CliRunner}: spawn `bin` in `cwd` (the agent directory, which is the build/upload context). stderr
- * is always inherited to the terminal.
+ * is always inherited to the terminal. `stdoutToStderr`: what the CLI prints is not this command's result (a command
+ * whose stdout is data, `secrets set --generate`), so it goes to this process's stderr, still on the terminal.
  */
-export function spawnRunner(bin, cwd) {
+export function spawnRunner(bin, cwd, options = {}) {
     return (args, opts) => new Promise((res) => {
         const child = spawn(bin, args, {
             cwd,
             env: opts?.env ? { ...process.env, ...opts.env } : process.env,
             stdio: [
                 opts?.input ? "pipe" : "inherit",
-                opts?.capture ? "pipe" : "inherit",
+                opts?.capture ? "pipe" : options.stdoutToStderr ? 2 : "inherit",
                 opts?.captureStderr ? "pipe" : "inherit",
             ],
         });

package/dist/deploy/secret-store.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Where a deployment's values live and how a deploy fills the gaps (agent-artifact.md §6.2). A target keeps its own
+ * values; `deploy` checks names and never carries a file. Most stores can say which names they hold and not the values,
+ * so that is all the interface asks of them.
+ *
+ * The gaps are filled from the person's own sources, in the order a deploy can ask least of them: a value file
+ * (`.secrets/production/.env` unless another is named) pushes the names it holds in one batch after one question; a name
+ * no source has is asked for. A coding agent's run, with nobody to ask, stops naming the commands instead.
+ */
+import type { SecretNeed } from "./secrets.ts";
+export interface SecretStore {
+    /** Whether the app or service the values belong to exists: absent, it holds no value, and `names()` cannot be asked. */
+    exists(): Promise<boolean>;
+    /** Make the app or service the values belong to, when it does not exist yet. */
+    ensure(): Promise<void>;
+    /** The names the target holds a value for. */
+    names(): Promise<ReadonlySet<string>>;
+    /** Set `values` in one batch. */
+    write(values: Readonly<Record<string, string>>): Promise<void>;
+}
+/** How a person at a terminal is asked. */
+export interface SecretAsker {
+    confirm(question: string): Promise<boolean>;
+    /** One value, typed without echo. */
+    secret(need: SecretNeed): Promise<string>;
+}
+/** The commands a gate names, written for the host and agent this run is about. */
+export interface SecretCommands {
+    /** Push the names a value file holds: `fastagent secrets push fly`. */
+    push: string;
+    /** Set one name: `fastagent secrets set fly NAME`. */
+    set(name: string): string;
+}
+export interface ProvideSecrets {
+    /** What the target is called in what is said: "Fly". */
+    host: string;
+    store: SecretStore;
+    /** What the target must hold. */
+    needs: readonly SecretNeed[];
+    /** Every name the definition declares: a source's copy of one the target lacks is offered, optional or not. */
+    known: readonly string[];
+    /** The value file a source reads, when it exists. */
+    source?: {
+        file: string;
+        values: ReadonlyMap<string, string>;
+    };
+    /** Absent: nobody to ask. */
+    asker?: SecretAsker;
+    commands: SecretCommands;
+    /** Values FastAgent makes itself, set when neither the target nor a source has one (the Agent API's key). */
+    mint?: readonly {
+        name: string;
+        make(): string;
+    }[];
+    /** Say a line to the person who runs the deploy, for what a deploy with nobody to ask leaves undone. */
+    say?: (line: string) => void;
+    /** Say what the deploy did by itself, which leaves the person nothing to do. */
+    inform?: (line: string) => void;
+    /** What was minted, once the target holds it: kept on this machine too, where the person who calls the API looks. */
+    onMinted?: (values: Readonly<Record<string, string>>) => Promise<void>;
+}
+/** Resolves a gate line when the target still lacks a required name afterwards, undefined once it holds them all. */
+export declare function provideSecrets(input: ProvideSecrets): Promise<string | undefined>;

package/dist/deploy/secret-store.js

@@ -0,0 +1,98 @@
+/** The gap the target has, as the line a person (or the agent relaying one) acts on. */
+function gapLine(host, missing, held, commands) {
+    const names = missing.map((need) => `${need.name} (${need.hint})`).join("; ");
+    const fromFile = missing.filter((need) => held.includes(need.name));
+    const rest = missing.filter((need) => !held.includes(need.name));
+    const ways = [
+        ...(fromFile.length > 0
+            ? [
+                `\`${commands.push}\` sets ${fromFile.length === 1 ? "the one" : "the ones"} a value file holds (${fromFile.map((n) => n.name).join(", ")})`,
+            ]
+            : []),
+        ...(rest.length > 0
+            ? [
+                `a person types ${fromFile.length > 0 ? "the others" : rest.length === 1 ? "it" : "them"} in a terminal, one command each: ${rest.map((need) => `\`${commands.set(need.name)}\``).join(", ")}`,
+            ]
+            : []),
+        `\`${commands.push} --from-env\` takes them from the environment of a secret manager or a CI job (\`op run\`, \`doppler run\`)`,
+    ];
+    return `${host} has no value for: ${names}. ${ways.join("; ")}. Then re-run. A value is never asked for in a conversation`;
+}
+/** Resolves a gate line when the target still lacks a required name afterwards, undefined once it holds them all. */
+export async function provideSecrets(input) {
+    const { host, store, needs, known, source, asker, commands, mint = [] } = input;
+    try {
+        const have = await store.names();
+        const missing = needs.filter((need) => !have.has(need.name));
+        const ours = new Set(mint.map((made) => made.name));
+        const filed = (name) => {
+            const value = source?.values.get(name);
+            return value !== undefined && value.trim() !== "" ? value : undefined;
+        };
+        // What FastAgent made is not the person's to be asked about: the file records it, so a target that lacks it (a
+        // deployment made again) gets that value, and one the file lacks too gets a new one.
+        const minted = {};
+        const restored = [];
+        for (const { name, make } of mint) {
+            if (have.has(name))
+                continue;
+            const kept = filed(name);
+            if (kept === undefined)
+                minted[name] = make();
+            else {
+                minted[name] = kept;
+                restored.push(name);
+            }
+        }
+        const offered = [...(source?.values ?? [])]
+            .filter(([name, value]) => value.trim() !== "" && known.includes(name) && !have.has(name) && !ours.has(name))
+            .map(([name]) => name);
+        if (missing.length === 0 && offered.length === 0 && Object.keys(minted).length === 0)
+            return undefined;
+        const finishMinted = async () => {
+            if (restored.length > 0) {
+                input.inform?.(`set ${restored.join(", ")} on ${host} from ${source?.file}, where an earlier deploy kept it`);
+            }
+            const made = Object.fromEntries(Object.entries(minted).filter(([name]) => !restored.includes(name)));
+            if (Object.keys(made).length > 0)
+                await input.onMinted?.(made);
+        };
+        const held = offered.filter((name) => missing.some((need) => need.name === name));
+        if (asker === undefined) {
+            const lacking = missing.filter((need) => !(need.name in minted));
+            if (lacking.length > 0)
+                return gapLine(host, lacking, held, commands);
+            // Names a file holds and the target lacks, which nothing requires: said, since nobody was asked to set them.
+            if (offered.length > 0 && source !== undefined) {
+                input.say?.(`${host} lacks ${offered.join(", ")}, which ${source.file} holds; \`${commands.push}\` sets ${offered.length === 1 ? "it" : "them"}`);
+            }
+            if (Object.keys(minted).length > 0) {
+                await store.write(minted);
+                await finishMinted();
+            }
+            return undefined;
+        }
+        const write = { ...minted };
+        if (offered.length > 0 && source !== undefined) {
+            const required = new Set(missing.map((need) => need.name));
+            const list = offered.map((name) => (required.has(name) ? name : `${name} (optional)`)).join(", ");
+            if (await asker.confirm(`${host} lacks ${list}, which ${source.file} holds. Set them on ${host} from it?`)) {
+                for (const name of offered)
+                    write[name] = source.values.get(name);
+            }
+        }
+        for (const need of missing) {
+            if (need.name in write)
+                continue;
+            write[need.name] = await asker.secret(need);
+        }
+        if (Object.keys(write).length > 0)
+            await store.write(write);
+        if (Object.keys(minted).length > 0)
+            await finishMinted();
+        return undefined;
+    }
+    catch (error) {
+        return `${host}'s values could not be read or set: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}