@penvhq/cli 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as citty from 'citty';
-import { Sink, ParameterRef, Scope } from '@penvhq/core';
+import { Sink, Provider, ParameterRef, Scope, RotationMechanism, RotationState } from '@penvhq/core';
 
 /**
  * A check reports one of four verdicts. `unknown` — a check that ran but could
@@ -8,7 +8,7 @@ import { Sink, ParameterRef, Scope } from '@penvhq/core';
  * and a write-only sink 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" | "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" | "sink-unreachable" | "sink-name-drift" | "sink-manual-edit" | "sink-value-drift";
 interface DoctorFinding {
     readonly check: DoctorCheck;
     readonly severity: DoctorSeverity;
@@ -29,6 +29,17 @@ interface DoctorOptions {
     readonly environment?: string;
     /** Injected in tests: the sink to check against. Defaults to the one the config declares. */
     readonly sink?: Sink;
+    /**
+     * 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.
+     */
+    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[];
@@ -53,10 +64,8 @@ interface SetResult {
 /**
  * Writes one value file, sealing it when meta says the parameter is a secret.
  *
- * There is no `--encrypt` flag, deliberately. A flag would make the command line
- * the authority on what is secret, and meta is (invariant 14) — the `.enc` marker
- * is validated *against* the policy, so a marker chosen at the keyboard would
- * invert the direction the check runs in. The policy decides; `set` obeys.
+ * 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>;
 
@@ -74,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;
@@ -437,6 +516,47 @@ 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;
+}
+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;
+}
+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 {
@@ -475,6 +595,44 @@ interface RemoveResult {
 }
 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[];
+
 interface WatchOptions {
     readonly cwd: string;
     readonly environment?: string;
@@ -523,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 PushOptions, type PushResult, type RemoveResult, type ResealResult, type SetResult, type ValidateIssue, type ValidateResult, type WatchHandle, type WatchOptions, generateDotenv, importDotenv, insertEnvAlias, main, renderDoctor, renderMove, renderPush, renderWatch, runDecrypt, runDoctor, runEncrypt, runExplain, runGenerate, runGet, runInit, runList, runMain, runMove, runPush, runRemove, 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

@@ -1,5 +1,5 @@
 import * as citty from 'citty';
-import { Sink, ParameterRef, Scope } from '@penvhq/core';
+import { Sink, Provider, ParameterRef, Scope, RotationMechanism, RotationState } from '@penvhq/core';
 
 /**
  * A check reports one of four verdicts. `unknown` — a check that ran but could
@@ -8,7 +8,7 @@ import { Sink, ParameterRef, Scope } from '@penvhq/core';
  * and a write-only sink 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" | "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" | "sink-unreachable" | "sink-name-drift" | "sink-manual-edit" | "sink-value-drift";
 interface DoctorFinding {
     readonly check: DoctorCheck;
     readonly severity: DoctorSeverity;
@@ -29,6 +29,17 @@ interface DoctorOptions {
     readonly environment?: string;
     /** Injected in tests: the sink to check against. Defaults to the one the config declares. */
     readonly sink?: Sink;
+    /**
+     * 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.
+     */
+    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[];
@@ -53,10 +64,8 @@ interface SetResult {
 /**
  * Writes one value file, sealing it when meta says the parameter is a secret.
  *
- * There is no `--encrypt` flag, deliberately. A flag would make the command line
- * the authority on what is secret, and meta is (invariant 14) — the `.enc` marker
- * is validated *against* the policy, so a marker chosen at the keyboard would
- * invert the direction the check runs in. The policy decides; `set` obeys.
+ * 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>;
 
@@ -74,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;
@@ -437,6 +516,47 @@ 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;
+}
+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;
+}
+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 {
@@ -475,6 +595,44 @@ interface RemoveResult {
 }
 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[];
+
 interface WatchOptions {
     readonly cwd: string;
     readonly environment?: string;
@@ -523,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 PushOptions, type PushResult, type RemoveResult, type ResealResult, type SetResult, type ValidateIssue, type ValidateResult, type WatchHandle, type WatchOptions, generateDotenv, importDotenv, insertEnvAlias, main, renderDoctor, renderMove, renderPush, renderWatch, runDecrypt, runDoctor, runEncrypt, runExplain, runGenerate, runGet, runInit, runList, runMain, runMove, runPush, runRemove, 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 };