@nexusbloom/cli 0.9.1 → 0.9.2

package/README.md

@@ -332,8 +332,7 @@ npm run test:watch    # re-run on change
 ```
 
 The suite runs fully offline and is isolated from your real config, API key and
-network — both properties are enforced by guard tests, not assumed. See
-[TESTING.md](./TESTING.md) for the harness and its gotchas.
+network — both properties are enforced by guard tests, not assumed.
 
 ## Security Notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexusbloom/cli",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "NexusBloom CLI — run tools and workflows from your terminal",
   "type": "module",
   "bin": {
@@ -9,8 +9,7 @@
   "files": [
     "src/",
     "package.json",
-    "README.md",
-    "TESTING.md"
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"

package/TESTING.md

@@ -1,125 +0,0 @@
-# Testing the CLI
-
-The test suite runs entirely offline and never touches a developer's real
-config, credentials or network. Both of those properties are enforced, not
-assumed — see [Leak guards](#leak-guards).
-
-```bash
-npm test              # run everything
-npm run test:coverage # run everything with a coverage report
-npm run test:watch    # re-run on change
-node --test --import ./test/setup.mjs test/pipe.test.js   # one file
-```
-
-## The isolation harness
-
-Every test file is launched with `--import ./test/setup.mjs`. That module runs
-**before any `src/` file is loaded**, which is the only moment it can work:
-`paths.js` and `API_BASE` are evaluated at import time, so isolation set up
-inside a test file would already be too late.
-
-`test/setup.mjs` gives each test file:
-
-| | |
-|---|---|
-| `XDG_CONFIG_HOME` / `XDG_CACHE_HOME` | a fresh `mkdtemp` directory, so tests read and write a throwaway config instead of yours |
-| `HOME` | masked, so any fallback path cannot reach your real home |
-| `NEXUSBLOOM_API_URL` | `https://api.nxb.invalid` — `.invalid` is reserved by RFC 2606, so a request that escapes a stub fails instead of reaching production |
-| `NEXUSBLOOM_API_KEY`, `NEXUSBLOOM_SUPABASE_ANON_KEY` | deleted, so a test can never spend your key |
-| `NXB_NO_INTERACTIVE`, `CI` | set, so no prompt can block a run |
-| `NEXUSBLOOM_TELEMETRY` | deleted, so no test can phone home |
-| `process.stdin` | replaced with a double that is **not** a TTY but does emit `end` |
-
-That last row is subtle and load-bearing. `readStdin()` resolves on `end`, or
-immediately when stdin is a TTY. Under `node --test` stdin is a pipe that is
-never closed, so `end` never arrives and any test reaching `readStdin()` waits
-forever — which surfaces as an 800-second file timeout rather than a failing
-assertion. The double has to satisfy three things at once: stay non-TTY so
-`isInteractive()` is correctly false, deliver `end` to a listener that attaches
-later, and hold no OS handle so the file can still exit. A test that wants piped
-input uses `withStdin()`.
-
-## Helpers
-
-| helper | use |
-|---|---|
-| `helpers/net.js` | `resetNetwork()` · `route/json/text/status` · `calledWith` · `calls` |
-| `helpers/output.js` | `captureOutput(fn)` · `captureBoth(fn)` → `{value, stdout, stderr}` |
-| `helpers/cli.js` | `withExitCode(fn)` → `{value, exitCode}` |
-| `helpers/stdin.js` | `withStdin(text, fn)` |
-| `helpers/capture.js` | `captureIO` — string chunks only |
-| `helpers/ui-double.mjs` | scripted stand-in for the interactive prompts |
-| `helpers/ui-hook.mjs` | `module.register` hook that redirects only `run.js`'s `./ui.js` import |
-
-## Gotchas
-
-Each of these cost real debugging time. They are properties of the runner and
-the harness, not opinions.
-
-**`node --test` writes its own protocol to stdout as Buffers.** A capture helper
-that decodes Buffers into the captured text corrupts it, and a
-`JSON.parse(captured)` fails intermittently with `Unexpected token` depending on
-timing. Record string chunks only and pass binary straight through. Both
-`helpers/output.js` and `helpers/capture.js` do this.
-
-**Do not capture stdout around anything that awaits a real timer or async gap.**
-The runner's own reporting written during that window is swallowed, and the file
-reports a wrong final test count with no error at all.
-
-**Wrap anything that reports a failure in `withExitCode`.** The CLI signals
-failure by setting `process.exitCode = 1` and returning, so the caller can keep
-working. That is right for the CLI and wrong for a test: a perfectly correct test
-of a failure path would make the whole file exit non-zero.
-
-**`resetNetwork()` between cases, not just between tests.** Routes only append
-and the first match wins, so registering two responses for one pattern leaves
-the second as dead code and every assertion after it passes for the wrong reason.
-
-**`await import("node:fs")` yields a namespace, not a live binding.** A stub
-assigned to the *default* export is invisible to a named-export read from inside
-the module. To exercise a path that checks the filesystem, change the
-filesystem — e.g. `sandbox-missing.test.js` copies `sandbox.js` into a temp
-directory with no `runner.js` beside it, which is a real broken install.
-
-**Module-level state latches.** `runnerMissing` in `sandbox.js` stays true once
-set, so that behaviour lives in its own test file; `node --test` gives each file
-a separate process, which is the isolation it needs.
-
-**Interactive code is tested by injection, not by a terminal.** Inquirer cannot
-be driven headlessly and a pending prompt keeps the process alive forever. The
-wizard takes a `prompts` bundle (`wizard-flow.test.js`); `run.js`'s interactive
-half is reached through a `module.register` hook that swaps only its `./ui.js`
-import (`run-interactive.test.js`). Both keep the real decision logic in `src`
-and replace only the presentation.
-
-**`index.js` is spawned, not imported.** It parses argv on import. Spawning it
-is also the honest way to assert the two contracts users depend on: exit codes,
-and the stdout/stderr split.
-
-## Writing a test for a new module
-
-1. `import` it normally at the top of the file. The `--import` hook has already
-   run, so isolation is in place.
-2. Network: `beforeEach(() => resetNetwork())`, `after(() => restoreNetwork())`.
-3. Failure paths: wrap in `withExitCode` and assert `exitCode`.
-4. Anything reading stdin: `withStdin`, or just let the default resolve `""`.
-5. Assert behaviour, not coverage. A test that exists only to execute a line is
-   a maintenance liability that fails for the wrong reasons.
-
-## Leak guards
-
-`test/isolation.test.js` is not an ordinary unit test file. Each test fails if a
-future change lets the suite read the developer's real config, reuse a real API
-key, or reach the real network:
-
-- config and cache resolve inside the temp sandbox, never under the real home
-- no inherited credentials or telemetry opt-in survive into the process
-- the API base is unroutable, so an unstubbed request fails rather than escaping
-- a canary secret never appears in captured stdout or stderr
-- redacted config leaks neither the value nor a fragment of it
-- `config.json` is `0600` inside a `0700` directory
-- no source file contains a hardcoded credential
-- no inlined JWT grants more than the `anon` role
-
-If you add a code path that could print a secret, add a canary test for it in the
-same change.