@super-repo/envx 0.2.3-b.3 → 0.2.3-b.5

package/README.md

@@ -54,6 +54,21 @@ The CLI shape, the `encrypted:<base64>` ciphertext format, the `ENVX_PUBLIC_KEY*
 | **Programmatic API**                      | `dotenvx.config()` / library functions                     | `envx()` (single call), `import "@super-repo/envx/auto"` side-effect entry           |
 | **Auto-environment detection**            | Limited                                                    | Reads `VERCEL_ENV`, Netlify `CONTEXT`, `NODE_ENV` to pick `.env.<env>` when `--env` is omitted |
 | **Distribution**                          | npm package                                                | npm package + workspace-private helpers (`envx-libs`, `envx-common`) bundled via Vite |
+| **Health check**                          | Not built in                                               | `envx doctor` — workspace, config, keys file, decryptability, required, expand cycles |
+| **`.env.example` sync**                   | Not built in                                               | `envx template` (and `--check` for CI drift detection)                                |
+| **Diff between env files**                | Not built in                                               | `envx diff` — keys-only-in-a/b + value mismatches (decrypts via `.env.keys`)         |
+| **Shell injection**                       | Not built in                                               | `envx hook bash|zsh|fish|powershell` — eval-able exports for the parent shell        |
+| **Typed `process.env`**                   | Not built in                                               | `envx types` — emits `env.d.ts` from loaded keys (Zod-shape-aware)                   |
+| **Watch mode**                            | Not built in                                               | `envx watch -- node app.js` — restart on `.env*` change                              |
+| **Repo-wide secret audit**                | Not built in                                               | `envx audit` — AKIA, ghp_, sk_live_, JWT, OpenAI/Anthropic keys, PEM blocks, …       |
+| **Selective encryption**                  | Per-key flag (`-k`)                                        | Per-key, glob patterns (`--pattern`), and `--secrets` preset                         |
+| **Schema validation (Zod)**               | Not built in                                               | `schema:` field in config — duck-typed `safeParse()` with fail-fast exit             |
+| **Named profiles**                        | Not built in                                               | `profiles: { staging: { ... } }` + `--profile staging` (per-field override)          |
+| **External secret refs**                  | Not built in                                               | `${aws-secrets:my-id}` resolved by user-registered `resolvers:` callbacks            |
+| **Secret-provider plugins**               | Not built in                                               | `@super-repo/envx-plugins` ships AWS, GCP, Azure, Vault, 1Password, Doppler, Infisical |
+| **Public-variable mirroring**             | Not built in                                               | `PUBLIC_*` vars auto-mirror under `VITE_`, `NEXT_PUBLIC_`, `REACT_APP_`, etc.        |
+| **Build-time secret bake**                | Not built in                                               | `envx bake` resolves all refs into `.env.resolved` for bundlers (Vite/Next/esbuild) |
+| **Runtime / edge secrets**                | Not built in                                               | `createSecretRuntime()` — async, TTL-cached, V8-isolate-safe (CF Workers, Vercel Edge) |
 | **License**                               | BSD-3-Clause                                               | MIT                                                                                   |
 
 In short: same crypto, same file formats, same CLI vocabulary — different path-resolution layer underneath.
@@ -81,6 +96,52 @@ The string form (`envx("prod")`) is shorthand for "scope this load to the named
 
 `envx()` discovers `envx.config.{ts,js,json}` and `package.json#envx.config` automatically; explicit args override matching fields from the config.
 
