@skitterbyte/skitterspec 20.0.0 → 22.0.0

package/assets/core/env.config.md

@@ -21,8 +21,27 @@ port block, and no `.env`.
 exactly as it does today.
 
 The loader (`src/env/config.js` → `loadEnvConfig`) merges your file over the
-frozen defaults below and returns `{ config, present }`; `present:false` means
-no live `env.config.json` was found.
+frozen defaults below and returns `{ config, present, unknown }`;
+`present:false` means no live `env.config.json` was found.
+
+**A key not listed below is ignored — and says so.** Every `spec-env` command
+prints one advisory line per unrecognised key, top-level or nested:
+
+```
+spec-env: env.config.json — unknown key "docker.portbase" is ignored.
+```
+
+It is advisory in the strongest sense: the key is dropped exactly as it always
+was, nothing refuses, and the exit status is unchanged. It exists because the
+two things an unknown key can be — a deliberate forward-compat entry and a typo
+— are indistinguishable from here, and only one of them is a mistake you would
+want to hear about. A mis-typed `review.required` leaves the commit gate on and
+a mis-typed `teardown.deleteRemoteBranch` reverts to `prompt`; before this, the
+only signal either gave was that nothing happened.
+
+A **known** key whose value is rejected — `mode: "Checkout"`,
+`teardown.deleteRemoteBranch: "yes"` — is not reported here. Each of those falls
+through to a documented conservative default; see the field notes below.
 
 ## Fields
 
@@ -74,8 +93,9 @@ no live `env.config.json` was found.
   // `spec-env up`, right after `git worktree add` and BEFORE `setup` runs — so a
   // fresh linked worktree (which starts with none of the repo's gitignored files)
   // has the .env / local secret overrides / local config that setup steps and
-  // git hooks depend on. Without this a step like `prisma generate` hard-fails in
-  // the new worktree because .env (its datasource URL) isn't there.
+  // git hooks depend on. Without this any setup step that reads .env — a schema
+  // or client generator, a codegen pass — hard-fails in the new worktree
+  // because the file it expects isn't there.
   //   mode   "symlink" (default) points the worktree file at the main file, so it
   //          stays in sync; "copy" makes an independent copy.
   //   files  repo-relative paths to seed. A source absent in main is a printed
@@ -221,13 +241,15 @@ no live `env.config.json` was found.
 
   // Reading a spec's diff (`spec-env review`, `/spec-diff`).
   //
-  // `reader` decides how the page's LOCATION IS WORDED, and — through
-  // `serveOnRemote` below — whether the engine stands its local server up so a
-  // remote reader gets a link that opens. It never decides to PUBLISH. Three
-  // values:
-  //   "local"  — you are at the machine holding the page; a file:// URL opens.
-  //   "remote" — you are not; it does not, so the page is served instead.
-  //   "detect" — work it out (the default).
+  // `reader` decides how the page's LOCATION IS WORDED. It no longer decides
+  // the bind — `allowNetwork` does, see below — and it no longer decides which
+  // tiers are offered, because every tier is now listed whatever it says.
+  // WHAT THE SERVER
+  // BINDS TO — and nothing else. It never decides whether to serve (`serve`
+  // does) and never decides to PUBLISH. Three values:
+  //   "local"  — you are at the machine holding the page; it binds 127.0.0.1.
+  //   "remote" — you are not; it binds every interface so the page opens.
+  //   "detect" — work it out (the default); cannot-tell binds 127.0.0.1.
   // An explicit "local"/"remote" is BELIEVED WITHOUT SNIFFING: you know where
   // you are reading, and no signal outranks being told. Detection is only the
   // default, and it has three outcomes rather than two — local, remote, and
@@ -237,25 +259,81 @@ no live `env.config.json` was found.
   // unrecognised value falls through to "detect", so a typo cannot become a
   // confident answer. Default: detect.
   //
-  // `servePort` is the default port for `spec-env review serve`, which renders
-  // every spec's diff per request on one local server. `--port` overrides it per
-  // run. The server binds 127.0.0.1 unless `--host 0.0.0.0` is passed, which
-  // mints an unguessable path token and prints the LAN URL including it —
-  // anyone holding that URL can read every spec's diff while it runs.
-  // Default: 7777.
+  // `servePort` is the port for `spec-env review serve`, which renders every
+  // spec's diff per request on one local server. Two forms:
+  //
+  //   "auto" (the default) — derive it from this repo's path, as
+  //     7700 + hash(realpath(repoRoot)) % 100. Two repos on one machine stop
+  //     competing for one shared port without anyone configuring anything, and
+  //     — the part that matters — THE SAME REPO GETS THE SAME PORT EVERY TIME.
+  //     The derivation reads nothing on disk, so the port survives a restart, a
+  //     reboot and a `--stop`, which is what lets a link handed out yesterday
+  //     still resolve. A symlinked spelling of the tree resolves first, so one
+  //     repo never lands on two ports.
+  //   <a number> — pin it. An explicit number always wins, and pinning is what
+  //     you do when you want a port you can memorise, or when two repos derive
+  //     the same one.
   //
