clearotron 0.4.0-beta.0 → 0.4.0-beta.2

package/scripts/added-reference-check.mjs

@@ -44,6 +44,7 @@
 // "what a public tree must not acquire" is one definition and one imitation of it, and the imitation
 // is whichever the reader did not run.
 import { execFileSync } from "node:child_process";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 import {
   CLASSES, offendingClasses, isProse, isScannable,
   withoutColourValues, withoutLinkTargets,
@@ -110,4 +111,4 @@ function main() {
   process.exit(1);
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) main();
+if (isEntrypoint(import.meta.url)) main();

package/scripts/backup-recall-stores.mjs

@@ -4,11 +4,11 @@
 // Copy every agent's recall store into the archive pool, so the engine's memory of confirmed
 // conflicts survives the loss of a workspace.
 //
-// WHY THIS EXISTS. `<studioRoot>/_known-conflicts/<mark>.json` is what stops the engine re-litigating
-// a conflict a lawyer already confirmed, and what carries a remembered opposition window into the
-// deadline-carry clamp. It lives only in the live workspace: no code copies it anywhere, and the
-// agent-state git backup does not reach it. One lost disk and every prior confirmed conflict is
-// forgotten silently — the next run on that mark reads clean and nothing says a memory used to exist.
+// WHY THIS EXISTS. `<studioRoot>/_known-conflicts/<mark>.json` was the engine's memory of conflicts
+// its delivered reports confirmed. No run reads or writes it since the recall store was removed
+// (2026-09-24), and the files were left on disk untouched, so what they hold is now a record rather
+// than an input. It lives only in the live workspace: no code copies it anywhere, and the agent-state
+// git backup does not reach it. One lost disk and that record is gone with nothing saying it existed.
 //
 // WHY THE POOL AND NOT GIT. These files name real client matters. The agent-state repo is pushed to
 // GitHub nightly, so backing them up THERE would widen exactly the exposure the 2026-07 audit found

package/scripts/demo-evidence.mjs

@@ -22,6 +22,7 @@ import { execFileSync } from "node:child_process";
 import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 
 const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 export const MANIFEST = join(ROOT, "demo", "MANIFEST.json");
@@ -53,7 +54,7 @@ export function mixedPaths(files) {
   return files.filter((f) => !f.startsWith("demo/"));
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isEntrypoint(import.meta.url)) {
   const apply = process.argv.includes("--apply");
 
   if (apply) {

package/scripts/deprecate-below.mjs

@@ -2,9 +2,11 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright 2026 Cordillera Sàrl. Additional terms under section 7 of the AGPL-3.0 apply — see ADDITIONAL-TERMS.md
 //
-// deprecate-below.mjs — put one warning on every published version below a named stable.
+// deprecate-below.mjs — put one warning on every published version below a named stable, or on a named
+// range of published versions.
 //
 //   node scripts/deprecate-below.mjs --below 0.3.1 [--dry-run]
+//   node scripts/deprecate-below.mjs --range "0.2.0..0.4.0-beta.0 except 0.3.3" [--dry-run]
 //
 // ── WHY THIS IS A SCRIPT IN CI AND NOT SOMETHING A PERSON RUNS ──────────────────────────────────────
 //
@@ -70,6 +72,56 @@ export function compareVersions(a, b) {
   return 0;
 }
 
+// ── THE RANGE MODE: A NAMED SET OF VERSIONS, ONE SENTENCE, NO REASON GIVEN ──────────────────────────
+//
+// Some versions have to be warned that are not simply "everything below a stable": a stretch of betas
+// and stables with one version held out because an install still runs it. The range says exactly that,
+// inclusive at both ends in npm's own order, and the exceptions are named one by one.
+//
+// ITS SENTENCE IS FIXED HERE AND NOT TYPED AT DISPATCH. It is public text on every version page, so it
+// is the owner's sentence, approved word for word, and a dispatch box is no place to redraft it.
+//
+// IT REPLACES AN OLDER MESSAGE IN THE RANGE, unlike the mode above. A range is warned for one reason, so
+// every version in it reads the same; a version that already says exactly this is left alone.
+//
+// IT NEVER TOUCHES A VERSION A DIST-TAG POINTS AT. `latest` and `beta` are what `npm install` resolves
+// to, and a warning on the version a reader is told to install is worse than none.
+export const RANGE_MESSAGE = "This version is no longer supported. Please upgrade to the latest version of clearotron.";
+
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?$/;
+
+/** Read "<from>..<through>[ except <v>[,<v>…]]". Throws on anything else. */
+export function parseRangeSpec(spec) {
+  const m = String(spec ?? "").trim().match(/^(\S+)\.\.(\S+?)(?:\s+except\s+(\S+))?$/);
+  if (!m) throw new Error(`"${spec}" is not a range: write <from>..<through>, optionally followed by " except <v>,<v>"`);
+  const [, from, through, ex = ""] = m;
+  const except = ex ? ex.split(",").map((v) => v.trim()).filter(Boolean) : [];
+  for (const v of [from, through, ...except]) if (!VERSION.test(v)) throw new Error(`"${v}" is not a version`);
+  if (compareVersions(from, through) > 0) throw new Error(`${from} is above ${through}: the range is empty`);
+  return { from, through, except };
+}
+
+/**
+ * The published versions a range names, in order: from and through inclusive, the exceptions out.
+ * Throws, before anything is written, when a bound is not published, an exception lies outside the
+ * range or is not published, or a selected version is one a dist-tag points at.
+ */
+export function selectRange(all, { from, through, except }, distTags = {}) {
+  for (const b of [from, through]) if (!all.includes(b)) throw new Error(`${b} is not a published version of ${PKG}`);
+  const inRange = (v) => compareVersions(v, from) >= 0 && compareVersions(v, through) <= 0;
+  for (const e of except) {
+    if (!all.includes(e)) throw new Error(`the exception ${e} is not a published version of ${PKG}`);
+    if (!inRange(e)) throw new Error(`the exception ${e} lies outside ${from}..${through}`);
+  }
+  const picked = all.filter((v) => inRange(v) && !except.includes(v)).sort(compareVersions);
+  const tagged = Object.entries(distTags).filter(([, v]) => picked.includes(v));
+  if (tagged.length) {
+    throw new Error(`the range takes ${tagged.map(([t, v]) => `${v} (${t})`).join(", ")}, which a dist-tag points at; `
+      + "move the tag or hold the version out");
+  }
+  return picked;
+}
+
 const npm = (...args) => execFileSync("npm", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
 
 /** Every published version, and the deprecation message each carries. Read once, as a list. */
@@ -130,9 +182,11 @@ async function main() {
   const argv = process.argv.slice(2);
   const at = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : null; };
   const DRY = argv.includes("--dry-run");
+  const range = at("--range");
+  if (range) return deprecateRange(range, DRY);
   const below = at("--below");
   if (!below) {
-    console.error("deprecate-below: --below <version> is required — the stable everything under it points at.");
+    console.error("deprecate-below: --below <version> or --range \"<from>..<through> except <v>\" is required.");
     return 2;
   }
   const MESSAGE = `This version is superseded. Please upgrade to ${below} or later: npm install ${PKG}@${below}`;
@@ -201,4 +255,62 @@ async function main() {
   return failed ? 1 : 0;
 }
 
+/** The range mode's run: select, write the fixed sentence where it is not already, read each back. */
+async function deprecateRange(spec, DRY) {
+  let picked;
+  try {
+    const parsed = parseRangeSpec(spec);
+    const all = published();
+    if (!all.length) throw new Error("the registry listed no versions");
+    const distTags = JSON.parse(npm("view", PKG, "dist-tags", "--json"));
+    picked = selectRange(all, parsed, distTags);
+    console.log(`deprecate-below: ${all.length} published version(s); ${picked.length} in ${spec}.`);
+  } catch (e) {
+    console.error(`deprecate-below: refusing — ${e.message}. Nothing was written.`);
+    return 2;
+  }
+  let done = 0, skipped = 0, failed = 0;
+  const wrote = [];
+  for (const v of picked) {
+    let existing;
+    try { existing = deprecationOf(v); }
+    catch (e) {
+      console.error(`  ${v}: could NOT be read (${String(e.message).split("\n")[0]}) — left alone.`);
+      failed += 1;
+      continue;
+    }
+    if (existing === RANGE_MESSAGE) { console.log(`  ${v}: already carries this message`); skipped += 1; continue; }
+    const was = existing ? ` (replacing "${existing.slice(0, 60)}")` : "";
+    if (DRY) { console.log(`  ${v}: would deprecate${was}`); done += 1; continue; }
+    try {
+      npm("deprecate", `${PKG}@${v}`, RANGE_MESSAGE);
+    } catch (e) {
+      console.error(`  ${v}: deprecate FAILED — ${String(e.stderr ?? e.message).split("\n")[0]}`);
+      failed += 1;
+      continue;
+    }
+    console.log(`  ${v}: deprecate accepted${was}`);
+    wrote.push(v);
+  }
+  let unconfirmed = [];
+  if (wrote.length && !DRY) {
+    // A replaced message is confirmed only once THIS sentence is served, not merely any sentence.
+    const r = await confirmWrites({
+      versions: wrote,
+      read: (v) => (deprecationOf(v) === RANGE_MESSAGE ? RANGE_MESSAGE : null),
+      sleep: (ms) => new Promise((res) => setTimeout(res, ms)),
+    });
+    unconfirmed = r.unconfirmed;
+    done += r.confirmed.length;
+    for (const v of r.confirmed) console.log(`  ${v}: serving the message`);
+    for (const v of unconfirmed) {
+      console.error(`  ${v}: WRITE ACCEPTED, not yet served after ${Math.round(r.waitedMs / 1000)}s — read it from `
+        + "outside before treating it as undone; re-running is safe and reports it as already carrying the message.");
+    }
+  }
+  console.log(`deprecate-below: ${done} ${DRY ? "would be " : ""}deprecated, ${skipped} already carried this message, `
+    + `${unconfirmed.length} accepted but not yet served, ${failed} failed.`);
+  return failed ? 1 : 0;
+}
+
 if (process.argv[1] && process.argv[1].endsWith("deprecate-below.mjs")) process.exit(await main());

package/scripts/drive-env-check.mjs

@@ -54,6 +54,7 @@
 import { readFileSync, readdirSync } from "node:fs";
 import { join, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isEntrypoint } from "../shared/is-entrypoint.mjs";
 
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
 const TEST_DIR = join(ROOT, "driver", "test");
@@ -138,7 +139,7 @@ export function scan(dir = TEST_DIR, read = (p) => readFileSync(p, "utf8"), list
   return { scanned: files.length, inClass };
 }
 
-if (import.meta.url === `file://${process.argv[1]}` || basename(process.argv[1] ?? "") === "drive-env-check.mjs") {
+if (isEntrypoint(import.meta.url) || basename(process.argv[1] ?? "") === "drive-env-check.mjs") {
   let r;
   try { r = scan(); }
   catch (e) {