@penvhq/cli 0.3.2 → 0.5.0

package/dist/index.d.cts

@@ -1,14 +1,15 @@
 import * as citty from 'citty';
-import { Sink, Provider, ParameterRef, Scope, RotationMechanism, RotationState } from '@penvhq/core';
+import { ProjectionProvider, Provider, ParameterRef, Scope, AnyProvider, RotationMechanism, RotationState } from '@penvhq/core';
 
 /**
  * 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 write-only sink makes most of what doctor can say the second kind.
+ * 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" | "plaintext-secret" | "public-secret" | "encryption" | "rotation-overdue" | "rotation-stuck" | "provider-value-drift" | "provider" | "sink-unreachable" | "sink-name-drift" | "sink-manual-edit" | "sink-value-drift";
+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";
 interface DoctorFinding {
     readonly check: DoctorCheck;
     readonly severity: DoctorSeverity;
@@ -27,13 +28,15 @@ interface DoctorReport {
 interface DoctorOptions {
     readonly cwd: string;
     readonly environment?: string;
-    /** Injected in tests: the sink to check against. Defaults to the one the config declares. */
-    readonly sink?: Sink;
+    /** 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 `sink`, for the same reason — the drift checks stay driveable without
-     * a live backend.
+     * 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. */
@@ -97,6 +100,12 @@ declare function runDecrypt(options: ResealOptions): Promise<ResealResult>;
  * 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 {
@@ -108,11 +117,21 @@ interface FillPrompt {
      * 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`
@@ -131,6 +150,12 @@ interface FillResult {
     }>;
     /** 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
@@ -156,6 +181,8 @@ 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. */
@@ -335,14 +362,34 @@ interface UndeclaredDrift {
     /** 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 `.penv/env.ts` 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.
+ * 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";
@@ -370,6 +417,8 @@ interface ValidateResult {
 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[];
 }
 declare function runValidate(options: ValidateOptions): Promise<ValidateResult>;
 
@@ -516,26 +565,13 @@ interface MoveResult {
 declare function runMove(options: MoveOptions): Promise<MoveResult>;
 declare function renderMove(result: MoveResult): string[];
 
-/**
- * `penv pull` — materialise the local `.penv` tree from an environment's
- * source-of-truth provider. It is the inverse of the deploy-time injection most
- * stacks already have: instead of reading the tree to feed a backend, it reads
- * the backend to feed the tree.
- *
- * It only means anything when the environment declares a real backend
- * (`vault`, `mock`): those hold the truth somewhere penv does not edit in place,
- * and pulling copies it down so every other command — which reads the local tree
- * — sees it. An environment with no separate `providers` entry has the local
- * tree *as* its source of truth, so a pull would be the tree copying onto
- * itself; that degenerate case is reported as nothing to do, never a self-copy.
- *
- * Values cross verbatim. They are opaque envelope strings the source holds and
- * penv does not open here — a sealed value stays sealed, byte-for-byte, so the
- * key that opens it never has to be present to pull it.
- */
 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;
@@ -553,6 +589,12 @@ interface PullResult {
     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[];
@@ -562,22 +604,41 @@ 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;
-    /** Injected in tests: the sink to push to. Defaults to the one the config declares. */
-    readonly sink?: Sink;
+    /** One-shot destination override: a provider package name. Nothing is persisted. */
+    readonly destination?: string;
+    /** The destination-side place, when `destination` needs one — `--location`. */
+    readonly location?: string;
+    /** Pre-approves creating a missing destination-side target (`--yes`). */
+    readonly yes?: boolean;
+    /** Injected in tests: the destination provider. Defaults to the one the config (or `--destination`) 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 `owner/repo` targeted, when the config named one. */
-    readonly repo: string | undefined;
+    /** The destination provider's type — its package name. */
+    readonly destination: string;
+    /** What the destination holds, which decided what crossed. */
+    readonly mode: "records" | "projection";
+    /** The `location` targeted, when one was declared. */
+    readonly location: string | undefined;
+    /** 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[];

package/dist/index.d.ts

@@ -1,14 +1,15 @@
 import * as citty from 'citty';
-import { Sink, Provider, ParameterRef, Scope, RotationMechanism, RotationState } from '@penvhq/core';
+import { ProjectionProvider, Provider, ParameterRef, Scope, AnyProvider, RotationMechanism, RotationState } from '@penvhq/core';
 
 /**
  * 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 write-only sink makes most of what doctor can say the second kind.
+ * 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" | "plaintext-secret" | "public-secret" | "encryption" | "rotation-overdue" | "rotation-stuck" | "provider-value-drift" | "provider" | "sink-unreachable" | "sink-name-drift" | "sink-manual-edit" | "sink-value-drift";
+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";
 interface DoctorFinding {
     readonly check: DoctorCheck;
     readonly severity: DoctorSeverity;
@@ -27,13 +28,15 @@ interface DoctorReport {
 interface DoctorOptions {
     readonly cwd: string;
     readonly environment?: string;
-    /** Injected in tests: the sink to check against. Defaults to the one the config declares. */
-    readonly sink?: Sink;
+    /** 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 `sink`, for the same reason — the drift checks stay driveable without
-     * a live backend.
+     * 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. */
@@ -97,6 +100,12 @@ declare function runDecrypt(options: ResealOptions): Promise<ResealResult>;
  * 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 {
@@ -108,11 +117,21 @@ interface FillPrompt {
      * 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`
@@ -131,6 +150,12 @@ interface FillResult {
     }>;
     /** 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
@@ -156,6 +181,8 @@ 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. */
@@ -335,14 +362,34 @@ interface UndeclaredDrift {
     /** 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 `.penv/env.ts` 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.
+ * 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";
@@ -370,6 +417,8 @@ interface ValidateResult {
 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[];
 }
 declare function runValidate(options: ValidateOptions): Promise<ValidateResult>;
 
@@ -516,26 +565,13 @@ interface MoveResult {
 declare function runMove(options: MoveOptions): Promise<MoveResult>;
 declare function renderMove(result: MoveResult): string[];
 
-/**
- * `penv pull` — materialise the local `.penv` tree from an environment's
- * source-of-truth provider. It is the inverse of the deploy-time injection most
- * stacks already have: instead of reading the tree to feed a backend, it reads
- * the backend to feed the tree.
- *
- * It only means anything when the environment declares a real backend
- * (`vault`, `mock`): those hold the truth somewhere penv does not edit in place,
- * and pulling copies it down so every other command — which reads the local tree
- * — sees it. An environment with no separate `providers` entry has the local
- * tree *as* its source of truth, so a pull would be the tree copying onto
- * itself; that degenerate case is reported as nothing to do, never a self-copy.
- *
- * Values cross verbatim. They are opaque envelope strings the source holds and
- * penv does not open here — a sealed value stays sealed, byte-for-byte, so the
- * key that opens it never has to be present to pull it.
- */
 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;
@@ -553,6 +589,12 @@ interface PullResult {
     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[];
@@ -562,22 +604,41 @@ 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;
-    /** Injected in tests: the sink to push to. Defaults to the one the config declares. */
-    readonly sink?: Sink;
+    /** One-shot destination override: a provider package name. Nothing is persisted. */
+    readonly destination?: string;
+    /** The destination-side place, when `destination` needs one — `--location`. */
+    readonly location?: string;
+    /** Pre-approves creating a missing destination-side target (`--yes`). */
+    readonly yes?: boolean;
+    /** Injected in tests: the destination provider. Defaults to the one the config (or `--destination`) 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 `owner/repo` targeted, when the config named one. */
-    readonly repo: string | undefined;
+    /** The destination provider's type — its package name. */
+    readonly destination: string;
+    /** What the destination holds, which decided what crossed. */
+    readonly mode: "records" | "projection";
+    /** The `location` targeted, when one was declared. */
+    readonly location: string | undefined;
+    /** 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[];