canopycms 0.0.67-int.90 → 0.0.67

package/dist/cli/init-github-app.d.ts

@@ -1,183 +1,42 @@
 /**
- * `canopycms init-github-app <create|verify>` — registers the GitHub App the CMS
- * worker authenticates as, and reads its grant back.
- *
- * WHY THIS EXISTS: THE PERMISSIONS ARE CODE HERE
- *
- * The worker can authenticate as a GitHub App instead of a personal access token
- * (adopter request #45). What did not ship with it was any machine-checkable
- * statement of which permissions that App needs — the answer lived only as prose
- * in `docs/deploying-to-aws.md`, which nothing derives and nothing verifies.
- *
- * A PAT's scope only ever exists as checkboxes somebody ticked, so "is this
- * credential wider than intended?" is unanswerable from the repository. The
- * manifest flow takes the permission set as JSON, so `CANOPY_APP_PERMISSIONS`
- * below is reviewable, diffable, and a desired state a program can check —
- * against the call sites that force each entry (see the constant) and against
- * what an installation actually holds (see `verify`).
- *
- * And guessing too narrow does not fail loudly. `task-runner.ts`'s
- * `convert-to-draft` runs a GraphQL mutation, and a GraphQL failure answers HTTP
- * 200 with a body-level error carrying NO numeric status — so
- * `isPermanentTaskFailure` reads a permission denial as transient, retries to the
- * cap, and wedges the branch in `sync-failed` with nothing naming a permission.
- * `createOrUpdatePullRequest` swallows a failed `markPullRequestReadyForReview`
- * into a warning by design (`github-service.ts`), leaving the PR stuck as a
- * draft. Both surface hours after setup. `verify` moves that discovery to setup
- * time, which is the only cheap place to find it.
- *
- * ONE APP PER SITE. NOT ONE APP PER ORGANISATION.
- *
- * Worth stating at length because the obvious economy is to register one App and
- * install it on every repository that needs it, and for a READ-ONLY App whose key
- * never leaves GitHub that is right. It is wrong here, and the reason is
- * structural rather than a matter of taste:
- *
- * **A GitHub App's private key is App-level. Installation scoping is not a
- * boundary GitHub enforces against whoever holds the key — it is a choice the
- * key-holder makes at mint time.** Anyone with the key can sign a JWT, call
- * `GET /app/installations` to enumerate every installation, and mint an access
- * token for any of them.
- *
- * Our key does not stay in one place: each site's worker reads it at runtime,
- * from that site's own secret store, on that site's own host. So one shared App
- * with `contents: write` would mean that reading the marketing site's secret
- * store hands you write access to the documentation site's repository. One App
- * per site, one installation each, one key each — blast radius contained to the
- * site that leaked.
- *
- * The cost is real and is not pretended away: N sites means N Apps, N keys and N
- * things to rotate. That is affordable only because creating one is cheap, which
- * is most of why this command exists.
- *
- * WHAT THE MANIFEST FLOW BUYS, WHICH IS MORE THAN IT LOOKS
- *
- * `redirect_url` is the point of it. GitHub redirects there with a one-hour code,
- * and `POST /app-manifests/{code}/conversions` exchanges that code for the App's
- * id, client id and **the private key itself**. So `create` runs a one-shot
- * loopback server, captures the key in memory, and hands it straight to a
- * destination the operator named. Sent to a command's stdin — the recommended
- * route — **the key never touches disk**, and nobody has to find a downloaded
- * `.pem`. `--key-out` deliberately does write it to a file, for an operator with
- * no such command; that is the trade, not an oversight.
- *
- * MEASURED (2026-09-05, in a sibling project) and it contradicts the
- * documentation: GitHub's REST docs list `redirect_url` as OPTIONAL, and the
- * organisation App-creation form refuses a manifest without it — "Invalid GitHub
- * App configuration ... Error 'redirect_url' wasn't supplied."
- *
- * THIS FILE TALKS TO GITHUB WITH `fetch`, NOT OCTOKIT, DELIBERATELY
- *
- * Two reasons. An App JWT requires `Authorization: Bearer <jwt>`, and a client
- * that sends `token <value>` is answered with `401 A JSON web token could not be
- * decoded` — measured in the sibling project, where it presented as "no
- * installation found" and sent the operator to check a page that was correct.
- * And Octokit here would add `octokit.apps.*` call sites to this package, which
- * the guard in `github-app-permission-drift.test.ts` would then have to carve an
- * exception for — an exception being exactly how a guard goes blind.
- *
- * The JWT is hand-rolled over `node:crypto` for a third reason that is not
- * optional: `.dependency-cruiser.mjs`'s `core-no-github-app-auth` rule scopes to
- * every package's own `src/`, so importing `@octokit/auth-app` here is a lint
- * error, same as anywhere else in this package.
- *
- * THE KEY'S DESTINATION IS NOT THIS TOOL'S BUSINESS
- *
- * `create` takes either a command to pipe the PEM into (`-- <cmd>`) or a file to
- * write (`--key-out`), and asks for a file path if that first one fails. It
- * knows nothing about AWS, or any other secret store: an adopter may not deploy
- * to AWS at all, and a setup tool that hardcodes one cloud is a setup tool for
- * one adopter. `docs/deploying-to-aws.md` carries the worked invocation.
+ * `canopycms init-github-app <create|verify>` — registers the GitHub App the
+ * CMS worker authenticates as, and reads its grant back. A PAT's scope is
+ * unauditable — checkboxes somebody ticked, nowhere recorded.
+ * `CANOPY_APP_PERMISSIONS` in github-app-manifest.ts is the machine-checkable statement of what
+ * this App needs instead, checked against the call sites that force each
+ * entry (see the constant) and what an installation holds (see `verify`). A
+ * missing permission fails silently — a GraphQL denial answers HTTP 200 with
+ * no numeric status — so `verify` exists to catch that at setup time.
+ * One App per site, never shared across an organisation: a GitHub App's
+ * private key is App-level — GitHub does not enforce per-installation
+ * scoping against the key-holder — so anyone holding it can mint a token for
+ * every installation. Each site's worker reads its own key from its own
+ * secret store, so sharing one App would let one leaked store reach every
+ * other site's repository.
+ * `create` runs a one-shot loopback server, exchanges GitHub's redirect code
+ * for the App's credentials including the private key, then hands it to the
+ * destination the operator named — over a command's stdin so it never
+ * touches disk, or to a file with `--key-out`. That destination is not this
+ * tool's business: it knows nothing about AWS or any other secret store.
+ * This file talks to GitHub with `fetch`, not Octokit: an App JWT needs
+ * `Authorization: Bearer <jwt>` (sent as `token <value>` it gets a misleading
+ * 401), and `.dependency-cruiser.mjs` forbids importing `@octokit/auth-app`
+ * from this package's `src/` anyway.
  */
 import type { ChildProcess } from 'node:child_process';
 import { createServer } from 'node:http';
