@fabrika/installation-init 0.9.0-dev.1 → 0.9.0-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/installation-init",
-	"version": "0.9.0-dev.1",
+	"version": "0.9.0-dev.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -12,12 +12,13 @@
 	},
 	"files": [
 		"src",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		}
 	},
@@ -27,8 +28,8 @@
 	},
 	"dependencies": {
 		"zod": "^3.25.76",
-		"@fabrika/app": "0.9.0-dev.1",
-		"@fabrika/email": "0.9.0-dev.1",
-		"@fabrika/iam-contract": "0.9.0-dev.1"
+		"@fabrika/app": "0.9.0-dev.2",
+		"@fabrika/email": "0.9.0-dev.2",
+		"@fabrika/iam-contract": "0.9.0-dev.2"
 	}
 }

package/types/src/admin.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The first administrator of a fresh installation — the admin-RPC calls that admit them, as mechanics
+ * rather than a script.
+ *
+ * `platform install` ends with a provisioning key and nobody who can sign in. What it takes to fix
+ * that is provider-neutral: which procedures, in which order, and what makes a second run change
+ * nothing. WHERE an installation's IAM answers, and how an operator names it, is the provider's own
+ * question and stays in its installation package.
+ *
+ * A trap a live bring-up found is encoded here rather than left to each caller: **the grant is
+ * CROSS-APP (`app: null`).** Grants filter to the calling app, so an `admin` grant scoped to the
+ * console's own app id leaves Delivery and Operations working while the Access plane refuses. IAM's
+ * own app id is not a registered app, so naming it would dangle instead.
+ *
+ * The enrollment URL is a CREDENTIAL IN TRANSIT. It is RETURNED, never logged: nothing in this module
+ * prints, and `log.ts` deliberately has no helper that takes a secret value.
+ */
+import { type InferRpcClient, type RpcFetch } from '@fabrika/app';
+import type { IamAdminRpcContract } from '@fabrika/iam-contract';
+/** The built-in cross-app role. It is the one role that carries `iam.admin`, which the Access plane checks. */
+export declare const ADMIN_ROLE_KEY = "admin";
+/** The typed admin surface, exactly as the console reaches it — one contract, so the two cannot drift. */
+export type IamAdminClient = InferRpcClient<IamAdminRpcContract>;
+/**
+ * The slice of that surface this flow calls, and nothing wider.
+ *
+ * `IamAdminClient` satisfies it, so the real client is passed straight in; a caller testing the flow
+ * stands up five procedures instead of the whole administration API.
+ */
+export interface FirstAdministratorApi {
+    readonly principals: Pick<IamAdminClient['principals'], 'get' | 'invite' | 'list'>;
+    readonly grants: Pick<IamAdminClient['grants'], 'create'>;
+    readonly passwords: Pick<IamAdminClient['passwords'], 'issueEnrollment'>;
+}
+export interface IamAdminConnection {
+    /** IAM's PUBLIC origin — the address the proxy fronts, e.g. `https://iam.example.com`. */
+    readonly origin: string;
+    /** The installation's `px_` provisioning key, sent as `Authorization: Bearer`. */
+    readonly provisioningKey: string;
+    /** Override `fetch` (tests). Defaults to the global one. */
+    readonly fetch?: RpcFetch;
+}
+/**
+ * A client for `<origin>/admin/rpc` authenticated by the provisioning key.
+ *
+ * Bearer AND NOTHING ELSE, which is what makes it work at all: IAM's cross-origin guard exempts a
+ * request carrying only `Authorization`, and refuses a credential-less one whatever the admin-origin
+ * registry holds (`iam/src/admin/router.ts`).
+ */
+export declare const createIamAdminClient: ({ origin, provisioningKey, fetch: fetcher }: IamAdminConnection) => IamAdminClient;
+export interface FirstAdministratorRequest {
+    /** The mailbox that identifies the human. Any spelling; IAM stores the normalized form. */
+    readonly email: string;
+    /**
+     * Issue a second enrollment URL when one is already outstanding. Default false, so a re-run prints
+     * nothing new — but an enrollment that expired unopened would otherwise be unrecoverable, because
+     * the only other way to issue one is a console nobody can sign in to yet.
+     */
+    readonly reissueEnrollment?: boolean;
+}
+/** What happened to the password enrollment. Only `issued` carries a URL, and only once. */
+export type EnrollmentOutcome = {
+    readonly state: 'issued';
+    readonly url: string;
+    readonly expiresAt: number;
+} | {
+    readonly state: 'emailed';
+    readonly email: string;
+    readonly expiresAt: number;
+} | {
+    readonly state: 'outstanding';
+} | {
+    readonly state: 'already-set';
+};
+export interface FirstAdministratorResult {
+    readonly principalId: string;
+    /** The normalized mailbox, as IAM holds it. */
+    readonly email: string;
+    readonly principal: 'invited' | 'existing';
+    readonly grant: 'created' | 'present';
+    readonly enrollment: EnrollmentOutcome;
+}
+/**
+ * Admit the first administrator, idempotently.
+ *
+ * Four states are reused rather than rewritten: an existing principal for this mailbox, an existing
+ * cross-app `admin` grant, an outstanding enrollment, and a password that is already set. A re-run
+ * therefore invites nobody twice, grants nothing twice and issues no second URL — and a run that loses
+ * the invite race to a concurrent one converges on the principal that won.
+ */
+export declare const ensureFirstAdministrator: (client: FirstAdministratorApi, request: FirstAdministratorRequest) => Promise<FirstAdministratorResult>;

