approval-md 0.0.1 → 0.2.0

package/dist/src/cli/setup-flow.d.ts

@@ -0,0 +1,287 @@
+/**
+ * The credential-collection flow (SPEC.md §5.2, §10.1, §10.4; APRV-78).
+ *
+ * `setup identity|vault|sampling|telegram` each hand-rolled their own
+ * conversation, and that was right while there were four of them and each was
+ * different. `setup adapter <name>` was the first verb whose conversation is
+ * DERIVED — from a manifest of {@link CredentialSpec}s an adapter declares — so
+ * the conversation itself becomes a function, and this file is that function.
+ * APRV-79 made it the second caller's too: `setup channel telegram` runs this
+ * flow over the Telegram channel's manifest, into `.approval/env` instead of
+ * into the vault, which is what the destination seam was built for.
+ *
+ * It knows nothing about email, SMTP, Telegram, or the vault's file format. It
+ * is handed a list of specs, somewhere to put the values
+ * ({@link FlowDestination}), and up to four hooks, and it runs one fixed order:
+ *
+ * 1. the title and the prerequisite line;
+ * 2. **the checklist** — one line per spec, before a single question is asked,
+ *    so an operator can see the whole shape of what is about to be demanded and
+ *    where it will land, and abandon at zero cost if it is the wrong vault;
+ * 3. **the preflight** ({@link FlowDestination.present}), which for a vault
+ *    means OPENING it. This is why it is step three and not step six: a wrong
+ *    passphrase must refuse before the operator has typed a password, not
+ *    after. The set it returns is also what step four reads;
+ * 4. **the replacement plan** ({@link planWrites}), asked up front for the same
+ *    reason `setup`'s own does: a confirmation asked after the value had been
+ *    replaced is a question whose "no" no longer means anything. A name the
+ *    operator declines is never even asked for;
+ * 5. **collection**, in manifest order;
+ * 6. **the cross-field check** ({@link FlowHooks.check}), before any write, so
+ *    a half-configured pair costs nothing;
+ * 7. **the writes**, in manifest order — which is why an adapter puts its
+ *    secret last: a destination that refuses half way reports exactly which
+ *    names landed and stops. **There is no rollback**, deliberately: deleting
+ *    credentials in response to a write failure is a destructive act taken by a
+ *    wizard on its own authority, over a store whose previous contents it
+ *    cannot restore;
+ * 8. **verification** ({@link FlowHooks.verify}), after the write, because the
+ *    thing being verified is the stored configuration; and
+ * 9. **the report** — where, how many, which names — and the next steps.
+ *
+ * **Values are held in this process and printed by nothing.** The flow must
+ * hold them: it collected them and it is about to write them. Every line it
+ * emits names a CREDENTIAL NAME, a kind, a count, or a path, and the suite in
+ * `tests/cli-setup.test.ts` sweeps every captured byte for the fixture secrets
+ * with no exemption on this path.
+ */
+import type { CredentialSpec } from "../core/credential-spec.js";
+import { envFilePathFor } from "../core/env-file.js";
+import type { Streams } from "./main.js";
+import { type Prompter } from "./prompt.js";
+/**
+ * A refusal from a destination, already carrying its exit code.
+ *
+ * The code is decided by the destination and not by this file, because the
+ * frozen exit table's split (4 is a filesystem fact, 1 is the runtime deciding
+ * no) is a property of the STORE's vocabulary — `cli/vault.ts` and
+ * `cli/setup.ts` each already map their own refusals that way, and a flow that
+ * re-derived the mapping would be a third opinion about the same table.
+ */
+export interface FlowRefusal {
+    code: string;
+    message: string;
+    exitCode: number;
+}
+/** Where a flow puts what it collected. Two implementations live below. */
+export interface FlowDestination {
+    kind: "vault" | "env-file";
+    /** The path, for the checklist and the report. Never a value. */
+    where(): string;
+    /**
+     * Which of the names are ALREADY there — and, for a store that must be
+     * unlocked, the act of unlocking it. Called once, before anything is asked.
+     */
+    present(): {
+        ok: true;
+        names: ReadonlySet<string>;
+    } | ({
+        ok: false;
+    } & FlowRefusal);
+    /** Store one value. Called once per name, in manifest order. */
+    write(name: string, value: string): {
+        ok: true;
+    } | ({
+        ok: false;
+    } & FlowRefusal);
+}
+/**
+ * The encrypted credential store (SPEC.md §10.4).
+ *
+ * `present()` is where the passphrase is proved. A vault that does not exist
+ * yet holds nothing and refuses nothing: the first `write` creates it, which is
+ * what `approval vault set` does too. A vault that DOES exist is opened here
+ * and nowhere later, so a wrong passphrase costs the operator one line of
+ * output rather than five typed values.
+ */
+export declare function vaultDestination(vaultPath: string, passphrase: string): FlowDestination;
+/**
+ * The `.approval/env` source map (SPEC.md §5.2).
+ *
+ * Unused by `setup adapter` — an adapter's credentials go to the vault, never
+ * to this file — and used by `setup channel telegram`, which is what a channel's
+ * two values are: a source for the token and a literal chat id, both of them
+ * things that unlock the machine rather than things an adapter spends.
+ *
+ * The value written is whatever the caller collected, which on this path is a
+ * SOURCE (`keychain:<service>`), an identity, or a chat id. Nothing here decides
+ * that; {@link upsertEnvFileEntries} preserves every other line and comment.
+ */
+export declare function envFileDestination(envPath: string): FlowDestination;
+/** The env file for a log path, re-exported so a caller needs one import. */
+export { envFilePathFor };
+/** How a destination talks about what it already holds. */
+export interface PlanPhrases {
+    /** `<name> already has a line in <path> (its value is not printed here).` */
+    present(name: string, where: string): string;
+    /** The confirm question. Defaults to no, like every other one in `setup`. */
+    replace(name: string): string;
+    /** The "left alone" report, or `null` when nothing was left alone. */
+    leftAlone(names: string[], where: string): string;
+}
+/**
+ * The two phrasings, kept as data.
+ *
+ * The env-file wording is BYTE-FOR-BYTE what `setup identity|vault|sampling|
+ * telegram` printed before this file existed, because those sentences are
+ * asserted on and, more to the point, an operator who has run `setup` before
+ * should not be told the same fact in new words for no reason.
+ */
+export declare const PLAN_PHRASES: Record<FlowDestination["kind"], PlanPhrases>;
+/**
+ * Which names to ask for, given which are already there.
+ *
+ * Asked BEFORE any work is done, and no previous VALUE is ever printed — not
+ * even one that is not a secret. A store may legitimately hold anything under
+ * any name, the operator put it there, and a verb that echoed "replacing
+ * smtp.user (you@example.net)?" would publish it into a terminal on their
+ * behalf.
+ */
+export declare function planWrites(streams: Streams, prompter: Prompter, present: ReadonlySet<string>, where: string, names: readonly string[], phrases: PlanPhrases): {
+    write: string[];
+    skipped: string[];
+};
+/** Report what was left alone, so a re-run's "no" is visible in the output. */
+export declare function reportLeftAlone(streams: Streams, where: string, skipped: readonly string[], phrases: PlanPhrases): void;
+/**
+ * A numbered picker over a closed list.
+ *
+ * Extracted from the Telegram chat picker, which is the same conversation over
+ * different nouns: print the options with an index and read a number. Both
+ * callers use this one (APRV-79).
+ *
+ * **An unparseable answer is asked again** (APRV-90). It used to be a refusal,
+ * on the argument that a wizard which loops on one question and not the others
+ * is unpredictable — the answer to which turned out to be that every question
+ * loops, not that none of them does. The options are printed once; only the
+ * question repeats, under one line saying which number was not on the list.
+ * `ok: false` now means the human withdrew (Ctrl-D) or ran out of attempts, and
+ * the message says which.
+ */
+export declare function pickOne<T>(streams: Streams, prompter: Prompter, options: {
+    heading: string;
+    items: readonly T[];
+    label(item: T): string;
+    prompt: string;
+    /** Index of the item an empty answer takes, or `null` for no default. */
+    defaultIndex: number | null;
+}): {
+    ok: true;
+    item: T;
+} | {
+    ok: false;
+    message: string;
+};
+/** What a verification attempt reports back. Never carries a value. */
+export interface VerifyOutcome {
+    /** Did the far end accept the stored configuration? */
+    ok: boolean;
+    /** The operator declined to verify. `ok` is ignored when this is true. */
+    declined?: boolean;
+    /** Lines to print, already redacted by whoever built them. */
+    detail: string;
+}
+/** What the flow has done by the time {@link FlowHooks.verify} is called. */
+export interface FlowProgress {
+    /** Names stored this run, in the order they landed. */
+    written: readonly string[];
+    /** Names the operator declined to replace, so this run never saw them. */
+    skipped: readonly string[];
+}
+/**
+ * What a {@link FlowHooks.collect} or {@link FlowHooks.discover} attempt did.
+ *
+ * `refused` carries an exit code and nothing else, because the hook has already
+ * printed its own sentences. A channel's refusals are specific to the far end
+ * it just talked to — an invalid bot token, a 409 from a running listener, no
+ * message reaching the bot after three attempts, each with its own repair and
+ * its own code from the frozen table — and a flow that re-derived them from a
+ * message string would be a second opinion about what went wrong.
+ */
+export type HookOutcome = {
+    kind: "value";
+    value: string;
+}
+/** Nothing to store for this spec. A required spec may not do this. */
+ | {
+    kind: "skip";
+} | {
+    kind: "refused";
+    code: number;
+};
+export interface FlowHooks {
+    /**
+     * Collect one value, overriding the built-in prompts.
+     *
+     * Async because a hook may need to prove what it collected before the flow
+     * writes anything: `setup channel telegram` calls `getMe` at the end of its
+     * token collection, so an invalid token refuses at step five and no line is
+     * ever written. Handed what has been collected so far, in manifest order.
+     */
+    collect?(spec: CredentialSpec, state: Readonly<Record<string, string>>): Promise<HookOutcome>;
+    /**
+     * The cross-field rule, run over everything collected, before any write.
+     * Returns the refusal sentence, or `null`. `kept` names the values already
+     * in the store that the operator declined to replace this run (APRV-98): the
+     * flow never reads a value back, so a rule that needs to know whether a
+     * kept name is PRESENT gets that from here rather than from `values`.
+     */
+    check?(values: Record<string, string>, kept: readonly string[]): string | null;
+    /**
+     * Prove the stored configuration against the far end. Runs after the write.
+     *
+     * It is handed what the run DID as well as what it collected, because
+     * "verify" and "verify what is in the store" are different questions on a
+     * re-run: a hook that only saw the values would probe a partial
+     * configuration and report a failure about a deployment that is fine. The
+     * flow will not read the store back to complete the picture, and neither
+     * should a hook — there is no verb in this CLI that reads a credential out.
+     */
+    verify?(values: Record<string, string>, progress: FlowProgress): Promise<VerifyOutcome>;
+    /**
+     * Ask the SERVICE what a value is, rather than asking the human to type it.
+     *
+     * Called for one spec at a time, and only when {@link FlowHooks.collect}
+     * skipped it (or there is no `collect` and the spec is optional and empty),
+     * so the two compose: a manifest can have some values typed and some
+     * discovered without the flow knowing which is which. It is handed what has
+     * been collected so far, because discovery generally needs it — Telegram's
+     * chat discovery cannot happen before the token it polls with.
+     *
+     * APRV-78 reserved this hook and called nothing; APRV-79 is the caller.
+     */
+    discover?(spec: CredentialSpec, state: Readonly<Record<string, string>>): Promise<HookOutcome>;
+}
+export interface FlowLabels {
+    /** The first line: what this verb is about to do. */
+    title: string;
+    /** The prerequisite sentence, printed under the title. */
+    prereq?: string;
+    /** Printed last, after the report. One line each. */
+    nextSteps?: readonly string[];
+}
+export interface FlowResult {
+    /** The exit code, from the frozen table. */
+    code: number;
+    /** Names actually stored, in the order they landed. */
+    written: string[];
+    /** Names the operator declined to replace. */
+    skipped: string[];
+    verified: "passed" | "failed" | "declined" | "not-attempted";
+}
+export interface CredentialFlow {
+    streams: Streams;
+    prompter: Prompter;
+    specs: readonly CredentialSpec[];
+    destination: FlowDestination;
+    labels: FlowLabels;
+    hooks?: FlowHooks;
+}
+/**
+ * Run one credential conversation, start to finish. Never throws.
+ *
+ * The caller has already done everything that is its own business: flags, the
+ * terminal check, the human-only gate, and resolving the passphrase out of the
+ * environment. What arrives here is a manifest and somewhere to put it.
+ */
+export declare function runCredentialFlow(flow: CredentialFlow): Promise<FlowResult>;