spfn 0.3.0-beta.12 → 0.3.0-beta.13

package/README.md

@@ -396,9 +396,29 @@ TLS by itself and `sslmode=disable` remains authoritative.
 
 ### `spfn env`
 
-Schema-driven environment variable tooling (schema comes from a package's `envSchema`,
-default `@spfn/core`). Routes vars to the right file: `NEXT_PUBLIC_*` → `.env`/`.env.local`,
-server vars → `.env.server`.
+Schema-driven environment variable tooling. Routes vars to the right file: `NEXT_PUBLIC_*`
+→ `.env`/`.env.local`, server vars → `.env.server`.
+
+Without `-p`, every subcommand reads the **whole-app list**: the app's own schema modules
+named in `spfn.config.js` under `env.schemas`, then every installed `@spfn/*` package whose
+`./config` exports `envSchema` (found through the app's `package.json`, resolved from the
+project root). Output is grouped by the source that declares each variable.
+
+```js
+// spfn.config.js
+export default {
+  env: {
+    // Modules exporting `envSchema`, relative to the project root.
+    // TypeScript and tsconfig path aliases load the way `spfn dev` loads them (tsx).
+    schemas: ['src/server/config/env.config.ts'],
+  },
+};
+```
+
+A variable declared by two sources alike is listed once. Two sources that declare it with a
+different type, `required` or `sensitive` are an error naming the key and both sources. A schema path that does not exist, or a
+module without an `envSchema` export, is an error naming the path. Top-level `env` is not
+`deployment.env`: the latter holds values to inject, the former says where the schemas are.
 
 | Subcommand | Description |
 |------------|-------------|
@@ -408,8 +428,41 @@ server vars → `.env.server`.
 | `env init` | Generate `.env` template files (`-e <env>` for per-env, `-f` to overwrite) |
 | `env check` | Check `.env` files against the schema (`-e <env>` for a full env chain) |
 | `env validate` | Validate `process.env` against the schema — for CI/CD (`-e <env>`, `-s` strict) |
+| `env audit` | Find direct `process.env` reads and app variables nothing reads; exits 1 on findings |
+
+All but `env audit` accept `-p, --package <pkg>` to read that one package only (`env validate` uses
+`-p, --packages <pkgs...>`).
+
+**Audit.** `spfn env audit` prints `file:line  NAME  reason` — names only — and exits 1 when
+it finds any of:
+
+- a direct read — `process.env.X`, `process.env['X']`, `process.env[expr]`,
+  `const { X } = process.env` — outside the `env.schemas` modules, root-level
+  `*.config.{js,cjs,mjs,ts}` files and `env.audit.ignore` (`NODE_ENV` is always allowed);
+- a name in the app's own schemas that no scanned file reads as a property (`env.X`), a
+  destructured key or a string literal, and that has no `readBy` (see the `@spfn/core/env`
+  README); a `readBy` file that does not exist or is not scanned. Skipped, with a notice,
+  when `env.schemas` is not set.
+
+A list that cannot be built — a missing schema module, or a name declared differently by an
+app schema and a package — is reported and exits 1.
+
+```js
+// spfn.config.js
+export default {
+  env: {
+    schemas: ['src/server/config/env.config.ts'],
+    audit: {
+      include: ['src'],             // default — directories or globs from the project root
+      ignore: ['src/**/*.test.ts'],
+    },
+  },
+};
+```
 
-All accept `-p, --package <pkg>` (`env validate` uses `-p, --packages <pkgs...>`).
+`node_modules`, build output, `*.d.ts` and symbolic links are never scanned. Sources —
+`.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs`, `.mts`, `.cts` — are parsed with TypeScript,
+taken from the app, else from the CLI's optional peer, else from `@spfn/core`.
 
 ### `spfn key [preset]`
 
@@ -436,16 +489,55 @@ reads plain `process.env`.
 
 | Subcommand | Description |
 |------------|-------------|