-/** Permission levels GitHub uses for App repository permissions, weakest first. */
-export declare const PERMISSION_LEVELS: readonly ["read", "write", "admin"];
-export type PermissionLevel = (typeof PERMISSION_LEVELS)[number];
-export type PermissionSet = Readonly<Record<string, PermissionLevel>>;
 /**
- * The App's entire security surface, and the derivation behind it.
- *
- * Every entry names the call site that forces it, because a permission whose
- * justification lives only in a commit message cannot be re-checked. Enumerated
- * from the only two modules in this package that issue GitHub calls —
- * `github-service.ts` and `worker/{task-runner,rebase}.ts` — plus every git
- * operation that reaches github.com. `canopycms-cdk` makes no REST calls at all.
- *
- * - `contents: write`
- *     - git over HTTPS: the first-boot bare clone (`worker/cms-worker.ts`), the
- *       per-cycle fetch of all branches (`worker/git-sync.ts`), and the branch
- *       pushes including `--force-with-lease` (`worker/task-runner.ts`).
- *     - `octokit.git.deleteRef` (`github-service.ts`, `worker/task-runner.ts`).
- *       GitHub's permissions reference puts `DELETE /repos/{o}/{r}/git/refs/{ref}`
- *       under Contents/write — NOT `administration`, which is the plausible wrong
- *       guess. It is also dead code today: nothing enqueues `delete-remote-branch`
- *       and `GitHubService.deleteBranch`'s only call site is commented out, so it
- *       forces nothing that pushing does not already force. Declared anyway
- *       because the handler is live the moment a producer appears.
- *
- * - `pull_requests: write`
- *     - `pulls.create` and `pulls.update` (`github-service.ts`,
- *       `worker/task-runner.ts`). GitHub's reference: Create and Update a pull
- *       request are Pull requests/write. `pulls.list` and `pulls.get` are
- *       Pull requests/read, subsumed by this.
- *     - the GraphQL mutations `markPullRequestReadyForReview` and
- *       `convertPullRequestToDraft`. **This is the one entry with no
- *       documentation line behind it** — GitHub's permissions reference
- *       enumerates REST endpoints only — so it is derived by analogy with the
- *       REST PR mutations. A live run is the oracle, and until one has happened
- *       this comment is the honest state of it.
- *
- * - `metadata: read` — implied: GitHub grants it alongside any repository
- *   permission. Declared explicitly so this object states the whole surface
- *   rather than the part that is not automatic.
- *
- * Nothing else. No `issues` (there are no `issues.*` calls — nothing sets labels
- * or assignees, which is the usual reason a PR bot needs it), no `administration`,
- * no `actions`, and no organisation permissions. No `workflows`: nothing in the
- * worker edits `.github/workflows/`, but GitHub may still refuse to push rebased
- * history that carries a base-branch change to it — see
- * .claude/future-tasks/worker-push-refused-when-base-changes-workflows.md, an
- * open P1.
+ * The repository an App is being registered for.
+ * @internal Exported for tests.
  */
