@sleepy_panda_srl/portulan 0.1.2 → 0.2.0

package/cli/pack-version.mjs

@@ -1,67 +1,7 @@
 #!/usr/bin/env node
 // A change to a pack's `contributes` must move that pack's `portulan.version`.
 //
-// Ruled by the maintainer on `#265`, 2026-08-14, in three parts: **arm 3** — a rail rather than a
-// convention; **a prose-only edit counts**, so a fragment whose `reason` alone changes owes the bump;
-// and the field is **`pack.json`'s `portulan.version`**, not the packs plugin's bundle version.
-//
-// ## Why the field is the pack's own
-//
-// `packs/.claude-plugin/plugin.json` versions the *bundle*. Measured on `c93a819`: it reads `0.2.1`,
-// `rituals/checkpoints` reads `0.2.1` and `tools/github` reads `0.1.0` — so the bundle agrees with one
-// pack by coincidence and cannot track both, and two packs changing in one pull request would contend
-// for a single field. `portulan.version` is per-pack, so it cannot contend. Tying the bundle to the pack
-// manifests is arm 4 of the issue and is deliberately NOT here.
-//
-// ## Why the whole `contributes` block, not only `gates`
-//
-// The issue's title asks about gate fragments; arm 3's own text says *"touching a pack's `contributes`
-// block"*, and arm 3 is what was ruled — confirmed by the maintainer when the two readings were put to
-// him. Skills, personas and verify recipes reach every composing workspace by the same route a gate
-// fragment does.
-//
-// ## THREE-DOT, and it is not a detail
-//
-// The comparison is `base...head` — from the **merge-base** to the head — never `base..head`.
-// Demonstrated rather than asserted, and pinned in `./pack-version.test.mjs`: with a branch that changes
-// `pack.json` while the base branch independently changes another file, two-dot reports BOTH files and
-// three-dot reports only the branch's. A rail on two-dot would red a pull request because somebody else
-// bumped a version upstream, and would read a `contributes` change the pull request never made.
-//
-// `git diff A...B` is exactly `git diff $(git merge-base A B) B`, so this resolves the merge-base once
-// and reads each base manifest at that commit. No diff is parsed: the manifests are compared as VALUES,
-// which is what makes a reformatting-only edit — whitespace, key order — correctly *not* a change.
-//
-// ## Exit codes, and the middle one is the point
-//
-//   0  every changed pack moved its version
-//   1  a pack changed `contributes` and did not move `portulan.version`
-//   2  could not run — no repository, no base ref, no merge-base, or a manifest that will not parse
-//
-// **2 is never 1.** A rail that cannot read its input must not report green, and must not report red
-// either: a red verdict is a claim about the work, and "I could not look" is a claim about the check.
-// That is `../.portulan/memory/verify-preconditions-fail-closed.md`'s rule and the doctrine `#208` is
-// open about for the sibling scanner. It matters most here because `actions/checkout` is shallow by
-// default — `../cli/librarian.mjs` calls that "not a theoretical clone; it is the *normal* one" — so a
-// missing merge-base is the ordinary case on an unprepared runner, not an exotic one.
-//
-// ## What "moved" means, stated because the ruling's word was "moves"
-//
-// **Any change to the string counts, including absent → present.** It is deliberately NOT "the SemVer
-// increased": this rail enforces the maintainer's word, and reading an ordering into it would be the
-// rail deciding a policy it was not given — `0.2.0` → `0.1.0` is a different question, and a bad answer
-// to it, but it is not this one. Absent → present has to count, or a pack red for having no version
-// could never discharge that red. Present → absent is the `unversioned` red, from the head side.
-//
-// ## What this rail does NOT see, named rather than left to be discovered
-//
-// It compares the `contributes` **block**. Content the block merely *points at* — a skill's `SKILL.md`
-// body, a persona file, the shell script a contributed verify recipe names — reaches every adopting
-// workspace and can change without touching `pack.json` at all. Inline material is covered: gate
-// fragments live in the manifest, and so do recipe objects. Pointed-at files are not. That is `#259`'s
-// class — a rail narrower than the sentence around it — and it is stated here rather than closed,
-// because widening it is a different change with a different argument. A rename, or a delete-plus-add
-// under a new name, likewise passes as `deleted` + `added`.
+// Exit 0 every changed pack moved its version · 1 one did not · 2 could not run.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -73,12 +13,6 @@ export class CannotRun extends Error {}
 
 const DEFAULT_BASE = "origin/main";
 