-  // `serveOnRemote` is whether a "remote" reader may have that server started
-  // FOR them. On (the default) the engine brings it up, binds 0.0.0.0, and puts
-  // the served URL on the `open:` line — best-guess network address first, the
-  // rest listed under it, because the guess reads interface names and a VPN or
-  // an unusual adapter will fool it. Off, you get the file:// URL with its
-  // "will not open where you are reading" marker and the command to type.
+  // A derived port CAN still collide — a hundred slots is a small chance, not
+  // no chance — and the server refuses rather than moving itself aside. The fix
+  // it names is `servePort`, because that is what the next link is built from;
+  // `--port` moves one run and leaves every link already handed out pointing at
+  // the busy port. `spec-env review serve --status` prints the port and which
+  // of the three chose it.
+  //
+  // An unrecognised value falls through to "auto", like every other typed key
+  // here. Default: "auto".
+  //
+  // The server binds 127.0.0.1 unless `--host 0.0.0.0` is passed, which mints
+  // an unguessable path token and prints the LAN URL including it — anyone
+  // holding that URL can read every spec's diff while it runs.
+  //
+  // `serve` is whether a render stands the local server up at all:
+  //   "always" — every render does (the default), so `local:` and `network:`
+  //              are both http URLs the page can POST a verdict back to. The
+  //              LAN address comes first with the rest listed under it, because
+  //              the guess reads interface names and a VPN or an unusual
+  //              adapter will fool it.
+  //   "never"  — `local:` is a file:// URL instead. Note what that costs: a
+  //              file:// page has no server to POST to, so its verdict buttons
+  //              copy a command for you to paste rather than sending anything.
+  // It replaced `serveOnRemote`, which gated serving on the reader — and so
+  // handed a local machine a page it could read and not answer. A legacy
+  // `serveOnRemote: false` is still read as `serve: "never"`.
   // Either way NOTHING IS PUBLISHED on a detection: a server is one process
   // ended by one flag, while a published page is one this tooling cannot
   // remove, so that half stays an explicit ask. Teardown names a server that
   // served the last spec, and `spec-env prune` reaps a pidfile whose process is
   // gone. Default: true.
   //
+  // `allowNetwork` and `allowRemote` decide WHICH TIERS a render offers, and
+  // they replaced the engine guessing where the reader was sitting. It guessed
+  // for a while and got it wrong three separate ways in one day: a file:// page
+  // on a session detected `unknown`, a LAN URL for a phone that had left the
+  // network, and an address that changed underneath a reader mid-session. So
+  // every tier is listed, labelled, and either a URL or the one command that
+  // turns it on — and you pick the one that reaches you.
+  //
+  //   `allowNetwork` — whether the review server binds EVERY INTERFACE, so the
+  //                    page opens on your phone, or loopback only. THIS IS WHAT
+  //                    CHOOSES THE BIND; `reader` no longer does. Default: true,
+  //                    which matches what the engine already did.
+  //   `allowRemote`  — whether PUBLISHING is permitted at all. It permits it; it
+  //                    publishes nothing. Default: FALSE, because a published
+  //                    page is one skitterspec cannot delete, so it must never
+  //                    happen unasked.
+  //
+  // `local` and `network` are two doors into ONE ROOM — the page POSTs to
+  // `location.pathname`, so both reach the same server and the same waiting
+  // verdict, and one wait covers both. `remote` is a second store: a verdict
+  // pressed on a published page needs `/spec-reviewed`, because nothing pushes
+  // from an artifact's store into a conversation.
+  //
+  // Both are toggled by `spec-env review allow <tier> --set [on|off]`, where an
+  // empty value toggles — which is what `/spec-remote-review` runs. It writes
+  // THIS FILE in the primary checkout, so it changes for everyone who pulls and
+  // leaves that tree dirty; the engine says so when it does.
+  //
   // `commitWith` names the skill a COMMITTING verdict hands off to. A review
   // page ends in a verdict — commit, commit & continue, request changes,
   // discuss — and the point of the first two is that the commit follows from
@@ -288,8 +366,8 @@ no live `env.config.json` was found.
   // place rather than quietly disabling it. Default: true.
   "review": {
     "reader": "detect",
-    "servePort": 7777,
-    "serveOnRemote": true,
+    "servePort": "auto",
+    "serve": "always",
     "commitWith": "/commit",
     "required": true
   }