+#### Programmatic options — full surface
+
+`envx()` accepts everything from `LoadEnvOptions` plus an optional `profile` string. The full shape (`EnvxProgrammaticOptions`):
+
+```ts
+import envx, { type EnvxProgrammaticOptions } from "@super-repo/envx";
+
+const opts: EnvxProgrammaticOptions = {
+  // env-file selection
+  envFiles: ["vault/.env.prod"],
+  envPath: "vault",
+  cascade: "prod",                        // string for explicit, true for auto-detected, false to disable
+  vault: false,                            // shortcut for envPath: "vault"
+
+  // load behavior
+  override: false,
+  quiet: true,
+  variables: ["DEBUG=1"],                  // post-load mutation; always wins
+
+  // auto-detection
+  autoDetect: true,
+  nodeEnvMap: { qa: "qa-prod" },
+
+  // post-load behavior
+  required: ["DATABASE_URL"],              // exit 1 if any is unset after load
+  expand: true,                            // resolve ${VAR} references
+  defaults: { LOG_LEVEL: "info" },         // fill holes; never overwrite
+
+  // validation + plug-ins
+  schema: zodSchema,                       // any { safeParse(input) → { success, error?, data? } }
+  resolvers: {                             // ${provider:id} → resolver(id)
+    "aws-secrets": (id) => fetchSecret(id),
+  },
+
+  // profile selection (programmatic equivalent of --profile)
+  profile: "staging",                      // throws if config.profiles[name] is missing
+
+  // advanced
+  workspaceRoot: "/abs/path",              // skip findWorkspaceRoot() walk-up
+};
+
+envx(opts);
+```
+
+Caller-supplied fields override matching fields from the discovered config **per-field** — anything you omit falls through to config, then to defaults.
+
 ### Side-effect import
 
 ```ts
@@ -102,9 +163,19 @@ envx --dir vault -- pnpm test            # load every .env* in vault/
 envx print DATABASE_URL                  # print one variable
 envx debug --cascade prod                # show resolved paths
 envx encrypt -e .env.prod                # encrypt values in .env.prod (writes ./.env.keys)
+envx encrypt --secrets                   # encrypt only conventional secret keys (*_SECRET, *_TOKEN, …)
 envx decrypt -e .env.prod -k FOO         # decrypt only FOO
 envx rotate --dir vault                  # rotate keypair for every vault/.env* file
 envx expand -e vault/.env.prod           # decrypt + expand to stdout
+envx doctor                              # health check (workspace, keys, decryptability, required, cycles)
+envx template                            # write .env.example with values stripped
+envx template --check                    # CI gate — exit 1 on .env.example drift
+envx diff .env.dev .env.prod             # show keys-only-in-a/b + value mismatches
+eval "$(envx hook bash)"                 # inject loaded env into the parent shell
+envx types                               # emit env.d.ts for typed process.env access
+envx watch -- node app.js                # restart on .env* change
+envx audit                               # scan repo for plaintext secrets
+envx --profile staging -- node app.js    # apply named profile from envx.config.*
 envx -c ./envx.config.json run -- node app.js
 ```
 
@@ -117,17 +188,32 @@ envx -c ./envx.config.json run -- node app.js
 
 ### Subcommands
 
+#### Core
+
 | command   | what it does                                                                           |
 | --------- | -------------------------------------------------------------------------------------- |
 | `run`     | (default) load env files into `process.env` and execute a command                      |
 | `print`   | load env files and print a single variable's value                                     |
 | `debug`   | show which files would be loaded without loading them                                  |
-| `encrypt` | encrypt values in one or more `.env*` files (writes `.env.keys` on first run)          |
+| `encrypt` | encrypt values in one or more `.env*` files (writes `.env.keys` on first run). Selective: `--key`, `--pattern '*_SECRET,*_TOKEN'`, `--secrets` preset |
 | `decrypt` | decrypt values back in place                                                           |
 | `rotate`  | generate a fresh keypair and re-encrypt every encrypted value in place                 |
 | `info`    | print resolved configuration, auto-detection details, NODE_ENV mappings, and the env files that would load |
 | `expand`  | decrypt (if needed) and expand `${VAR}` / `$VAR` / `${VAR:-default}` / `${VAR:?msg}`   |
 
