projectstore-codex 0.0.1 → 0.28.1

package/node_modules/projectstore/scripts/touch-session.mjs

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+// projectstore — touch-session.mjs
+//
+// Called by BOTH the PreToolUse and PostToolUse hooks, and gated on which:
+// a write inside the vault fires both events, so without the gate the pointer
+// patch below would run twice per call — and that patch is the unguarded
+// read-modify-write the entry-rule state deliberately avoids.
+//
+// Responsibilities:
+// 1. Liveness — touches this session's registration file (mtime) so other
+//    sessions can see we are active. Bootstraps the record on first call
+//    when SessionStart did not run (plugin installed mid-session via
+//    /reload-plugins, or rare path where SessionStart was skipped).
+// 2. Activity log — extracts the target file path from the tool input
+//    and, if it lives inside the vault, appends an entry to
+//    `recent_activity` in the session file (capped at 50, deduped).
+//    The PreCompact hook reads this list to build a survival packet.
+// 3. Entry-rule detection (PostToolUse only) — counts distinct SOURCE paths
+//    written this session and, once the threshold is reached with no story
+//    open, emits the one advisory reminder. PostToolUse rather than
+//    PreToolUse because it fires only after a call succeeds, so declined
+//    edits are not counted as work that happened. Spec: "Entry-rule
+//    detection: the score, the open-story predicate, and the delivery seams".
+//
+// Session identity comes from Claude's own `session_id` field in the
+// hook input JSON (stdin), so two Claude Code instances open on the
+// same project get distinct session files.
+//
+// Silent no-op when there is no projectstore config, when stdin lacks
+// session_id, or on any error — a PreToolUse hook must never crash the
+// user's tool call.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  readConfig,
+  readStdinJson,
+  adoptHookInput,
+  touchSession,
+  writeSession,
+  cleanupStaleSessions,
+  sessionFilePath,
+  projectRoot,
+  appendActivity,
+  isInsideVault,
+  parseFrontmatter,
+  readSessionState,
+  writeSessionState,
+  isSourcePath,
+  registerSourcePath,
+  entryScore,
+  resolveOpenStory,
+  readOpenStoryCache,
+  writeOpenStoryCache,
+  mayRemind,
+  electEmitter,
+  appendEntryLog,
+  entryReminderText,
+  ENTRY_THRESHOLD,
+  isWriteTool,
+  loadLayout,
+  anchorKeyOf,
+  foldAnchor,
+  composeAnchorName,
+  bumpAnchor,
+  readAnchorState,
+  readAnchorOffer,
+  writeAnchorOffer,
+  liveSessionNames,
+  ownSessionName,
+  sessionNameOffer,
+  sessionNameOfferText,
+  toolPaths,
+} from "./lib.mjs";
+
+const NUDGE_INTERVAL_MS = 10 * 60 * 1000;
+
+// Per-session active pointer (ADR-006) — denormalized titles/status captured
+// at write time so the statusline renders with zero vault reads — plus the
+// raw-edit nudge (PS-IMPROVE story-003): throttled, never blocking.
+// The session-name offer (ADR: the settled-anchor offer). Returns a line or
+// null. Separate from the pointer patch because the two answer different
+// questions — the pointer is "what is current", this is "has the session
+// settled" — and because this one must be gated where the pointer is not.
+let LAYOUT = null;
+function layoutOnce(cfg) {
+  if (LAYOUT === null) LAYOUT = loadLayout(cfg.layout);
+  return LAYOUT;
+}
+
+function anchorOffer(cfg, proj, sid, filePath, toolName, isSubagent, sessionsDir = null) {
+  // The two gates. The pointer patch above deliberately has neither: it answers
+  // "what am I looking at", for which a Read is a fine answer. A NAME is a
+  // claim about what the session is DOING, so a review session that greps
+  // thirty files must not be named after them, and a subagent — which shares
+  // this session id and cannot accept a name — must not vote on one.
+  if (!isWriteTool(toolName || "")) return null;
+  if (isSubagent) return null;
+
+  const rel = filePath.slice(cfg.vault_path.length + 1);
+  let hit = null;
+  try { hit = anchorKeyOf(rel, layoutOnce(cfg)); } catch { return null; }
+  if (!hit) return null;
+
+  // Both slots: the key tally is what settles an anchor, the leaf tally only
+  // picks which story names it. Bumping the leaf alone leaves the anchor
+  // permanently unsettled — silently, since a rule that never fires looks
+  // exactly like a quiet one.
+  bumpAnchor(proj, sid, hit.key, null);
+  if (hit.leaf) bumpAnchor(proj, sid, hit.key, hit.leaf);
+
+  const prev = readAnchorState(proj, sid);
+  // The tally on disk already includes this event, so replay it against the
+  // state MINUS this event: fold is what decides an offer, and it must see the
+  // increment happen rather than find it already there.
+  const counts = { ...prev.counts };
+  if (counts[hit.key]) counts[hit.key] -= 1;
+  const leaves = { ...prev.leaves };
+  if (hit.leaf && leaves[hit.key] && leaves[hit.key][hit.leaf]) {
+    leaves[hit.key] = { ...leaves[hit.key], [hit.leaf]: leaves[hit.key][hit.leaf] - 1 };
+  }
+  const { state, offer } = foldAnchor(
+    { counts, leaves, incumbent: prev.incumbent, offered: prev.offered }, hit);
+  if (!offer) return null;
+
+  const rec = readAnchorOffer(proj, sid);
+  const current = ownSessionName(sid, sessionsDir);
+  // A session almost always arrives already wearing a name the harness assigned
+  // — so "current is not our last offer" does NOT mean the person chose it.
+  // Reading it that way silenced the feature permanently for every real
+  // session: on the first offer `offered` is null, so any pre-existing name was
+  // classified as a deliberate choice and nothing was ever spoken again.
+  // A name is the person's only if we have spoken at least once and it is none
+  // of the names we composed.
+  const declined = current && rec.offers.length > 0 && !rec.offers.includes(current)
+    && !rec.declined.includes(current)
+    ? [...rec.declined, current]
+    : rec.declined;
+
+  const chosen = sessionNameOffer(offer.name, {
+    peers: liveSessionNames(sid, sessionsDir),
+    current,
+    declined,
+  });
+  // The incumbent moved whether or not we speak, or the same anchor would
+  // re-arm and offer again on the next write. But `offered` records what was
+  // actually SAID: a name suppressed by the collision ladder was never heard,
+  // and burning it would keep this session silent after the peer exits.
+  writeAnchorOffer(proj, sid, {
+    incumbent: state.incumbent,
+    offered: chosen ? chosen.name : rec.offered,
+    offers: chosen ? [...new Set([...rec.offers, chosen.name])] : rec.offers,
+    declined,
+  });
+  if (!chosen) return null;
+  try {
+    appendEntryLog(proj, {
+      at: new Date().toISOString(), session_id: sid, kind: "name-offer", name: chosen.name,
+    });
+  } catch {}
+  return sessionNameOfferText(chosen);
+}
+
+function updatePointerAndNudge(cfg, proj, sid, filePath, toolName) {
+  const rel = filePath.slice(cfg.vault_path.length + 1);
+  let patch = null;
+
+  const m = rel.match(/^epics\/([^/]+)\//);
+  if (m) {
+    const epicId = m[1];
+    patch = { active_epic: epicId };
+    try {
+      const { data } = parseFrontmatter(
+        readFileSync(join(cfg.vault_path, "epics", epicId, "epic.md"), "utf8"));
+      if (data.title) patch.epic_title = String(data.title);
+    } catch {}
+    const sm = rel.match(/^epics\/[^/]+\/stories\/([^/]+\.md)$/);
+    if (sm) {
+      patch.active_story = sm[1].replace(/\.md$/, "");
+      try {
+        const { data } = parseFrontmatter(readFileSync(filePath, "utf8"));
+        if (data.title) patch.story_title = String(data.title);
+        if (data.status) patch.story_status = String(data.status);
+      } catch {}
+    }
+  }
+
+  let nudge = null;
+  if (isWriteTool(toolName || "") && cfg.guard !== "off") {
+    const st = readSessionState(proj, sid);
+    const last = st && st.nudged_at ? Date.parse(st.nudged_at) : 0;
+    if (Date.now() - last > NUDGE_INTERVAL_MS) {
+      nudge =
+        "projectstore: vault file edited directly — if this bypassed a /projectstore:* command, run /projectstore:reconcile (or doctor) afterwards so the board/indexes stay in sync.";
+      patch = { ...(patch || {}), nudged_at: new Date().toISOString() };
+    }
+  }
+
+  if (patch) writeSessionState(proj, sid, patch);
+  return nudge;
+}
+
+// The source-side branch (PostToolUse). Never throws: every failure here must
+// leave the user's tool call untouched.
+async function entryBranch(cfg, proj, sid, filePath, input) {
+  // Writes only. extractToolPath happily yields a path for Read, Grep, Glob and
+  // LS — all of which carry file_path or path — so without this gate three
+  // read-only calls would trip the threshold and the reminder would announce
+  // work that never happened. (Grep's `path` is often a directory, which would
+  // then be counted as a "source file".) The event tells us the call succeeded;
+  // only the tool name tells us it wrote.
+  if (!isWriteTool(input.tool_name || "")) return;
+  if (!isSourcePath(filePath, proj, cfg.vault_path)) return;
+
+  // Belt and braces. PostToolUse only fires after success — failures raise
+  // PostToolUseFailure, which this script is not registered on — so the event
+  // itself is the discrimination. Nothing may DEPEND on this field's shape, and
+  // the shape varies by BOTH harness and tool: Claude Code sends an object;
+  // Codex sent a string for 368 of 371 PostToolUse firings and a content-block
+  // array for the other 3, all of them `webrun` (measured 2026-09-07). So the
+  // guard is written for "an object with success === false", and every other
+  // shape is a pass-through. Narrowed explicitly rather than relying on
+  // `"…".success` being undefined — that is an accident of JavaScript, not a
+  // decision, and it does not hold for every shape a tool may invent.
+  const response = input.tool_response;
+  if (response && typeof response === "object" && response.success === false) return;
+
+  registerSourcePath(proj, sid, filePath);
+
+  // Subagents count toward the score but are never the audience: a reminder
+  // delivered there reaches an actor mid-implementation under explicit
+  // instructions, who cannot open a story.
+  if (input.agent_id || input.agent_type) return;
+  if (cfg.guard === "off") return;
+
+  const score = entryScore(proj, sid);
+  if (score < ENTRY_THRESHOLD) return;
+  if (!mayRemind(proj, sid)) return;
+
+  let verdict = readOpenStoryCache(proj, sid);
+  if (verdict === null) {
+    verdict = await resolveOpenStory(cfg.vault_path);
+    writeOpenStoryCache(proj, sid, verdict);
+  }
+  if (verdict === "unknown") {
+    // Reached either from a fresh sweep that hit its budget with reads still
+    // outstanding (the event loop would keep this hook alive until they settle)
+    // or from a cached unknown, where nothing is outstanding and the exit is
+    // merely redundant. Exiting is safe here and only here: an unknown verdict suppresses the reminder, so stdout is
+    // untouched — process.exit does not flush pending pipe writes, and exiting
+    // after emitting would truncate the reminder.
+    process.exit(0);
+  }
+  if (verdict !== false) return;
+
+  if (!electEmitter(proj, sid)) return;
+  appendEntryLog(proj, { at: new Date().toISOString(), session_id: sid, score });
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext: entryReminderText(score),
+    },
+  }) + "\n");
+}
+
+async function main() {
+  // The payload before the project. On a harness that exports no project-dir
+  // variable the payload's cwd is the only answer better than "whatever
+  // directory this process started in", and readConfig() resolves through
+  // projectRoot() — so anything read before this line answers for the wrong
+  // project, silently. Read once: fd 0 is empty on a second read.
+  const input = adoptHookInput(readStdinJson());
+  if (!input) return;
+
+  const cfg = readConfig();
+  if (!cfg) return;
+
+  const sid = input.session_id;
+  if (!sid) return;
+
+  const proj = projectRoot();
+  const event = input.hook_event_name;
+
+  // Liveness and the vault-side branch stay on PreToolUse, exactly as before.
+  // PreToolUse always precedes PostToolUse for the same call, so pinning them
+  // here changes nothing about when they run — it only stops them running twice.
+  if (event !== "PostToolUse") {
+    if (existsSync(sessionFilePath(cfg.vault_path, sid))) {
+      touchSession(cfg.vault_path, sid);
+    } else {
+      // The exemption (contract 23) is passed for agreement with the other
+      // caller, not for effect: this branch runs only when our own session file
+      // does NOT exist, so there is nothing here to exempt. Two callers of one
+      // function disagreeing about its signature is how the next reader
+      // concludes the argument is optional.
+      cleanupStaleSessions(cfg.vault_path, 24, sid);
+      writeSession(cfg.vault_path, sid, proj);
+    }
+  }
+
+  if (!input.tool_name) return;
+  const filePaths = toolPaths(input);
+  if (!filePaths.length) return;
+
+  if (event === "PostToolUse") {
+    for (const filePath of filePaths) await entryBranch(cfg, proj, sid, filePath, input);
+    return;
+  }
+
+  const messages = [];
+  for (const filePath of filePaths) if (isInsideVault(filePath, cfg.vault_path)) {
+    try { appendActivity(cfg.vault_path, sid, filePath, input.tool_name); } catch {}
+    let nudge = null, offer = null;
+    try { nudge = updatePointerAndNudge(cfg, proj, sid, filePath, input.tool_name); } catch {}
+    if (cfg.guard !== "off") {
+      try {
+        offer = anchorOffer(cfg, proj, sid, filePath, input.tool_name,
+          Boolean(input.agent_id || input.agent_type),
+          process.env.PROJECTSTORE_SESSIONS_DIR || null);
+      } catch {}
+    }
+    // One invocation carries one systemMessage, so the two compose rather than
+    // race: emitting twice would silently drop whichever went second, and the
+    // offer fires once or twice a session against a nudge that fires every ten
+    // minutes — the rare one would be the one lost.
+    messages.push(...[nudge, offer].filter(Boolean));
+  }
+  if (messages.length) {
+    process.stdout.write(JSON.stringify({ systemMessage: [...new Set(messages)].join("\n") }) + "\n");
+  }
+}
+
+main().catch(() => {
+  // A hook must never crash the user's tool call — sync throws and rejected
+  // promises alike.
+});