package/types/src/checkout.d.ts

@@ -0,0 +1,9 @@
+/** `--checkout=<dir>`: where `platform init` keeps the sidecar repository's local checkout. */
+export declare const CHECKOUT_FLAG = "--checkout";
+/**
+ * The sidecar checkout directory: `--checkout`, or `defaultName` in the working directory.
+ *
+ * Refused inside another repository, where it would sit as an untracked nested repository that a
+ * blanket `git add` records as a gitlink.
+ */
+export declare const sidecarCheckoutDir: (explicit: string | undefined, defaultName: string, cwd?: string) => string;

package/types/src/confirmations.d.ts

@@ -0,0 +1,21 @@
+/** The one question `install` and `init` ask. Injected so a flow can be exercised without a TTY. */
+export interface Confirmations {
+    confirm(question: string, defaultYes?: boolean): Promise<boolean>;
+}
+/**
+ * The one way a confirming command runs with nobody watching it.
+ *
+ * Every confirmation defaults to yes, so a pipe carrying blank lines would answer all of them with
+ * nobody reading what they agree to — which is why saying yes unattended is a FLAG and never an
+ * inference: it makes the choice explicit, and it puts it in the shell history of whoever ran it.
+ */
+export declare const UNATTENDED_FLAG = "--yes";
+/**
+ * How a command's confirmations are answered — and the refusal when nothing can answer them.
+ *
+ * Unattended, each question is still printed with the answer it was given, so the run leaves the same
+ * record of what was agreed to that an interactive one does.
+ */
+export declare const confirmations: (unattended: boolean, stdin: {
+    readonly isTTY?: boolean;
+}, announce: (line: string) => void, whatItDoes: string) => Confirmations;

package/types/src/email.d.ts

@@ -0,0 +1,15 @@
+import { type EmailProviderRegistry } from '@fabrika/email';
+import { type CommandEnv } from './options';
+export type InstallationEmail = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'provider';
+    readonly variables: ReadonlyMap<string, string>;
+    readonly secretNames: ReadonlySet<string>;
+};
+export declare const EMAIL_FLAGS: readonly ["--email-provider", "--email-from", "--email-from-name"];
+/** Throws naming flags and variables, never a value. */
+export declare function readInstallationEmail(argv: readonly string[], env: CommandEnv, options: {
+    readonly registry: EmailProviderRegistry;
+    readonly required: boolean;
+}): InstallationEmail;

