@blamejs/core 0.17.20 → 0.17.21

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.17.x
 
+- v0.17.21 (2026-07-25) — **`blamejs erase` treats only `--confirm true` as confirmation, so `--confirm false` no longer triggers the irreversible erase.** Three fixes to the blamejs command line. The `erase` subcommand (a cryptographic single-row erase) gated its irreversible action on a bare-truthiness check, so `--confirm false` -- a string -- counted as confirmation and the erase proceeded; the gate now accepts only `true` / "true", matching `audit purge`, and refuses anything else. A stray `-v` / `--version` token alongside a subcommand no longer short-circuits to the version print: `blamejs migrate up --db x -v` previously returned 0 after printing the version without running the migration, handing automation a false pass; the version flag is now honored only when it is the whole invocation. And `blamejs dev` now survives a crash of the watched child -- it stays up to hot-restart on the next file change instead of draining the event loop and exiting 0 -- and awaits the child's full termination on SIGINT/SIGTERM so a shutdown cannot orphan it. **Fixed:** *blamejs erase refuses --confirm false instead of performing the irreversible erase* — The erase subcommand confirmed its irreversible action with a bare-truthiness check, so the string `--confirm false` was treated as confirmation and the erase ran. Confirmation is now satisfied only by `--confirm true` (or the bare `--confirm`), matching the check `audit purge` already used; any other value -- including `false` -- is refused with a non-zero exit and no erase. A shared confirmation helper backs every destructive subcommand so the acknowledgement contract cannot drift between them. · *A stray -v / --version no longer turns a subcommand into a silent no-op* — The top-level version flag was evaluated before subcommand dispatch and returned 0 whenever `-v` / `--version` appeared anywhere in the arguments, so a consequential command such as `migrate up`, `seed run`, or `erase` alongside a stray `-v` printed the version and exited 0 without doing anything -- a false success for any script checking the exit code. The version flag is now honored only when the invocation carries no subcommand; otherwise the subcommand runs (or fails) as written. · *blamejs dev survives a watched-child crash and shuts the child down cleanly* — The dev supervisor held the event loop open with an unref'd timer, so when the watched child process crashed the supervisor drained the loop and exited 0 -- defeating crash-resilience (it should stay up and hot-restart on the next file change) and reporting success even though the app had crashed. It now holds a referenced heartbeat so a child crash leaves the supervisor running, and on SIGINT/SIGTERM it awaits the child's full termination (graceful signal, then escalation) before exiting, so a shutdown can no longer race ahead and orphan the child.
+
 - v0.17.20 (2026-07-24) — **`b.forms.validate` enforces required checkboxes server-side and rejects malformed field bounds, closing two validation gaps.** b.forms.validate previously let an unchecked required checkbox pass: the renderer emits the HTML `required` attribute for it, but the server-side validator skipped the check, so a client that omitted the box -- or any non-browser caller -- bypassed a constraint the form advertised. It now rejects an unchecked required checkbox, keeping backend validation in lock-step with what the form displays. Separately, a field whose numeric bound (min/max/minlength/maxlength) was not a finite number went silently unenforced -- a NaN comparison is always false -- so the bound became a no-op; validate now throws on such a spec at the entry point, the same way it already rejects a non-precompiled regex pattern. Two smaller fixes: a field rendered without an explicit type now emits type="text" (matching the widget it dispatches to) rather than an empty type attribute, and b.externalDb reports EXPLAIN statements as row-returning so a query plan's rows are not dropped by the local-execution row/no-row chooser. **Changed:** *b.forms.validate option reference corrected* — The validate() reference described length bounds as minLength/maxLength, but the option keys are the HTML-attribute spellings minlength/maxlength (the same keys the renderer reads); the reference and its example are corrected, and the example now uses a numeric min bound on its number field. · *Vendored Public Suffix List refreshed to the current snapshot* — The bundled Public Suffix List that backs domain classification (registrable-domain and public-suffix checks in URL, cookie, and SSRF handling) is updated to the latest upstream publicsuffix.org snapshot, so newly delegated public suffixes and private-domain entries are recognized. **Fixed:** *Required checkboxes are enforced server-side in b.forms.validate* — A checkbox marked required is rendered with the HTML `required` attribute, but validate() treated an unchecked box (which coerces to false) as satisfying the field, so an unchecked required checkbox passed. Any caller that skipped the box -- a scripted client, or a browser with the constraint stripped -- bypassed a documented requirement. validate() now returns an error for an unchecked required checkbox (honouring the field's errorMessages.required), so the backend enforces the same constraint the frontend shows. A form that relied on the previous pass-through for an unchecked required checkbox will now surface a validation error, which is the intended behaviour. · *A malformed numeric field bound is rejected instead of silently ignored* — When a field's min, max, minlength, or maxlength was not a finite number (a non-numeric string, NaN, or Infinity), its comparison could never fire -- a NaN comparison is always false -- so the bound was quietly unenforced while appearing to constrain the field. validate() now throws at the entry point when a defined bound is non-finite, matching how it already requires pattern to be a pre-compiled RegExp. Numeric-string bounds (e.g. min: "1") remain accepted. · *A typeless field renders type="text" instead of an empty type attribute* — b.forms.render dispatches a field with no explicit type to a text input, but the emitted markup carried type="" rather than type="text". The rendered type attribute now matches the widget dispatched, so the markup is self-consistent. · *b.externalDb reports EXPLAIN statements as row-returning* — statementReturnsRows classified a plain EXPLAIN (and an EXPLAIN ANALYZE wrapping a write) as producing no row set, so the local-execution path could route it to a no-row call and drop the query plan. EXPLAIN always returns plan rows to the caller; it is now reported as row-returning whenever its prefix resolves, while an unparseable EXPLAIN prefix stays fail-closed. This is distinct from the cross-border residency read/write classification, which is unchanged.
 
 - v0.17.19 (2026-07-24) — **The error and adversarial paths of the sanctions-screening, JSON Schema, and HTTP client primitives are now under test.** This release adds no behaviour change. The fail-closed error paths, boundary conditions, and adversarial-input handling of b.complianceSanctions, b.jsonSchema, and b.httpClient -- previously exercised only on their happy paths -- are now asserted, verifying that each rejects malformed input, unresolvable references, and edge cases the documented contract already promised. No defects were found; the primitives behaved as specified. Genuinely-unreachable defensive fallbacks are documented rather than contorted into coverage. **Changed:** *Verified error-path behaviour for sanctions screening, JSON Schema, and the HTTP client* — The sanctions-screening list parsers (OFAC SDN/alias, EU CSL, UN 1267), the fuzzy/exact match strategy toggle, and the entry normalizer; the JSON Schema $ref/$dynamicRef resolution, JSON-pointer traversal, format assertions, and unevaluated-properties/items handling; and the HTTP client's error, redirect, and stream branches now have explicit tests for their failure and boundary behaviour. Behaviour is unchanged -- these assert guarantees the primitives already met -- so no migration is needed; the value is regression protection for the fail-closed paths of security-relevant primitives.