package/node_modules/projectstore/scripts/version-guard.mjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+// projectstore — version-guard.mjs (PS-HARNESS: "Claim the npm name and ship
+// the first release")
+//
+// The release-time guard. It did not exist before this story: ADR-009 and the
+// harness-landscape research note both describe "the version-check guard" as
+// something already in place, and neither was true — there was no script, no
+// test and no CI step. Doctor's version checks are a different guard entirely
+// (runtime: an installed plugin against the marketplace), and they stay.
+//
+//   node scripts/version-guard.mjs [--tag vX.Y.Z]
+//   node scripts/version-guard.mjs --write-packlist
+//
+// Checks that every version-bearing manifest agrees, and — when --tag is
+// given — that the release tag agrees with them. CI passes the tag; a human
+// running it before a manual publish does not, because publish #1 is not
+// tag-triggered and nothing else covers it.
+//
+// Exit 0 when everything agrees, 1 on disagreement or a malformed manifest.
+// Output is JSON on stdout, always, so a workflow step can quote it.
+
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+// Contract 2 of the atomic-regeneration work: nothing under scripts/ writes
+// directly, and tests/scripts.test.mjs enforces it by globbing this directory.
+import { writeFileAtomic } from "./lib.mjs";
+import { LAYOUT } from "./harness.mjs";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export const PACKLIST = "tests/fixtures/packlist.json";
+
+// [path, how to read the version, required]. Required sites must exist: with
+// everything optional, a checkout missing package.json reported agreement,
+// because "no site disagrees" is trivially true when there are no sites.
+const VERSION_SITES = [
+  ["package.json", (j) => j.version, true],
+  [".claude-plugin/plugin.json", (j) => j.version, true],
+  // Found by name, not by position: `plugins[0]` reads a sibling plugin's
+  // version the moment the marketplace lists more than one, and reports the
+  // disagreement against the wrong file.
+  [
+    ".claude-plugin/marketplace.json",
+    (j) => j.plugins?.find((p) => p.name === "projectstore")?.version,
+    true,
+  ],
+];
+
+// The distribution shells (the shells ADR; layout spec contract 11): one
+// package.json per shell under packaging/shells/, each at the core's version
+// with an exact pin on it. Read directly — the directory is in the repository
+// but not in the tarball, and the guard runs from the repository.
+export const SHELLS_DIR = "packaging/shells";
+
+export function collectShells(root = ROOT) {
+  const dir = resolve(root, SHELLS_DIR);
+  if (!existsSync(dir)) return { shells: [] };
+  const shells = [];
+  // Directories only: a .DS_Store Finder drops on a browse is not a shell.
+  for (const name of readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort()) {
+    const rel = `${SHELLS_DIR}/${name}/package.json`;
+    const abs = resolve(root, rel);
+    if (!existsSync(abs)) return { error: `${rel}: missing — every directory under ${SHELLS_DIR}/ is a shell` };
+    let json;
+    try { json = JSON.parse(readFileSync(abs, "utf8")); } catch (e) { return { error: `${rel}: ${e.message}` }; }
+    if (json.name !== name) return { error: `${rel}: name "${json.name}" is not its directory's` };
+    if (typeof json.version !== "string" || !json.version) return { error: `${rel}: no version found where one is required` };
+    const pluginVersions = [];
+    if (name === "projectstore-codex") {
+      for (const manifest of ["plugin.json", ".codex-plugin/plugin.json"]) {
+        const manifestRel = `${SHELLS_DIR}/${name}/${manifest}`;
+        const manifestAbs = resolve(root, manifestRel);
+        if (!existsSync(manifestAbs)) return { error: `${manifestRel}: missing — the Codex shell carries both canonical and compatibility manifests` };
+        let parsed;
+        try { parsed = JSON.parse(readFileSync(manifestAbs, "utf8")); } catch (e) { return { error: `${manifestRel}: ${e.message}` }; }
+        if (typeof parsed.version !== "string" || !parsed.version) return { error: `${manifestRel}: no version found where one is required` };
+        pluginVersions.push({ file: manifestRel, version: parsed.version });
+      }
+    }
+    shells.push({
+      name, file: rel, version: json.version,
+      pin: json.dependencies?.projectstore ?? null,
+      private: json.private === true,
+      bin: json.bin?.[name] ?? null,
+      binExists: typeof json.bin?.[name] === "string" && existsSync(resolve(root, SHELLS_DIR, name, json.bin[name])),
+      bundled: Array.isArray(json.bundleDependencies) && json.bundleDependencies.includes("projectstore"),
+      pluginVersions,
+    });
+  }
+  return { shells };
+}
+
+function die(msg) {
+  process.stdout.write(JSON.stringify({ ok: false, error: msg }) + "\n");
+  process.exit(1);
+}
+
+export function collectVersions(root = ROOT) {
+  if (existsSync(resolve(root, ".codex-plugin", "plugin.json"))) {
+    return { error: ".codex-plugin/plugin.json must live in the projectstore-codex shell, not at the core package root" };
+  }
+  const found = [];
+  for (const [rel, pick, required] of VERSION_SITES) {
+    if (!existsSync(resolve(root, rel))) {
+      if (required) return { error: `${rel}: missing, and it carries the release version` };
+      continue;
+    }
+    let json;
+    try {
+      json = JSON.parse(readFileSync(resolve(root, rel), "utf8"));
+    } catch (e) {
+      return { error: `${rel}: ${e.message}` };
+    }
+    const version = pick(json);
+    if (typeof version !== "string" || !version) {
+      return { error: `${rel}: no version found where one is required` };
+    }
+    found.push({ file: rel, version });
+  }
+  return { found };
+}
+
+// `v0.25.0` and `0.25.0` are the same release; the tag carries the prefix by
+// this repository's convention and the manifests never do.
+const stripV = (t) => (t.startsWith("v") ? t.slice(1) : t);
+
+export function checkVersions({ root = ROOT, tag = null } = {}) {
+  const { found, error } = collectVersions(root);
+  if (error) return { ok: false, error };
+  const sh = collectShells(root);
+  if (sh.error) return { ok: false, error: sh.error };
+
+  // A shell's version is one more site under the same rule.
+  const sites = [...found, ...sh.shells.flatMap((s) => [{ file: s.file, version: s.version }, ...(s.pluginVersions || [])])];
+  if (tag) sites.push({ file: "<tag>", version: stripV(tag) });
+  const distinct = [...new Set(sites.map((s) => s.version))];
+  if (distinct.length !== 1) return { ok: false, error: "version mismatch", versions: distinct, checked: sites };
+
+  // Its pin is exact and equal to that version; its core is bundled; its bin
+  // is the one file it ships. A range here is the unverified pairing the
+  // shells ADR rejects; a missing bundle ships an installer with no core.
+  for (const s of sh.shells) {
+    if (s.pin !== `=${s.version}`) return { ok: false, error: "shell pin mismatch", shell: s.name, pin: s.pin, expected: `=${s.version}`, checked: sites };
+    if (!s.bundled) return { ok: false, error: "shell does not bundle the core", shell: s.name, checked: sites };
+    if (s.bin !== `bin/${s.name}.mjs` || !s.binExists) return { ok: false, error: "shell bin missing or misnamed", shell: s.name, bin: s.bin, expected: `bin/${s.name}.mjs`, checked: sites };
+  }
+  return { ok: true, version: distinct[0], checked: sites, shells: sh.shells.map((s) => ({ name: s.name, private: s.private })) };
+}
+
+// Everything at the repository root that is deliberately NOT in the tarball.
+// This list is the whole point of the tree check below: `npm pack` can only
+// report what `files[]` already allows, so comparing pack output against the
+// fixture is blind to a directory missing from `files[]` — it is absent from
+// both sides and they agree. The tree, not the pack output, is the only place
+// a forgotten directory is visible.
+//
+// Adding a name here is a decision that it must never ship. Anything else new
+// at the root fails the check until it is added to `files[]`.
+export const NOT_SHIPPED = new Set([
+  ".git",
+  ".github", // release/test workflows — not part of the plugin payload
+  ".claude", // local worktrees and the harness's own files
+  LAYOUT.root, // this project's own binding, overlays and state (the layout ADR)
+  ".omc",
+  ".gitignore",
+  ".DS_Store",
+  "node_modules",
+  // `packaging/shells.mjs --build --out dist` writes here, and the release
+  // workflow does exactly that. Gitignored, so it is invisible to git status —
+  // and the tree check is the only place an unlisted root directory shows up.
+  "dist",
+  "CLAUDE.md", // a pointer to AGENTS.md, which does ship
+  "tests", // 240 kB of fixtures nobody installing the plugin needs
+  "packaging", // reserved-name stubs; see packaging/README.md
+  "adapters", // generated harness inputs copied into their distribution shells at build time
+  "package-lock.json",
+]);
+
+// Top-level entries that are neither shipped nor deliberately excluded. Kept
+// pure — it takes the tree listing rather than reading it — so a test can hand
+// it a directory that does not exist and watch it fail.
+export function unshippedTopLevel(entries, packlist) {
+  const shipped = new Set(
+    packlist.map((p) => (p.includes("/") ? p.slice(0, p.indexOf("/")) : p)),
+  );
+  return entries
+    .filter((e) => e !== "." && e !== ".." && !shipped.has(e) && !NOT_SHIPPED.has(e))
+    .sort();
+}
+
+// The packlist is the second release-time invariant: what npm would actually
+// ship. Stored as sorted paths only — sizes churn on every content edit and
+// would make the fixture unreviewable.
+export function currentPacklist(root = ROOT) {
+  const r = spawnSync("npm", ["pack", "--dry-run", "--json"], {
+    cwd: root,
+    encoding: "utf8",
+    timeout: 120000,
+  });
+  if (r.status !== 0) return { error: `npm pack failed: ${r.stderr?.trim()}` };
+  try {
+    const [pkg] = JSON.parse(r.stdout);
+    return { files: pkg.files.map((f) => f.path).sort() };
+  } catch (e) {
+    return { error: `npm pack output unparseable: ${e.message}` };
+  }
+}
+
+async function main(argv) {
+  const tagIdx = argv.indexOf("--tag");
+  const tag = tagIdx !== -1 ? argv[tagIdx + 1] : null;
+  if (tagIdx !== -1 && !tag) die("--tag requires a value");
+
+  if (argv.includes("--write-packlist")) {
+    const { files, error } = currentPacklist();
+    if (error) die(error);
+    try {
+      writeFileAtomic(resolve(ROOT, PACKLIST), JSON.stringify(files, null, 2) + "\n");
+    } catch (e) {
+      // The header promises JSON on stdout always; an escaping stack trace
+      // would break the one caller that parses this.
+      die(`${PACKLIST}: ${e.message}`);
+    }
+    // The shells' fixtures, from the core's CURRENT pack — after the core's
+    // fixture, since each lists the core's files under node_modules/. A lazy
+    // import: scripts/ ships and packaging/ does not, so a static specifier
+    // here would ship a module that cannot load.
+    const shellsModule = resolve(ROOT, "packaging", "shells.mjs");
+    const shells = [];
+    if (existsSync(shellsModule)) {
+      const m = await import(pathToFileURL(shellsModule).href);
+      const built = m.buildShells({ root: ROOT });
+      if (built.error) die(built.error);
+      for (const b of built.shells) {
+        if (b.error) die(b.error);
+        const rel = m.shellPacklistPath(b.name);
+        try { writeFileAtomic(resolve(ROOT, rel), JSON.stringify(b.files, null, 2) + "\n"); } catch (e) { die(`${rel}: ${e.message}`); }
+        shells.push({ wrote: rel, count: b.files.length });
+      }
+    }
+    process.stdout.write(
+      JSON.stringify({ ok: true, wrote: PACKLIST, count: files.length, shells }) + "\n",
+    );
+    return;
+  }
+
+  const result = checkVersions({ tag });
+  process.stdout.write(JSON.stringify(result) + "\n");
+  if (!result.ok) process.exit(1);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main(process.argv.slice(2));
+}