package/types/src/environment.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Write the collected configuration into the base repo's GitHub **Environment** (not repo-level), so the
+ * platform pipeline reads it per-environment. Secret VALUES go to `gh secret set --env` over STDIN (gh does
+ * the libsodium encryption; the value never hits argv or a log line); non-secret values go to
+ * `gh variable set --env --body`. The environment itself is created (idempotent PUT) first, carrying the
+ * deployment-branch policy that is the only thing an Environment buys over a repository secret — a policy
+ * that restricts nothing until `main` itself carries a branch-protection rule.
+ */
+import { type GhAttempt, type ProtectionOutcome } from './protection';
+import { type ShellAttempt, type ShellStep } from './shell';
+export interface EnvironmentConfig {
+    repo: string;
+    environment: string;
+    /** Secret name → value (written via `gh secret set`). */
+    secrets: Record<string, string>;
+    /** Variable name → value (written via `gh variable set`). */
+    vars: Record<string, string>;
+    /**
+     * Told once whether only a protected branch may use this Environment's secrets, so a provider's
+     * closing summary can restate it. A callback rather than a return value: both providers already
+     * bind this function through a `Promise<void>` collaborator.
+     */
+    onProtection?(outcome: ProtectionOutcome): void;
+}
+/** The child processes `configureEnvironment` drives. Replaced wholesale in tests. */
+export interface EnvironmentEffects {
+    attempt: GhAttempt;
+    run(step: ShellStep): Promise<void>;
+}
+/** Create the GitHub Environment and populate its secrets + variables. */
+export declare function configureEnvironment(config: EnvironmentConfig, effects?: EnvironmentEffects): Promise<void>;
+/** One reviewer in a PUT body: GitHub's GET nests the id under `reviewer`, its PUT wants it flat. */
+interface EnvironmentReviewer {
+    readonly type: string;
+    readonly id: number;
+}
+/** The protection rules a PUT must carry forward, read off `gh api repos/…/environments/<name>`. */
+export interface ExistingEnvironmentProtection {
+    readonly reviewers?: readonly EnvironmentReviewer[];
+    readonly wait_timer?: number;
+}
+/**
+ * Translate a GET's `protection_rules` into the shape a PUT takes. Anything unrecognised is dropped:
+ * a body GitHub rejects would cost the deployment-branch policy, which is what this write is for.
+ */
+export declare function existingEnvironmentProtection(result: ShellAttempt): ExistingEnvironmentProtection;
+/** Trigger the platform workflow (the real deploy runs in GitHub Actions). */
+export declare function triggerPlatformWorkflow(repo: string): Promise<void>;
+export {};

package/types/src/gh.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `gh` CLI helpers. The CLI shells out to `gh` for everything GitHub-side (repo create, secrets, the
+ * deploy trigger) rather than re-implementing the REST API + libsodium secret encryption — `gh` already
+ * does the encryption for `secret set`. These are the small probes shared across scaffold + environment.
+ */
+/** Is the `gh` CLI available + authenticated? `gh auth status` exits non-zero when not logged in. */
+export declare function hasGhCli(): Promise<boolean>;
+/** Does `<org>/<repo>` exist and is it visible to the current `gh` login? */
+export declare function ghRepoExists(repo: string): Promise<boolean>;

package/types/src/index.d.ts

@@ -0,0 +1,12 @@
+export { ADMIN_ROLE_KEY, createIamAdminClient, type EnrollmentOutcome, ensureFirstAdministrator, type FirstAdministratorApi, type FirstAdministratorRequest, type FirstAdministratorResult, type IamAdminClient, type IamAdminConnection, } from './admin';
+export { CHECKOUT_FLAG, sidecarCheckoutDir } from './checkout';
+export { type Confirmations, confirmations, UNATTENDED_FLAG } from './confirmations';
+export { EMAIL_FLAGS, type InstallationEmail, readInstallationEmail } from './email';
+export { configureEnvironment, type EnvironmentConfig, type EnvironmentEffects, type ExistingEnvironmentProtection, existingEnvironmentProtection, triggerPlatformWorkflow, } from './environment';
+export { ghRepoExists, hasGhCli } from './gh';
+export { action, detail, fail, info, ok, step, url, warn } from './log';
+export { type CommandEnv, describeArgument, readEnv, readFlag, requiredSetting, setting, shellWord } from './options';
+export { confirm } from './prompt';
+export { branchProtectionCommand, DEPLOYMENT_BRANCH_POLICY, environmentPolicyCommand, environmentReviewerCommand, type GhAttempt, isPlanLimited, PLAN_LIMITED, probeSidecarBranchProtection, type ProtectionOutcome, protectSidecarBranch, } from './protection';
+export { INITIAL_SCAFFOLD_COMMIT_MESSAGE, REFRESH_SCAFFOLD_COMMIT_MESSAGE, scaffoldSidecarRepository, type SidecarScaffoldEffects, type SidecarScaffoldInput, type SidecarScaffoldResult, } from './scaffold';
+export { attempt, capture, probe, run, type ShellAttempt, type ShellStep } from './shell';