package/lib/arg-parser.js

@@ -625,7 +625,7 @@ function create(opts) {
 
 /**
  * @primitive b.argParser.parseRaw
- * @signature b.argParser.parseRaw(argv)
+ * @signature b.argParser.parseRaw(argv, opts?)
  * @since     0.8.48
  * @status    stable
  * @related   b.argParser.create
@@ -638,12 +638,21 @@ function create(opts) {
  * value`, `--key=value`, and bare `--bool`. `--` terminates flag
  * parsing.
  *
+ * Pass `opts.booleanNames` (an array of long-flag names) to declare flags
+ * that never consume a following token as their value — a bare
+ * `--version` stays boolean instead of swallowing the next token, so
+ * `--version foo` yields `flags.version === true` with `foo` left as a
+ * positional. An inline `--version=x` still records the explicit value.
+ *
  * A flag repeated on the command line accumulates every occurrence into
  * an array, in order — `--watch a --watch b` yields `["a", "b"]`, not
  * just the last value. A flag seen once stays a scalar. This keeps
  * repeatable flags (the `dev` command's `--arg` / `--watch` / `--ignore`)
  * from silently dropping all but the final occurrence.
  *
+ * @opts
+ *   booleanNames: string[],   // long-flag names that never consume a following token as a value (default: none)
+ *
  * @example
  *   var r = b.argParser.parseRaw(
  *     ["build", "--target=node", "-v", "--out", "dist", "--", "extra"]);
@@ -670,11 +679,21 @@ function _assignFlag(flags, name, val) {
   }
 }
 
-function parseRaw(argv) {
+function parseRaw(argv, opts) {
   if (!Array.isArray(argv)) {
     throw new ArgParserError("arg-parser/argv-not-array",
       "argv must be an array of strings");
   }
+  opts = opts || {};
+  // Long-flag names declared boolean never consume a following token as a
+  // value (a bare `--version` stays true instead of swallowing the next
+  // token). Inline `--flag=value` still records the explicit value.
+  var booleanNames = Object.create(null);
+  if (Array.isArray(opts.booleanNames)) {
+    for (var bn = 0; bn < opts.booleanNames.length; bn++) {
+      booleanNames[opts.booleanNames[bn]] = true;
+    }
+  }
   var pos = [];
   var flags = Object.create(null);
   for (var i = 0; i < argv.length; i++) {
@@ -694,7 +713,8 @@ function parseRaw(argv) {
       if (eq !== -1) {
         val = name.slice(eq + 1);
         name = name.slice(0, eq);
-      } else if (i + 1 < argv.length && argv[i + 1].indexOf("--") !== 0) {
+      } else if (i + 1 < argv.length && argv[i + 1].indexOf("--") !== 0 &&
+                 booleanNames[name] !== true) {
         val = argv[++i];
       } else {
         val = true;

package/lib/cli.js

@@ -84,7 +84,12 @@ function _writeLine(stream, line) {
 // written flag validation continues to read the same { pos, flags }
 // shape the cli has always exposed.
 function _parseArgs(argv) {
-  return argParser.parseRaw(argv);
+  // `--version` is the global boolean version flag — declare it so it never
+  // swallows a following token as its value. Without this, `--version <cmd>`
+  // (or `<cmd> --version <sub>`) would consume the subcommand and a stray
+  // version flag could no-op the command it accompanies. (`-v` is a
+  // single-dash flag and is already boolean in parseRaw.)
+  return argParser.parseRaw(argv, { booleanNames: ["version"] });
 }
 
 function _resolvePath(p, cwd) {
@@ -93,6 +98,16 @@ function _resolvePath(p, cwd) {
   return nodePath.resolve(cwd || process.cwd(), p);
 }
 
+// A destructive command's --confirm gate is satisfied ONLY by an explicit
+// `true` / "true"; a bare-truthiness check (`!flags.confirm`) would accept
+// `--confirm false` as confirmation, so an operator who typed `--confirm
+// false` — meaning "do NOT proceed" — would still trigger an irreversible
+// operation. Shared by every destructive subcommand so the acknowledgement
+// contract can't drift between them.
+function _isConfirmed(flags) {
+  return flags.confirm === true || flags.confirm === "true";
+}
+
 function _openSqlite(dbPath) {
   // Lazy-required so the CLI doesn't crash on `blamejs version` or
   // `blamejs help` if node:sqlite isn't usable for some reason.
@@ -424,7 +439,7 @@ async function _runDev(args, ctx) {
   }
   var killSignal = args.flags["kill-signal"];
 
-  var d = dev.create({
+  var d = (ctx._dev || dev.create)({
     command:    String(command),
     args:       argList,
     watch:      watchList.length ? watchList : undefined,
@@ -435,31 +450,51 @@ async function _runDev(args, ctx) {
     env:        ctx.env,
   });
 
-  // Forward parent SIGINT/SIGTERM to the child via stop()
+  // Forward parent SIGINT/SIGTERM to the child via stop(). The supervisor
+  // resolves ONLY after stop() has fully completed (SIGTERM → SIGKILL
+  // escalation → watchers disarmed), so main() never returns — and the bin
+  // shim never process.exit()s — while a child kill is still in flight and
+  // could be abandoned, orphaning the app child.
   var stopped = false;
+  var onStopComplete;
+  var stopComplete = new Promise(function (resolve) { onStopComplete = resolve; });
   function shutdown() {
     if (stopped) return;
     stopped = true;
-    d.stop().then(function () { /* exit naturally */ });
+    Promise.resolve(d.stop()).then(onStopComplete, onStopComplete);
   }
   process.once("SIGINT",  shutdown);
   process.once("SIGTERM", shutdown);