-| `secret set [key]` | Store a value (masked prompt). `--env local` → keychain; other envs → SOPS |
-| `secret list` | List declared secrets and their status per env (never prints values) |
+| `secret set [key]` | Store a value (masked prompt, or `--stdin`). `--env local` → keychain; other envs → SOPS |
+| `secret list` | List declared secrets and their status per env; names in a deployed file that the list lacks show as "not in list" (never prints values) |
 | `secret generate [key]` | Mint values for schema secrets with a `generate` strategy (`-a/--all`) |
 | `secret rotate [key]` | Rotate values; external secrets are flagged for manual reissue (`-a/--all`) |
 | `secret keygen` | Generate an age key pair for the SOPS no-cloud backend |
 | `secret recipients <add\|remove\|list> [age1…]` | Manage `.sops.yaml` recipients + re-encrypt |
-| `secret check` | Static lint — flag plaintext secret leaks |
+| `secret check` | Static lint — flag plaintext secret leaks; with a deployed `--env`, names in the wrong layer's file |
+| `secret export` | Decrypt and merge one deployment's layers into a 0600 dotenv file (prints names only) |
 
 Options: `-e, --env <env>` (`local` default; also `development`/`staging`/`production`),
-`-p, --package <pkg>` (schema source, default `@spfn/core`).
+`-i, --instance <name>` (one instance of a deployed environment: `secrets/<env>.<instance>.enc.json`;
+lowercase letters, digits and dashes), `-p, --package <pkg>` (read that one package's
+schema; without it, the whole-app list described under `spfn env`).
+
+**`--stdin`.** `spfn secret set --stdin --env staging SIGNING_KEY < key.pem` stores the
+whole of stdin as the value — one trailing newline dropped, inner newlines kept — for
+local and deployed targets alike. It never prompts, and refuses a terminal on stdin.
+Shaped values such as key pairs come from the app's own command, piped in.
+
+**Layers.** A schema entry's `layer` (`'environment'` default, or `'instance'`) says where a
+deployment's value comes from. Without `--instance`, `set`/`generate`/`rotate`/`list` on a
+deployed environment work on the `environment` names in `secrets/<env>.enc.json`; with
+`--instance blue`, on the `instance` names in `secrets/<env>.blue.enc.json`. A named key of
+the other layer is refused.
+
+**Export.**
+
+```bash
+spfn secret export --env <env> [--instance <name>] [--with <file>]... --out <file>
+```
+
+Decrypts `secrets/<env>.enc.json` and — with `--instance`, when it exists —
+`secrets/<env>.<instance>.enc.json`, reads each plaintext `--with` dotenv file (computed
+instance values such as port and URLs), and writes the merge to `--out`. Only names in the
+whole-app list are written; an unlisted name in an encrypted file is a warning by name.
+The export fails, writing nothing, when a required name is in no layer, a name is in two
+layers, an `instance` name is in the environment file, an `environment` name is in an
+instance layer, a value fails its validator (the error names the variable and the
+reason, never the value), or decryption fails. `--out` is required and its directory must
+exist; relative paths resolve from the working directory. The file is created 0600 beside
+the destination and renamed over it, so a failure leaves the previous file untouched
+(POSIX only — Windows does not enforce the mode).
+
+**SOPS rules for instance files.** The rule `spfn secret recipients add` writes,
+`secrets/.*\.enc\.json$`, already covers `secrets/<env>.<instance>.enc.json`. A project
+with per-environment rules needs each to accept the instance form too, e.g.
+`path_regex: secrets/production(\.[a-z0-9-]+)?\.enc\.json$`. Writes need sops 3.10 or
+later (`sops encrypt` from stdin, `sops set --value-stdin`), so a value never appears as a
+process argument.
 
 **Local (keychain).** `spfn secret set DB_URL` stores the value in the OS keychain
 (macOS `security`, Windows Credential Manager via optional `@napi-rs/keyring`, Linux