+#### Workflow + DX
+
+| command       | what it does                                                                                                     |
+| ------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `doctor`      | run health checks: workspace + config visible, env files exist, keys file present, every encrypted value decrypts, `required` keys filled after a dry load, expansion has no cycles. Exits non-zero on hard failures. CI-friendly. |
+| `template`    | emit a value-stripped `.env.example` from your real env files. `--check` mode exits 1 on drift; `--stdout` prints to stdout; `--annotate` (default on) tags each key with the source file. |
+| `diff <a> <b>` | compare two env files key-by-key. Reports keys-only-in-a, keys-only-in-b, and value mismatches. Decrypts via `.env.keys` so the comparison reflects logical values; values are masked unless `--show-values`. |
+| `hook <shell>` | print eval-able shell exports for the loaded env. Supports `bash`, `zsh`, `fish`, `powershell`/`pwsh` with proper escaping. Use `eval "$(envx hook bash)"` to inject env into the parent shell. |
+| `types`       | emit an `env.d.ts` declaring every loaded key on `NodeJS.ProcessEnv`. Keys listed in `required` (or non-optional in a Zod schema) narrow to `string`; everything else is `string \| undefined`. |
+| `watch`       | spawn a command and restart it whenever any of the resolved env files change. Debounce + SIGTERM-then-SIGKILL grace for clean restarts. |
+| `audit`       | walk the repo looking for plaintext secrets — AWS keys, GitHub PATs, Stripe live/test keys, JWTs, OpenAI / Anthropic keys, Google API keys, Slack tokens, PEM private-key blocks. Findings are redacted; exit 1 on any hit. `--json` for downstream tools. |
+| `bake`        | resolve every `${{provider:id}}` ref + decrypt every encrypted value + run defaults / expand / schema / public-mirror, then write a sealed `.env.resolved` for build tools to consume. Output is plaintext — refuses to write under `.git/`; use `--public-only` for client bundles. `--json` for structured tools, `--out=-` for stdout. |
+
 ### Global options
 
 | option            | alias            | default              | description                                                                              |
@@ -141,6 +227,7 @@ envx -c ./envx.config.json run -- node app.js
 | `--cascade`       |                  | _(off)_              | Cascade name; expands `.env`, `.env.<c>`, `.env.local`, `.env.<c>.local`.                |
 | `--override`      | `-o`             | `false`              | Override existing `process.env` values. Conflicts with `--cascade`.                      |
 | `--quiet`         | `-q`             | `true`               | Suppress dotenv's own output.                                                            |
+| `--profile`       | `-P`             | _(none)_             | Named profile from `profiles` in `envx.config.*` — fields override the base config per-field. |
 
 ### Defaults
 
@@ -430,7 +517,9 @@ Final value of process.env.SOME_KEY is the FIRST hit, top-down:
 
 ```ts
 // envx.config.ts
-export default {
+import { defineConfig } from "@super-repo/envx";
+
+export default defineConfig({
   // ── env-file selection ─────────────────────────────────
   envFiles: [".env", ".env.local"],   // bypass auto-detect; explicit list
   envPath: "vault",                    // workspace-relative subdir (cwd-first, ws-root fallback)
@@ -464,12 +553,44 @@ export default {
     PORT: "3000",
   },
 
+  // ── validation ─────────────────────────────────────────
+  schema: z.object({                     // any object exposing `safeParse(input) → { success, error?, data? }`
+    DATABASE_URL: z.string().url(),       // Zod is the obvious choice but envx duck-types — bring your own
+    PORT: z.coerce.number(),              // coerced values are written back to process.env
+  }),
+
+  // ── named profiles ─────────────────────────────────────
+  profiles: {                            // `--profile staging` (or programmatic `envx({ profile: "staging" })`)
+    staging: {                            // merges this object onto the base config per-field, profile wins
+      envFiles: [".env.staging"],
+      required: ["DB_URL"],
+    },
+    prod: {
+      envFiles: [".env.prod"],
+      cascade: true,
+      required: ["DB_URL", "API_KEY"],
+    },
+  },
+
+  // ── external secret refs ───────────────────────────────
+  resolvers: {                           // values like `${aws-secrets:my-id}` get passed to the resolver
+    "aws-secrets": (id: string) => {     // and replaced by its return. Sync — wrap async SDK calls externally.
+      return cachedAwsSecret(id);         // (e.g. pre-warm a cache before envx() runs in your bootstrap)
+    },
+  },
+
+  // ── public-variable mirroring (SSR / client-side bundlers) ─
+  publicPrefixes: ["VITE_", "NEXT_PUBLIC_"],  // duplicate every PUBLIC_* under each prefix
+  publicSource: "PUBLIC_",                     // (default) the prefix that marks a var as public
+
   // ── advanced ───────────────────────────────────────────
   workspaceRoot: "/abs/path/to/repo",   // escape hatch — skip findWorkspaceRoot() walk-up
-}
+})
 ```
 