+  function _clearSignalHandlers() {
+    process.removeListener("SIGINT",  shutdown);
+    process.removeListener("SIGTERM", shutdown);
+  }
 
   try {
     await d.start();
   } catch (e) {
     _writeLine(ctx.stderr, "blamejs dev: " + ((e && e.message) || String(e)));
+    _clearSignalHandlers();
     return 1;
   }
-  // The dev loop runs until the operator interrupts. Resolve a
-  // never-settling promise so main() awaits forever; the SIGINT handler
-  // above flips stopped+resolves on Ctrl-C.
-  await new Promise(function (resolve) {
-    var iv = setInterval(function () {
-      if (stopped) { clearInterval(iv); resolve(); }
-    }, 250);
-    if (typeof iv.unref === "function") iv.unref();
-  });
+  // The dev loop runs until the operator interrupts. A REF'd heartbeat holds
+  // the event loop open so a watched-child CRASH does not drain it and exit
+  // the supervisor — dev's crash-resilience contract is to stay up and
+  // hot-restart on the next file change, but an unref'd keep-alive let a
+  // child's exit terminate the parent with a false code 0. Cleared once
+  // stop() has completed on SIGINT/SIGTERM. Unref'ing would drain the loop on
+  // a child crash and reintroduce the exit-on-crash bug this heartbeat fixes.
+  // allow:timer-no-unref-process-pinning — supervisor must stay pinned.
+  var heartbeat = setInterval(function () {}, C.TIME.minutes(1));
+  // Hand the shutdown trigger to a test seam (no-op in production) so a test
+  // can drive the signal path deterministically instead of raising SIGINT.
+  if (typeof ctx._onDevRunning === "function") ctx._onDevRunning(shutdown);
+  try {
+    await stopComplete;
+  } finally {
+    clearInterval(heartbeat);
+    _clearSignalHandlers();
+  }
   return 0;
 }
 