package/types/src/log.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Console formatting for the fabrika CLI — a thin, consistent presentation layer over the orchestration
+ * in the other modules. Every line the operator sees during `init` flows through here.
+ *
+ * HARD RULE (see the worker CLAUDE.md): this module NEVER prints a secret VALUE. Callers may pass
+ * secret NAMES, counts, or "✓ set" confirmations — never the bytes of a token / key / PEM / webhook
+ * secret. There is deliberately no helper here that takes a secret value, so a careless caller can't
+ * accidentally route one through formatting.
+ */
+/** A numbered, bold section heading — the spine of the CLI's progress. Resets nothing else. */
+export declare function step(title: string): void;
+/** A plain informational line, slightly indented under the current step. */
+export declare function info(message: string): void;
+/** A dim, secondary detail line (context the operator usually skims). */
+export declare function detail(message: string): void;
+/** A success line (green ✓). */
+export declare function ok(message: string): void;
+/** A non-fatal warning (yellow ⚠) — the CLI keeps going. */
+export declare function warn(message: string): void;
+/** A failure line (red ✗). Does NOT exit — the caller decides whether to throw. */
+export declare function fail(message: string): void;
+/**
+ * A boxed OPERATOR ACTION — something the human must do out-of-band (open a URL, log in, click
+ * "create", paste a value back). These are the hand-off points the whole bring-up is built around, so
+ * they are visually loud and never scroll past unnoticed.
+ */
+export declare function action(title: string, lines: string[]): void;
+/** Render a URL prominently (cyan, underlined) — operators copy these by eye. */
+export declare function url(value: string): string;

package/types/src/options.d.ts

@@ -0,0 +1,9 @@
+export type CommandEnv = Record<string, string | undefined>;
+export declare const readFlag: (argv: readonly string[], name: string) => string | undefined;
+export declare const readEnv: (env: CommandEnv, name: string) => string | undefined;
+export declare const setting: (argv: readonly string[], env: CommandEnv, flag: string, variable: string) => string | undefined;
+export declare const requiredSetting: (value: string | undefined, flag: string, variable: string) => string;
+/** How a refusal names an argument: a flag by its name only, never its value, which may be a pasted credential. */
+export declare const describeArgument: (arg: string) => string;
+/** One argument as a POSIX shell reads it back unchanged, for the rerun command a declined step prints. */
+export declare const shellWord: (arg: string) => string;

package/types/src/prompt.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The one interactive question the fabrika CLI asks: a yes/no confirmation before a step that leaves
+ * the operator's machine. Every other input is a flag or an environment variable, and a run with no
+ * terminal answers confirmations with `--yes` (`confirmations.ts`), so this reads a TTY only.
+ *
+ * A fresh interface per question, closed afterwards: a persistent one holds the terminal in raw mode
+ * (`-icanon -echo`, measured) between questions, and init spawns `git` and `gh` between them — a child
+ * inheriting a raw terminal echoes nothing and stair-steps its output.
+ */
+/** A yes/no confirmation. Defaults to `defaultYes` on an empty answer. */
+export declare function confirm(question: string, defaultYes?: boolean): Promise<boolean>;