-All fields are optional. Anything you omit falls through to the built-in default for that field.
+All fields are optional. Anything you omit falls through to the built-in default for that field. `defineConfig` is an identity helper — at runtime it just returns the object, but it gives editors full autocomplete and type-checking for `DotenvxConfig`. A plain `export default { … }` works too.
+
+> **Note:** `schema`, `profiles`, and `resolvers` are TS/JS-only — JSON configs can't carry callable functions. A `package.json#envx.config` reference must point at a `.ts` / `.mts` / `.js` / `.mjs` / `.cjs` file to use them.
 
 ### Discovery order
 
@@ -509,6 +630,371 @@ Expanded explanations, worked examples, and recipes ship with the package in [`.
 - **[Configuration](./docs/configuration.md)** — full schema, the per-field merge rules, where each field gets read from, and the discovery walk.
 - **[Monorepo recipes](./docs/recipes.md)** — common layouts (single workspace `.env.keys`, vault subdir, per-app overrides, CI patterns) with the exact files and commands.
 
+## Library API
+
+Beyond `envx()`, the package re-exports the building blocks the CLI uses internally — useful when you need to script the same behavior from your own tool, plugin, or test harness. Everything below is importable from the default entry:
+
+```ts
+import {
+  // Programmatic loader
+  envx,
+  type EnvxProgrammaticOptions,
+  type LoadEnvOptions,
+
+  // Audit (plaintext-secret scanner)
+  auditFiles,
+  BUILT_IN_PATTERNS,
+  type AuditFinding,
+  type AuditOptions,
+  type SecretPattern,
+
+  // Crypto primitives
+  ENCRYPTED_PREFIX,
+  generateKeyPair,
+  encryptValueAsymmetric,
+  decryptValueAsymmetric,
+  isEncrypted,
+
+  // Higher-level operations
+  encryptFiles,
+  decryptFiles,
+  rotateFiles,
+
+  // Env-file parser (line-preserving)
+  parseEnv,
+  serializeEnv,
+  toRecord,
+
+  // Variable expansion (cycle-safe)
+  expandRecord,
+  expandEnvSrc,
+
+  // Config + path resolution
+  defineConfig,
+  loadDotenvxConfig,
+  findWorkspaceRoot,
+  resolveCwdOrWorkspace,
+  resolveEnvPaths,
+  detectEnvironment,
+
+  // Keys-file management
+  readKeysFile,
+  writeKeysFile,
+  defaultKeysPath,
+} from "@super-repo/envx";
+```
+
+### Audit programmatically
+
+`envx audit` is a thin wrapper around `auditFiles()`. Use it directly to plug envx's secret detection into a pre-commit hook, a CI script, or your own dashboard:
+
+```ts
+import { auditFiles, type SecretPattern } from "@super-repo/envx";
+
+// Add custom patterns alongside the built-ins.
+const orgPatterns: SecretPattern[] = [
+  { id: "internal-token", label: "ACME internal token", regex: /\bacme_[A-Za-z0-9]{32}\b/ },
+];
+
+const { findings, filesScanned } = auditFiles({
+  roots: ["packages/", "apps/"],
+  ignore: ["fixtures", "snapshots"],
+  extra: orgPatterns,
+  max: 100,                       // 0 = unlimited
+});
+
+if (findings.length > 0) {
+  console.error(`audit: ${findings.length} finding(s) across ${filesScanned} files`);
+  process.exit(1);
+}
+```
+
+Findings are redacted (`AKIA…MPLE [redacted 20 chars]`) so the report itself never leaks the secret payload.
+
+### Custom profiles + resolvers in code
+
+When you need conditional behavior in a programmatic call (without a config file):
+
+```ts
+import envx from "@super-repo/envx";
+import { z } from "zod";
+
+const Schema = z.object({
+  DATABASE_URL: z.string().url(),
+  PORT: z.coerce.number().int().min(1).max(65535),
+});
+
+await preloadAwsSecretsCache();   // resolvers are sync — warm caches up front
+
+envx({
+  schema: Schema,
+  resolvers: {
+    "aws-secrets": (id) => awsSecretsCache.get(id),
+    "1password": (ref) => onePasswordCache.get(ref),
+  },
+  required: ["DATABASE_URL", "PORT"],
+  expand: true,                    // ${HOST}/api works after resolvers run
+});
+```
+
+Order of operations inside `envx()` once a profile / resolvers / schema are in play:
+
+```
+1. resolve workspaceRoot
+2. resolve env file paths
+3. load each env file              → mutates process.env (subject to `override`)
+4. apply `variables`               → unconditional overwrite
+5. run `resolvers` on ${provider:id} refs
+6. apply `defaults`                → only for keys still unset
+7. expand `${VAR}` references      (when `expand: true`)
+8. validate against `schema`       (when configured) — exits 1 on failure
+9. enforce `required`              (any unset → log + exit 1)
+```
+
+## Public variables (SSR + client bundlers)
+
+Modern frameworks each demand their own prefix for variables that should reach client-side code:
+
+| framework         | prefix          |
+| ----------------- | --------------- |
+| Vite              | `VITE_`         |
+| Next.js           | `NEXT_PUBLIC_`  |
+| Create React App  | `REACT_APP_`    |
+| Nuxt 3 (public)   | `NUXT_PUBLIC_`  |
+| SvelteKit (public)| `PUBLIC_`       |
+| Remix (loader)    | _(none)_        |
+
+Maintaining the same value under three different keys (`VITE_API_URL`, `NEXT_PUBLIC_API_URL`, `REACT_APP_API_URL`) is the kind of busywork envx exists to delete. Mark a variable "public" once with `PUBLIC_` (or any prefix you configure as `publicSource`), and envx mirrors it under every framework prefix at load time.
+
+```ts
+// envx.config.ts
+export default {
+  publicPrefixes: ["VITE_", "NEXT_PUBLIC_"],
+  // publicSource: "PUBLIC_"  // (default)
+}
+```
+
+```env
+# .env
+PUBLIC_API_URL=https://api.example.com
+PUBLIC_FEATURE_FLAG=true
+DATABASE_URL=secret-stuff       # not mirrored — no PUBLIC_ prefix
+```
+
+After `envx -- node app.js`, `process.env` looks like:
+
+| key                          | value                       | source          |
+| ---------------------------- | --------------------------- | --------------- |
+| `PUBLIC_API_URL`             | `https://api.example.com`   | original        |
+| `VITE_API_URL`               | `https://api.example.com`   | mirror          |
+| `NEXT_PUBLIC_API_URL`        | `https://api.example.com`   | mirror          |
+| `PUBLIC_FEATURE_FLAG`        | `true`                      | original        |
+| `VITE_FEATURE_FLAG`          | `true`                      | mirror          |
+| `NEXT_PUBLIC_FEATURE_FLAG`   | `true`                      | mirror          |
+| `DATABASE_URL`               | `secret-stuff`              | original (kept private — no mirror) |
+
+CLI flag for one-off use:
+
+```sh
+envx --public-prefix VITE_ --public-prefix NEXT_PUBLIC_ -- pnpm build
+```
+
+Mirroring runs **after** `expand`, so `${VAR}` references inside `PUBLIC_*` values resolve before being mirrored. Existing target keys are never overwritten — a `VITE_API_URL` already set in the parent shell wins over the auto-mirror.
+
+## Security models — when secrets are fetched
+
+Pick one based on where you want plaintext to live:
+
+| model                          | when secrets are fetched                | plaintext on disk?              | best for                                 |
+| ------------------------------ | --------------------------------------- | ------------------------------- | ---------------------------------------- |
+| **Encrypted-at-rest** (default)| process startup — `envx run --` decrypts via `.env.keys` | ciphertext only, in committed `.env*` | most apps — single binary, fast cold start |
+| **Load-time fetch** (resolvers)| process startup — plugins fetch via `resolvers:` | none — plaintext stays in process memory | server processes, long-running workers   |
+| **Build-time bake**            | once, in CI — `envx bake` writes `.env.resolved` | yes (in the build artifact) ⚠️   | static SPA bundles, public-only vars     |
+| **Runtime fetch** (edge)       | per cold start, lazily — `secrets.get()` on first read | none — secrets stay in the source-of-truth | edge functions, serverless, zero-trust   |
+
+The four models stack — most apps end up using two or more (e.g. encrypted-at-rest for non-secret config, runtime fetch for actual secrets).
+
+### Build-time bake (`envx bake`)
+
+```sh
+# CI step — resolves every encrypted value + ${provider:id} ref + ${VAR}
+# expansion + schema validation, then writes a sealed file the bundler picks up.
+envx bake --out dist/.env.resolved
+
+# Public-only mode for client bundles — only PUBLIC_* keys + their framework mirrors.
+envx bake --public-only --out dist/.env.public
+```
+
+⚠️ The output file is **plaintext**. envx writes a `# DO NOT COMMIT` banner and refuses to write under `.git/`, but you must add the path to `.gitignore` yourself. Use `--public-only` whenever the artifact will ship to clients.
+
+Build-tool integration:
+
+```ts
+// vite.config.ts
+import { defineConfig, loadEnv } from "vite";
+
+export default defineConfig(({ mode }) => {
+  // Vite's loadEnv reads .env.resolved like any other .env file.
+  const env = loadEnv(mode, process.cwd(), ".env.resolved");
+  return {
+    define: {
+      "import.meta.env.VITE_API_URL": JSON.stringify(env.VITE_API_URL),
+    },
+  };
+});
+```
+
+```sh
+# CI script
+envx bake --public-only --out .env.resolved && pnpm vite build
+```
+
+### Runtime fetch — edge / serverless
+
+For the "secrets never leave the source-of-truth" model, use `createSecretRuntime` from `@super-repo/envx-plugins/runtime`. Async-first, TTL caching, no `fs` / `child_process` dependencies — works in Cloudflare Workers, Vercel Edge, Deno Deploy, AWS Lambda, Bun, Node.
+
+```ts
+// src/secrets.ts — module-level singleton, one per worker
+import { createSecretRuntime } from "@super-repo/envx-plugins/runtime";
+import { hcVault } from "@super-repo/envx-plugins/vault";
+
+export const secrets = createSecretRuntime({
+  providers: [
+    hcVault({
+      endpoint: env.VAULT_ADDR,
+      token: env.VAULT_TOKEN,
+    }),
+  ],
+  ttl: 300,                    // refresh every 5 min
+  onFailure: "cache-stale",    // serve stale on transient backend failures
+});
+```
+
+```ts
+// src/handler.ts (Cloudflare Worker / Vercel Edge / Lambda — same shape)
+import { secrets } from "./secrets";
+
+export default async function handler(req: Request): Promise<Response> {
+  const dbUrl = await secrets.get("vault:prod/db");
+  const apiKey = await secrets.get("vault:prod/api");
+  // … handler logic …
+}
+```
+
+What you get:
+- **Lazy fetch** — first read triggers the network call. Subsequent reads within the TTL window hit memory.
+- **Single-flight** — N concurrent reads of the same ref coalesce into one fetch. Edge functions handling a burst of requests don't fan out N parallel calls to your secret store.
+- **TTL refresh** — values older than `ttl` seconds are refetched on next read. Set `ttl: Infinity` to cache forever; `ttl: 0` to fetch every read.
+- **Failure modes** — `"throw"` (default), `"cache-stale"` (serve previous value, log warning), or `"cache-error"` (cache the failure for `errorTtl` seconds so you don't hammer a failing backend).
+- **No fs / child_process imports** — the runtime entry point is V8-isolate-safe.
+
+### Compatibility note
+
+Plugin compatibility for the runtime entry depends on what each provider's transport needs:
+
+| provider           | edge runtime?               | reason                              |
+| ------------------ | --------------------------- | ----------------------------------- |
+| HashiCorp Vault    | ✓                           | native `fetch`                       |
+| Doppler            | ✓                           | native `fetch`                       |
+| Infisical          | ✓                           | native `fetch`                       |
+| AWS Secrets Manager| ⚠ Node-compat only           | `@aws-sdk/client-secrets-manager` uses Node streams |
+| GCP Secret Manager | ⚠ Node-compat only           | `@google-cloud/secret-manager` uses gRPC |
+| Azure Key Vault    | ⚠ Node-compat only           | `@azure/identity` token chain        |
+| 1Password (CLI)    | ✗                           | spawns the `op` binary               |
+| 1Password (SDK)    | depends on `@1password/sdk`  | check the SDK's runtime support       |
+
+For Cloudflare Workers / Vercel Edge / Deno: prefer Vault, Doppler, Infisical, or a custom HTTP `buildProvider`. AWS / GCP / Azure SDKs run fine in Lambda / Cloud Run / Cloud Functions but won't work in V8-only edges.
+
+## Secret-provider plugins
+
+Ship as a sibling package: [`@super-repo/envx-plugins`](https://www.npmjs.com/package/@super-repo/envx-plugins). Plugins return a `SecretProvider` you wire into envx's `resolvers:` config so values like `${aws-secrets:my-db}` and `${vault:prod/api}` fetch from the matching backend at load time.
+
+```ts
+import envx from "@super-repo/envx";
+import { awsSecrets, autoPreload, asResolvers } from "@super-repo/envx-plugins";
+
+const aws = awsSecrets({ region: "us-east-1" });
+
+await autoPreload([aws], { envFiles: [".env", "vault/.env.prod"] });
+
+envx({ resolvers: asResolvers([aws]) });
+```
+
+```env
+DATABASE_URL=${aws-secrets:prod/db}
+```
+
+Built-in providers: AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, HashiCorp Vault, 1Password (CLI + SDK), Doppler, Infisical. Each plugin lazy-loads its SDK — install only what you use. See the [`@super-repo/envx-plugins` README](../plugins/README.md) for per-provider setup.
+
+## Pre-commit hooks
+
+Three of the new commands (`audit`, `doctor`, `template --check`) are designed to compose into a single git pre-commit gate so secrets, broken configs, and stale `.env.example` files never reach the remote.
+
+The repo ships a reference `.hooks/pre-commit` you can adopt verbatim or copy into your own setup:
+
+```sh
+# Activate the in-repo .hooks/ directory (one-time per clone)
+git config core.hooksPath .hooks
+```
+
+That single config line tells git to look for hooks under `<repo>/.hooks/` instead of `.git/hooks/`. The directory is committed (everyone gets the same hooks), no third-party tool is required.
+
+The hook itself:
+
+```bash
+#!/usr/bin/env bash
+# .hooks/pre-commit
+set -euo pipefail
+[[ "${ENVX_SKIP_HOOK:-}" == "1" ]] && exit 0
+
+# Use the workspace binary if available, else a global envx
+if command -v pnpm >/dev/null && [[ -f package.json ]]; then
+  ENVX="pnpm exec envx"
+else
+  ENVX="envx"
+fi
+
+failed=0
+
+# 1. Audit staged files for plaintext secrets (AKIA, ghp_, sk_live_, JWTs, …)
+staged=$(git diff --cached --name-only --diff-filter=ACMR | tr '\n' ' ')
+[[ -n "$staged" ]] && ! $ENVX audit $staged && failed=1
+
+# 2. Workspace health (skip required-key gate so dev machines don't fail)
+$ENVX doctor --ignore-required || failed=1
+
+# 3. .env.example drift gate
+[[ -f .env ]] && ! $ENVX template --check && failed=1
+
+exit $failed
+```
+
+Bypass options:
+- `ENVX_SKIP_HOOK=1 git commit ...` — skip just the envx hook
+- `git commit --no-verify` — skip every git hook (use sparingly)
+
+The full annotated script lives at `.hooks/pre-commit` in this repo. CI should run the same three commands without the `--ignore-required` flag so missing required keys fail builds (not just commits).
+
+### Pre-push variant
+
+For a stricter gate that runs only on push (so commits stay fast but pushes are guarded):
+
+```bash
+#!/usr/bin/env bash
+# .hooks/pre-push — same checks, run against the whole repo, no skip.
+set -euo pipefail
+envx audit && envx doctor && envx template --check
+```
+
+### CI-friendly invocations
+
+```yaml
+# .github/workflows/secrets.yml
+- run: pnpm exec envx audit --json > audit.json
+- run: pnpm exec envx doctor                        # fails the build on missing required keys
+- run: pnpm exec envx template --check              # fails on .env.example drift
+```
+
 ## Embedding the CLI
 
 The yargs factory is exported under the `./commands` subpath if you want to register envx's commands inside your own tool:
@@ -542,13 +1028,21 @@ packages/envx/core/
 │   │   └── dotenvx.ts      # `dotenvx-proxy` direct passthrough to upstream
 │   └── commands/
 │       ├── index.ts        # createCli — registers subcommands + global options
-│       ├── run.ts          # `run [command..]`
-│       ├── print.ts        # `print <variable>`
-│       ├── debug.ts        # `debug`
-│       ├── encrypt.ts      # `encrypt`
+│       ├── run.ts          # `run [command..]`     — load env + spawn
+│       ├── print.ts        # `print <variable>`    — print one value
+│       ├── debug.ts        # `debug`               — show resolved paths
+│       ├── encrypt.ts      # `encrypt`             — incl. --pattern / --secrets
 │       ├── decrypt.ts      # `decrypt`
-│       ├── rotate.ts       # `rotate`
-│       └── expand.ts       # `expand`
+│       ├── rotate.ts       # `rotate`              — refresh keypair across files
+│       ├── expand.ts       # `expand`              — resolve ${VAR} on stdout
+│       ├── info.ts         # `info`                — print resolved config
+│       ├── doctor.ts       # `doctor`              — health checks (CI gate)
+│       ├── template.ts     # `template`            — emit/check .env.example
+│       ├── diff.ts         # `diff <a> <b>`        — keys + value mismatches
+│       ├── hook.ts         # `hook <shell>`        — eval-able shell exports
+│       ├── types.ts        # `types`               — emit env.d.ts
+│       ├── watch.ts        # `watch -- <cmd>`      — restart on env change
+│       └── audit.ts        # `audit`               — plaintext-secret scanner
 ├── tests/
 │   ├── *.test.ts           # unit suites
 │   └── integration/

package/dist/auto.js.map

@@ -1 +1 @@
-{"version":3,"file":"auto.js","names":[],"sources":["../src/auto.ts"],"sourcesContent":["// #region -- Side-effect entry point ----------------------\n\n// `import \"@honeycluster/envx/auto\"` (or \"/config\") loads .env into\n// process.env on import — same ergonomics as `import \"dotenv/config\"`.\n// Picks up envx.config.* and the package.json `envx.config` discovery\n// chain automatically. Use the named/default export from the package\n// root when you want an explicit handle.\n\nimport envx from \"./index.js\";\n\nenvx();\n\n// #endregion -----------------------------------------------\n"],"mappings":";;AAUA,MAAM"}
+{"version":3,"file":"auto.js","names":[],"sources":["../src/auto.ts"],"sourcesContent":["// #region -- Side-effect entry point ----------------------\n\n// `import \"@super-repo/envx/auto\"` (or \"/config\") loads .env into\n// process.env on import — same ergonomics as `import \"dotenv/config\"`.\n// Picks up envx.config.* and the package.json `envx.config` discovery\n// chain automatically. Use the named/default export from the package\n// root when you want an explicit handle.\n\nimport envx from \"./index.js\";\n\nenvx();\n\n// #endregion -----------------------------------------------\n"],"mappings":";;AAUA,MAAM"}