spfn 0.3.0-beta.13 → 0.3.0-beta.15

package/README.md

@@ -495,7 +495,7 @@ reads plain `process.env`.
 | `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; with a deployed `--env`, names in the wrong layer's file |
+| `secret check` | Static lint — flag plaintext secret leaks; with a deployed `--env`, names outside their declared layer or in both files |
 | `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`),
@@ -508,11 +508,15 @@ whole of stdin as the value — one trailing newline dropped, inner newlines kep
 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.
+**Layers.** A schema entry's `layer` (`'environment'` or `'instance'`) pins where a
+deployment's value must live; unset, the value may come from any layer. Without
+`--instance`, `set`/`generate`/`rotate`/`list` on a deployed environment work on
+`secrets/<env>.enc.json`; with `--instance blue`, on `secrets/<env>.blue.enc.json`. A named
+key declared with the other layer is refused; a key without `layer` is accepted by either.
+`--all` (and `list`) takes the names declared with the target's layer, and names without
+`layer` on the environment target only — so `--all --instance blue` never fills an
+instance file with names every instance shares. To give each instance its own value of
+such a name, set it by name with `--instance`.
 
 **Export.**
 
@@ -525,8 +529,8 @@ Decrypts `secrets/<env>.enc.json` and — with `--instance`, when it exists —
 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
+layers, a name declared `instance` is in the environment file, a name declared
+`environment` 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
@@ -681,6 +685,39 @@ Because the package is the app's, it is resolved **from the directory the comman
 Run `spfn ops token` from the app's root; running it elsewhere reports the package as
 missing, and the message names the directory it looked in.
 
+#### Can I call a surface from my own code?
+
+Yes — the client `spfn ops` runs on is a library export, `spfn/surface`, and it reaches any
+namespace a [`defineSurface`](../core/README.md#can-a-second-surface-sit-beside-_ops)
+serves, not only `/_ops`:
+
+```typescript
+import { createSurfaceClient } from 'spfn/surface';
+
+const client = createSurfaceClient({
+    appUrl: 'https://app.example',
+    namespace: '/_app',                               // manifest at /_app/_manifest
+    token: async () => issueToken(),                  // string | () => Promise<string>
+    onWarning: message => console.error(message),    // dropped commands; default: silent
+});
+
+const manifest = await client.manifest();
+const usage = client.describe(manifest, 'pageAdd');  // the --describe text
+const answer = await client.call('pageAdd', { params: {}, query: {}, body: { title: 'Hello' } });
+// answer: { status, body } — the app's answer, relayed
+```
+
+It keeps every check `spfn ops` makes: the manifest's shape, each command's path staying
+under `<namespace>/`, module metadata, and path parameters that would decode into a dot
+segment. `appUrl` must be https (`http` only against a loopback host) — refused when the
+client is created, with a thrown `Error`. A manifest request that does not answer 200
+throws a `SurfaceManifestError` carrying the `status`. The library prints nothing and does
+not load the CLI's terminal stack; `spfn ops` is this client on `/_ops` with its own
+printer.
+
+The `spfn` package has an `exports` map: `spfn` (the CLI's index), `spfn/surface`, and
+`spfn/package.json`. No other path inside the package is importable.
+
 ### `spfn kit`
 
 Install, verify and update a **Superfunction Kit** — a licensed product that ships as a