package/types/src/protection.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Harden the sidecar repository the operator owns. It holds the installation's entire credential set,
+ * so a push to `main` must not be able to rewrite the pipeline that reads them. ADR-0025 leaves the
+ * repository operator-owned; this only stops it from being weaker than the account it controls.
+ *
+ * GitHub Free offers neither rule on a PRIVATE repository, so a refusal is REPORTED, never fatal: the
+ * operator is told what is unprotected and the exact command that applies it later. Every body travels
+ * over stdin (`gh api --input -`), never on argv.
+ *
+ * An Environment's `protected_branches` policy is only as strong as the branch rule it points at: with no
+ * protection rule on `main`, the policy admits `main` and restricts nothing. The two are reported together
+ * for that reason.
+ */
+import { type ShellAttempt, type ShellStep } from './shell';
+/** No force pushes, no deletions, admins included. No required review: `platform upgrade` pushes to `main`. */
+export declare const BRANCH_PROTECTION_BODY: string;
+/** Only a protected branch may use the Environment's secrets — and only where such a rule exists. */
+export declare const DEPLOYMENT_BRANCH_POLICY: {
+    readonly protected_branches: true;
+    readonly custom_branch_policies: false;
+};
+/** The same policy as a standalone PUT body, for the command an operator runs by hand. */
+export declare const DEPLOYMENT_BRANCH_POLICY_BODY: string;
+/** Whether one hardening rule is in place, plus the command that applies it when it is not. */
+export interface ProtectionOutcome {
+    readonly applied: boolean;
+    /** One short, printable line saying why it is not applied. Absent when it is. */
+    readonly reason?: string;
+    /** The `gh api` invocation that applies this rule later. */
+    readonly command: string;
+}
+/** Run a `gh` step whose failure is an ANSWER rather than an error. The seam tests drive. */
+export type GhAttempt = (step: ShellStep) => Promise<ShellAttempt>;
+export declare const branchProtectionCommand: (repo: string) => string;
+export declare const environmentPolicyCommand: (repo: string, environment: string) => string;
+/** Recommended, never applied by us: an approval click per deploy is the operator's call. */
+export declare const environmentReviewerCommand: (repo: string, environment: string) => string;
+/** The HTTP status `gh` names in its error line (`gh: … (HTTP 403)`), when it names one. */
+export declare const ghHttpStatus: (result: ShellAttempt) => number | undefined;
+/**
+ * The three statuses GitHub answers when a plan does not offer a protection rule. A 422 can also mean a
+ * malformed request, so this is a heuristic — it decides only whether we DEGRADE or give up, never
+ * whether something is safe.
+ */
+export declare const PLAN_LIMITED: ReadonlySet<number>;
+/** True when GitHub's answer is one this code is willing to continue without the rule on. */
+export declare const isPlanLimited: (result: ShellAttempt) => boolean;
+/** One printable line for a refusal — the plan limit when GitHub named one, the exit code otherwise. */
+export declare const unavailableReason: (result: ShellAttempt) => string;
+/** Protect `main` on the sidecar. Reports what is unprotected and never throws. */
+export declare function protectSidecarBranch(repo: string, gh?: GhAttempt): Promise<ProtectionOutcome>;
+/**
+ * Read-only: does `main` already carry a protection rule? For a repository this run did NOT create — a
+ * PUT there would replace whatever the operator configured, so the existing rules are reported, never
+ * overwritten. A 404 is GitHub's answer for "no protection rule", which is exactly what we warn about.
+ */
+export declare function probeSidecarBranchProtection(repo: string, gh?: GhAttempt): Promise<ProtectionOutcome>;