-export declare const CANOPY_APP_PERMISSIONS: PermissionSet;
-/**
- * GitHub's limit on an App's display name.
- *
- * MEASURED 2026-09-06 in a sibling project, by having a 39-character name
- * refused while a 33-character one was accepted; the documentation states no
- * limit at all. So the true bound is somewhere in 33..38 and 34 is the safe
- * direction: a wrongly-refused name costs the operator one `--name` flag, while a
- * wrongly-accepted one costs a browser round trip to find out. Re-measure when a
- * real App is created from this file.
- */
-export declare const APP_NAME_MAX_LENGTH = 34;
-/**
- * How much of a description the account's App LIST renders before truncating —
- * mid-word, with an ellipsis.
- *
- * MEASURED 2026-09-06 in the same project: a description opening "Read-only,
- * organisation-wide. Lets th…" was cut at 37 characters. The list appears to
- * truncate by CHARACTER rather than by line, so a newline does not rescue a long
- * opening sentence. Hence the shape of `appDescription`: a standalone summary
- * inside this budget, a blank line, then the detail only the App's own page
- * shows.
- */
-export declare const APP_SUMMARY_MAX_LENGTH = 37;
-/** How long `create` waits for the browser round trip before giving up. */
-export declare const CALLBACK_TIMEOUT_MS: number;
-/** The repository an App is being registered for. */
 export type AppTarget = {
     owner: string;
     repo: string;
     /** Organisation accounts and user accounts post the manifest to different URLs. */
     isOrganization: boolean;
 };
