@penvhq/cli 0.2.0 → 0.3.1

package/dist/index.d.cts

@@ -83,6 +83,76 @@ interface ResealResult {
 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.
+ */
+/** 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;
+    readonly description?: string;
+}
+interface FillOptions {
+    readonly cwd: string;
+    readonly environment?: 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 `.penv/`. */
+        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 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;
@@ -611,4 +681,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 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, renderMove, renderPull, renderPush, renderRotate, renderWatch, runDecrypt, runDoctor, runEncrypt, runExplain, 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 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 };

package/dist/index.d.ts

@@ -83,6 +83,76 @@ interface ResealResult {
 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.
+ */
+/** 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;
+    readonly description?: string;
+}
+interface FillOptions {
+    readonly cwd: string;
+    readonly environment?: 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 `.penv/`. */
+        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 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;
@@ -611,4 +681,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 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, renderMove, renderPull, renderPush, renderRotate, renderWatch, runDecrypt, runDoctor, runEncrypt, runExplain, 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 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 };