@penvhq/cli 0.8.0 → 0.9.0

package/dist/index.d.cts

@@ -1,5 +1,53 @@
 import * as citty from 'citty';
-import { ProjectionProvider, Provider, ParameterRef, Scope, AnyProvider, RotationMechanism, RotationState } from '@penvhq/core';
+import { ProjectionProvider, Provider, PenvConfig, DotenvEntry, ParameterRef, Scope, DotenvDiagnostic, Resolution, AnyProvider, RotationMechanism, RotationState } from '@penvhq/core';
+import { z } from 'zod';
+
+/**
+ * `penv artifact build` — the sealed deployment artifact CI hands a release.
+ *
+ * It is the third step of the sequence PRD §7 names: pull the target
+ * environment, validate it, build the artifact, mount it. Each step is a command
+ * with one job, and this one's is narrow on purpose — it does not re-reach a
+ * verdict `penv validate` already reaches, because two implementations of "is
+ * this configuration good" would eventually let a release be built that CI had
+ * already rejected.
+ *
+ * Two properties are the whole design:
+ *
+ * **It never decrypts.** A sealed value is copied ciphertext-and-address into
+ * the artifact exactly as the record holds it, so building needs no key at all —
+ * CI can produce a production artifact without ever being able to read one. The
+ * AAD is still the value file's full name, so the ciphertext stays bound to the
+ * scope it was sealed at (invariant 17).
+ *
+ * **It refuses to guess the environment.** `--env` is named explicitly and never
+ * defaulted, `--out` likewise. An artifact built for "whatever the default was"
+ * is a release that ships the wrong environment's credentials, and the default
+ * that made it is one config edit nobody reviewed.
+ */
+interface ArtifactBuildOptions {
+    readonly cwd: string;
+    /** Named explicitly. There is no default, and none is invented. */
+    readonly environment?: string;
+    /** Named explicitly. Where the release will mount it from. */
+    readonly out?: string;
+}
+interface ArtifactBuildResult {
+    readonly file: string;
+    readonly environment: string;
+    readonly engineVersion: string;
+    readonly keySource: string;
+    /** Delivery mappings with a value. */
+    readonly values: number;
+    /** How many of those travelled as ciphertext. */
+    readonly sealed: number;
+    /** Declared mappings the environment has no non-local winner for. */
+    readonly absent: number;
+    /** True when the artifact was written inside the project — a `doctor` finding. */
+    readonly insideRepo: boolean;
+}
+declare function runArtifactBuild(options: ArtifactBuildOptions): Promise<ArtifactBuildResult>;
+declare function renderArtifactBuild(result: ArtifactBuildResult, cwd: string): string[];
 
 /**
  * A check reports one of four verdicts. `unknown` — a check that ran but could
@@ -9,7 +57,7 @@ import { ProjectionProvider, Provider, ParameterRef, Scope, AnyProvider, Rotatio
  * second kind.
  */
 type DoctorSeverity = "pass" | "warning" | "failure" | "unknown";