package/types/src/scaffold.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The mechanics of a sidecar repository: ensure `<owner>/<name>` exists on GitHub, materialize the
+ * files the CLI owns, commit and push. Idempotent, and the same on every provider:
+ *   - repo absent  → create a fresh local checkout, commit the scaffold, `gh repo create … --source --push`,
+ *   - repo present → clone it (if not already local), refresh the CLI-owned files, commit + push on drift.
+ *
+ * WHAT the files are is the provider's answer, not this module's — `materialize` writes them and `files`
+ * lists everything the scaffold ever stages. Scaffold commits carry `[skip ci]`, so a push here cannot
+ * deploy anything before `init` has written the GitHub Environment the pipeline reads.
+ *
+ * A freshly created repository is protected before anything else is written to it. An EXISTING one is
+ * only PROBED, never PUT to: its protection is whatever its operator chose, and a blind PUT would replace
+ * stricter rules with ours. Either way the outcome is reported, so an unprotected sidecar is never silent.
+ */
+import { type ProtectionOutcome } from './protection';
+import { type ShellStep } from './shell';
+export declare const INITIAL_SCAFFOLD_COMMIT_MESSAGE = "chore: initial fabrika platform scaffold [skip ci]";
+export declare const REFRESH_SCAFFOLD_COMMIT_MESSAGE = "chore: refresh fabrika platform scaffold [skip ci]";
+export interface SidecarScaffoldInput {
+    /** The sidecar repository, e.g. `contember/fabrika-zerops-test`. */
+    readonly repo: string;
+    /** Local directory to check the repository out into. */
+    readonly dir: string;
+    /** Every path the scaffold stages — CLI-owned files plus any operator-owned, write-once pin. */
+    readonly files: readonly string[];
+    /** Write the scaffold into an existing directory. Called for a fresh creation and for a refresh alike. */
+    materialize(dir: string): Promise<void>;
+}
+/** Result of scaffolding: the local checkout dir + whether the repository was freshly created. */
+export interface SidecarScaffoldResult {
+    readonly dir: string;
+    readonly created: boolean;
+    /** Applied for a repository this run created, probed read-only for one that already existed. */
+    readonly branchProtection?: ProtectionOutcome;
+}
+/** The child processes and GitHub calls the scaffold drives. Replaced wholesale in tests. */
+export interface SidecarScaffoldEffects {
+    hasGhCli(): Promise<boolean>;
+    repositoryExists(repo: string): Promise<boolean>;
+    run(step: ShellStep): Promise<void>;
+    probe(step: ShellStep): Promise<number>;
+    protect(repo: string): Promise<ProtectionOutcome>;
+    probeProtection(repo: string): Promise<ProtectionOutcome>;
+}
+/**
+ * Ensure the sidecar repository exists and carries the current scaffold. Returns the local checkout.
+ * Requires `gh` authenticated with rights to create/administer the repository.
+ */
+export declare function scaffoldSidecarRepository(input: SidecarScaffoldInput, effects?: SidecarScaffoldEffects): Promise<SidecarScaffoldResult>;

package/types/src/shell.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shell-out helpers for the CLI, over `Bun.spawn`. Every orchestrated step (git, gh, the deploy
+ * trigger) goes through here so the rules are enforced in ONE place:
+ *   - argv is passed verbatim (no shell) — nothing interpolated can be a metacharacter,
+ *   - the child gets ONLY `process.env` + the explicit `env` the step needs,
+ *   - on a non-zero exit we throw a SHORT message naming the command — never the child env, never a
+ *     secret value, never the raw error object (which could carry a token-bearing URL).
+ */
+/** A child step to run: the command + args, its cwd, and the extra env it needs (merged over process.env). */
+export interface ShellStep {
+    command: string;
+    args: string[];
+    cwd: string;
+    /** Extra env vars for this child only. Secret VALUES live here and nowhere else. */
+    env?: Record<string, string>;
+    /** Optional stdin written to the child (used for `gh secret set`, which reads the value from stdin). */
+    stdin?: string;
+}
+/**
+ * What a streaming child gets on stdin.
+ *
+ * A TTY child may INHERIT it — `git` and `gh` prompt on their own, and a terminal is shared by turns.
+ * Without a terminal nobody can answer a child's question, so it gets none and fails instead of waiting.
+ */
+export declare const childStdin: (step: ShellStep, isTty?: boolean) => Uint8Array | "inherit" | "ignore";
+/**
+ * Run a step, STREAMING its stdout/stderr to this terminal so the operator watches the underlying
+ * tool live (git/gh print progress). Throws on a non-zero exit. The thrown message names the command
+ * + exit code only.
+ */
+export declare function run(step: ShellStep): Promise<void>;
+/**
+ * Run a step and CAPTURE its stdout (returned), while streaming stderr to this terminal. Used when we
+ * need to parse a tool's output (e.g. `gh repo view`). Throws on a non-zero exit; the captured stdout
+ * is NOT echoed by this helper.
+ */
+export declare function capture(step: ShellStep): Promise<string>;
+/** Run a step quietly: no stdout/stderr to the terminal, returns the exit code. For existence probes. */
+export declare function probe(step: ShellStep): Promise<number>;
+/** What a step that is allowed to fail reported: its exit code plus everything it wrote. */
+export interface ShellAttempt {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/**
+ * Run a step WITHOUT throwing, capturing both pipes. For a call whose failure is an ANSWER rather than
+ * an error — a `gh api` PUT that GitHub refuses because the plan does not offer the feature.
+ */
+export declare function attempt(step: ShellStep): Promise<ShellAttempt>;