@mccaskie-labs/workbench-config 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @mccaskie-labs/workbench-config
 
+## 0.1.1
+
+### Patch Changes
+
+- Ship the config guide (`capabilities/config.md`) with the manifests.
+
 ## 0.1.0
 
 - First release: `workbenchEnv`, `defineConfig`, `workerSecret`, `sharedSecret`, `redact`, `redactAll`, the capabilities manifests (`gateway`, `config`, `ai`) with `capabilitySchema`, and the `workbench-config check` CLI.

package/capabilities/config.md

@@ -0,0 +1,23 @@
+# Config
+
+Every Workbench app reads its settings through `@mccaskie-labs/workbench-config`, so a missing or wrong variable stops the app at startup with the variable's name, and no value ever reaches a log or an error.
+
+## The environment
+
+`WORKBENCH_ENV` is `development`, `staging` or `production`. It is required in every environment and has no fallback: not `NODE_ENV`, not a default. The Gateway key's own environment must match it (`gateway.key-per-environment`).
+
+## Declaring variables
+
+Declare every variable the app reads with `defineConfig`, once, at module level, and call `parse(env)` in the handler. Use zod to say what a valid value looks like: `z.string().startsWith('wbk_')` for a Gateway key, `z.coerce.number()` for numbers, `.default()` for optional settings.
+
+An empty string counts as missing, so a blank line in `.dev.vars` fails the same way as no line.
+
+## Secrets
+
+- Worker secrets: read them through `defineConfig` or `workerSecret(env, name)`.
+- Secrets Store bindings: `await sharedSecret(env.BINDING, 'NAME')`.
+- Logging anything near a secret: `redact(value)` or `redactAll(text, [secrets])`. Both write `[redacted]` and keep nothing of the value.
+
+## Local development
+
+`.dev.vars` holds local values and is gitignored. `.dev.vars.example` lists the same names with no values and is committed. `npx workbench-config check` compares the two and prints names only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mccaskie-labs/workbench-config",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Workbench app configuration: WORKBENCH_ENV, typed variables that fail by name, secrets that are never printed, and the capabilities manifest.",
   "license": "UNLICENSED",
   "type": "module",