-type DoctorCheck = "schema" | "missing" | "declared" | "weak" | "unused" | "unscoped-fallback" | "plaintext-secret" | "public-secret" | "encryption" | "rotation-overdue" | "rotation-stuck" | "provider-value-drift" | "snapshot-stale" | "bundle-invisible-plaintext" | "provider" | "projection-unreachable" | "projection-name-drift" | "projection-manual-edit" | "projection-value-drift" | "environment-flag-shadow";
+type DoctorCheck = "schema" | "missing" | "declared" | "weak" | "unused" | "unscoped-fallback" | "plaintext-secret" | "public-secret" | "encryption" | "rotation-overdue" | "rotation-stuck" | "provider-value-drift" | "provider" | "projection-unreachable" | "projection-name-drift" | "projection-manual-edit" | "projection-value-drift" | "environment-flag-shadow" | "artifact-in-tree";
 interface DoctorFinding {
     readonly check: DoctorCheck;
     readonly severity: DoctorSeverity;
@@ -47,6 +95,28 @@ interface DoctorOptions {
 declare function runDoctor(options: DoctorOptions): Promise<DoctorReport>;
 declare function renderDoctor(report: DoctorReport): string[];
 
+/**
+ * Opening a penv project from a working directory, and the pieces every command
+ * needs once it is open: the config, the environment to act on, the provider
+ * rooted at the records tree, and the parameter a CLI key names.
+ */
+
+interface Project {
+    /** The directory holding `penv.config.ts`. */
+    readonly root: string;
+    readonly configFile: string;
+    readonly config: PenvConfig;
+    /** The parameter tree, absolute — `.penv/state/records/`. */
+    readonly recordsDir: string;
+    /**
+     * The project's provider, as the contract — never the concrete
+     * implementation. Shared commands speak the async interface and nothing more;
+     * the sync twins a command genuinely needs are reached through `localTree`,
+     * which is the one place the filesystem-only surface is named.
+     */
+    readonly provider: Provider;
+}
+
 interface ScopeOptions {
     /** The environment scope. Combined with `local`, the environment-scoped override. */
     readonly environment?: string;
@@ -59,7 +129,7 @@ interface SetOptions extends ScopeOptions {
 }
 interface SetResult {
     readonly parameter: string;
-    /** The value file written, relative to `.penv/`. */
+    /** The value file written, relative to the records tree. */
     readonly location: string;
     /** Whether meta's policy sealed it. Reported, so the marker is never a surprise. */
     readonly encrypted: boolean;
@@ -144,7 +214,7 @@ interface FillResult {
     /** The value files written, one per answered prompt. */
     readonly written: ReadonlyArray<{
         readonly parameter: string;
-        /** The value file written, relative to `.penv/`. */
+        /** The value file written, relative to the records tree. */
         readonly location: string;
         readonly encrypted: boolean;
     }>;
@@ -249,8 +319,136 @@ declare function runGet(options: GetOptions): Promise<string>;
  */
 declare function runExplain(options: GetOptions): Promise<GetExplanation>;
 
+/**
+ * What the codebase already says about itself.
+ *
+ * `penv init` asks a human to confirm a plan, and a plan the human has to fill
+ * in from scratch is an interrogation. So penv reads the two facts it can
+ * observe — the framework in `package.json`, and whether a `src/` directory
+ * exists — and offers them as a suggestion.
+ *
+ * The line this module does not cross: a framework is an identity, never a
+ * config key. Nothing here is written to `penv.config.ts` as `framework: "next"`
+ * — the answers become concrete decisions (`schemaFile`, `publicPrefixes`) that
+ * mean the same thing in a year, when the project has been rewritten twice and
+ * penv would otherwise still be reinterpreting a name it read once.
+ *
+ * Everything here is a suggestion. The one thing that is never suggested is an
+ * environment: deployment topology is not in `package.json`, and invariant 10
+ * forbids inferring it.
+ */
+/** A framework penv recognised, and what it implies about a project's layout. */
+interface Detected {
+    /** The framework's own name, as a human writes it — `"Next.js"`. */
+    readonly name: string;
+    /** Where this framework's projects keep their modules, relative to the root. */
+    readonly schemaFile: string;
+    /**
+     * The conventional path penv stepped aside from, because a module that is not
+     * penv's schema already lives there. Set only when it happened, so the plan can
+     * say why the schema is not where the convention would have put it.
+     */
+    readonly displacedFrom?: string;
+    /** The prefixes this framework inlines into its client bundle. */
+    readonly publicPrefixes: readonly string[];
+}
+
+/**
+ * The dotenv files a project's framework reads, and what each one says.
+ *
+ * One module answers this for both ends of adoption: `penv init` offers these
+ * files for the cutover, and `penv run` refuses the ones that come back
+ * afterwards. Two readings of "which files are active" would eventually let init
+ * move a file run does not watch, or run refuse a file init never offered.
+ *
+ * The four scopes are invariant 4's, which are Next.js's and Vite's:
+ * `.env` > `.env.local` > `.env.<environment>` > `.env.<environment>.local`.
+ * Anything else with an `.env` prefix is documentation (`.env.example`), a
+ * leftover (`.env.backup`), or a filename penv has no reading of — none of them
+ * is configuration a framework loads, so none is offered or refused.
+ *
+ * Reading an environment out of a filename here is not inference: nothing
+ * reaches `penv.config.ts` until a human selects the file, and
+ * {@link activeDotenvFiles} judges the segment against the declared whitelist
+ * (invariant 10) rather than believing it.
+ */
+
+/** Where a dotenv file sits in the cascade. */
+type DotenvKind = "shared" | "local" | "environment" | "environment-local";
+interface DotenvFile {
+    /** The filename exactly as it is on disk — what undo restores. */
+    readonly name: string;
+    readonly kind: DotenvKind;
+    /** The environment the filename names, for the two environment-scoped kinds. */
+    readonly environment?: string;
+    /** How the file is described in the selection table. */
+    readonly label: string;
+}
+
+/**
+ * The draft schema penv writes when it adopts a dotenv file.
+ *
+ * It is a draft and says so in the file it lands in: single-sample inference
+ * cannot know that a boolean seen as `true` must also accept `1`, or that a
+ * string is really a URL. penv scaffolds `penv.schema.ts` once and never
+ * regenerates it (invariant 2), so every correction the reader makes is safe.
+ *
+ * Requiredness across several files is the one judgement here, and it is
+ * deliberately coarse: a field observed in every adopted environment starts
+ * required, and a field missing from any of them starts optional. That is not
+ * per-environment requiredness — there is one schema, never one per environment
+ * (invariant 1) — it is the weakest shape that every adopted environment
+ * satisfies, which is what makes the first `penv run` after a cutover pass with
+ * no edits.
+ */
+
+/** One schema field, rendered into `penv.schema.ts` as `<key>: <type>,`. */
+interface SchemaField {
+    readonly key: string;
+    /** The Zod expression, e.g. `z.url()` — `.optional()` already applied when it belongs. */
+    readonly type: string;
+}
+/** A drafted field, plus the verdict a report prints. */
+interface DraftField extends SchemaField {
+    readonly required: boolean;
+}
+
+/**
+ * The one runtime dependency an adopted project takes, and how it gets there.
+ *
+ * PRD §3: an adopted project depends on exactly `@penvhq/penv` at the engine's
+ * own version — the typed `@env` surface, not a CLI distribution. `penv init`
+ * installs it with the package manager the project already uses, and only after
+ * showing the exact `package.json` and lockfile change: an install is the one
+ * step of adoption that reaches outside the repository, so it is the one step
+ * that is shown before it happens rather than reported after.
+ *
+ * The install itself is a seam. It shells out to a package manager, which the
+ * tests must never do — and a fake here is not a weaker test, because what init
+ * has to get right is the plan, the consent, and the refusal when the install
+ * does not happen.
+ */
+
+type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
+interface InstallPlan {
+    readonly root: string;
+    readonly manager: PackageManager;
+    readonly package: string;
+    readonly version: string;
+    /** The command, argv-shaped — what runs, and what a refusal tells the user to run. */
+    readonly command: readonly string[];
+    /** The lockfile the manager will rewrite, when the project has one. */
+    readonly lockfile?: string;
+    /** What `package.json` already says about the package, when it says anything. */
+    readonly declared?: string;
+    /** True when `package.json` already pins this exact version — nothing to install. */
+    readonly satisfied: boolean;
+}
+/** Runs an install plan, or throws. Replaced in tests; never spawns there. */
+type InstallRuntime = (plan: InstallPlan) => Promise<void>;
+
 /** What init touched, so a caller can report it and a test can assert it. */
-type InitTarget = "penv-dir" | "schema" | "env" | "config" | "snapshot" | "tsconfig" | "gitignore" | "seam";
+type InitTarget = "penv-dir" | "schema" | "env" | "config" | "tsconfig" | "gitignore" | "seam";
 /**
  * `conflicted` is the one that is not a success. penv wanted to write something,
  * found the user's file already saying something else about the same thing, and
@@ -279,6 +477,12 @@ interface InitStep {
 interface InitDecisions {
     /** The whitelist. Empty unless a human named them — penv never infers one. */
     readonly environments: readonly string[];
+    /**
+     * The environment every command falls back to when `--env` is absent (seal 3).
+     * Written only when the cutover adopted one — a declared decision, so the
+     * whitelist rule is untouched, and CI keeps naming `--env` anyway.
+     */
+    readonly defaultEnvironment?: string;
     /** The schema module, relative to the project root, POSIX. */
     readonly schemaFile: string;
     /** The prefixes the framework inlines into its client bundle. */
@@ -313,6 +517,15 @@ interface InitOptions {
     /** The detected framework name, passed by the command so the seam step need not re-detect it. */
     readonly framework?: string;
 }
+interface InitPlan {
+    readonly detected: Detected | undefined;
+    /** What init writes unless a human edits it. */
+    readonly decisions: InitDecisions;
+    /** Environments the `.env*` files on disk are evidence for. Offered, never taken. */
+    readonly suggestedEnvironments: readonly string[];
+    /** Why each decision is what it is. Printed — a fallback penv takes silently is a guess. */
+    readonly notes: readonly string[];
+}
 interface AliasEdit {
     readonly source: string;
     readonly changed: boolean;
@@ -338,6 +551,85 @@ interface AliasEdit {
  * `@env`, and this line is the only thing that has to know where that is.
  */
 declare function insertEnvAlias(source: string, target?: string, name?: string): AliasEdit;
+/** One adopted file: what it holds, and the scope its values are written at. */
+interface Adopted {
+    readonly file: DotenvFile;
+    readonly entries: readonly DotenvEntry[];
+    readonly refs: readonly ParameterRef[];
+    readonly scope: Scope;
+}
+interface AdoptionPlan {
+    readonly root: string;
+    /** Every dotenv file penv found, in the order the list shows them. */
+    readonly found: readonly DotenvFile[];
+    /** Checked when the list is first shown: the development cascade, where it exists. */
+    readonly preselected: readonly string[];
+}
+/** What there is to adopt, and what penv proposes taking. */
+declare function planAdoption(root: string): AdoptionPlan;
+interface CutoverPlan {
+    readonly root: string;
+    readonly selected: readonly DotenvFile[];
+    readonly adopted: readonly Adopted[];
+    /** The whitelist after this cutover — what the config declares, or is about to. */
+    readonly environments: readonly string[];
+    /**
+     * The environments this cutover is *about*: the ones its files name. Narrower
+     * than the whitelist on a project that already declared more, and the ones the
+     * draft is judged against and the import is validated for — an environment
+     * this cutover did not touch must not fail it for a state it was already in.
+     */
+    readonly adopting: readonly string[];
+    readonly decisions: InitDecisions;
+    readonly fields: readonly DraftField[];
+    readonly variables: number;
+    /** Values the parser read but that look like a mistake. Shown, never fixed. */
+    readonly diagnostics: readonly DotenvDiagnostic[];
+    readonly install: InstallPlan;
+    readonly framework: string | undefined;
+    /** True when `penv.config.ts` already existed, so init keeps every decision it records. */
+    readonly configured: boolean;
+}
+interface CutoverInput {
+    readonly root: string;
+    /** What init would scaffold anyway: detection, the schema's home, the alias. */
+    readonly base: InitPlan;
+    readonly selected: readonly DotenvFile[];
+    /** The environment named when the selection declares none — `.env` alone declares nothing. */
+    readonly environment?: string;
+    /** The `@penvhq/penv` version to pin. Defaults to this engine's own. */
+    readonly version?: string;
+    readonly inject?: boolean;
+}
+/**
+ * Everything a cutover needs, checked before anything is written.
+ *
+ * The order is the order the failures matter in: an unresolved bundle first
+ * (there is nothing to plan on top of it), then what the selection declares,
+ * then whether the selection is complete, then every variable name, and only
+ * then the schema and the install. Each one throws, so the caller has a plan or
+ * a refusal and never a half-answer.
+ */
+declare function planCutover(input: CutoverInput): CutoverPlan;
+interface CutoverResult {
+    readonly plan: CutoverPlan;
+    readonly steps: readonly InitStep[];
+    /** The dotenv files moved into the bundle, by name. */
+    readonly moved: readonly string[];
+    /** The environments whose imported values were validated before the move. */
+    readonly validated: readonly string[];
+}
+interface CutoverOptions {
+    /** Injected in tests: how the runtime dependency is installed. Never spawns there. */
+    readonly install?: InstallRuntime;
+}
+/**
+ * Installs, scaffolds, imports, validates — and only then moves the dotenv
+ * files aside. The order is the guarantee: every step before the move leaves a
+ * project whose `.env` files are exactly where they were, so a refusal at any
+ * of them costs a re-run and nothing else.
+ */
+declare function applyCutover(plan: CutoverPlan, options?: CutoverOptions): Promise<CutoverResult>;
 declare function runInit(options: InitOptions): InitResult;
 
 /**
@@ -433,7 +725,26 @@ interface ValidateOptions {
     /** Bare flags the command did not declare — environment shorthands, judged against the whitelist. */
     readonly envFlags?: readonly string[];
 }
+/**
+ * One environment, checked — and everything the check produced on the way.
+ *
+ * The verdict is `result` and it is the only verdict penv has. The rest is what
+ * `penv run` needs to build a child environment, handed back rather than
+ * recomputed: a second walk of the same tree could disagree with the one the
+ * verdict was reached on, and then `run` would start a process `validate`
+ * refuses.
+ */
+interface EnvironmentCheck {
+    readonly result: ValidateResult;
+    /** Absent when the schema module could not be evaluated — `result.issues` says why. */
+    readonly schema?: z.ZodType;
+    /** Every parameter the tree holds, resolved for this environment. */
+    readonly resolutions: readonly Resolution[];
+    /** The schema-validated object. Present only when the verdict passed. */
+    readonly validated?: unknown;
+}
 declare function runValidate(options: ValidateOptions): Promise<ValidateResult>;
+declare function checkEnvironment(project: Project, environment: string): Promise<EnvironmentCheck>;
 
 interface ImportOptions {
     readonly cwd: string;
@@ -518,7 +829,7 @@ interface ListEntry {
     readonly variable: string;
     /** `<env>.local`, `local`, an environment name, `default`, or `absent`. */
     readonly scope: string;
-    /** The winning value file relative to `.penv/`, or `undefined` when nothing wins. */
+    /** The winning value file relative to the records tree, or `undefined` when nothing wins. */
     readonly location: string | undefined;
     readonly encrypted: boolean;
     readonly viaUnscopedFallback: boolean;
@@ -529,6 +840,66 @@ interface ListResult {
 }
 declare function runList(options: ListOptions): Promise<ListResult>;
 
+/**
+ * `penv migrate` — move a project's records under `.penv/state/records/`.
+ *
+ * penv reads one layout, so this is the one command that knows two. It is a
+ * relocation and nothing else: records move byte for byte, keeping their names,
+ * so the grammar, the cascade, the meta and the AAD that binds a ciphertext to
+ * its address all mean afterwards exactly what they meant before.
+ * `penv.schema.ts`, `penv.config.ts` and `.penv/env.ts` are the project's, and
+ * are never touched.
+ *
+ * It previews before it moves, because the one thing a migration must not do is
+ * surprise the person who ran it — and it refuses a half-migrated tree rather
+ * than merging two, since which copy of a parameter is current is a question
+ * only the user can answer.
+ */
+/** One thing that moves, project-relative and POSIX. */
+interface MigrateMove {
+    readonly from: string;
+    readonly to: string;
+}
+interface MigratePlan {
+    readonly root: string;
+    /** What moves, in the order it is reported. */
+    readonly moves: readonly MigrateMove[];
+    /** What penv writes that is not there yet — the tree root and the safety boundary. */
+    readonly creates: readonly string[];
+    /** What penv removes: the ignore file that described the old layout. */
+    readonly removes: readonly string[];
+}
+/**
+ * `previewed` is a plan nobody approved, so nothing was written; `current` is a
+ * project that was already on the new layout, which is what a second run says.
+ */
+type MigrateStatus = "migrated" | "current" | "previewed";
+interface MigrateResult extends MigratePlan {
+    readonly status: MigrateStatus;
+}
+interface MigrateOptions {
+    readonly cwd: string;
+    /** Approve the plan. Without it `migrate` previews and writes nothing. */
+    readonly yes?: boolean;
+}
+/**
+ * What a migration would do, without doing any of it.
+ *
+ * The move list is `oldLayoutEntries` — the same list every command's refusal is
+ * keyed off — so the preview can never describe a different migration from the
+ * one that runs.
+ */
+declare function planMigrate(cwd: string): MigratePlan;
+/**
+ * Performs a plan. Separate from {@link planMigrate} so what runs is the plan the
+ * user approved, not a second reading of the disk between the question and the
+ * answer.
+ */
+declare function applyMigrate(plan: MigratePlan): MigrateResult;
+/** Plans, and applies only when the move was approved. */
+declare function runMigrate(options: MigrateOptions): MigrateResult;
+declare function renderMigrate(result: MigrateResult): string[];
+
 /**
  * `penv mv <from> <to>` — rename a parameter, every scope at once.
  *
@@ -664,7 +1035,7 @@ interface RemoveOptions extends ScopeOptions {
 }
 interface RemoveResult {
     readonly parameter: string;
-    /** The value files that existed and are now gone, relative to `.penv/`. */
+    /** The value files that existed and are now gone, relative to the records tree. */
     readonly removed: readonly string[];
     /** Both files penv looked at, whether or not they were there. */
     readonly considered: readonly string[];
@@ -710,44 +1081,90 @@ declare function runRotate(options: RotateOptions): Promise<RotateResult>;
 declare function renderRotate(result: RotateResult): string[];
 
 /**
- * The committed snapshot — `penv.snapshot.ts` at the project root — that lets
- * `load()` resolve in a bundled or serverless runtime where no `penv.config.ts`
- * or `.penv/` tree is on disk. It embeds the evaluated config and every committed
- * sealed value; the scaffolded `env.ts` imports it and passes it to `load`.
+ * Starting someone else's command, opaquely.
  *
- * Sealed records only, by decision: the snapshot ships exactly what a git clone
- * already sees — ciphertext, safe to commit — and never plaintext, at any scope,
- * nor either `.local` scope. Determinism is the point of the text output: value
- * keys are code-unit sorted, so `doctor snapshot-stale` is a plain text compare
- * against a recomputed snapshot.
+ * `penv run -- <command>` starts exactly what follows `--`: the argument
+ * boundaries the shell already worked out are handed to the operating system
+ * untouched, stdio is the parent's, and the child's exit code and terminating
+ * signal come back out. penv never parses the command, never rebuilds a command
+ * line from it, never wraps it in a shell — a shell would re-split what the user
+ * already split, and `penv run -- node -e "console.log(1 > 2)"` would redirect to
+ * a file called `2`.
  *
- * It sits beside `penv.config.ts` and `penv.schema.ts`, outside `.penv/`, so the
- * value-file grammar walker never sees it (no `StrayCodeFileError`) and it is
- * committed by default — the same placement rationale as the schema shape.
+ * Windows is the one place where "hand it to the operating system" needs help.
+ * `pnpm`, `next` and every other node-installed tool are `.cmd` shims there, and
+ * Node refuses to execute one without a shell. So a `.cmd`/`.bat` target — and
+ * only that — is started through `cmd.exe /d /s /c` with
+ * `windowsVerbatimArguments`, building the one command line cmd will accept and
+ * escaping every argument so that cmd hands the child the same bytes penv was
+ * given. Everything else spawns directly, on every platform.
  */
 
-interface SnapshotWriteResult {
-    readonly file: string;
-    readonly action: "created" | "updated" | "unchanged";
+/** How a child ended. Exactly one of these is meaningful, and both are forwarded. */
+interface ChildResult {
+    /** The child's own exit code, or 1 when a signal ended it. */
+    readonly exitCode: number;
+    /** The signal that ended the child, when one did. */
+    readonly signal: NodeJS.Signals | null;
 }
-/** What {@link wireEnvModule} did — `manual` carries the exact lines to add by hand. */
-interface WireResult {
-    readonly file: string;
-    readonly action: "wired" | "kept" | "manual";
-    /** The import line to add — printed on `manual`. */
-    readonly importLine: string;
-    /** How to add `snapshot` to the load options — printed on `manual`. */
-    readonly loadHint: string;
+interface ChildInvocation {
+    /** The command exactly as it followed `--`: the executable, then its arguments. */
+    readonly command: readonly string[];
+    readonly env: Record<string, string>;
+    readonly cwd: string;
 }
-
-interface SnapshotResult {
-    readonly write: SnapshotWriteResult;
-    readonly wire: WireResult;
+/** A started child: how it ends, and the one thing a wrapper may do to it. */
+interface ChildHandle {
+    /** Resolves when the child has ended, however it ended. */
+    readonly ended: Promise<ChildResult>;
+    /** Asks the child to stop — what `--watch` does before it starts the next one. */
+    kill(signal?: NodeJS.Signals): void;
 }
-declare function runSnapshot(options: {
+/** The seam `run` starts a child through — replaced in tests that assert what it was given. */
+type StartChild = (invocation: ChildInvocation) => ChildHandle;
+
+/** Where a run reads its values from. `snapshot` is the sealed artifact. */
+type RunSource = "project" | "snapshot";
+interface RunOptions {
     readonly cwd: string;
-}): SnapshotResult;
-declare function renderSnapshot(result: SnapshotResult): string[];
+    readonly environment?: string;
+    /** Bare flags the command did not declare — environment shorthands, judged against the whitelist. */
+    readonly envFlags?: readonly string[];
+    /** Defaults to `project`. */
+    readonly source?: string;
+    /** The one mode allowed to synchronise. Off by default. */
+    readonly watch?: boolean;
+    /** The command exactly as it followed `--`. */
+    readonly command: readonly string[];
+    /** The environment penv itself was started with. Defaults to `process.env`. */
+    readonly host?: Readonly<Record<string, string | undefined>>;
+    /** Injected in tests: how a child is started. */
+    readonly start?: StartChild;
+    /** Injected in tests: the sync `--watch` performs. */
+    readonly pull?: (options: PullOptions) => Promise<PullResult>;
+    /** Injected in tests: what tells `--watch` something changed. */
+    readonly changes?: (onChange: () => void) => {
+        close(): void;
+    };
+    /** How long a replaced child has to leave before `--watch` insists. Defaults to 5s. */
+    readonly stopGraceMs?: number;
+}
+interface RunResult {
+    readonly environment: string;
+    readonly source: RunSource;
+    readonly command: readonly string[];
+    /** Declared variables written into the child. */
+    readonly written: number;
+    /** Declared-but-valueless variables deleted from the child. */
+    readonly deleted: number;
+    /** penv's own variables removed before the child saw them. */
+    readonly stripped: readonly string[];
+    readonly exitCode: number;
+    readonly signal: NodeJS.Signals | null;
+    /** How many times `--watch` replaced the child. */
+    readonly restarts: number;
+}
+declare function runRun(options: RunOptions): Promise<RunResult>;
 
 interface WatchOptions {
     readonly cwd: string;
@@ -786,6 +1203,54 @@ declare function runWatch(options: WatchOptions): WatchHandle;
  */
 declare function renderWatch(result: ValidateResult): string[];
 
+interface Cutover {
+    readonly format: number;
+    /** When the files were moved, ISO-8601 UTC. */
+    readonly movedAt: string;
+    /** The filenames as they were at the project root — what undo restores, exactly. */
+    readonly files: readonly string[];
+    /** The environments the cutover declared, so a report can name them without the config. */
+    readonly environments: readonly string[];
+}
+interface UndoResult {
+    readonly root: string;
+    /** The files put back, in the order they were moved. */
+    readonly restored: readonly string[];
+    /** Recorded names already at the project root — what an interrupted undo had reached. */
+    readonly alreadyBack: readonly string[];
+    /** Recorded names in neither the bundle nor the project root. Nothing penv can restore. */
+    readonly missing: readonly string[];
+}
+/**
+ * Puts every bundled file back under its exact original name, then drops the
+ * bundle and the state that named it.
+ *
+ * Undo is resumable, because the thing it recovers from is an interruption. A
+ * name already at the project root and no longer in the bundle is a file an
+ * earlier run put back, not a collision — only a name that is in both places at
+ * once is, and that is the one case worth refusing over, since restoring would
+ * write over whatever came back. A name in neither place is reported rather than
+ * refused: the old refusal's remedy was `penv cleanup`, which would have deleted
+ * every file that was still recoverable.
+ */
+declare function runUndo(options: {
+    readonly cwd: string;
+}): UndoResult;
+interface CleanupResult {
+    readonly root: string;
+    /** The files the bundle held. Empty when there was nothing to clean up. */
+    readonly removed: readonly string[];
+    readonly cleaned: boolean;
+}
+/**
+ * Drops the rollback bundle and the cutover state, and nothing else. The records
+ * tree, the schema, the config and the loader are the project's — cleanup is the
+ * end of the migration, not the end of the adoption.
+ */
+declare function runCleanup(options: {
+    readonly cwd: string;
+}): CleanupResult;
+
 /**
  * penv's command line.
  *
@@ -797,4 +1262,4 @@ declare function renderWatch(result: ValidateResult): string[];
 declare const main: citty.CommandDef<citty.ArgsDef>;
 declare function runMain(): Promise<void>;
 
-export { type DoctorCheck, type DoctorFinding, type DoctorReport, type DoctorSeverity, type FillOptions, type FillPrompt, type FillResult, type GenerateResult, type GetExplanation, type ImportReport, type InitResult, type InitStep, LAST_PUSHED_KEY, type ListResult, type MoveResult, type PullOptions, type PullResult, type PushOptions, type PushResult, type RemoveResult, type ResealResult, type RotateOptions, type RotatePhase, type RotateResult, type SetResult, type SnapshotResult, type ValidateIssue, type ValidateResult, type WatchHandle, type WatchOptions, generateDotenv, importDotenv, insertEnvAlias, main, renderDoctor, renderFill, renderMove, renderPull, renderPush, renderRotate, renderSnapshot, renderWatch, runDecrypt, runDoctor, runEncrypt, runExplain, runFill, runGenerate, runGet, runInit, runList, runMain, runMove, runPull, runPush, runRemove, runRotate, runSet, runSnapshot, runValidate, runWatch };
+export { type AdoptionPlan, type ArtifactBuildOptions, type ArtifactBuildResult, type CleanupResult, type Cutover, type CutoverPlan, type CutoverResult, type DoctorCheck, type DoctorFinding, type DoctorReport, type DoctorSeverity, type EnvironmentCheck, type FillOptions, type FillPrompt, type FillResult, type GenerateResult, type GetExplanation, type ImportReport, type InitResult, type InitStep, LAST_PUSHED_KEY, type ListResult, type MigrateMove, type MigratePlan, type MigrateResult, type MigrateStatus, type MoveResult, type PullOptions, type PullResult, type PushOptions, type PushResult, type RemoveResult, type ResealResult, type RotateOptions, type RotatePhase, type RotateResult, type RunOptions, type RunResult, type RunSource, type SetResult, type UndoResult, type ValidateIssue, type ValidateResult, type WatchHandle, type WatchOptions, applyCutover, applyMigrate, checkEnvironment, generateDotenv, importDotenv, insertEnvAlias, main, planAdoption, planCutover, planMigrate, renderArtifactBuild, renderDoctor, renderFill, renderMigrate, renderMove, renderPull, renderPush, renderRotate, renderWatch, runArtifactBuild, runCleanup, runDecrypt, runDoctor, runEncrypt, runExplain, runFill, runGenerate, runGet, runInit, runList, runMain, runMigrate, runMove, runPull, runPush, runRemove, runRotate, runRun, runSet, runUndo, runValidate, runWatch };