@penvhq/cli 0.1.0 → 0.2.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>;
 
@@ -437,6 +446,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 +525,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 +611,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 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 };

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>;
 
@@ -437,6 +446,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 +525,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 +611,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 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 };