@penvhq/cli 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,526 @@
+import * as citty from 'citty';
+import { Sink, ParameterRef, Scope } 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.
+ */
+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";
+interface DoctorFinding {
+    readonly check: DoctorCheck;
+    readonly severity: DoctorSeverity;
+    readonly label: string;
+    readonly subject?: string;
+    readonly detail?: string;
+    /** A line the reader can act on — the `penv set` to paste, where there is one. */
+    readonly remedy?: string;
+}
+interface DoctorReport {
+    readonly environment: string;
+    readonly findings: readonly DoctorFinding[];
+    /** False when any finding is a failure. Warnings and unknowns do not fail the run. */
+    readonly ok: boolean;
+}
+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;
+}
+declare function runDoctor(options: DoctorOptions): Promise<DoctorReport>;
+declare function renderDoctor(report: DoctorReport): string[];
+
+interface ScopeOptions {
+    /** The environment scope. Combined with `local`, the environment-scoped override. */
+    readonly environment?: string;
+    readonly local?: boolean;
+}
+interface SetOptions extends ScopeOptions {
+    readonly cwd: string;
+    readonly key: string;
+    readonly value: string;
+}
+interface SetResult {
+    readonly parameter: string;
+    /** The value file written, relative to `.penv/`. */
+    readonly location: string;
+    /** Whether meta's policy sealed it. Reported, so the marker is never a surprise. */
+    readonly encrypted: boolean;
+}
+/**
+ * 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.
+ */
+declare function runSet(options: SetOptions): Promise<SetResult>;
+
+interface ResealOptions extends ScopeOptions {
+    readonly cwd: string;
+    readonly key: string;
+}
+interface ResealResult {
+    readonly parameter: string;
+    /** The file that now holds the value. */
+    readonly location: string;
+    /** The file that no longer exists, because its twin replaced it. */
+    readonly removed: string;
+}
+declare function runEncrypt(options: ResealOptions): Promise<ResealResult>;
+declare function runDecrypt(options: ResealOptions): Promise<ResealResult>;
+
+interface GenerateOptions {
+    readonly cwd: string;
+    readonly environment?: 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. */
+    readonly allowDecrypt?: boolean;
+}
+interface GenerateResult {
+    readonly file: string;
+    readonly environment: string;
+    readonly entries: number;
+    /** How many of them were sealed and are now plaintext in the artifact. */
+    readonly decrypted: number;
+}
+/** The `.env` text for one environment — what `penv generate` writes. */
+declare function generateDotenv(options: Omit<GenerateOptions, "out">): string;
+declare function runGenerate(options: GenerateOptions): GenerateResult;
+
+/**
+ * `penv get <key>` — read a parameter, or explain which file wins and why.
+ *
+ * Fallback is never silent, and neither is precedence: `--explain` prints every
+ * candidate in the order the cascade considered them, so a value quietly coming
+ * from a shared default has nowhere to hide.
+ */
+interface GetOptions {
+    readonly cwd: string;
+    readonly key: string;
+    readonly environment?: string;
+}
+interface GetExplanation {
+    readonly parameter: string;
+    readonly environment: string;
+    /** `undefined` when no candidate was present. */
+    readonly location: string | undefined;
+    /**
+     * Why the winning file did not open, when it is `.enc` and did not.
+     *
+     * A winner that cannot be decrypted is not a skipped candidate — it won, and
+     * the cascade is over. Reporting it as a skip would say a lower scope should
+     * have been reached, which is the scope-widening answer the cascade refuses.
+     */
+    readonly undecryptable?: string;
+    readonly candidates: readonly GetCandidate[];
+}
+interface GetCandidate {
+    readonly location: string;
+    readonly present: boolean;
+    readonly wins: boolean;
+    /** Why a present candidate did not win, or why it was never considered. */
+    readonly skipped: string | undefined;
+}
+/**
+ * The value, or a named error.
+ *
+ * `requireValue` answers first, so a winner that exists but did not decrypt is
+ * reported as undecryptable rather than as absent. Only a genuine absence — no
+ * candidate at any scope — reaches the refusal below, which is what keeps `penv
+ * set` from being offered as the fix for a secret the user still has.
+ */
+declare function runGet(options: GetOptions): Promise<string>;
+/**
+ * Which file wins, and why — never a value, so this must not be stopped by the
+ * winner being unreadable. Core describes an `.enc` winner rather than refusing
+ * it, so `--explain` is the same walk every other command does.
+ */
+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";
+/**
+ * `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.
+ */
+type InitAction = "created" | "kept" | "updated" | "conflicted";
+interface InitStep {
+    readonly target: InitTarget;
+    readonly action: InitAction;
+    /** The reported line, in the docs' voice. */
+    readonly text: string;
+    readonly note?: string;
+}
+/**
+ * The answers init writes down. Every one of these is a decision a human either
+ * made or consented to — never an identity penv recorded to reinterpret later.
+ * There is deliberately no `framework` here: `schemaFile` and `publicPrefixes`
+ * still mean exactly what they say after the project is rewritten in something
+ * else, and `framework: "next"` would not.
+ */
+interface InitDecisions {
+    /** The whitelist. Empty unless a human named them — penv never infers one. */
+    readonly environments: readonly string[];
+    /** The schema module, relative to the project root, POSIX. */
+    readonly schemaFile: string;
+    /** The prefixes the framework inlines into its client bundle. */
+    readonly publicPrefixes: readonly string[];
+    /**
+     * How the user's code names the schema module — `@env` or `#env`.
+     *
+     * Two forms, resolved by two different things: `@env` is a tsconfig `paths`
+     * entry that a bundler resolves and plain Node does not, and `#env` is a
+     * package.json `imports` entry that Node resolves itself. Which one a project
+     * wants is a fact about the project, so penv reads what it already does and
+     * offers that.
+     */
+    readonly alias: string;
+}
+interface InitResult {
+    readonly root: string;
+    readonly decisions: InitDecisions;
+    readonly steps: readonly InitStep[];
+}
+interface InitOptions {
+    readonly cwd: string;
+    /** What to write. Omitted means the plan's defaults, as `--yes` takes them. */
+    readonly decisions?: InitDecisions;
+}
+interface AliasEdit {
+    readonly source: string;
+    readonly changed: boolean;
+    /**
+     * What the alias already points at, when that is not penv's schema.
+     *
+     * The alias is how the user's code reaches penv, so an alias that resolves
+     * somewhere else is not a small problem: `import { env } from "@env"` compiles,
+     * runs, and hands back another module's export. Reporting "kept the alias"
+     * because the *key* was present is how penv would say that was fine — a silent
+     * seam, in the scaffolder of the tool whose subject is silent seams.
+     *
+     * Left as the user's, never rewritten: penv cannot tell a stale mapping from a
+     * deliberate one, and the file is theirs.
+     */
+    readonly conflict?: string;
+}
+/**
+ * `tsconfig.json` with the `@env` alias present, everything else untouched.
+ * Already-aliased input comes back unchanged rather than gaining a duplicate.
+ *
+ * The alias is why the schema can live anywhere: application code imports
+ * `@env`, and this line is the only thing that has to know where that is.
+ */
+declare function insertEnvAlias(source: string, target?: string, name?: string): AliasEdit;
+declare function runInit(options: InitOptions): InitResult;
+
+/**
+ * Reading the user's schema, and the distance between it and the parameter tree.
+ *
+ * `.penv/env.ts` declares what must exist and the tree holds what does. The gap
+ * between them is the signal `penv validate` exists to raise; this module makes
+ * it legible without closing it. Nothing here writes or deletes a value file —
+ * a declaration has no value, so materialising one could only invent it, and an
+ * invented value is the silent-value-reaching-runtime failure penv exists to
+ * delete. `penv set` stays the only writer.
+ *
+ * The introspection below lives here, not in `doctor`, because `doctor` and
+ * `watch` both report drift and two readers of the same schema would be two
+ * answers to one question.
+ *
+ * Every helper answers "I cannot tell" rather than guessing. A report is only
+ * worth reading if every line in it is true, so a field this module cannot
+ * understand produces no line at all.
+ */
+
+/** A parameter `.penv/env.ts` declares that the tree has no value for. */
+interface DeclaredDrift {
+    /** The parameter id, or the dotted schema path when no filename could reach it. */
+    readonly subject: string;
+    /** Absent when no filename reaches this key, which is drift `penv set` cannot close. */
+    readonly ref?: ParameterRef;
+    /** The line to paste: the `penv set` that closes this, or the rename that must precede it. */
+    readonly remedy: string;
+    readonly detail: string;
+}
+/** A parameter the tree holds a value for that `.penv/env.ts` does not declare. */
+interface UndeclaredDrift {
+    readonly ref: ParameterRef;
+    /** The generated variable, which is the name the application would have read. */
+    readonly variable: 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.
+ */
+interface DriftReport {
+    readonly declared: readonly DeclaredDrift[];
+    readonly undeclared: readonly UndeclaredDrift[];
+}
+
+type ValidateIssueKind = "config" | "reserved" | "collision" | "schema" | "undecryptable";
+interface ValidateIssue {
+    readonly kind: ValidateIssueKind;
+    /** What the line is about: a parameter, a variable, a token, or a file. */
+    readonly subject: string;
+    readonly message: string;
+    readonly remedy?: string;
+}
+interface ValidateResult {
+    readonly ok: boolean;
+    readonly environment: string;
+    readonly parameters: number;
+    readonly issues: readonly ValidateIssue[];
+    /**
+     * The distance between the schema and the tree, carried for the callers
+     * that report it (`watch`). Never folded into `ok` and never rendered by
+     * `renderValidate`: drift is a report, and CI's verdict must not move because
+     * a parameter the schema tolerates is absent. Empty when the schema did not
+     * load, since there is nothing to measure against.
+     */
+    readonly drift: DriftReport;
+}
+interface ValidateOptions {
+    readonly cwd: string;
+    readonly environment?: string;
+}
+declare function runValidate(options: ValidateOptions): Promise<ValidateResult>;
+
+interface ImportOptions {
+    readonly cwd: string;
+    /** The dotenv file to adopt, absolute or relative to `cwd`. */
+    readonly file: string;
+    /**
+     * `--env`. It reads as "these are <environment>'s values", so for a file whose
+     * name carries no environment it names the *scope* as well as the environment
+     * to run against: `penv import prod-secrets.txt --env production` writes
+     * `<name>.production`, and `--env production` on `.env.local` writes
+     * `<name>.production.local`. The filename supplies both when it carries an
+     * environment, so the flag is needed only for a file that does not — and
+     * contradicting the filename is an error rather than a silent choice between
+     * the two.
+     */
+    readonly environment?: string;
+}
+interface ImportReport {
+    readonly root: string;
+    readonly file: string;
+    readonly backup: string;
+    /** The scope the source named — filename, `--env`, or both — and the scope every value was written at. */
+    readonly scope: Scope;
+    /**
+     * The environment the import ran against, or `undefined` when none is set.
+     *
+     * Undefined only ever accompanies the unscoped default: any other scope names
+     * an environment, so it always has one. It means the values were written and
+     * the closing validation was skipped, which the output states.
+     */
+    readonly environment: string | undefined;
+    /** The declared environments, so a skipped validation can name one to pass. */
+    readonly environments: readonly string[];
+    readonly variables: number;
+    /**
+     * Comment blocks that belonged to no variable. Reported rather than discarded
+     * silently: a file header has no parameter to describe, but that is not a
+     * reason to pretend it was never there.
+     */
+    readonly orphanComments: number;
+    readonly steps: readonly InitStep[];
+}
+/**
+ * Adopts the file: parses it, scaffolds the project, writes one value file per
+ * variable and each attached comment into that parameter's meta, and backs the
+ * source up. Validation is the caller's next step rather than part of adoption —
+ * an inferred schema is a draft, and a draft that needs correcting has still
+ * imported every value correctly.
+ *
+ * Adoption is all or nothing. Every name is checked against the config, and any
+ * environment the source names resolved, before the tree is scaffolded or a
+ * value written. The two names that fail here fail *destructively*: a reserved
+ * name bricks every later command, and a lossy name renames the user's variable
+ * behind their back. What the source names is resolved here rather than left to
+ * the closing `validate` because a command that writes a tree and *then*
+ * discovers it cannot name an environment has already half-adopted the project
+ * it just refused. A half-imported tree would be the drift penv exists to
+ * remove, introduced by penv itself.
+ *
+ * An environment nothing names is a different case, and not an error: an
+ * unscoped import writes at the unscoped default, which needs no environment.
+ * Only the validation that follows needs one, so it is skipped and said to be
+ * skipped. Requiring one here would fail `penv import .env` on a greenfield
+ * project — the first command the quickstart gives, where no environment could
+ * plausibly be set yet — to satisfy a step that is the caller's next one.
+ */
+declare function importDotenv(options: ImportOptions): ImportReport;
+
+/**
+ * `penv list` — every parameter, and the scope that wins for one environment.
+ *
+ * The winning scope is the point: `production` and `default` are both "it
+ * resolves", and only one of them means the value was written for production.
+ */
+interface ListOptions {
+    readonly cwd: string;
+    readonly environment?: string;
+}
+interface ListEntry {
+    readonly parameter: string;
+    /** The generated `.env` variable, so the two names are legible side by side. */
+    readonly variable: string;
+    /** `<env>.local`, `local`, an environment name, `default`, or `absent`. */
+    readonly scope: string;
+    /** The winning value file relative to `.penv/`, or `undefined` when nothing wins. */
+    readonly location: string | undefined;
+    readonly encrypted: boolean;
+    readonly viaUnscopedFallback: boolean;
+}
+interface ListResult {
+    readonly environment: string;
+    readonly parameters: readonly ListEntry[];
+}
+declare function runList(options: ListOptions): Promise<ListResult>;
+
+/**
+ * `penv mv <from> <to>` — rename a parameter, every scope at once.
+ *
+ * A parameter is not one file. It is up to eight — four cascade levels, each
+ * with a plaintext and an encrypted address — plus its meta, and a rename that
+ * moved some of them would split one parameter into two. So this moves all of
+ * them or none of them, and the whole plan is checked before a single byte is
+ * written.
+ *
+ * **This is the only correct way to move an encrypted value.** A ciphertext is
+ * sealed against the address it lives at, so `mv redis-password.production.enc
+ * redis/password.production.enc` at the shell produces a file that will never
+ * open again — the value is not moved, it is destroyed, and the shell reports
+ * success. Re-sealing at the new address is the whole reason this command
+ * exists: penv asked for namespacing to be "a deliberate refactor afterwards"
+ * and then, once values could be encrypted, made doing it by hand a way to lose
+ * them.
+ *
+ * It moves the tree and never the schema. `.penv/env.ts` is yours (invariant 2),
+ * so renaming `database-url` to `database/url` leaves it declaring the old access
+ * path — and the drift report is what says so. penv names the distance; you close
+ * it. This command's report says which line to change rather than changing it.
+ */
+interface MoveOptions {
+    readonly cwd: string;
+    readonly from: string;
+    readonly to: string;
+}
+interface MovedFile {
+    readonly from: string;
+    readonly to: string;
+    /** True when the value was opened and sealed again for its new address. */
+    readonly resealed: boolean;
+}
+interface MoveResult {
+    readonly from: string;
+    readonly to: string;
+    readonly files: readonly MovedFile[];
+    /** The meta file's new location, or `undefined` when the parameter had none. */
+    readonly meta: string | undefined;
+    /** The access path the schema still declares, and the one it should now. */
+    readonly schema: {
+        readonly was: string;
+        readonly now: string;
+    };
+}
+declare function runMove(options: MoveOptions): Promise<MoveResult>;
+declare function renderMove(result: MoveResult): 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 {
+    readonly cwd: string;
+    readonly environment?: 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;
+    /** 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;
+    readonly pushed: number;
+    readonly repositorySecrets: number;
+    readonly environmentSecrets: number;
+    /** How many were sealed and crossed as plaintext for the destination to re-seal. */
+    readonly decrypted: number;
+}
+declare function runPush(options: PushOptions): Promise<PushResult>;
+declare function renderPush(result: PushResult): string[];
+
+interface RemoveOptions extends ScopeOptions {
+    readonly cwd: string;
+    readonly key: string;
+}
+interface RemoveResult {
+    readonly parameter: string;
+    /** The value files that existed and are now gone, relative to `.penv/`. */
+    readonly removed: readonly string[];
+    /** Both files penv looked at, whether or not they were there. */
+    readonly considered: readonly string[];
+}
+declare function runRemove(options: RemoveOptions): Promise<RemoveResult>;
+
+interface WatchOptions {
+    readonly cwd: string;
+    readonly environment?: string;
+    /** Defaults to {@link DEBOUNCE_MS}. */
+    readonly debounceMs?: number;
+    /** Called with every completed validation, starting with the initial one. */
+    readonly onResult?: (result: ValidateResult) => void;
+    /**
+     * Called when a cycle could not produce a result at all — an unreadable
+     * config, a watcher the platform dropped. Never called for a *failing*
+     * validation: that is a result, and it goes to `onResult`.
+     */
+    readonly onError?: (error: unknown) => void;
+}
+interface WatchHandle {
+    /** Stops watching. Idempotent, and safe to call from inside a callback. */
+    close(): void;
+}
+/**
+ * Watches, and re-validates on change.
+ *
+ * Returns a handle rather than blocking, so the loop is a plain object a test
+ * can drive and close instead of a live process it would have to spawn. The
+ * command below is the only thing that turns it into a process that waits.
+ */
+declare function runWatch(options: WatchOptions): WatchHandle;
+/**
+ * One cycle's report: `penv validate`'s, with a rule above it — on a loop, the
+ * reader's first question is where the last run ended — and the drift below it.
+ *
+ * Drift comes last because it is the part that is not a verdict. The rows above
+ * say whether the configuration is valid; these say what the schema and the tree
+ * disagree about, which is often *why*, and is worth reading even on a run that
+ * passed.
+ */
+declare function renderWatch(result: ValidateResult): string[];
+
+/**
+ * penv's command line.
+ *
+ * The wiring here is deliberately thin: every command's real work is a plain
+ * exported function that takes a `cwd` and returns a result, and citty only
+ * parses arguments, calls it, and prints what it returned. That is what lets the
+ * tests call the commands rather than spawn them.
+ */
+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 };