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

package/docs/library-api.md

@@ -0,0 +1,121 @@
+# 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
+  respectGitignore: true,         // default — skip anything matched by .gitignore / .git/info/exclude
+});
+
+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)
+```

package/docs/public-variables.md

@@ -0,0 +1,49 @@
+# 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.

package/docs/security-models.md

@@ -0,0 +1,103 @@
+# 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.

package/docs/template.md

@@ -0,0 +1,87 @@
+# `envx template`
+
+Generate a `.env.example` from your real env files. The output mirrors the source's organization — comments, blank lines, and declaration order are preserved verbatim. Values are stripped (or replaced with AI-generated placeholders when `--ai` is set).
+
+## What gets dropped
+
+- The encryption banner block — any line starting with `#/` (the four-line `#/-------------------[ENVX_PUBLIC_KEY]----------------------/` decoration emitted by `envx encrypt`).
+- `ENVX_PUBLIC_KEY*` and `DOTENV_PUBLIC_KEY*` kv lines themselves. The example file is encryption-agnostic; consumers don't need a public key to hand-edit a copy.
+
+Everything else passes through:
+
+```env
+# === Database ===
+DATABASE_URL=postgres://prod        # primary connection
+DATABASE_POOL=10
+
+# === Auth ===
+API_KEY=sk_live_abc123
+```
+
+becomes:
+
+```env
+# === Database ===
+DATABASE_URL=        # primary connection
+DATABASE_POOL=
+
+# === Auth ===
+API_KEY=
+```
+
+## `--ai` — generate placeholder values
+
+Pass `--ai` to populate each `KEY=` with a realistic-looking-but-obviously-fake placeholder. envx loads your env files first (decrypting via `.env.keys` automatically), then reads `ANTHROPIC_API_KEY` from `process.env` to call Claude. One API call covers the entire key set — keys + their trailing comments are sent as hints; Claude returns a JSON map; the renderer drops the values into the template.
+
+```sh
+envx template --ai                                    # default: anthropic + claude-haiku-4-5-20251001
+envx template --ai --ai-model claude-sonnet-4-6       # bigger model
+envx template --ai --ai-provider openai               # use OPENAI_API_KEY instead
+```
+
+### API key lookup
+
+Same chain as `@super-repo/czar`'s AI integration:
+
+1. `process.env[apiKeyEnv]` (default `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`)
+2. For Anthropic: `CLAUDE_CODE_OAUTH_TOKEN`, then `ANTHROPIC_AUTH_TOKEN` (subscription / Claude-Code-style bearer tokens are detected by their `sk-ant-oat` prefix and sent via `Authorization: Bearer` instead of `x-api-key`)
+
+The whole point of envx loading the env first is so the API key can live in your `.env` (encrypted, even) rather than the shell environment. Anywhere envx normally finds a value, the AI client will find the key.
+
+### Determinism + `--check`
+
+`--ai` is not deterministic — Claude returns slightly different placeholder values per run. Don't pair it with `--check` (the on-disk file would always drift). Typical workflow:
+
+- Local dev: `envx template --ai` once, review, commit.
+- CI: `envx template --check` (no `--ai`) — verifies the structure is up to date with the source `.env*` files. The committed AI placeholder values stay put.
+
+If you want CI to also regenerate values, drop `--check` and rely on a separate "fix-up" PR.
+
+## Multi-file source
+
+When the resolved env-file list has more than one entry (e.g. `--cascade prod` expands to `.env`, `.env.prod`, `.env.local`, `.env.prod.local`), each file gets its own section header:
+
+```env
+# Generated by `envx template` — do not edit by hand.
+# Run `envx template` to regenerate, or `envx template --check` in CI.
+
+# ── .env ─────────────────────────────────
+DATABASE_URL=
+LOG_LEVEL=
+
+# ── .env.prod ─────────────────────────────────
+DATABASE_REPLICAS=
+```
+
+Keys are deduplicated across files: the first occurrence wins. Subsequent files' comments and blank lines still pass through (so each section's structure stays visible), but duplicate kv lines are skipped.
+
+## Flags
+
+| flag                    | default                         | what it does                                                                                          |
+| ----------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `--out <path>`          | `.env.example`                  | Output path (relative to cwd).                                                                        |
+| `--stdout`              | `false`                         | Print to stdout instead of writing.                                                                   |
+| `--check`               | `false`                         | Compare on-disk template vs regenerated; exit 1 on drift.                                             |
+| `--ai`                  | `false`                         | Populate example values via Claude. Requires an API key (see lookup chain above).                     |
+| `--ai-provider`         | `anthropic`                     | `anthropic` or `openai`.                                                                              |
+| `--ai-model <model>`    | `claude-haiku-4-5-20251001` / `gpt-4o-mini` | Override the model. Defaults pick the smallest sensible model per provider.                           |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@super-repo/envx",
   "description": "A global executable to run applications with the ENV variables witin a monorepo loaded by dotenvx",
-  "version": "0.2.3-b.5",
+  "version": "0.2.3-b.6",
   "type": "module",
   "bin": {
     "envx": "./dist/cli.js",
@@ -48,6 +48,7 @@
   "dependencies": {
     "@dotenvx/dotenvx": "^1.49.1",
     "eciesjs": "^0.4.10",
+    "ignore": "^5.3.2",
     "yargs": "^17.7.0",
     "zod": "^3.25.0"
   },
@@ -60,8 +61,8 @@
     "vite": "^8.0.11",
     "vite-plugin-dts": "^5.0.0",
     "vitest": "^4.1.5",
-    "@super-repo/cli": "0.2.3-b.5",
-    "@super-repo/envx-libs": "0.0.1",
-    "@super-repo/envx-common": "0.0.1"
+    "@super-repo/cli": "0.2.3-b.6",
+    "@super-repo/envx-common": "0.0.1",
+    "@super-repo/envx-libs": "0.0.1"
   }
 }