-/**
- * Run git, or say why it could not.
- *
- * `stdio` pins stderr to a pipe so a failure's own message rides into the exception rather than
- * leaking to the terminal and leaving the thrown error to say only "command failed".
- */
 function git(root, args, what) {
     try {
         return execFileSync("git", ["-C", root, ...args], {
@@ -90,38 +24,10 @@ function git(root, args, what) {
     }
 }
 
-/**
- * The merge-base of `base` and `HEAD`, which IS the three-dot comparison point.
- *
- * **A shallow clone reaches this function by TWO different routes, and an earlier draft of these
- * messages knew about only one.** Measured on git, both shapes built as fixtures:
- *
- *   - `--depth 1` alone is also `--single-branch`, so `origin/main` is **not fetched at all** and the
- *     failure is an unknown ref. This is the common CI shape.
- *   - `--depth 1 --no-single-branch` fetches the ref and truncates its history, so the ref resolves and
- *     **no merge-base exists**.
- *
- * So both messages name `fetch-depth: 0` — a reader who lands on either one is most likely looking at a
- * shallow checkout — while staying distinguishable, because the *other* causes differ: an unknown ref
- * can also be a typo or an unfetched remote, and a missing merge-base can also be genuinely unrelated
- * histories. Naming only one of the two would send half of the readers to the wrong repair.
- */
-// **`--end-of-options` on every call that takes the caller's ref**, because `base` is user-supplied —
-// `PORTULAN_BASE_REF`, or `--base` — and git will otherwise read a value that starts with `-` as a FLAG.
-// Measured on git 2.50.1: `git merge-base --is-ancestor HEAD` is parsed as the `--is-ancestor` option and
-// exits 129, so the command silently stops being a merge-base lookup and becomes an ancestry test. With
-// the guard it exits 128, refused as a ref, which is what a bad ref should do.
-//
-// `rev-parse` was already shielded by accident rather than by design: the `^{commit}` suffix makes
-// `--help^{commit}` an unparseable revision rather than a flag. Guarded anyway, so the protection is
-// stated instead of resting on a suffix somebody could reasonably remove.
-//
-// _(Copilot proposed `--` for both, and it is the wrong separator here: measured,
-// `git rev-parse --verify -- HEAD^{commit}` exits **128** — `--` marks the start of PATHS for rev-parse,
-// so the fix would have broken every call. Raised on #274, round 2; the concern was right and the
-// mechanism was not.)_
+// `base` is user-supplied; `--end-of-options` keeps a leading `-` from reading as a flag (`--` means paths).
 const END = "--end-of-options";
 
+/** The merge-base of `base` and HEAD: comparing from it, never from `base`, leaves upstream changes out. */
 export function mergeBase(root, base = DEFAULT_BASE) {
     const shallowHint =
         "`actions/checkout` is shallow by default — `../cli/librarian.mjs` calls that the normal clone rather than a " +
@@ -129,16 +35,6 @@ export function mergeBase(root, base = DEFAULT_BASE) {
     try {
         git(root, ["rev-parse", "--verify", END, `${base}^{commit}`], `resolve ${base}`);
     } catch (cause) {
-        // The cause rides along. A bare `catch {}` here reported EVERY failure of this command as an
-        // unknown ref — including a corrupt object store, a permissions failure, or a git that would not
-        // start — so the message named the one cause it could think of and discarded the one git gave.
-        // `git()` has already captured that stderr; throwing it away and substituting a guess is the
-        // wrong-mechanism-in-a-user-facing-string class this repository keeps finding. Raised by Copilot
-        // on #274, round 4 — and its round 6 caught that the FIX was half-done: the cause rode along
-        // while the leading clause still asserted `is not in this repository`, so the sentence stated one
-        // cause as fact and listed the alternatives underneath it. It now says what HAPPENED (could not
-        // resolve) and ranks the causes as causes. The defect class named in this very comment, surviving
-        // one round inside the repair for it.
         throw new CannotRun(
             `could not resolve base ref \`${base}\` — refusing to report a verdict against a ref nothing could read. ` +
                 `The usual cause is a SHALLOW single-branch clone, which does not fetch it at all; a typo or an ` +
@@ -157,14 +53,7 @@ export function mergeBase(root, base = DEFAULT_BASE) {
     }
 }
 
-/**
- * Is this path THERE — as a directory entry, not as something openable?
- *
- * `fs.existsSync` follows symlinks, so it answers **false** for a dangling link and the entry disappears
- * from every listing built on it. That is the same absent-versus-unreadable confusion this file has now
- * repaired at three sites, and this helper is the sweep `0020` asks for *at the first fix* rather than
- * after a third round found the third one: existence is `lstat`, readability is whoever opens the file.
- */
+/** `lstat`, because `existsSync` follows a symlink and answers false for a dangling one. */
 function presentOnDisk(file) {
     try {
         fs.lstatSync(file);
@@ -174,27 +63,7 @@ function presentOnDisk(file) {
     }
 }
 
-/**
- * `--packs` as a repository-relative path, or a refusal.
- *
- * The flag is documented as *relative to the repository root* and, until #274's round 2, the parser took
- * that on trust. Measured: `path.join("/repo", "../../etc")` is `/etc`, so `--packs ../..` sent the
- * filesystem scan **outside the repository** — and the escape was invisible in the result, because
- * `git ls-tree` then refused the same path and the run ended at exit 2 for a reason that named the wrong
- * thing. Containment is checked after resolution rather than by pattern, since a `..` chain satisfies any
- * regex and still escapes; the same shape `../compile.mjs`'s `policyPath` uses for the same reason.
- *
- * An absolute path is refused outright rather than silently re-rooted: `path.join` turns `/etc` into
- * `<root>/etc`, which is *contained* and is not what the caller asked for, and a flag that quietly means
- * something else is worse than one that refuses.
- */
-// **It returns the CANONICAL path, and the first draft returned the caller's spelling.** That was a
-// correctness defect rather than untidiness, and it produced a false green. `--packs packs/../packs`
-// validated fine — it resolves inside — and then the two halves of `compare` disagreed about what a pack
-// is called: the filesystem scan joined the raw value (`packs/../packs/tools/github/pack.json`) while
-// `git ls-tree` canonicalised its pathspec (`packs/tools/github/pack.json`). Measured: every pack was
-// reported TWICE, once `added` from the uncanonical spelling and once `unchanged` from git's — and
-// `added` is exempt, so a real unbumped change would have passed. Raised by Copilot on #274, round 3.
+/** `--packs`, canonical and repository-relative, so the disk scan and `git ls-tree` spell a pack alike. */
 export function insideRepo(value) {
     if (path.isAbsolute(value)) {
         throw new CannotRun(
@@ -202,9 +71,6 @@ export function insideRepo(value) {
                 `joining an absolute path would silently re-root it under the repository instead of refusing.`,
         );
     }
-    // Normalised, then checked — a `..` chain satisfies any pattern and still escapes, so containment is
-    // decided on the resolved form. Separators are forced to `/` because every downstream consumer is a
-    // git pathspec or a repository-relative id, neither of which is a platform path.
     const canonical = path.normalize(value).split(path.sep).join("/").replace(/\/+$/, "");
     if (canonical === "" || canonical === "." || canonical === ".." || canonical.startsWith("../")) {
         throw new CannotRun(
@@ -215,17 +81,6 @@ export function insideRepo(value) {
     return canonical;
 }
 
-/**
- * Every pack manifest in the tree, as repository-relative paths, sorted so output is stable.
- *
- * **ENOENT is the only benign failure, and an earlier draft of this function treated every failure as
- * benign.** A bare `catch { return [] }` turns an unreadable `packs/` — wrong permissions, a broken
- * symlink, a mount that went away — into *the empty set*, and an empty set is a **green**. That is the
- * shape `../.portulan/memory/verify-preconditions-fail-closed.md` exists about: a recipe that enumerates
- * nothing and reports success has described the machine rather than the work. So the absent directory is
- * an answer (a workspace that composes nothing has no manifests to check) and everything else is a
- * refusal. Found by the session-open checkpoint, which asked what guards the enumeration.
- */
 export function packManifests(root, packsDir = "packs") {
     const base = path.join(root, packsDir);
     const found = [];
@@ -255,21 +110,7 @@ export function packManifests(root, packsDir = "packs") {
     return found.sort();
 }
 
-// **ABSENCE IS A FACT FROM THE LISTING, NEVER AN INFERENCE FROM A FAILED READ.** Both readers below got
-// this wrong in the same way, one function apart from the `readdir` guard that got it right — a fix that
-// missed its own siblings inside a single change, which is `0020`'s shape at its smallest. Demonstrated:
-// `chmod 000` on a tracked `pack.json` made this report the pack **deleted** and exit **0**, so a
-// permissions accident read as an intentional removal and the whole rail went quiet. Found by the
-// pre-commit checkpoint, which attacked the readers after the enumeration guard was added rather than
-// assuming the class had been swept.
-
-/**
- * A manifest as it stood at `commit`, or `null` where it genuinely did not exist there.
- *
- * `present` is the caller's listing from `ls-tree` at that same commit, and it is what decides absence —
- * `git show` failing is then always a refusal, never a shrug. Matching on git's stderr would be the
- * other way to tell the two apart, and it would be a string comparison against another tool's prose.
- */
+/** A manifest at `commit`, or `null` where the caller's `ls-tree` listing lacks it; a failed read throws. */
 export function manifestAt(root, commit, rel, present) {
     if (!present) return null;
     const raw = git(root, ["show", `${commit}:${rel}`], `read ${rel} at ${commit.slice(0, 7)}`);
@@ -283,26 +124,10 @@ export function manifestAt(root, commit, rel, present) {
     }
 }
 
-/**
- * The manifest in the working tree, or `null` where the pack has genuinely been deleted.
- *
- * **`lstat` decides whether the file is there; `readFileSync`'s ENOENT does not.** Third instance of one
- * class in this file, and the sharpest: a **dangling symlink** at `pack.json` makes `readFileSync` throw
- * ENOENT while the path itself plainly exists — measured, `lstat` succeeds and reports
- * `isSymbolicLink: true` — so an ENOENT-only carve-out reported a present-but-unreadable manifest as a
- * pack somebody deleted, at exit 0. The same shape as the `readdir` guard and the absent-vs-unreadable
- * repair before it, at a site both of those left alone.
- *
- * The lstat-first pattern is not invented here: `./control-chars.mjs`'s `bytesOf` already does exactly
- * this, for exactly this reason, down to the sentence — *"Refusing to report it clean: this is a fact
- * about the filesystem, not about the file."* Raised by Copilot on #274, round 7, which also supplied the
- * precedent.
- */
 export function manifestHere(root, rel) {
     const file = path.join(root, rel);
     try {
-        // `lstat`, not `stat`: `stat` follows the link and would throw ENOENT for the dangling case,
-        // which is the very confusion this guard exists to end.
+        // `lstat`, not `stat`: a dangling symlink is there and unreadable, never a deleted pack.
         fs.lstatSync(file);
     } catch (cause) {
         if (cause.code === "ENOENT") return null;
@@ -315,8 +140,6 @@ export function manifestHere(root, rel) {
     try {
         raw = fs.readFileSync(file, "utf8");
     } catch (cause) {
-        // The path EXISTS — `lstat` just said so — so every failure here is the check unable to look:
-        // a dangling symlink, EACCES, EISDIR, a symlink loop. None of them is a deletion.
         throw new CannotRun(
             `cannot read ${rel} — ${cause.code ?? cause.message}. The path exists, so this is not a removal: a ` +
                 `dangling symlink, an unreadable mode or a directory in its place all land here.`,
@@ -329,20 +152,13 @@ export function manifestHere(root, rel) {
     }
 }
 
-/**
- * Deep value equality over parsed JSON, which is deliberately NOT a text comparison.
- *
- * Reformatting a manifest — reindenting, reordering keys — changes its bytes and changes nothing a
- * composing workspace yields, so it must not owe a version bump. Comparing values is what makes that
- * true, and it is why this reads the manifests rather than parsing `git diff`.
- */
+/** Deep equality over parsed JSON, so a reformatted manifest is not a changed one. */
 export function sameValue(a, b) {
     if (a === b) return true;
     if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
     if (Array.isArray(a) !== Array.isArray(b)) return false;
     if (Array.isArray(a)) {
-        // Order IS significant in an array: `contributes.gates` is an ordered list, and `composeFragments`
-        // applies fragments in the order it finds them, so a reordering can change what a workspace yields.
+        // Order is significant: gate fragments apply in the order they are listed.
         return a.length === b.length && a.every((item, i) => sameValue(item, b[i]));
     }
     const ka = Object.keys(a).sort();
@@ -350,22 +166,12 @@ export function sameValue(a, b) {
     return ka.length === kb.length && ka.every((k, i) => k === kb[i]) && ka.every((k) => sameValue(a[k], b[k]));
 }
 
-/**
- * Judge one pack. Returns `{ rel, verdict, why }` with verdict `ok` | `unchanged` | `added` | `deleted`
- * | `stale` | `unversioned`.
- *
- * The two reds are told apart because they need different sentences: `stale` has a version and did not
- * move it, `unversioned` has no version to move.
- */
 export function judge(rel, before, after) {
     if (after === null) return { rel, verdict: "deleted", why: "the pack was removed" };
     if (before === null) {
-        // An added pack has no prior state to bump FROM, so no bump is owed. Whether a new pack must
-        // declare a version at all is a Pack Definition question — `spec/pack.schema.json` currently
-        // makes `portulan.version` optional — and annexing it here would be this rail deciding a schema
-        // rule it was not given. Named in `#265` as a hole with a shape, left to the schema.
         return { rel, verdict: "added", why: "the pack is new — nothing to bump from" };
     }
+    // The block alone: a file it points at, such as a skill's `SKILL.md`, can change unseen.
     if (sameValue(before?.contributes, after?.contributes)) {
         return { rel, verdict: "unchanged", why: "`contributes` is unchanged" };
     }
@@ -391,24 +197,9 @@ export function judge(rel, before, after) {
     return { rel, verdict: "ok", why: `\`contributes\` changed and \`portulan.version\` moved \`${was ?? "(absent)"}\` → \`${now}\`` };
 }
 
-/**
- * Compare every pack in the tree against the merge-base.
- *
- * `packsNamed` says whether the caller *chose* `packsDir`, and it decides what an empty result means.
- * **A directory that is absent is an answer only when nobody named it.** The default `packs/` missing is
- * a workspace that composes nothing — green, correctly. But `--packs paks`, a typo, found nothing at head
- * and nothing at the merge-base and reported *"nothing to check"* at exit **0**: a false green, and a
- * bypass anyone experimenting locally could reach by accident. Measured. So a named directory that exists
- * in neither tree is a refusal, and the ENOENT carve-out in `packManifests` keeps its narrower job.
- * Raised by Copilot on #274, round 5 — on the `Copilot` login of the comments endpoint rather than the
- * `copilot-pull-request-reviewer[bot]` login of `/reviews`, which is the two-logins gotcha this
- * repository already records.
- */
+/** Every pack against the merge-base; a `packsDir` the caller named that neither tree holds is refused. */
 export function compare(root, { base = DEFAULT_BASE, packsDir = "packs", packsNamed = false } = {}) {
     const at = mergeBase(root, base);
-    // The union of what exists NOW and what existed at the merge-base — a pack deleted in this change
-    // has no working-tree manifest and would otherwise never be looked at. It is green either way, but
-    // being green by having been considered is not the same as being green by being invisible.
     const here = packManifests(root, packsDir);
     const there = git(root, ["ls-tree", "-r", "--name-only", at, "--", `${packsDir}/`], `list packs at ${at.slice(0, 7)}`)
         .split("\n")
@@ -431,10 +222,6 @@ export function compare(root, { base = DEFAULT_BASE, packsDir = "packs", packsNa
 
 function usage() {
     return [
-        // NOT `portulan pack-version` — `./portulan.mjs` has eight subcommands and this is not one of
-        // them (measured: it answers "unknown subcommand"), and its own header forbids minting a ninth.
-        // The sibling checkers carry no `portulan <name>` banner either. This is the form the verify
-        // recipe actually runs, which is the only invocation that exists.
         "pack-version — a change to a pack's `contributes` must move its `portulan.version`",
         "",
         "  node cli/pack-version.mjs [--base <ref>] [--packs <dir>] [<repository-root>]",
@@ -450,8 +237,7 @@ function usage() {
 }
 
 export function run(argv = [], { stdout = process.stdout, stderr = process.stderr, cwd = process.cwd() } = {}) {
-    // Before every other argument decision, so asking for help cannot be outranked by a complaint about
-    // the rest of the command line — the contract `./portulan.mjs` states.
+    // First, so a request for help is never outranked by a complaint about the other arguments.
     if (argv.includes("--help") || argv.includes("-h")) {
         stdout.write(`${usage()}\n`);
         return 0;
@@ -466,12 +252,6 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
                 const which = argv[i];
                 const value = argv[i + 1];
                 i += 1;
-                // A single leading `-` is refused too, not just `--`: `--base --packs` would otherwise
-                // consume the next flag as a ref and fail later as an unreadable one. The three tools in
-                // `cli/` that take a directory already read it this way; this aligns with them rather
-                // than inventing. _(A draft used `--base -h` as the example, which never reaches here:
-                // `--help` is answered before any other argument decision, so that spelling exits 0 on
-                // the help path. Measured.)_
                 if (value === undefined || value.startsWith("-")) throw new CannotRun(`${which} needs a value`);
                 if (which === "--base") base = value;
                 else {
@@ -487,9 +267,6 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
             }
         }
         const where = path.resolve(root ?? cwd);
-        // Resolved to the repository top level rather than trusting the argument: a caller invoking this
-        // from a subdirectory would otherwise have every `packs/…` path resolved against the wrong root,
-        // which is #131's class — paths against the author's layout.
         const top = git(where, ["rev-parse", "--show-toplevel"], `find a git repository at ${where}`).trim();
 
         const { at, results } = compare(top, { base, packsDir, packsNamed });
@@ -497,10 +274,7 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
         const moved = results.filter((r) => r.verdict === "ok");
 
         stdout.write(`pack-version: comparing against \`${base}\` at merge-base ${at.slice(0, 7)} (three-dot)\n`);
-        // Every pack is printed, not only the failures. A rail that prints only reds cannot be told from
-        // one that examined nothing — the same reason `compile` prints its refusals on every run. The
-        // `ok` rows carry their `why` too, so a green states WHICH version moved rather than leaving a
-        // reader to diff the manifest to find out what the rail approved.
+        // Every pack is printed, green included, so a green shows what was examined.
         for (const r of results) {
             stdout.write(`  ${r.verdict.padEnd(12)} ${r.rel}${r.verdict === "ok" ? ` — ${r.why}` : ""}\n`);
         }
@@ -519,15 +293,6 @@ export function run(argv = [], { stdout = process.stdout, stderr = process.stder
             stderr.write(`pack-version: ${error.message}\n`);
             return 2;
         }
-        // **A CRASH IS A COULD-NOT-RUN, NOT A RED**, and this file's own header says so two screens up
-        // while an earlier draft did the opposite: an uncaught throw left node exiting **1**, which the
-        // recipe faithfully printed as *"RED — verify recipe failed"*. So a TypeError in this checker
-        // accused the pull request of a policy breach it had not committed — the exact defect `#208` is
-        // open about in the sibling scanner, shipped new in the change that cites it. Demonstrated by
-        // the pre-commit checkpoint with an injected throw.
-        //
-        // The stack is printed rather than swallowed: a crash must stay loud, it just must not wear a
-        // verdict it did not earn.
         stderr.write(`pack-version: CRASHED — ${error?.stack ?? error}\n`);
         stderr.write("pack-version: reporting could-not-run (2) rather than a red verdict — a defect in this checker is not a finding about the work.\n");
         return 2;