@penvhq/cli 0.16.1 → 1.0.0-alpha.2

package/dist/index.d.cts

@@ -1,1240 +0,0 @@
-import * as citty from 'citty';
-import { ProjectionProvider, Provider, PenvConfig, DotenvEntry, ParameterRef, Scope, DotenvDiagnostic, Resolution, AnyProvider, RotationMechanism, RotationState } from '@penvhq/core';
-import { InstallPlan, InstallRuntime } from './install.cjs';
-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
- * not reach a verdict — is never rendered as a pass: "I looked and found nothing
- * wrong" and "I could not look" are opposite situations with opposite remedies,
- * and a value-withholding destination makes most of what doctor can say the
- * second kind.
- */
-type DoctorSeverity = "pass" | "warning" | "failure" | "unknown";
-type DoctorCheck = "schema" | "missing" | "declared" | "weak" | "unused" | "unscoped-fallback" | "secrecy-undeclared" | "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" | "local-extension" | "artifact-in-tree";
-interface DoctorFinding {
-    readonly check: DoctorCheck;
-    readonly severity: DoctorSeverity;
-    readonly label: string;
-    readonly subject?: string;
-    readonly detail?: string;
-    /** A line the reader can act on — the `penv set` to paste, where there is one. */
-    readonly remedy?: string;
-}
-interface DoctorReport {
-    readonly environment: string;
-    readonly findings: readonly DoctorFinding[];
-    /** False when any finding is a failure. Warnings and unknowns do not fail the run. */
-    readonly ok: boolean;
-}
-interface DoctorOptions {
-    readonly cwd: string;
-    readonly environment?: string;
-    /** Bare flags the command did not declare — environment shorthands, judged against the whitelist. */
-    readonly envFlags?: readonly string[];
-    /** Injected in tests: the projection-holding destination to check against. Defaults to the one the config declares. */
-    readonly projection?: ProjectionProvider;
-    /**
-     * Injected in tests: the source-of-truth provider to compare the local tree
-     * against. Defaults to the one the config declares (`sourceProviderFor`).
-     * Mirrors `projection`, for the same reason — the drift checks stay driveable
-     * without a live backend.
-     */
-    readonly source?: Provider;
-    /** Injected in tests: the wall-clock reading the rotation clocks are read against. Defaults to now. */
-    readonly now?: string;
-    /** Injected in tests: how long a `dual-valid` window may stay open before it reads as stuck. Defaults to 24h. */
-    readonly stuckThresholdMs?: number;
-}
-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;
-    readonly local?: boolean;
-}
-interface SetOptions extends ScopeOptions {
-    readonly cwd: string;
-    readonly key: string;
-    readonly value: string;
-}
-interface SetResult {
-    readonly parameter: string;
-    /** 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;
-}
-/**
- * Writes one value file, sealing it when meta says the parameter is a secret.
- *
- * The scope is chosen from the flags, then the seal-and-twin write is the shared
- * {@link sealAwareWrite}, against the local tree — the store `set` always edits.
- */
-declare function runSet(options: SetOptions): Promise<SetResult>;
-
-interface ResealOptions extends ScopeOptions {
-    readonly cwd: string;
-    readonly key: string;
-}
-interface ResealResult {
-    readonly parameter: string;
-    /** The file that now holds the value. */
-    readonly location: string;
-    /** The file that no longer exists, because its twin replaced it. */
-    readonly removed: string;
-}
-declare function runEncrypt(options: ResealOptions): Promise<ResealResult>;
-declare function runDecrypt(options: ResealOptions): Promise<ResealResult>;
-
-/**
- * `penv fill` — walk the schema's required-but-missing parameters and ask for
- * each one, deriving the value file's name so the user never has to.
- *
- * The schema-first flow writes `.penv/env.ts` before any value exists, and there
- * the user hits a translation they should not have to make: `databaseUrl` in the
- * schema is `database-url` on disk, and typing the wrong one writes a file the
- * schema still cannot see. `fill` reads the same declared drift `validate`
- * computes, and for each missing parameter asks for a value and writes it through
- * the one writer — `runSet` — deriving the kebab filename from the schema key.
- *
- * A value is never invented: a blank answer skips the parameter, because the
- * silent value reaching runtime is the failure penv exists to delete, and a
- * placeholder written here is exactly that value by a friendlier route.
- *
- * Optional parameters — `.optional()`, `.default()` — are asked too, after the
- * required gaps, tagged so the reader knows an answer is an override and Enter
- * keeps what the schema declared. Skipping them silently was the old behavior,
- * and it hid a real choice: a schema default reaching runtime is legal, but the
- * user who never heard the question never chose it.
- */
-/** One question `fill` puts to the user: which parameter, in which environment. */
-interface FillPrompt {
-    /** The value file's key, kebab and slash-separated — the name the user need never derive. */
-    readonly parameter: string;
-    readonly environment: string;
-    /**
-     * Whether meta says this is a secret. Carried so a wrapper can mute the echo;
-     * v1 does not, and the drift carries no meta, so this is `false` today.
-     */
-    readonly secret: boolean;
-    /**
-     * Whether the schema excuses absence — `.optional()`, `.default()`. An answer
-     * writes an override; a blank one leaves the schema's own behavior in place,
-     * which is a kept default rather than a lingering gap.
-     */
-    readonly optional: boolean;
-    /** What the schema falls back to, rendered for display, when it declares one penv can read. */
-    readonly defaultValue?: string;
-    readonly description?: string;
-}
-interface FillOptions {
-    readonly cwd: string;
-    readonly environment?: string;
-    /** Bare flags the command did not declare — environment shorthands, judged against the whitelist. */
-    readonly envFlags?: readonly string[];
-    /**
-     * How a value is obtained for one prompt. `undefined` or an empty answer skips
-     * the parameter — the readline half lives only in the wrapper, so `runFill`
-     * stays pure and unit-testable.
-     */
-    readonly ask: (prompt: FillPrompt) => Promise<string | undefined>;
-}
-interface FillResult {
-    readonly environment: string;
-    /** The value files written, one per answered prompt. */
-    readonly written: ReadonlyArray<{
-        readonly parameter: string;
-        /** The value file written, relative to the records tree. */
-        readonly location: string;
-        readonly encrypted: boolean;
-    }>;
-    /** The parameters a blank answer left for later — never written as an empty value. */
-    readonly skipped: readonly string[];
-    /**
-     * The optional parameters a blank answer left to the schema. Not `skipped`:
-     * a skipped parameter is still a gap, and one of these is a decision — the
-     * schema's default (or declared absence) is the value, on purpose.
-     */
-    readonly kept: readonly string[];
-    /**
-     * The declared keys no filename reaches (`apiURL`, a reserved token). `fill`
-     * cannot ask for a value it could never write, so it carries the rename remedy
-     * out rather than prompting for a file that would error.
-     */
-    readonly unreachable: ReadonlyArray<{
-        readonly subject: string;
-        readonly remedy: string;
-    }>;
-}
-/**
- * Asks for every declared-but-missing parameter, and writes the ones answered.
- *
- * The drift is `validate`'s, not a second reading of the schema: `runValidate`
- * already computes exactly the required-but-absent set, so `fill` and `validate`
- * can never disagree about what is missing. The writing is `runSet`'s, so a
- * filled secret is sealed exactly as a `set` one is — `fill` owns neither the
- * resolution nor the write, only the prompting between them.
- */
-declare function runFill(options: FillOptions): Promise<FillResult>;
-declare function renderFill(result: FillResult): string[];
-
-interface GenerateOptions {
-    readonly cwd: string;
-    readonly environment?: string;
-    /** Bare flags the command did not declare — environment shorthands, judged against the whitelist. */
-    readonly envFlags?: readonly string[];
-    /** Where to write, absolute or relative to `cwd`. Defaults to `.env` at the project root. */
-    readonly out?: string;
-    /** Permits sealed values to be written into the artifact as plaintext. */
-    readonly allowDecrypt?: boolean;
-}
-interface GenerateResult {
-    readonly file: string;
-    readonly environment: string;
-    readonly entries: number;
-    /** How many of them were sealed and are now plaintext in the artifact. */
-    readonly decrypted: number;
-}
-/** The `.env` text for one environment — what `penv generate` writes. */
-declare function generateDotenv(options: Omit<GenerateOptions, "out">): string;
-declare function runGenerate(options: GenerateOptions): GenerateResult;
-
-/**
- * `penv get <key>` — read a parameter, or explain which file wins and why.
- *
- * Fallback is never silent, and neither is precedence: `--explain` prints every
- * candidate in the order the cascade considered them, so a value quietly coming
- * from a shared default has nowhere to hide.
- */
-interface GetOptions {
-    readonly cwd: string;
-    readonly key: string;
-    readonly environment?: string;
-}
-interface GetExplanation {
-    readonly parameter: string;
-    readonly environment: string;
-    /** `undefined` when no candidate was present. */
-    readonly location: string | undefined;
-    /**
-     * Why the winning file did not open, when it is `.enc` and did not.
-     *
-     * A winner that cannot be decrypted is not a skipped candidate — it won, and
-     * the cascade is over. Reporting it as a skip would say a lower scope should
-     * have been reached, which is the scope-widening answer the cascade refuses.
-     */
-    readonly undecryptable?: string;
-    readonly candidates: readonly GetCandidate[];
-}
-interface GetCandidate {
-    readonly location: string;
-    readonly present: boolean;
-    readonly wins: boolean;
-    /** Why a present candidate did not win, or why it was never considered. */
-    readonly skipped: string | undefined;
-}
-/**
- * The value, or a named error.
- *
- * `requireValue` answers first, so a winner that exists but did not decrypt is
- * reported as undecryptable rather than as absent. Only a genuine absence — no
- * candidate at any scope — reaches the refusal below, which is what keeps `penv
- * set` from being offered as the fix for a secret the user still has.
- */
-declare function runGet(options: GetOptions): Promise<string>;
-/**
- * Which file wins, and why — never a value, so this must not be stopped by the
- * winner being unreadable. Core describes an `.enc` winner rather than refusing
- * it, so `--explain` is the same walk every other command does.
- */
-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;
-}
-
-/** What init touched, so a caller can report it and a test can assert it. */
-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
- * left it alone — so the step is reported with a warning rather than a ✓, and the
- * text says what will not work until the user decides.
- *
- * `info` is a step penv did not perform automatically — a manual instruction (the
- * injection seam for a framework penv cannot scaffold), reported so the user
- * knows the one thing left to do.
- */
-type InitAction = "created" | "kept" | "updated" | "conflicted" | "info";
-interface InitStep {
-    readonly target: InitTarget;
-    readonly action: InitAction;
-    /** The reported line, in the docs' voice. */
-    readonly text: string;
-    readonly note?: string;
-}
-/**
- * The answers init writes down. Every one of these is a decision a human either
- * made or consented to — never an identity penv recorded to reinterpret later.
- * There is deliberately no `framework` here: `schemaFile` and `publicPrefixes`
- * still mean exactly what they say after the project is rewritten in something
- * else, and `framework: "next"` would not.
- */
-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. */
-    readonly publicPrefixes: readonly string[];
-    /**
-     * How the user's code names the schema module — `@env` or `#env`.
-     *
-     * Two forms, resolved by two different things: `@env` is a tsconfig `paths`
-     * entry that a bundler resolves and plain Node does not, and `#env` is a
-     * package.json `imports` entry that Node resolves itself. Which one a project
-     * wants is a fact about the project, so penv reads what it already does and
-     * offers that.
-     */
-    readonly alias: string;
-    /**
-     * Whether to inject the validated config into `process.env` for libraries that
-     * read it directly, so `env.ts` loads with `{ inject: true }` and penv places
-     * the framework's pre-app seam. Off by default and only ever turned on by an
-     * explicit yes — a project that reads config only through `@env` gets none.
-     */
-    readonly inject: boolean;
-}
-interface InitResult {
-    readonly root: string;
-    readonly decisions: InitDecisions;
-    readonly steps: readonly InitStep[];
-}
-interface InitOptions {
-    readonly cwd: string;
-    /** What to write. Omitted means the plan's defaults, as `--yes` takes them. */
-    readonly decisions?: InitDecisions;
-    /** 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;
-    /**
-     * What the alias already points at, when that is not penv's schema.
-     *
-     * The alias is how the user's code reaches penv, so an alias that resolves
-     * somewhere else is not a small problem: `import { env } from "@env"` compiles,
-     * runs, and hands back another module's export. Reporting "kept the alias"
-     * because the *key* was present is how penv would say that was fine — a silent
-     * seam, in the scaffolder of the tool whose subject is silent seams.
-     *
-     * Left as the user's, never rewritten: penv cannot tell a stale mapping from a
-     * deliberate one, and the file is theirs.
-     */
-    readonly conflict?: string;
-}
-/**
- * `tsconfig.json` with the `@env` alias present, everything else untouched.
- * Already-aliased input comes back unchanged rather than gaining a duplicate.
- *
- * The alias is why the schema can live anywhere: application code imports
- * `@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.
- *
- * The scaffold is snapshotted first, and rolled back when anything after it
- * refuses. Without that, "a refusal costs a re-run" was only true of the dotenv
- * files: a failed run still left a config, a draft schema, an edited tsconfig
- * and an imported records tree behind, and the next run kept every one of them
- * rather than starting clean. The install is not rolled back — it is the one
- * step the developer consented to by itself, and a re-run finds it satisfied.
- */
-declare function applyCutover(plan: CutoverPlan, options?: CutoverOptions): Promise<CutoverResult>;
-declare function runInit(options: InitOptions): InitResult;
-
-/**
- * Reading the user's schema, and the distance between it and the parameter tree.
- *
- * The schema declares what must exist and the tree holds what does. The gap
- * between them is the signal `penv validate` exists to raise; this module makes
- * it legible without closing it. Nothing here writes or deletes a value file —
- * a declaration has no value, so materialising one could only invent it, and an
- * invented value is the silent-value-reaching-runtime failure penv exists to
- * delete. `penv set` stays the only writer.
- *
- * The introspection below lives here, not in `doctor`, because `doctor` and
- * `watch` both report drift and two readers of the same schema would be two
- * answers to one question.
- *
- * Every helper answers "I cannot tell" rather than guessing. A report is only
- * worth reading if every line in it is true, so a field this module cannot
- * understand produces no line at all.
- */
-
-/** A parameter the schema declares that the tree has no value for. */
-interface DeclaredDrift {
-    /** The parameter id, or the dotted schema path when no filename could reach it. */
-    readonly subject: string;
-    /** Absent when no filename reaches this key, which is drift `penv set` cannot close. */
-    readonly ref?: ParameterRef;
-    /** The line to paste: the `penv set` that closes this, or the rename that must precede it. */
-    readonly remedy: string;
-    readonly detail: string;
-}
-/** A parameter the tree holds a value for that the schema does not declare. */
-interface UndeclaredDrift {
-    readonly ref: ParameterRef;
-    /** The generated variable, which is the name the application would have read. */
-    readonly variable: string;
-}
-/**
- * A parameter the schema declares but does not require — `.optional()`,
- * `.default()`, and their kin — that the tree has no value for. Not drift in the
- * verdict sense: absence here is a state the schema itself blessed, so `doctor`
- * and `watch` say nothing about it. It is measured for `fill`, whose reader is
- * deciding what to write, and for whom "the schema would take an override here"
- * is exactly the kind of fact a silent skip would hide.
- */
-interface OptionalDrift {
-    /** The parameter id, or the dotted schema path when no filename could reach it. */
-    readonly subject: string;
-    /** Absent when no filename reaches this key — an override `penv set` cannot write. */
-    readonly ref?: ParameterRef;
-    /** What the schema falls back to, rendered for display, when it declares one this module can read. */
-    readonly defaultValue?: string;
-    /** The rename that must precede any override, for the key no filename reaches. */
-    readonly remedy: string;
-}
-/**
- * The distance between the schema and the tree, in both directions. Named
- * `declared`/`undeclared` for the side that has it, not for a verdict: neither
- * direction is by itself an error, and only `validate` decides that. `optional`
- * is the deliberately verdict-free third list — see {@link OptionalDrift}.
- */
-interface DriftReport {
-    readonly declared: readonly DeclaredDrift[];
-    readonly undeclared: readonly UndeclaredDrift[];
-    readonly optional: readonly OptionalDrift[];
-}
-
-type ValidateIssueKind = "config" | "reserved" | "collision" | "schema" | "undecryptable";
-interface ValidateIssue {
-    readonly kind: ValidateIssueKind;
-    /** What the line is about: a parameter, a variable, a token, or a file. */
-    readonly subject: string;
-    readonly message: string;
-    readonly remedy?: string;
-}
-interface ValidateResult {
-    readonly ok: boolean;
-    readonly environment: string;
-    readonly parameters: number;
-    readonly issues: readonly ValidateIssue[];
-    /**
-     * The distance between the schema and the tree, carried for the callers
-     * that report it (`watch`). Never folded into `ok` and never rendered by
-     * `renderValidate`: drift is a report, and CI's verdict must not move because
-     * a parameter the schema tolerates is absent. Empty when the schema did not
-     * load, since there is nothing to measure against.
-     */
-    readonly drift: DriftReport;
-}
-interface ValidateOptions {
-    readonly cwd: string;
-    readonly environment?: string;
-    /** 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;
-    /** The dotenv file to adopt, absolute or relative to `cwd`. */
-    readonly file: string;
-    /**
-     * `--env`. It reads as "these are <environment>'s values", so for a file whose
-     * name carries no environment it names the *scope* as well as the environment
-     * to run against: `penv import prod-secrets.txt --env production` writes
-     * `<name>.production`, and `--env production` on `.env.local` writes
-     * `<name>.production.local`. The filename supplies both when it carries an
-     * environment, so the flag is needed only for a file that does not — and
-     * contradicting the filename is an error rather than a silent choice between
-     * the two.
-     */
-    readonly environment?: string;
-}
-interface ImportReport {
-    readonly root: string;
-    readonly file: string;
-    readonly backup: string;
-    /** The scope the source named — filename, `--env`, or both — and the scope every value was written at. */
-    readonly scope: Scope;
-    /**
-     * The environment the import ran against, or `undefined` when none is set.
-     *
-     * Undefined only ever accompanies the unscoped default: any other scope names
-     * an environment, so it always has one. It means the values were written and
-     * the closing validation was skipped, which the output states.
-     */
-    readonly environment: string | undefined;
-    /** The declared environments, so a skipped validation can name one to pass. */
-    readonly environments: readonly string[];
-    readonly variables: number;
-    /**
-     * Comment blocks that belonged to no variable. Reported rather than discarded
-     * silently: a file header has no parameter to describe, but that is not a
-     * reason to pretend it was never there.
-     */
-    readonly orphanComments: number;
-    readonly steps: readonly InitStep[];
-}
-/**
- * Adopts the file: parses it, scaffolds the project, writes one value file per
- * variable and each attached comment into that parameter's meta, and backs the
- * source up. Validation is the caller's next step rather than part of adoption —
- * an inferred schema is a draft, and a draft that needs correcting has still
- * imported every value correctly.
- *
- * Adoption is all or nothing. Every name is checked against the config, and any
- * environment the source names resolved, before the tree is scaffolded or a
- * value written. The two names that fail here fail *destructively*: a reserved
- * name bricks every later command, and a lossy name renames the user's variable
- * behind their back. What the source names is resolved here rather than left to
- * the closing `validate` because a command that writes a tree and *then*
- * discovers it cannot name an environment has already half-adopted the project
- * it just refused. A half-imported tree would be the drift penv exists to
- * remove, introduced by penv itself.
- *
- * An environment nothing names is a different case, and not an error: an
- * unscoped import writes at the unscoped default, which needs no environment.
- * Only the validation that follows needs one, so it is skipped and said to be
- * skipped. Requiring one here would fail `penv import .env` on a greenfield
- * project — the first command the quickstart gives, where no environment could
- * plausibly be set yet — to satisfy a step that is the caller's next one.
- */
-declare function importDotenv(options: ImportOptions): ImportReport;
-
-/**
- * `penv list` — every parameter, and the scope that wins for one environment.
- *
- * The winning scope is the point: `production` and `default` are both "it
- * resolves", and only one of them means the value was written for production.
- */
-interface ListOptions {
-    readonly cwd: string;
-    readonly environment?: string;
-}
-interface ListEntry {
-    readonly parameter: string;
-    /** The generated `.env` variable, so the two names are legible side by side. */
-    readonly variable: string;
-    /** `<env>.local`, `local`, an environment name, `default`, or `absent`. */
-    readonly scope: string;
-    /** The winning value file relative to the records tree, or `undefined` when nothing wins. */
-    readonly location: string | undefined;
-    readonly encrypted: boolean;
-    readonly viaUnscopedFallback: boolean;
-}
-interface ListResult {
-    readonly environment: string;
-    readonly parameters: readonly ListEntry[];
-}
-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.
- *
- * A parameter is not one file. It is up to eight — four cascade levels, each
- * with a plaintext and an encrypted address — plus its meta, and a rename that
- * moved some of them would split one parameter into two. So this moves all of
- * them or none of them, and the whole plan is checked before a single byte is
- * written.
- *
- * **This is the only correct way to move an encrypted value.** A ciphertext is
- * sealed against the address it lives at, so `mv redis-password.production.enc
- * redis/password.production.enc` at the shell produces a file that will never
- * open again — the value is not moved, it is destroyed, and the shell reports
- * success. Re-sealing at the new address is the whole reason this command
- * exists: penv asked for namespacing to be "a deliberate refactor afterwards"
- * and then, once values could be encrypted, made doing it by hand a way to lose
- * them.
- *
- * It moves the tree and never the schema. `.penv/env.ts` is yours (invariant 2),
- * so renaming `database-url` to `database/url` leaves it declaring the old access
- * path — and the drift report is what says so. penv names the distance; you close
- * it. This command's report says which line to change rather than changing it.
- */
-interface MoveOptions {
-    readonly cwd: string;
-    readonly from: string;
-    readonly to: string;
-}
-interface MovedFile {
-    readonly from: string;
-    readonly to: string;
-    /** True when the value was opened and sealed again for its new address. */
-    readonly resealed: boolean;
-}
-interface MoveResult {
-    readonly from: string;
-    readonly to: string;
-    readonly files: readonly MovedFile[];
-    /** The meta file's new location, or `undefined` when the parameter had none. */
-    readonly meta: string | undefined;
-    /** The access path the schema still declares, and the one it should now. */
-    readonly schema: {
-        readonly was: string;
-        readonly now: string;
-    };
-    /** The file that holds the shape to rename — cohort-aware, so the tip names one that exists. */
-    readonly schemaFile: string;
-}
-declare function runMove(options: MoveOptions): Promise<MoveResult>;
-declare function renderMove(result: MoveResult): string[];
-
-interface PullOptions {
-    readonly cwd: string;
-    readonly environment?: string;
-    /** Bare flags the command did not declare — environment shorthands, judged against the whitelist. */
-    readonly envFlags?: readonly string[];
-    /** Injected in tests: the source provider. Defaults to the one the config declares. */
-    readonly source?: AnyProvider;
-}
-interface PullResult {
-    readonly environment: string;
-    /** The source provider's type — `filesystem` when the environment declares no separate backend. */
-    readonly source: string;
-    /**
-     * True when the source *is* the local tree, so there was nothing to pull. The
-     * caller distinguishes "pulled nothing because the backend was empty" from
-     * "there is no backend to pull from" — opposite situations.
-     */
-    readonly localSource: boolean;
-    /** Value files written into the local tree. */
-    readonly values: number;
-    /** Meta files written into the local tree. */
-    readonly meta: number;
-    /** Distinct parameters the pull touched, at any scope. */
-    readonly refs: number;
-    /**
-     * True when the source declares `readsValues: false`: names and meta came
-     * down, values stayed absent — the destination never returns one, and the
-     * pull says so rather than dressing emptiness as freshness.
-     */
-    readonly valuesUnreadable?: boolean;
-}
-declare function runPull(options: PullOptions): Promise<PullResult>;
-declare function renderPull(result: PullResult): string[];
-
-/** The per-environment meta field recording penv's last push, compared against the destination's `updatedAt`. */
-declare const LAST_PUSHED_KEY = "lastPushedAt";
-interface PushOptions {
-    readonly cwd: string;
-    readonly environment?: string;
-    /** Bare flags the command did not declare — environment shorthands, judged against the whitelist. */
-    readonly envFlags?: readonly string[];
-    /** Permits sealed values to be decrypted locally and pushed as plaintext for the destination to re-seal. */
-    readonly allowDecrypt?: boolean;
-    /** Pre-approves creating a missing destination-side target (`--yes`). */
-    readonly yes?: boolean;
-    /** Injected in tests: the destination provider. Defaults to the one the environment's entry declares. */
-    readonly provider?: AnyProvider;
-    /** Injected in tests: answers the create-target question. Defaults to a terminal prompt. */
-    readonly confirm?: (question: string) => Promise<boolean>;
-    /** Injected in tests: the wall-clock reading recorded in meta. Defaults to now. */
-    readonly now?: string;
-}
-interface PushResult {
-    readonly environment: string;
-    /** The destination provider's type — its package name. */
-    readonly destination: string;
-    /** What the destination holds, which decided what crossed. */
-    readonly mode: "records" | "projection";
-    /** Values sent — resolved secrets for a projection, value files for records. */
-    readonly pushed: number;
-    /** Meta records mirrored. Records mode only. */
-    readonly meta: number;
-    readonly repositorySecrets: number;
-    readonly environmentSecrets: number;
-    /** How many were sealed and crossed as plaintext for the destination to re-seal. */
-    readonly decrypted: number;
-    /** True when the destination-side target was created by this push, on approval. */
-    readonly createdTarget: boolean;
-}
-declare function runPush(options: PushOptions): Promise<PushResult>;
-declare function renderPush(result: PushResult): string[];
-
-interface RemoveOptions extends ScopeOptions {
-    readonly cwd: string;
-    readonly key: string;
-}
-interface RemoveResult {
-    readonly parameter: string;
-    /** 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[];
-}
-declare function runRemove(options: RemoveOptions): Promise<RemoveResult>;
-
-interface RotateOptions {
-    readonly cwd: string;
-    readonly key: string;
-    readonly environment?: string;
-    /** Open a `dual-valid` window: write the new value while the old is still retained. */
-    readonly begin?: boolean;
-    /** Close a `dual-valid` window: return to `active`, stamp the completion. */
-    readonly complete?: boolean;
-    /**
-     * The new value. A `begin` and an `atomic-cutover` flip write it; a `complete`
-     * does not touch the value at all, so it needs none. Injected in tests; on the
-     * CLI it is the positional argument or stdin, the same source `set` reads.
-     */
-    readonly value?: string;
-    /** Injected in tests: the wall-clock reading recorded in meta. Defaults to now. */
-    readonly now?: string;
-}
-/** The single step a run performed — the three the two mechanisms decompose into. */
-type RotatePhase = "begin" | "complete" | "cutover";
-interface RotateResult {
-    readonly parameter: string;
-    readonly environment: string;
-    readonly mechanism: RotationMechanism;
-    readonly phase: RotatePhase;
-    /** The source provider's type — where the value and its meta were written. */
-    readonly source: string;
-    /** True when this run wrote a new value. `begin` and `cutover` do; `complete` does not. */
-    readonly wroteValue: boolean;
-    /** The rotation state after this run — `rotating` after a begin, `active` otherwise. */
-    readonly state: RotationState;
-    /** When the current window opened, ISO. Set only after a `begin`, else `null`. */
-    readonly rotatingSince: string | null;
-    /** When a rotation last completed, ISO. Set after a `complete` or a `cutover`. */
-    readonly lastRotated: string | null;
-}
-declare function runRotate(options: RotateOptions): Promise<RotateResult>;
-declare function renderRotate(result: RotateResult): string[];
-
-/**
- * Starting someone else's command, opaquely.
- *
- * `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`.
- *
- * 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.
- */
-
-/** 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;
-}
-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;
-    /**
-     * What penv is starting this on its own behalf to do — `init`'s dependency
-     * install. Absent means the command is the user's, from after `--`, and the
-     * two failures have opposite remedies: one is about what they typed, the other
-     * about a program penv chose to run.
-     */
-    readonly purpose?: string;
-}
-/** 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;
-}
-/** 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;
-    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;
-    readonly environment?: string;
-    /** Defaults to {@link DEBOUNCE_MS}. */
-    readonly debounceMs?: number;
-    /** Called with every completed validation, starting with the initial one. */
-    readonly onResult?: (result: ValidateResult) => void;
-    /**
-     * Called when a cycle could not produce a result at all — an unreadable
-     * config, a watcher the platform dropped. Never called for a *failing*
-     * validation: that is a result, and it goes to `onResult`.
-     */
-    readonly onError?: (error: unknown) => void;
-}
-interface WatchHandle {
-    /** Stops watching. Idempotent, and safe to call from inside a callback. */
-    close(): void;
-}
-/**
- * Watches, and re-validates on change.
- *
- * Returns a handle rather than blocking, so the loop is a plain object a test
- * can drive and close instead of a live process it would have to spawn. The
- * command below is the only thing that turns it into a process that waits.
- */
-declare function runWatch(options: WatchOptions): WatchHandle;
-/**
- * One cycle's report: `penv validate`'s, with a rule above it — on a loop, the
- * reader's first question is where the last run ended — and the drift below it.
- *
- * Drift comes last because it is the part that is not a verdict. The rows above
- * say whether the configuration is valid; these say what the schema and the tree
- * disagree about, which is often *why*, and is worth reading even on a run that
- * passed.
- */
-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.
- *
- * The wiring here is deliberately thin: every command's real work is a plain
- * exported function that takes a `cwd` and returns a result, and citty only
- * parses arguments, calls it, and prints what it returned. That is what lets the
- * tests call the commands rather than spawn them.
- */
-declare const main: citty.CommandDef<citty.ArgsDef>;
-declare function runMain(): Promise<void>;
-
-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 };