approval-md 0.1.0 → 0.2.0

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

@@ -0,0 +1,275 @@
+/**
+ * What every `approval setup` subcommand shares (SPEC.md §5.2, §10.1; APRV-79).
+ *
+ * `setup` began as one file with four subcommands in it. APRV-78 added
+ * `setup adapter <name>` in a file of its own, and it had to reach back into
+ * `cli/setup.ts` for the front matter — which made a cycle: `setup.ts` imports
+ * the adapter verb to dispatch it, and the adapter verb imports `front`,
+ * `requireHuman` and `SetupDeps` back. ESM tolerates that until the day an
+ * initialisation order changes and a `const` at module scope is `undefined` in
+ * one direction only. APRV-79 adds a THIRD such file (`setup-channel.ts`), so
+ * the cycle is broken by extraction rather than tolerated a second time.
+ *
+ * The rule this file exists to enforce, asserted in `tests/layering.test.ts`:
+ *
+ * ```
+ * setup.ts ──┬─> setup-adapter.ts ──┐
+ *            └─> setup-channel.ts ──┴─> setup-common.ts   (and no arrow back)
+ * ```
+ *
+ * What lives here is what more than one of those three needs: the dependency
+ * bag, the keystore seam, the flag table, the front matter (`--help`, the paths,
+ * the policy, the terminal check), the human-only gate, the `.approval/env`
+ * refusal mapping, the service names, and the plaintext-literal offer. What does
+ * NOT live here is anything one subcommand alone uses: the chat picker is
+ * `setup-channel.ts`'s, the manifest hint generator is `setup-adapter.ts`'s, and
+ * the generated-secret path (`storeGeneratedSecret`) stays with `vault` and
+ * `sampling` in `setup.ts`.
+ *
+ * The reasoning for each decision this file encodes — why the token is never
+ * handled by this process, why a generated value may reach an argv and an
+ * operator's own may not, why every subcommand refuses a non-terminal stdin —
+ * is in `cli/setup.ts`'s module doc, which is the family's front page. It is not
+ * repeated here; this file is the mechanism.
+ */
+import { type EnvFileRefusal } from "../core/env-file.js";
+import { type PolicyLoadResult } from "../core/policy-load.js";
+import type { CredentialProvider } from "../adapters/contract.js";
+import type { probeSmtp } from "../adapters/smtp.js";
+import { type TelegramFetch } from "../channels/telegram.js";
+import { type FlagKind } from "./args.js";
+import type { Streams } from "./main.js";
+import { type Prompter } from "./prompt.js";
+/**
+ * The keystore item names, one per secret, SCOPED TO THIS INSTANCE (APRV-178).
+ *
+ * They were three fixed strings until a demo gate in another directory stored
+ * its bot token over the production gate's item, read the production token
+ * back, and had a human's approval tap consumed by the wrong listener. A
+ * keystore is machine-global and the filesystem scoping every other part of an
+ * instance has was simply missing here; `core/instance.ts` carries the whole
+ * reasoning and the shape of the suffix.
+ *
+ * Still not a flag. An operator reading `.approval/env` sees the service name
+ * in the file itself (`keychain:approval-tg-token-3f2a9c11`), so the name is
+ * discoverable, and a `--service-prefix` would add a way for two checkouts to
+ * disagree about which item is which — which is the bug, not the fix.
+ */
+export interface ServiceNames {
+    telegramToken: string;
+    vaultPassphrase: string;
+    samplingSecret: string;
+}
+/** The three item names the instance owning `logPath` reads and writes. */
+export declare function servicesFor(logPath: string): ServiceNames;
+/**
+ * The variable a sampling secret goes into when the policy names none. The
+ * value is stored either way; what the operator is then told to do is add the
+ * `audit.sampling_secret_env` line, because until the POLICY names a variable
+ * the sampler stays off (SPEC.md §5.2) and no amount of environment fixes that.
+ */
+export declare const DEFAULT_SAMPLING_ENV = "APPROVAL_SAMPLING_SECRET";
+/** The long-poll `getUpdates` asks for, in seconds. */
+export declare const POLL_TIMEOUT_SECONDS = 10;
+/** doctor's probe timeout, for the calls that answer immediately. */
+export declare const PROBE_TIMEOUT_MS = 10000;
+/** The flags every subcommand accepts. One table, so none of them drifts. */
+export declare const FLAGS: Record<string, FlagKind>;
+/** Which credential store this machine has, as a closed set. */
+export type KeystoreKind = "keychain" | "secret-service" | "none";
+/** What a store attempt did. `viaArgv` is reported, never hidden. */
+export type StoreOutcome = {
+    ok: true;
+    /**
+     * The value passed through the helper's argv rather than its stdin. True
+     * only on the generated-secret fallback path; see `cli/setup.ts`.
+     */
+    viaArgv: boolean;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * The keystore operations `setup` needs, injectable for exactly the reason
+ * {@link defaultSourceRunner}'s seam exists: no test in this repository may
+ * touch a real Keychain or a real secret service, and the way to guarantee that
+ * is for the tests to hand over a fake rather than for the runtime to grow a
+ * test-only flag.
+ */
+export interface KeystoreRunner {
+    /** What is available here. Consulted once per run. */
+    kind(): KeystoreKind;
+    /**
+     * Store a value THIS PROCESS GENERATED. Prefers the helper's stdin; may fall
+     * back to its argv, and says which it did.
+     */
+    storeGenerated(service: string, value: string): StoreOutcome;
+    /**
+     * Have the HELPER'S OWN no-echo prompt collect the value from the terminal.
+     * The value never enters this process. macOS and `secret-tool` both support
+     * this; there is no such thing on a machine with neither.
+     */
+    storePrompted(service: string): StoreOutcome;
+    /** Read a stored value back. The value arrives on stdout, never in an argv. */
+    read(service: string): {
+        ok: true;
+        value: string;
+    } | {
+        ok: false;
+        message: string;
+    };
+}
+/** A thrown thing, as a sentence. */
+export declare function detail(cause: unknown): string;
+/** The real one. Nothing in the test suite constructs it. */
+export declare const defaultKeystoreRunner: KeystoreRunner;
+/** The `.approval/env` scheme a backend writes. */
+export declare function schemeFor(kind: KeystoreKind, service: string): string | null;
+/** The command an operator runs by hand to see that the item is really there. */
+export declare function retrievalCommand(kind: KeystoreKind, service: string): string;
+/** The command an operator runs by hand to STORE the item, with no value in it. */
+export declare function storageCommand(kind: KeystoreKind, service: string): string;
+/** Everything this verb reaches the world through. Defaults are the real ones. */
+export interface SetupDeps {
+    prompter?: Prompter | null;
+    keystore?: KeystoreRunner;
+    fetch?: TelegramFetch;
+    apiBase?: string;
+    /** Overridable so a test can assert on a value it chose. */
+    generate?: () => string;
+    /**
+     * The `getUpdates` long poll, in seconds. Overridable for one reason: the
+     * "nobody messaged the bot" path polls three times, and a suite that spent
+     * thirty seconds proving a refusal is a suite people stop running. Not a
+     * flag — no operator has a reason to change it.
+     */
+    pollTimeoutSeconds?: number;
+    /**
+     * The environment the passphrase is read from. `process.env` by default.
+     *
+     * A seam and not a back door: it is read through `passphraseFrom`, which is
+     * the same function `approval vault set` uses, and it never resolves
+     * `.approval/env` (§11.1 invariant 7). Injectable so a test can prove both
+     * the unset refusal and the happy path without mutating the suite's own
+     * environment, which is shared by every other test in the process.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * The SMTP probe `setup adapter email` verifies with. The real one by
+     * default; a test injects a wrapper so that the only TLS relaxation in this
+     * repository stays inside the test that needs it (`tests/smtp-mock.ts`'s
+     * self-signed fixture on 127.0.0.1).
+     */
+    probe?: typeof probeSmtp;
+    /**
+     * The vault read `setup adapter email` probes a partial re-run through
+     * (APRV-99). The real {@link vaultCredentialProvider} by default — the same
+     * provider `approval adapter email` hands to `act` — and injectable for one
+     * reason: the fallback for a vault that will not open is unreachable
+     * otherwise, because the flow proved the passphrase at its preflight and the
+     * writes have already landed by the time verification runs.
+     */
+    credentials?: CredentialProvider;
+}
+export declare function usageError(streams: Streams, json: boolean, message: string, helpText: string): number;
+/**
+ * A refused PROMPT, as one line and no help page (APRV-90).
+ *
+ * The distinction this function exists to draw: {@link usageError} answers a
+ * mangled command line, so it names the shape that line should have had, which
+ * is the thing the operator got wrong. A prompt that was aborted or answered
+ * wrongly five times is not a command line at all — the operator was in a
+ * conversation, the question was on screen, and a usage block under it teaches
+ * nothing. Same exit code (the frozen table is unchanged), one line of output,
+ * and not even the `--help` pointer a usage error carries.
+ */
+export declare function promptRefusal(streams: Streams, message: string): number;
+export declare function absolute(value: string, cwd: string): string;
+export declare function refusalExitCode(refusal: EnvFileRefusal): number;
+export declare function emitRefusal(streams: Streams, refusal: EnvFileRefusal): number;
+export interface Context {
+    flags: Record<string, string | boolean>;
+    positionals: string[];
+    prompter: Prompter;
+    keystore: KeystoreRunner;
+    /**
+     * Which keystore this machine has. Named `backend` rather than `kind` because
+     * the outcome union around this context already discriminates on `kind`.
+     */
+    backend: KeystoreKind;
+    load: PolicyLoadResult;
+    logPath: string;
+    envPath: string;
+    /** This instance's keystore item names (APRV-178). */
+    services: ServiceNames;
+    apiBase: string;
+    generate: () => string;
+    pollTimeoutSeconds: number;
+}
+export type FrontOutcome = {
+    kind: "handled";
+    code: number;
+} | ({
+    kind: "run";
+} & Context);
+/**
+ * What a non-interactive hint needs: where the map lives, which keystore is
+ * present, and the variable NAMES the loaded policy resolves to. The hints
+ * must print the names the interactive path would write, or an operator on a
+ * renamed policy copies a line the runtime never reads.
+ */
+export interface HintContext {
+    envPath: string;
+    kind: KeystoreKind;
+    /**
+     * The instance's item names. A hint that printed the unscoped legacy name
+     * would teach the operator to create by hand exactly the shared item
+     * APRV-178 exists to stop.
+     */
+    services: ServiceNames;
+    passphraseEnv: string;
+    samplingEnv: string;
+    tokenEnv: string;
+    chatEnv: string;
+}
+/** The policy's `audit.sampling_secret_env`, or `null`. */
+export declare function samplingEnvName(load: PolicyLoadResult): string | null;
+export declare function hintContextFor(load: PolicyLoadResult, envPath: string, kind: KeystoreKind, services: ServiceNames): HintContext;
+/**
+ * `--help`, the paths, the policy, the terminal check.
+ *
+ * The terminal check has no `process.stdin.isTTY` in it, deliberately: the real
+ * prompter refuses to construct without one ({@link createPrompter}), so "there
+ * is no prompter" IS "there is no terminal", and a test that injects one has
+ * not bypassed a check that a CI job could also bypass — it has supplied the
+ * human's side of the conversation, which is the only thing a test can honestly
+ * do here.
+ */
+export declare function front(subcommand: string, argv: string[], streams: Streams, cwd: string, deps: SetupDeps, helpText: string, nonInteractiveHint: (context: HintContext) => string, 
+/**
+ * Flags this subcommand accepts on top of the shared table (APRV-110).
+ *
+ * `setup service` is the first subcommand whose subject is not a credential,
+ * so it needs words the other four have no use for (a platform, a unit label,
+ * a log directory). They are passed in rather than added to {@link FLAGS},
+ * because a flag every subcommand silently accepts is a flag an operator will
+ * eventually pass to the one that ignores it.
+ */
+extraFlags?: Record<string, FlagKind>): FrontOutcome;
+/** The human-only rule, spelled exactly as `vault set` spells it. */
+export declare function requireHuman(flags: Record<string, string | boolean>, streams: Streams, helpText: string, verb: string): {
+    ok: true;
+    actor: string;
+} | {
+    ok: false;
+    code: number;
+};
+/**
+ * The plaintext-literal offer, for a machine with no keystore.
+ *
+ * An explicit typed `yes` — not `y`, not Enter — because the whole content of
+ * this question is that the operator understood it. The warning is worded to
+ * match what `approval env --check` will print at them on every run afterwards,
+ * so the two never read as different claims about the same file.
+ */
+export declare function offerLiteral(streams: Streams, prompter: Prompter, envPath: string, what: string): boolean;

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>;

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

@@ -0,0 +1,96 @@
+/**
+ * `approval setup service` — the login service that runs the ambient runtime
+ * (SPEC.md §10.2, APRV-110).
+ *
+ * `approval up` is a foreground process. This verb writes the one file that
+ * makes it start at login and stay started: a launchd user agent on macOS, or a
+ * systemd user unit on Linux. It is the fifth member of the `setup` family and
+ * it obeys the family's rules — interactive by refusal, human-only, appending
+ * nothing to the log, editing no policy — with two of its own.
+ *
+ * ## It never copies a value
+ *
+ * A unit file is world-readable configuration that survives reboots and gets
+ * backed up. A bot token in one is a bot token in a backup. So the unit NAMES
+ * where the environment comes from and never carries it:
+ *
+ * - by default it runs a WRAPPER the human reads in the printed unit —
+ *   `eval "$(approval env)"` and then `exec approval up` — so the keystore
+ *   references stay in the keystore and `approval env` stays the only thing
+ *   that resolves them (SPEC.md §11.1 invariant 7: nothing loads that file
+ *   implicitly, and here it is a human's line in a file they approved);
+ * - or, with `--env-file`, it points at a file THE OPERATOR AUTHORED, which
+ *   this verb neither writes nor reads.
+ *
+ * ## It prints the unit before it writes it, and it does not arm it
+ *
+ * The whole file goes to stdout first, and nothing is written until the operator
+ * confirms. Loading it is a separate act: this verb prints the exact
+ * `launchctl` or `systemctl` line and stops there. A login service is a standing
+ * capability on someone's machine — it will start a process that holds a
+ * credential and can put prompts on a phone — and a wizard that armed one as a
+ * side effect of writing a file would be making that decision on the operator's
+ * behalf. Printing the command costs one paste and buys an explicit act.
+ *
+ * ## Logs never go into `.approval/`
+ *
+ * The service's stdout and stderr go where the operator chooses, defaulting to
+ * the platform's own log home. A path inside the approval home is REFUSED:
+ * `.approval/` holds the log, the queue projection, the payload store, the
+ * vault and the environment source map, and a service that appended its console
+ * output beside them would put unverifiable text in the one directory whose
+ * contents are supposed to mean something.
+ */
+import type { Streams } from "./main.js";
+import { type SetupDeps } from "./setup-common.js";
+/** The two service managers this verb writes for. */
+export type ServicePlatform = "launchd" | "systemd";
+/** The conventional names. `--label` overrides both. */
+export declare const LAUNCHD_LABEL = "md.approval.up";
+export declare const SYSTEMD_UNIT = "approval-up";
+/** Which manager this machine has, or `null` when it has neither. */
+export declare function platformFor(platform: NodeJS.Platform): ServicePlatform | null;
+/** Where the unit file belongs, for a platform and a label. */
+export declare function unitPathFor(platform: ServicePlatform, label: string, home: string): string;
+/** Where the platform keeps a user's own logs. */
+export declare function defaultLogsDir(platform: ServicePlatform, home: string): string;
+/** The command that arms the written unit, printed and never run. */
+export declare function armCommand(platform: ServicePlatform, label: string, path: string): string;
+/**
+ * The command that disarms it, printed before the file is removed.
+ *
+ * Takes no path, unlike {@link armCommand}: launchd boots a service OUT by its
+ * label, and the plist it was booted in from may already be gone.
+ */
+export declare function disarmCommand(platform: ServicePlatform, label: string): string;
+/** Everything a unit is generated from, all of it already resolved. */
+export interface ServicePlan {
+    platform: ServicePlatform;
+    label: string;
+    /** The unit file this would be written to. */
+    path: string;
+    /** The primary checkout the runtime is started in. */
+    workingDir: string;
+    /** The `approval` invocation, as argv words. */
+    exec: string[];
+    /** An operator-authored EnvironmentFile, or `null` for the `approval env` wrapper. */
+    envFile: string | null;
+    outLog: string;
+    errLog: string;
+    /** The variable NAMES the runtime will look for. Printed as a comment only. */
+    variables: string[];
+}
+/** One `sh -lc` script: the wrapper the operator reads inside the unit. */
+export declare function wrapperScript(plan: ServicePlan): string;
+/** The whole unit file, as the operator will read it and as it will be written. */
+export declare function renderUnit(plan: ServicePlan): string;
+/**
+ * The approval invocation this process was started as.
+ *
+ * `node dist/src/cli/main.js` and the installed `approval` bin are both
+ * legitimate, and a unit that named the wrong one would fail at login rather
+ * than here. `--exec` overrides for the case neither guess fits.
+ */
+export declare function execWords(override: string | null, argv: readonly string[]): string[];
+/** `approval setup service` — write the login unit. HUMAN-ONLY, INTERACTIVE. */
+export declare function commandSetupService(argv: string[], streams: Streams, cwd: string, deps?: SetupDeps): number;