@penvhq/cli 0.4.0 → 0.6.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. */
@@ -127,6 +130,8 @@ interface FillPrompt {
 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`
@@ -176,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. */
@@ -243,14 +250,18 @@ declare function runGet(options: GetOptions): Promise<string>;
 declare function runExplain(options: GetOptions): Promise<GetExplanation>;
 
 /** What init touched, so a caller can report it and a test can assert it. */
-type InitTarget = "penv-dir" | "schema" | "config" | "tsconfig" | "gitignore";
+type InitTarget = "penv-dir" | "schema" | "config" | "tsconfig" | "gitignore" | "seam";
 /**
  * `conflicted` is the one that is not a success. penv wanted to write something,
  * found the user's file already saying something else about the same thing, and
  * left it alone — so the step is reported with a warning rather than a ✓, and the
  * text says what will not work until the user decides.
+ *
+ * `info` is a step penv did not perform automatically — a manual instruction (the
+ * injection seam for a framework penv cannot scaffold), reported so the user
+ * knows the one thing left to do.
  */
-type InitAction = "created" | "kept" | "updated" | "conflicted";
+type InitAction = "created" | "kept" | "updated" | "conflicted" | "info";
 interface InitStep {
     readonly target: InitTarget;
     readonly action: InitAction;
@@ -282,6 +293,13 @@ interface InitDecisions {
      * offers that.
      */
     readonly alias: string;
+    /**
+     * Whether to inject the validated config into `process.env` for libraries that
+     * read it directly, so `env.ts` loads with `{ inject: true }` and penv places
+     * the framework's pre-app seam. Off by default and only ever turned on by an
+     * explicit yes — a project that reads config only through `@env` gets none.
+     */
+    readonly inject: boolean;
 }
 interface InitResult {
     readonly root: string;
@@ -410,6 +428,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>;
 
@@ -556,26 +576,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;
@@ -593,6 +600,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[];
@@ -602,22 +615,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. */
@@ -127,6 +130,8 @@ interface FillPrompt {
 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`
@@ -176,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. */
@@ -243,14 +250,18 @@ declare function runGet(options: GetOptions): Promise<string>;
 declare function runExplain(options: GetOptions): Promise<GetExplanation>;
 
 /** What init touched, so a caller can report it and a test can assert it. */
-type InitTarget = "penv-dir" | "schema" | "config" | "tsconfig" | "gitignore";
+type InitTarget = "penv-dir" | "schema" | "config" | "tsconfig" | "gitignore" | "seam";
 /**
  * `conflicted` is the one that is not a success. penv wanted to write something,
  * found the user's file already saying something else about the same thing, and
  * left it alone — so the step is reported with a warning rather than a ✓, and the
  * text says what will not work until the user decides.
+ *
+ * `info` is a step penv did not perform automatically — a manual instruction (the
+ * injection seam for a framework penv cannot scaffold), reported so the user
+ * knows the one thing left to do.
  */
-type InitAction = "created" | "kept" | "updated" | "conflicted";
+type InitAction = "created" | "kept" | "updated" | "conflicted" | "info";
 interface InitStep {
     readonly target: InitTarget;
     readonly action: InitAction;
@@ -282,6 +293,13 @@ interface InitDecisions {
      * offers that.
      */
     readonly alias: string;
+    /**
+     * Whether to inject the validated config into `process.env` for libraries that
+     * read it directly, so `env.ts` loads with `{ inject: true }` and penv places
+     * the framework's pre-app seam. Off by default and only ever turned on by an
+     * explicit yes — a project that reads config only through `@env` gets none.
+     */
+    readonly inject: boolean;
 }
 interface InitResult {
     readonly root: string;
@@ -410,6 +428,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>;
 
@@ -556,26 +576,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;
@@ -593,6 +600,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[];
@@ -602,22 +615,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[];