-/**
- * Where `create` should send the captured private key. Exactly one, chosen by
- * the operator BEFORE the App exists — see `requireDestination`.
- */
-export type KeyDestination = {
+/** Where `create` should send the captured private key, chosen by the operator BEFORE the App exists. */
+type KeyDestination = {
     kind: 'command';
     argv: string[];
 } | {
@@ -185,246 +44,85 @@ export type KeyDestination = {
     filePath: string;
 };
 /**
- * The App's display name, and the slug GitHub derives from it.
- *
- * Named after the REPOSITORY, because the App is per-site (see the file header):
- * an App named after the organisation would suggest it is shared, which is the
- * arrangement this file exists to avoid.
- *
- * GitHub App names are unique across the WHOLE of GitHub, not merely within an
- * account, so a short generic name is plausibly already taken by somebody else.
- * `create` pre-checks what it can and `--name` overrides; see
- * `checkNameAvailable`.
- */
-export declare function appName(repo: string): string;
-/**
- * GitHub's slug derivation, as far as this needs it: lowercase, and runs of
- * anything that is not alphanumeric collapse to single hyphens.
- *
- * Pinned by a test. If GitHub ever derives differently the name pre-check goes
- * blind rather than loud, so this is not something to assume.
- */
-export declare function appSlug(name: string): string;
-/**
- * A short summary that survives the App list's truncation, then the detail.
- *
- * Two audiences, two parts. Deliberately generic in both: this text is stored ON
- * GITHUB rather than here, so anything in it that can go stale goes stale
- * silently, with nothing in this repository able to detect or fix it. It
- * therefore says only what stays true of the App itself — what it does, that it
- * is installed on one repository, and that it is registered per site.
- */
-export declare function appDescription(): string;
-/**
- * Where the manifest form posts, which differs by account type.
- *
- * A solo adopter who owns the content repository personally needs the user-level
- * URL; posting an organisation manifest to it (or the reverse) fails at the form.
+ * Where the manifest form posts: user-owned and organisation repositories use
+ * different URLs, and posting the wrong one fails at the form.
+ * @internal Exported for tests.
  */
 export declare function manifestPostUrl(target: AppTarget, state: string): string;
 /**
- * The App as GitHub's manifest flow takes it.
- *
- * `default_permissions` is the entire security surface and lives in
- * `CANOPY_APP_PERMISSIONS`, where each entry carries the call site that forces
- * it. `default_events` is empty and the webhook is inactive: nothing is ever
- * delivered to this App — it is only ever assumed outward by the worker.
+ * The App as GitHub's manifest flow takes it. `default_permissions` is the
+ * entire security surface, defined in `CANOPY_APP_PERMISSIONS`. The webhook is
+ * declared but inactive: nothing is ever delivered to this App.
+ * @internal Exported for tests.
  */
 export declare function appManifest(target: AppTarget, redirectUrl: string, name?: string): Record<string, unknown>;
 /**
- * The auto-submitting form that carries the manifest to GitHub.
- *
- * A manifest can only be delivered as a form POST from a browser, which is why
- * this exists at all. Both interpolations are escaped: the manifest embeds
- * adopter-supplied owner and repository names, and this string is written to a
- * file that a browser then executes.
+ * The auto-submitting form that carries the manifest to GitHub — a manifest
+ * can only be delivered as a browser form POST. Both interpolations are
+ * escaped: this embeds adopter-supplied names into a file a browser executes.
+ * @internal Exported for tests.
  */
 export declare function creationForm(target: string, manifest: Record<string, unknown>): string;
 /**
- * A short-lived App JWT, signed RS256 with `node:crypto`.
- *
- * `iat` is backdated 60s because GitHub rejects a JWT whose `iat` is in its own
- * future, and a second of clock skew between here and GitHub is entirely
- * ordinary. `exp` leaves headroom rather than sitting on GitHub's stated
- * ten-minute maximum for no benefit.
+ * A short-lived App JWT, signed RS256 with `node:crypto`. `iat` is backdated
+ * 60s because GitHub rejects a JWT whose `iat` is in its own future, and a
+ * second of clock skew is ordinary; `exp` leaves headroom rather than sitting
+ * on GitHub's stated ten-minute maximum for no benefit.
+ * @internal Exported for tests.
  */
 export declare function appJwt(issuer: string, privateKey: string, now?: number): string;
-export type GitHubResponse<T> = {
-    ok: boolean;
-    status: number;
-    body: T | null;
-    /**
-     * On a FAILURE: GitHub's own `message`, a redacted prefix of the response text,
-     * or — when `status` is 0, meaning the request or the body read never completed
-     * — the redacted client-side error, since there is no response to quote. Empty
-     * string on success: a success body here is App credentials, and a prefix of one
-     * is not worth handing to a caller that might print it.
-     */
-    message: string;
-};
-/**
- * One call to api.github.com.
- *
- * Returns the status and body rather than collapsing failure to `null`, because
- * the two failures a caller has to tell apart here — "this credential cannot
- * authenticate" and "this App is not installed on that repository" — send an
- * operator to entirely different pages. Collapsing them is measured to have sent
- * a real run's operator to check a page that was correct.
- */
-export declare function githubRequest<T>(apiPath: string, init?: {
-    method?: string;
-    body?: unknown;
-    token?: string;
-    jwt?: string;
-}): Promise<GitHubResponse<T>>;
-/** The parts of GitHub's installation object this tool reads back. */
-export type InstallationSummary = {
-    id: number;
-    permissions?: Record<string, string>;
-    repository_selection?: string;
-    suspended_at?: string | null;
-    app_slug?: string;
-};
-export type ReadbackFinding = {
-    severity: 'error' | 'warn';
-    message: string;
-};
-/**
- * Compare what an installation actually holds against what this package needs.
- *
- * Pure, so the whole judgement is testable without a live App — which matters,
- * because everything around it can only ever be exercised by hand.
- *
- * Reports in BOTH directions. A credential does not usually fail by being
- * unusable; that gets noticed immediately. It fails by being one permission too
- * wide, which works perfectly and is never noticed. So an extra permission, or
- * an installation scoped to every repository in the account, is an error here
- * and not a shrug.
- */
-export declare function readbackVerdict(installation: InstallationSummary, desired?: PermissionSet): ReadbackFinding[];
-export type HandOffResult = {
+type HandOffResult = {
     stored: boolean;
     detail: string;
 };
 /**
- * Injectable so `handOffKey` is testable without spawning anything real.
- *
- * Everywhere but Windows the child must carry the bridge's status channel at
- * `stdio[3]`, as `spawnKeyDestination` does: `handOffKey` reads `cat`'s exit
- * status from it, and without a `0` there nothing is reported as stored.
- */
-export type SpawnFn = (command: string, args: string[]) => ChildProcess;
-/**
- * Send the captured private key to the destination the operator named.
- *
- * For a command: no shell parses the operator's argv (see `KEY_INPUT_BRIDGE`
- * for how `sh` is used without doing so). The PEM goes over **stdin**, never
- * argv — an argument is visible in `ps` and lands in shell history. The
- * child's stdout and stderr are INHERITED rather than captured, and that is
- * load-bearing rather than lazy: `aws secretsmanager create-secret` prints the
- * ARN, and CDK's `Secret.fromSecretCompleteArn` needs the full ARN including its
- * six-character suffix. Swallowing the child's output would leave the operator
- * holding a stored secret with no way to learn the one string that wires it up.
- *
- * The `'error'` listener on `child.stdin` is not optional. A child that exits or
- * closes stdin early can make the write fail with EPIPE, and an unhandled error
- * on a stream takes the process down — carrying with it the only copy of a
- * private key for an App that already exists.
- *
- * WHAT `stored: true` DOES AND DOES NOT MEAN. Everywhere but Windows it means
- * three things: the command exited 0, the `cat` feeding it exited 0, and nothing
- * went wrong writing to it. `cat` exiting 0 means every byte of the key went into
- * the pipe. It still does NOT prove the command READ them, and cannot: a pipe
- * write lands in the kernel's buffer, and a key this size fits in one write, so a
- * command that exits without reading races `cat`'s write and can lose or win.
- * MEASURED on macOS with a real 1.7KB key, 100 runs each through this function,
- * with the same result before the bridge and after it: `true`, `head -c 10`,
- * `sh -c 'exec 0<&-; exit 0'` and `sh -c 'head -c 5 >/dev/null; exit 0'` were
- * each reported stored 100 times of 100. What IS caught, whatever the timing,
- * is a command that leaves more unread than a pipe buffer holds: ~100KB into
- * `true` was reported not stored 20 times of 20, by `cat` exiting 141 — the
- * same case the direct spawn caught as a write EPIPE.
- *
- * So the command's EXIT CODE is still the contract, and the operator is still
- * responsible for naming a command that fails loudly. That is stated here rather
- * than papered over, because the tempting fix — waiting for the stream to flush
- * — measures the kernel buffer rather than the command, and would look like a
- * check while being one.
+ * Injectable so `handOffKey` is testable without spawning anything real. Everywhere but Windows
+ * the child carries the bridge's status channel at `stdio[3]`, without which nothing is stored.
+ */
+type SpawnFn = (command: string, args: string[]) => ChildProcess;
+/**
+ * Send the captured private key to the destination the operator named. For a
+ * command, the PEM goes over **stdin**, never argv — an argument is visible
+ * in `ps` and lands in shell history (see `KEY_INPUT_BRIDGE` for how `sh`
+ * runs it without parsing that argv itself). Stdout/stderr are INHERITED,
+ * not captured: `aws secretsmanager create-secret` prints the ARN the
+ * operator needs, which this function must not swallow. The `'error'`
+ * listener on `child.stdin` is not optional: a child that exits or closes
+ * stdin early can fail the write with EPIPE, an unhandled stream error that
+ * would take the process — and the key — down with it.
+ * Everywhere but Windows, `stored: true` means the command exited 0, `cat`
+ * exited 0, and nothing went wrong writing — every byte reached the pipe. It
+ * does NOT prove the command read them: a write lands in the kernel buffer,
+ * and a key this size fits in one write, so a command that exits without
+ * reading races `cat`'s write and can win or lose silently. What IS caught is
+ * a command leaving more unread than the buffer holds, which fails loudly as
+ * `cat` exiting on SIGPIPE — so the exit code is still the contract, and
+ * naming a command that fails loudly is the operator's job.
+ * @internal Exported for tests.
  */
 export declare function handOffKey(pem: string, destination: KeyDestination, spawnFn?: SpawnFn): Promise<HandOffResult>;
-export type CallbackServer = {
+type CallbackServer = {
     port: number;
     code: Promise<string>;
     close: () => void;
 };
 /**
- * One request, then closed — closed by the handler itself, as soon as it has the
- * code. Bound to loopback only.
- *
- * The standard CLI pattern (`gh auth login` does the same): it exists solely so
- * the private key can arrive over the redirect rather than through a downloads
- * folder.
- *
- * A REJECTED REQUEST IS ANSWERED AND IGNORED, never fatal. The `state` check is
- * the CSRF guard the manifest flow provides, but rejecting the promise on a
- * mismatch ends the run on the first stray loopback request — a browser
- * prefetch, an extension, a retried tab — possibly seconds before GitHub's real
- * redirect arrives, and AFTER the App has been created. Aborting there leaves an
- * App nobody holds a key for, over a request that was never GitHub's.
+ * One request, then closed by the handler itself, bound to loopback only —
+ * the standard CLI pattern (`gh auth login` does the same) so the key
+ * arrives over the redirect, not a downloads folder. A rejected request is
+ * answered and ignored, never fatal: the `state` check
+ * is the CSRF guard the manifest flow provides, but rejecting the promise on
+ * a mismatch would end the run on a stray loopback request, possibly before
+ * GitHub's real redirect, leaving an App nobody holds a key for.
+ * @internal Exported for tests.
  */
 export declare function startCallbackServer(state: string, timeoutMs?: number, createServerFn?: typeof createServer): Promise<CallbackServer>;
-type CreatedApp = {
-    id: number;
-    slug: string;
-    clientId: string;
-    pem: string;
-};
-/**
- * The exchange. Unauthenticated by design: the one-hour code IS the credential.
- *
- * Only the four fields this tool needs are lifted out. The response also carries
- * `client_secret` and `webhook_secret`, which this App never uses — so the body
- * is never logged, never returned whole, and never reaches an error message.
- * Failures collapse to `null` and nothing from the response is surfaced, for
- * the same reason: the code itself is exchangeable for the private key for a
- * full hour. That also drops the HTTP status, which the caller does not report
- * (.claude/future-tasks/init-github-app-review-round-1-lows.md, item 2).
- */
-export declare function convertManifest(code: string): Promise<CreatedApp | null>;
-/**
- * Whether the account is an organisation, which decides where the manifest posts.
- *
- * Unauthenticated, so it needs no credential at a point in the flow where we have
- * none. `null` means "could not tell" and the caller says so rather than
- * guessing — guessing wrong sends the operator to a form that refuses the
- * manifest with no useful explanation.
- */
-export declare function detectAccountType(owner: string): Promise<boolean | null>;
-/**
- * Best-effort check that the App name is not already taken.
- *
- * `true` = available as far as we can tell, `false` = definitely taken, `null` =
- * could not check. The three are kept apart deliberately: a PRIVATE App with
- * this slug also answers 404, so a 404 is not proof of availability, and
- * reporting "could not check" as "checked, it is free" is how a guard goes
- * blind. This exists because name collisions can otherwise only be discovered by
- * the creation form — with the CLI already sitting on a loopback server waiting
- * for a redirect that will never arrive.
- */
-export declare function checkNameAvailable(slug: string): Promise<boolean | null>;
-/** Wait for the operator to continue. Returns at once if stdin has ended. */
-export declare function pressEnter(prompt: string): Promise<void>;
-/** Read one line from the operator. `null` when stdin ended instead. */
-export declare function askLine(prompt: string): Promise<string | null>;
-/** Reset between tests. Not used by the command itself. */
-export declare function resetStdinStateForTesting(): void;
 /**
- * What to do with one answer to the retry prompt: write the key to a file, ask
- * again, or stop asking. There is deliberately no command here — see
- * `parseKeyRetryAnswer`.
- *
- * `reprompt` carries WHY, so `handOffWithRetry` can tell the operator what was
- * wrong with what they typed instead of silently asking again.
+ * What to do with one answer to the retry prompt: write to a file, ask again,
+ * or stop. No command here — see `parseKeyRetryAnswer`. `reprompt` carries
+ * WHY, so `handOffWithRetry` can tell the operator what was wrong instead of
+ * silently asking again.
+ * @internal Exported for tests.
  */
 export type KeyRetryChoice = {
     kind: 'give-up';
@@ -436,72 +134,40 @@ export type KeyRetryChoice = {
     filePath: string;
 };
 /**
- * Route one line of operator input at the retry prompt, which accepts a FILE
- * PATH and nothing else. Exported and pure so every rule below is a table test
- * rather than something only reachable by driving a live prompt end to end.
- *
- * WHY NO COMMANDS. The first destination can be a command because the
- * operator's own shell parsed `-- <command…>` into argv. A typed line here has
- * no such parser, and three consecutive review rounds each found splitting it on
- * whitespace sending the key somewhere unintended: a one-word answer written as
- * a file in the working directory; a `|` inside the argv becoming a file name;
- * then `>`, `;`, `&&` and quotes each becoming literal argv words, so
- * `tee key.pem > /dev/null` wrote 0644 copies of the key into the repository
- * root and reported it stored. Each fix closed one spelling. Accepting a path
- * only closes the class: an operator who wants a command writes the file, runs
- * the command against it, and deletes the file.
- *
- * The rules, in order:
- *
- * - `null` (stdin has already ended — see `stdinEnded` above) gives up: there
- *   is nobody left who could answer.
- * - A blank or whitespace-only line MUST NOT give up. Nothing reads stdin
- *   until a readline interface exists, so an Enter pressed during the long
- *   wait for GitHub's redirect — or while the FIRST destination's command was
- *   running — sits in the terminal's line buffer. When that first hand-off
- *   then fails, `askLine` reads the buffered blank line immediately, before
- *   the operator has even seen this prompt. Treating that as "give up"
- *   discarded the only copy of the key without anyone actually answering.
- *   Re-prompting instead costs nothing when the blank line really was
- *   intentional, because the very next prompt still offers "give up" as
- *   something the operator has to type.
- * - The words "give up", case-insensitively and with whitespace normalised, is
- *   the one deliberate way to give up once stdin is live.
- * - Any whitespace inside the answer, or a leading `|`, is re-prompted with
- *   "commands are not accepted here" and the write-run-delete route. Every
- *   command-shaped answer above was spelled with whitespace, and nothing about
- *   a typed line tells a command apart from a path that contains spaces — so
- *   the cost, stated in the reason, is that such a path cannot be entered here.
- * - A leading `~` is re-prompted: nothing here expands it, so `~/key.pem`
- *   would name a directory literally called `~` under the working directory.
- * - A single token with NO `/` or `\` — `pbcopy`, `wl-copy`, any script on
- *   PATH — is re-prompted, suggesting `./<token>`. A "one word is a path" rule
- *   once let `writeFile('pbcopy', pem, { flag: 'wx' })` succeed in
- *   `process.cwd()` — normally the git repository root — leaving a
- *   `contents: write` private key sitting untracked on disk, while the
- *   operator read "written to pbcopy (mode 0600)" and believed it had gone
- *   into the command they meant.
- * - Anything else is a path, which `handOffKey` creates with mode 0600 and
+ * Route one line of operator input at the retry prompt, accepting a FILE
+ * PATH and nothing else (exported and pure, so every rule is table-tested
+ * directly). The first destination can be a command because the operator's
+ * shell parses `-- <command…>` into argv; a typed line has no such parser,
+ * and splitting on whitespace sends the key somewhere unintended (a stray
+ * `|`, `>`, `;`, `&&` or quote becomes a literal argv word). Accepting only a
+ * path closes that class — a command means write, run, then delete. Rules,
+ * in order:
+ * - `null` (stdin has already ended — see prompt.ts) gives up.
+ * - A blank or whitespace-only line MUST NOT give up — a stray Enter pressed
+ *   earlier sits buffered and is read back before the operator has seen this
+ *   prompt — but the words "give up", case-insensitively and
+ *   whitespace-normalised, deliberately do once stdin is live.
+ * - Whitespace inside the answer, or a leading `|`, is re-prompted: nothing
+ *   tells a command apart from a path containing spaces, so such paths
+ *   aren't accepted either.
+ * - A leading `~` is re-prompted (unexpanded, `~/key.pem` would name a
+ *   directory literally called `~`), as is a single token with no `/` or `\`
+ *   (`pbcopy`, any PATH script): as a bare word it would write the key into
+ *   the current directory while the operator believes it reached the command.
+ * - Anything else is a path: `handOffKey` creates it with mode 0600 and
  *   refuses to write if something already exists there.
+ * @internal Exported for tests.
  */
 export declare function parseKeyRetryAnswer(answer: string | null): KeyRetryChoice;
 /**
  * Hand the key over, and keep asking while the operator still has a chance.
- *
- * The pre-flight can only refuse a MISSING destination — it cannot know whether
- * a command exists, whether a path is writable, or whether a secret store will
- * accept the call. Measured: `--key-out` at a directory, `--key-out` under a
- * parent that does not exist, and a command not on PATH all pass the pre-flight
- * and fail here. Exiting at that point destroys the only copy of a private key
- * for an App that already exists, over a typo.
- *
- * So a failure asks for a file path instead, while the key is still in memory —
- * a path only, never a command, for the reasons on `parseKeyRetryAnswer`.
- * `create` already requires a TTY, so there is someone there to answer. Only a
- * closed stdin (nobody left to answer) or the operator typing "give up" ends the
- * loop without a destination — a blank line re-prompts instead, since that is
- * exactly what a stray Enter pressed before this prompt existed leaves buffered.
- * See `parseKeyRetryAnswer` for the exact rules.
+ * The pre-flight can only refuse a MISSING destination — a bad path or a
+ * command not on PATH fails only here, and exiting on that would destroy the
+ * only copy of a private key for an App that already exists, over a typo. So
+ * a failure asks for a file path instead, while the key is still in memory —
+ * a path only, never a command, per `parseKeyRetryAnswer`'s rules. Only a
+ * closed stdin or "give up" ends the loop without a destination.
+ * @internal Exported for tests.
  */
 export declare function handOffWithRetry(pem: string, destination: KeyDestination): Promise<boolean>;
 export type InitGitHubAppOptions = {