@penvhq/cli 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -9,7 +9,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" | "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" | "snapshot-stale" | "bundle-invisible-plaintext" | "provider" | "projection-unreachable" | "projection-name-drift" | "projection-manual-edit" | "projection-value-drift" | "environment-flag-shadow";
 interface DoctorFinding {
     readonly check: DoctorCheck;
     readonly severity: DoctorSeverity;
@@ -250,7 +250,7 @@ declare function runGet(options: GetOptions): Promise<string>;
 declare function runExplain(options: GetOptions): Promise<GetExplanation>;
 
 /** What init touched, so a caller can report it and a test can assert it. */
-type InitTarget = "penv-dir" | "schema" | "config" | "tsconfig" | "gitignore" | "seam";
+type InitTarget = "penv-dir" | "schema" | "env" | "config" | "snapshot" | "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
@@ -310,6 +310,8 @@ 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 AliasEdit {
     readonly source: string;
@@ -341,7 +343,7 @@ declare function runInit(options: InitOptions): InitResult;
 /**
  * Reading the user's schema, and the distance between it and the parameter tree.
  *
- * `.penv/env.ts` declares what must exist and the tree holds what does. The gap
+ * 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
@@ -357,7 +359,7 @@ declare function runInit(options: InitOptions): InitResult;
  * understand produces no line at all.
  */
 
-/** A parameter `.penv/env.ts` declares that the tree has no value for. */
+/** 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;
@@ -367,7 +369,7 @@ interface DeclaredDrift {
     readonly remedy: string;
     readonly detail: string;
 }
-/** A parameter the tree holds a value for that `.penv/env.ts` does not declare. */
+/** 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. */
@@ -392,7 +394,7 @@ interface OptionalDrift {
     readonly remedy: string;
 }
 /**
- * The distance between `.penv/env.ts` and the tree, in both directions. Named
+ * 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}.
@@ -572,6 +574,8 @@ interface MoveResult {
         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[];
@@ -705,6 +709,46 @@ interface RotateResult {
 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`.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+interface SnapshotWriteResult {
+    readonly file: string;
+    readonly action: "created" | "updated" | "unchanged";
+}
+/** 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 SnapshotResult {
+    readonly write: SnapshotWriteResult;
+    readonly wire: WireResult;
+}
+declare function runSnapshot(options: {
+    readonly cwd: string;
+}): SnapshotResult;
+declare function renderSnapshot(result: SnapshotResult): string[];
+
 interface WatchOptions {
     readonly cwd: string;
     readonly environment?: string;
@@ -753,4 +797,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 ValidateIssue, type ValidateResult, type WatchHandle, type WatchOptions, generateDotenv, importDotenv, insertEnvAlias, main, renderDoctor, renderFill, renderMove, renderPull, renderPush, renderRotate, renderWatch, runDecrypt, runDoctor, runEncrypt, runExplain, runFill, runGenerate, runGet, runInit, runList, runMain, runMove, runPull, runPush, runRemove, runRotate, runSet, runValidate, runWatch };
+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 };

package/dist/index.d.ts

@@ -9,7 +9,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" | "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" | "snapshot-stale" | "bundle-invisible-plaintext" | "provider" | "projection-unreachable" | "projection-name-drift" | "projection-manual-edit" | "projection-value-drift" | "environment-flag-shadow";
 interface DoctorFinding {
     readonly check: DoctorCheck;
     readonly severity: DoctorSeverity;
@@ -250,7 +250,7 @@ declare function runGet(options: GetOptions): Promise<string>;
 declare function runExplain(options: GetOptions): Promise<GetExplanation>;
 
 /** What init touched, so a caller can report it and a test can assert it. */
-type InitTarget = "penv-dir" | "schema" | "config" | "tsconfig" | "gitignore" | "seam";
+type InitTarget = "penv-dir" | "schema" | "env" | "config" | "snapshot" | "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
@@ -310,6 +310,8 @@ 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 AliasEdit {
     readonly source: string;
@@ -341,7 +343,7 @@ declare function runInit(options: InitOptions): InitResult;
 /**
  * Reading the user's schema, and the distance between it and the parameter tree.
  *
- * `.penv/env.ts` declares what must exist and the tree holds what does. The gap
+ * 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
@@ -357,7 +359,7 @@ declare function runInit(options: InitOptions): InitResult;
  * understand produces no line at all.
  */
 
-/** A parameter `.penv/env.ts` declares that the tree has no value for. */
+/** 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;
@@ -367,7 +369,7 @@ interface DeclaredDrift {
     readonly remedy: string;
     readonly detail: string;
 }
-/** A parameter the tree holds a value for that `.penv/env.ts` does not declare. */
+/** 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. */
@@ -392,7 +394,7 @@ interface OptionalDrift {
     readonly remedy: string;
 }
 /**
- * The distance between `.penv/env.ts` and the tree, in both directions. Named
+ * 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}.
@@ -572,6 +574,8 @@ interface MoveResult {
         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[];
@@ -705,6 +709,46 @@ interface RotateResult {
 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`.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+interface SnapshotWriteResult {
+    readonly file: string;
+    readonly action: "created" | "updated" | "unchanged";
+}
+/** 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 SnapshotResult {
+    readonly write: SnapshotWriteResult;
+    readonly wire: WireResult;
+}
+declare function runSnapshot(options: {
+    readonly cwd: string;
+}): SnapshotResult;
+declare function renderSnapshot(result: SnapshotResult): string[];
+
 interface WatchOptions {
     readonly cwd: string;
     readonly environment?: string;
@@ -753,4 +797,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 ValidateIssue, type ValidateResult, type WatchHandle, type WatchOptions, generateDotenv, importDotenv, insertEnvAlias, main, renderDoctor, renderFill, renderMove, renderPull, renderPush, renderRotate, renderWatch, runDecrypt, runDoctor, runEncrypt, runExplain, runFill, runGenerate, runGet, runInit, runList, runMain, runMove, runPull, runPush, runRemove, runRotate, runSet, runValidate, runWatch };
+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 };