@@ -766,7 +801,7 @@ async function _runAudit(args, ctx) {
       _writeLine(ctx.stderr, "blamejs audit purge: --archive (path to verified archive bundle) is required");
       return 2;
     }
-    if (args.flags.confirm !== true && args.flags.confirm !== "true") {
+    if (!_isConfirmed(args.flags)) {
       _writeLine(ctx.stderr, "blamejs audit purge: --confirm is REQUIRED — destructive operation");
       return 2;
     }
@@ -2081,7 +2116,7 @@ async function _runErase(args, ctx) {
   var rowId = args.flags["row-id"];
   if (!table || table === true)  return report.error("--table <name> is required", 2);
   if (!rowId || rowId === true)  return report.error("--row-id <id> is required", 2);
-  if (!args.flags.confirm) {
+  if (!_isConfirmed(args.flags)) {
     return report.error("--confirm is required (this operation is irreversible)", 2);
   }
   var dataDirFlag = args.flags["data-dir"];
@@ -2317,12 +2352,24 @@ async function main(argv, opts) {
     stderr: opts.stderr || process.stderr,
     env:    opts.env    || process.env,
     cwd:    opts.cwd    || process.cwd(),
+    // Test seams (undefined in production): _dev injects the dev-supervisor
+    // factory; _onDevRunning receives the shutdown fn once `dev` is live, so
+    // a test can drive graceful teardown without raising a real OS signal.
+    _dev:          opts._dev,
+    _onDevRunning: opts._onDevRunning,
   };
   if (!Array.isArray(argv)) argv = [];
   var args = _parseArgs(argv);
 
-  // Top-level flags handled before subcommand dispatch
-  if (args.flags.version || args.flags.v) {
+  // Version is honored only as the WHOLE invocation — a bare `-v` /
+  // `--version` with no subcommand. `_parseArgs` declares `--version`
+  // boolean, so a stray version flag never swallows a token: it works in any
+  // order (leading, trailing, or between a command and its subcommand) and
+  // leaves the positional list intact, so the command dispatches instead of
+  // a silent version no-op returning a false 0. A `-v` used as another
+  // option's value stays that value, and a version token after the `--`
+  // terminator stays a literal positional.
+  if ((args.flags.version || args.flags.v) && args.pos.length === 0) {
     _writeLine(ctx.stdout, C.version);
     return 0;
   }

package/lib/dev.js

@@ -255,14 +255,29 @@ function create(opts) {
         if (killTimer) { try { clearTimeoutFn(killTimer); } catch (_e) { /* timer already cleared */ } killTimer = null; }
         resolve();
       }
+      // 'exit' is the only event that reliably means the process is gone, so
+      // it is the only one that completes shutdown. A child that FAILED TO
+      // SPAWN has no pid and never emits 'exit' — it is settled by the
+      // no-process check below, NOT by listening for 'error'/'close', which
+      // can also fire for a LIVE child (a rejected kill emits 'error' while
+      // the process keeps running) and must not complete shutdown then.
       c.once("exit", done);
-      try { c.kill(killSignal); }
+      var sent;
+      try { sent = c.kill(killSignal); }
       catch (e) {
         _logVia(log, "warn", "kill threw, child may already be gone",
           { error: (e && e.message) || String(e) });
         done();
         return;
       }
+      // kill() returning false means the signal was NOT delivered — which can
+      // be either "no process exists" (a child that failed to spawn has no
+      // pid; no 'exit' will ever arrive, so settle now) OR "a live process
+      // rejected the signal" (e.g. EPERM after the child changed credentials;
+      // pid is set). Only the no-process case completes shutdown here; a live
+      // child keeps the SIGKILL escalation + awaits exit/close, so stop()
+      // never falsely reports termination while the process is still running.
+      if (!sent && !c.pid) { done(); return; }
       // Hard-kill if the child ignores SIGTERM
       killTimer = setTimeoutFn(function () {
         if (settled) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.17.20",
+  "version": "0.17.21",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:ca04b307-a233-4b08-991a-1182e07f9ff1",
+  "serialNumber": "urn:uuid:5c9f188a-268c-45b5-b70b-b8a8c8fcd062",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-25T06:27:12.675Z",
+    "timestamp": "2026-07-25T13:10:41.119Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.17.20",
+      "bom-ref": "@blamejs/core@0.17.21",
       "type": "application",
       "name": "blamejs",
-      "version": "0.17.20",
+      "version": "0.17.21",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.17.20",
+      "purl": "pkg:npm/%40blamejs/core@0.17.21",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.17.20",
+      "ref": "@blamejs/core@0.17.21",
       "dependsOn": []
     }
   ]