@penvhq/cli 0.3.2 → 0.4.0

package/dist/index.d.cts

@@ -97,6 +97,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,6 +114,14 @@ 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 {
@@ -131,6 +145,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
@@ -335,14 +355,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";

package/dist/index.d.ts

@@ -97,6 +97,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,6 +114,14 @@ 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 {
@@ -131,6 +145,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
@@ -335,14 +355,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";