entropy-machines 0.1.1

package/lib/changelog-collate.mjs

@@ -0,0 +1,328 @@
+#!/usr/bin/env node
+/**
+ * changelog-collate — turn fragment files into changelog sections.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The naive design has every commit edit the TOP of one shared changelog
+ * file. Under concurrent agents editing in parallel worktrees, that file is
+ * the one place their otherwise-disjoint changes collide — three parallel
+ * merges landing at once is enough to guarantee a conflict there and nowhere
+ * else in the diff. The usual mitigation is procedural (one session writes
+ * all the entries, everyone else is forbidden to touch the file), which
+ * serialises a step that should be parallel. One file per entry removes the
+ * shared write instead: two agents produce two adds, and two adds never
+ * conflict.
+ *
+ * ORDER
+ * -----
+ * Not the filename. A fragment authored earlier on a branch that merges
+ * after one authored later belongs *after* it in history, so the order of
+ * record is the order the fragments entered git — `git log --diff-filter=A`
+ * over the fragment directory, newest first, which is exactly the order the
+ * file reads in. Fragments that are not committed yet are the in-flight
+ * commit: they sort to the top by filename, descending, and render with a
+ * `HEAD` hash. Filename order is the fallback when git is unavailable.
+ *
+ * STATUS
+ * ------
+ * The ⏳/✅ marker in the `##` heading comes from the fragment's `status:`
+ * line, not from the collated file. A project may wire an external hook to
+ * flip the newest pending fragment's status and re-collate — after a QA pass,
+ * say, or a CI job — but that integration is optional and lives outside this
+ * script; nothing here assumes it exists or names what triggers it. Status is
+ * deliberately NOT derived from commit ancestry against some checkpoint file:
+ * a repo that cherry-picks onto its main branch rewrites hashes, and an
+ * ancestry-derived marker would silently reset.
+ *
+ * MODES
+ *   (none)    print the collated block to stdout
+ *   --write   splice it into the collated file between the collation markers
+ *   --init    insert the markers if absent, then --write
+ *   --check   validate every fragment; with markers present, also verify the
+ *             collated region in the collated file is not stale
+ *
+ * --write refuses to act when the markers are absent. That keeps the change
+ * inert until someone runs --init once on purpose: the collated file is the
+ * file this whole exercise is about not touching by surprise.
+ *
+ * Fragment directory, collated-file path and the marker text all come from
+ * config.json's `changelog.*` keys — see docs/CONFIG.md.
+ */
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from './config.mjs';
+
+const config = loadConfig();
+const REPO_ROOT = config._root;
+const FRAGMENT_DIR = path.join(REPO_ROOT, config.changelog.fragmentDir);
+const FRAGMENT_PREFIX = `${config.changelog.fragmentDir}/`;
+const CHANGELOG = path.join(REPO_ROOT, config.changelog.collatedFile);
+
+const CHANGELOG_REL = config.changelog.collatedFile;
+const COLLATE_CMD = config.changelog.collateCmd ?? 'node lib/changelog-collate.mjs';
+
+const BEGIN = config.changelog.marker;
+if (!BEGIN.includes('BEGIN')) {
+  throw new Error(
+    `changelog.marker (${JSON.stringify(BEGIN)}) must contain the literal text "BEGIN" — ` +
+      'the matching end marker is derived by swapping it for "END".',
+  );
+}
+const END = BEGIN.replace('BEGIN', 'END');
+
+const STATUS_MARKER = {
+  pending: '⏳',
+  verified: '✅',
+  broken: '🚫',
+};
+
+/** Fragment files, in plain descending filename order. `_`-prefixed are skipped. */
+function listFragments() {
+  if (!fs.existsSync(FRAGMENT_DIR)) return [];
+  return fs
+    .readdirSync(FRAGMENT_DIR)
+    .filter((n) => n.endsWith('.md') && !n.startsWith('_') && !n.startsWith('.'))
+    .sort()
+    .reverse();
+}
+
+/**
+ * Parse the `---`-delimited header. Values may be quoted; a `#` inside a value
+ * is not a comment (titles contain them). Returns {header, body}.
+ */
+function parseFragment(name, text) {
+  const lines = text.split('\n');
+  let i = 0;
+  while (i < lines.length && lines[i].trim() === '') i++;
+  if (lines[i]?.trim() !== '---') {
+    throw new Error(`${name}: expected a \`---\` header block on the first non-blank line`);
+  }
+  i++;
+  const header = {};
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '---') {
+      i++;
+      break;
+    }
+    const m = /^([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$/.exec(line);
+    if (!m) throw new Error(`${name}: unparseable header line ${i + 1}: ${JSON.stringify(line)}`);
+    let value = m[2].trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"') && value.length > 1) ||
+      (value.startsWith("'") && value.endsWith("'") && value.length > 1)
+    ) {
+      value = value.slice(1, -1);
+    }
+    header[m[1]] = value;
+  }
+  return { header, body: lines.slice(i).join('\n').trim() };
+}
+
+function validate(name, header, body) {
+  const problems = [];
+  for (const key of ['status', 'date', 'title']) {
+    if (!header[key]) problems.push(`missing \`${key}:\``);
+  }
+  if (header.status && !STATUS_MARKER[header.status]) {
+    problems.push(
+      `status \`${header.status}\` is not one of ${Object.keys(STATUS_MARKER).join(' / ')}`,
+    );
+  }
+  if (header.date && !/^\d{4}-\d{2}-\d{2}$/.test(header.date)) {
+    problems.push(`date \`${header.date}\` is not YYYY-MM-DD`);
+  }
+  if (!body) problems.push('empty body');
+  return problems.map((p) => `${name}: ${p}`);
+}
+
+/**
+ * name -> short hash of the commit that ADDED it. Absent for fragments that
+ * are not committed yet. Insertion order of the returned Map is the git order:
+ * newest commit first.
+ */
+function gitAddOrder() {
+  const order = new Map();
+  let out;
+  try {
+    out = execFileSync(
+      'git',
+      [
+        '-C',
+        REPO_ROOT,
+        'log',
+        '--diff-filter=A',
+        '--format=%h',
+        '--name-only',
+        '--',
+        FRAGMENT_PREFIX,
+      ],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+    );
+  } catch {
+    return order; // not a repo, or git missing — filename order is the fallback
+  }
+  let hash = null;
+  for (const raw of out.split('\n')) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (/^[0-9a-f]{7,40}$/.test(line) && !line.endsWith('.md')) {
+      hash = line;
+      continue;
+    }
+    if (line.startsWith(FRAGMENT_PREFIX)) {
+      const name = line.slice(FRAGMENT_PREFIX.length);
+      if (!order.has(name)) order.set(name, hash);
+    }
+  }
+  return order;
+}
+
+function collectEntries() {
+  const byFilename = listFragments();
+  const added = gitAddOrder();
+  const problems = [];
+  const parsed = new Map();
+
+  for (const name of byFilename) {
+    const text = fs.readFileSync(path.join(FRAGMENT_DIR, name), 'utf8');
+    try {
+      const { header, body } = parseFragment(name, text);
+      problems.push(...validate(name, header, body));
+      parsed.set(name, { name, header, body });
+    } catch (err) {
+      problems.push(String(err.message));
+    }
+  }
+
+  // Uncommitted first (filename-descending), then committed in git order.
+  const uncommitted = byFilename.filter((n) => !added.has(n));
+  const committed = [...added.keys()].filter((n) => parsed.has(n));
+
+  const entries = [];
+  for (const name of uncommitted) {
+    if (parsed.has(name)) entries.push({ ...parsed.get(name), hash: 'HEAD' });
+  }
+  for (const name of committed) {
+    entries.push({ ...parsed.get(name), hash: added.get(name) ?? 'HEAD' });
+  }
+  return { entries, problems };
+}
+
+function render(entries) {
+  if (entries.length === 0) return '';
+  return entries
+    .map((e) => {
+      const marker = STATUS_MARKER[e.header.status] ?? '⏳';
+      const issue = e.header.issue ? ` (${e.header.issue})` : '';
+      const title = e.header.title.endsWith(issue) ? e.header.title : `${e.header.title}${issue}`;
+      return `## ${marker} ${e.hash} — ${e.header.date} — ${title}\n\n${e.body}\n\n---\n`;
+    })
+    .join('\n');
+}
+
+function readChangelog() {
+  return fs.readFileSync(CHANGELOG, 'utf8');
+}
+
+function spliceInto(text, block) {
+  const b = text.indexOf(BEGIN);
+  const e = text.indexOf(END);
+  if (b === -1 || e === -1 || e < b) return null;
+  const before = text.slice(0, b + BEGIN.length);
+  const after = text.slice(e);
+  return `${before}\n\n${block}${block ? '\n' : ''}${after}`;
+}
+
+/** Insert an empty marker pair immediately above the first `## ` section. */
+function insertMarkers(text) {
+  if (text.includes(BEGIN)) return text;
+  const lines = text.split('\n');
+  let at = lines.findIndex((l) => l.startsWith('## '));
+  if (at === -1) at = lines.length;
+  const head = lines.slice(0, at);
+  // Drop the trailing `---` rule the old header ended with; the last collated
+  // entry supplies its own, so keeping both would double the rule.
+  while (head.length && head[head.length - 1].trim() === '') head.pop();
+  if (head.length && head[head.length - 1].trim() === '---') head.pop();
+  while (head.length && head[head.length - 1].trim() === '') head.pop();
+  return [...head, '', BEGIN, '', '---', '', END, '', ...lines.slice(at)].join('\n');
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const mode = args.find((a) => a.startsWith('--')) ?? '';
+  const { entries, problems } = collectEntries();
+
+  if (problems.length) {
+    for (const p of problems) console.error(`changelog: ${p}`);
+    if (mode === '--check') {
+      console.error(`\nchangelog: ${problems.length} malformed fragment(s). See ${config.changelog.fragmentDir}/_template.md.`);
+      process.exit(1);
+    }
+    process.exit(1);
+  }
+
+  const block = render(entries);
+
+  if (mode === '--check') {
+    const text = fs.existsSync(CHANGELOG) ? readChangelog() : '';
+    if (!text.includes(BEGIN)) {
+      console.log(
+        `changelog: ${entries.length} fragment(s) OK. ${CHANGELOG_REL} has no collation markers yet (run --init when you want them).`,
+      );
+      return;
+    }
+    // Compare with heading hashes normalised away. A fragment added by the
+    // commit under test renders as `HEAD` while it is uncommitted and as its
+    // real short hash once it lands, so a literal comparison reports "stale"
+    // for every commit that adds an entry — a state the author cannot fix,
+    // because the hash does not exist until after the commit does. Found by
+    // dogfooding this on its own landing commit. Content drift is the thing
+    // worth guarding; hash resolution is bookkeeping that `--write` does at
+    // build time.
+    const unhash = (s) => s.replace(/^## (✅|⏳|🚫) [0-9a-f]{7,40} —/gm, '## $1 <hash> —')
+                           .replace(/^## (✅|⏳|🚫) HEAD —/gm, '## $1 <hash> —');
+    const want = spliceInto(text, block);
+    if (unhash(want) !== unhash(text)) {
+      console.error(
+        `changelog: ${CHANGELOG_REL} collated region is stale. Run \`${COLLATE_CMD}\`.`,
+      );
+      process.exit(1);
+    }
+    console.log(`changelog: ${entries.length} fragment(s) OK, collated region current.`);
+    return;
+  }
+
+  if (mode === '--write' || mode === '--init') {
+    let text = readChangelog();
+    if (!text.includes(BEGIN)) {
+      if (mode !== '--init') {
+        console.error(
+          `changelog: ${CHANGELOG_REL} has no collation markers. Run \`${COLLATE_CMD} --init\` once to add them (this is the only edit that touches the existing file).`,
+        );
+        process.exit(2);
+      }
+      text = insertMarkers(text);
+    }
+    const next = spliceInto(text, block);
+    if (next === null) {
+      console.error('changelog: markers present but malformed (END before BEGIN?).');
+      process.exit(2);
+    }
+    if (next !== readChangelog()) {
+      fs.writeFileSync(CHANGELOG, next);
+      console.log(`changelog: wrote ${entries.length} fragment(s) into ${CHANGELOG_REL}.`);
+    } else {
+      console.log(`changelog: ${CHANGELOG_REL} already current (${entries.length} fragment(s)).`);
+    }
+    return;
+  }
+
+  process.stdout.write(block);
+}
+
+main();

package/lib/changelog-guard.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# changelog-guard — a commit that touches a watched path must add a fragment
+# under `changelog.fragmentDir`. What counts as "watched" is config.json's
+# `changelog.watchedPathPatterns`; the default is `["**"]`, i.e. every path,
+# until a project narrows it.
+#
+# One implementation, two callers, so the local hook and CI cannot drift:
+#
+#   lib/changelog-guard.sh --staged            # pre-commit: the index
+#   lib/changelog-guard.sh --range A..B         # CI: every non-merge commit
+#   lib/changelog-guard.sh --commit <sha>       # one commit
+#
+# A rule enforced only by a hook is enforced by nothing: hooks live in
+# .git/ and are not version-controlled, so anyone who never runs the hook
+# installer has no hook at all. That is the general shape of a setting that
+# is silently ignored rather than refused — this repo's own hook installer
+# (lib/install-hooks.sh) verifies its own install for exactly that reason.
+# CI is the gate that actually lives in the repo; the hook is the fast local
+# echo of it.
+#
+# Escape hatch, for a genuinely entry-free commit (a revert, a mechanical
+# rename). It takes two forms because the two callers see different things:
+# pre-commit has no commit message yet, and CI has nothing but the message.
+#
+#   SKIP_CHANGELOG=1 git commit -m "chore: rename only [skip changelog]"
+#
+# The env var satisfies the hook; the `[skip changelog]` marker is what
+# survives into history and satisfies CI. Use both, or the commit passes
+# locally and fails on push.
+#
+# `git commit --no-verify` is NOT an escape hatch. It skips the hook and
+# leaves nothing behind, so CI fails and there is no record of the intent.
+#
+# The whole feature is optional: `changelog.enabled: false` in config.json
+# turns this script into a no-op. A consuming project may not want a
+# fragment-per-commit changelog at all.
+
+set -euo pipefail
+
+# ENTROPY_MACHINES_HOME is the harness DIRECTORY — where config.py sits — which may be
+# the repo root or a subdirectory of it. It is not a root and not a separate
+# repo (see lib/roots.sh). The shim installed by lib/install-hooks.sh exports
+# it; the fallback is for direct invocation, by hand or from a test.
+#
+# There is deliberately NO root variable here. Everything this guard reads is
+# `git diff --cached` against whatever working tree git put us in, which is
+# the tree the commit belongs to — the right answer in a linked worktree as
+# well as the main checkout. config.py finds config.json from cwd the same
+# way, and config.json is a TRACKED file, so it is present in every worktree.
+if [ -z "${ENTROPY_MACHINES_HOME:-}" ]; then
+  ENTROPY_MACHINES_HOME="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd -P)"
+fi
+CONFIG_PY="$ENTROPY_MACHINES_HOME/lib/config.py"
+
+ENABLED="$(python3 "$CONFIG_PY" get changelog.enabled)"
+if [ "$ENABLED" != "true" ]; then
+  echo "changelog-guard: changelog.enabled is false in config.json — skipped."
+  exit 0
+fi
+
+FRAGMENT_DIR="$(python3 "$CONFIG_PY" get changelog.fragmentDir)"
+NEW_FRAGMENT_CMD="$(python3 "$CONFIG_PY" get changelog.newFragmentCmd)"
+WATCHED_RE="$(python3 "$CONFIG_PY" glob-re changelog.watchedPathPatterns)"
+FRAGMENT_RE="$(python3 "$CONFIG_PY" changelog-fragment-re)"
+SKIP_MARKER='[skip changelog]'
+
+fail() {
+  cat >&2 <<EOF
+changelog-guard: $1 touches a watched path (config.json changelog.watchedPathPatterns) but adds no fragment under ${FRAGMENT_DIR}/.
+
+  ${NEW_FRAGMENT_CMD} "type(scope): what changed" [issue-id]
+
+then fill in the body and stage it. One fragment per commit — that is the
+whole point: your fragment is a file nobody else writes, so it cannot
+conflict with another agent's.
+
+Genuinely no entry needed?
+  SKIP_CHANGELOG=1 git commit -m "... ${SKIP_MARKER}"
+Both parts matter: the env var clears the hook, the marker clears CI.
+EOF
+  exit 1
+}
+
+if [ "${SKIP_CHANGELOG:-}" = "1" ]; then
+  echo "changelog-guard: SKIP_CHANGELOG=1 — skipped."
+  echo "changelog-guard: put '${SKIP_MARKER}' in the commit message too, or CI will fail this commit."
+  exit 0
+fi
+
+# A commit whose message carries the marker is exempt in CI, the same way the
+# env var exempts it locally.
+skipped_by_message() {
+  git log -1 --format='%B' "$1" | grep -qF "$SKIP_MARKER"
+}
+
+check_lists() {
+  # $1 = all changed paths, $2 = added paths
+  local changed="$1" added="$2" label="$3"
+  if ! printf '%s\n' "$changed" | grep -Eq "$WATCHED_RE"; then
+    return 0
+  fi
+  if printf '%s\n' "$added" | grep -Eq "$FRAGMENT_RE"; then
+    return 0
+  fi
+  fail "$label"
+}
+
+MODE="${1:---staged}"
+
+case "$MODE" in
+  --staged)
+    changed=$(git diff --cached --name-only --diff-filter=ACMRD)
+    added=$(git diff --cached --name-only --diff-filter=A)
+    check_lists "$changed" "$added" "the staged change"
+    echo "changelog-guard: staged change OK."
+    ;;
+
+  --commit)
+    sha="${2:?--commit needs a sha}"
+    if skipped_by_message "$sha"; then
+      echo "changelog-guard: $(git log -1 --format='%h %s' "$sha") — ${SKIP_MARKER}, skipped."
+      exit 0
+    fi
+    changed=$(git show --pretty=format: --name-only --diff-filter=ACMRD "$sha")
+    added=$(git show --pretty=format: --name-only --diff-filter=A "$sha")
+    check_lists "$changed" "$added" "commit $(git log -1 --format='%h %s' "$sha")"
+    echo "changelog-guard: $(git log -1 --format='%h %s' "$sha") OK."
+    ;;
+
+  --range)
+    range="${2:?--range needs A..B}"
+    # Merge commits are skipped: their content already passed on the branch.
+    commits=$(git rev-list --no-merges --reverse "$range")
+    if [ -z "$commits" ]; then
+      echo "changelog-guard: no non-merge commits in $range."
+      exit 0
+    fi
+    n=0
+    for sha in $commits; do
+      if skipped_by_message "$sha"; then
+        echo "changelog-guard: $(git log -1 --format='%h %s' "$sha") — ${SKIP_MARKER}, skipped."
+        n=$((n + 1))
+        continue
+      fi
+      changed=$(git show --pretty=format: --name-only --diff-filter=ACMRD "$sha")
+      added=$(git show --pretty=format: --name-only --diff-filter=A "$sha")
+      check_lists "$changed" "$added" "commit $(git log -1 --format='%h %s' "$sha")"
+      n=$((n + 1))
+    done
+    echo "changelog-guard: $n commit(s) in $range OK."
+    ;;
+
+  *)
+    echo "usage: changelog-guard.sh [--staged | --commit <sha> | --range A..B]" >&2
+    exit 2
+    ;;
+esac

package/lib/changelog-new.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * changelog-new — create one changelog fragment, print its path.
+ *
+ *   node lib/changelog-new.mjs -- "fix(scope): what changed" issue-id
+ *
+ * The filename is <YYYYMMDD>-<HHMMSS>-<slug>-<6 hex>.md.
+ *
+ * The timestamp is for ordering and for reading the directory by eye. The six
+ * random hex characters are what make it collision-proof, and they are the
+ * point: two agents in two worktrees cannot see each other, so anything
+ * derived from the directory (a sequence number) is a race, and anything
+ * derived from the clock alone collides at second resolution. Randomness is
+ * the only per-write unique value available without coordination. Ordering
+ * does not depend on it — the collator orders by the commit that added the
+ * file, and falls back to filename only for fragments not yet committed.
+ *
+ * Fragment directory is config.json's `changelog.fragmentDir` (default
+ * `changelog.d`) — see docs/CONFIG.md.
+ */
+
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from './config.mjs';
+
+const config = loadConfig();
+const REPO_ROOT = config._root;
+const FRAGMENT_DIR = path.join(REPO_ROOT, config.changelog.fragmentDir);
+
+const [, , titleArg, issueArg] = process.argv;
+if (!titleArg) {
+  console.error('usage: node lib/changelog-new.mjs -- "type(scope): subject" [issue-id]');
+  process.exit(2);
+}
+
+const now = new Date();
+const p2 = (n) => String(n).padStart(2, '0');
+const day = `${now.getFullYear()}${p2(now.getMonth() + 1)}${p2(now.getDate())}`;
+const time = `${p2(now.getHours())}${p2(now.getMinutes())}${p2(now.getSeconds())}`;
+const date = `${now.getFullYear()}-${p2(now.getMonth() + 1)}-${p2(now.getDate())}`;
+
+const slugSource = issueArg || titleArg;
+const slug =
+  slugSource
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48) || 'entry';
+
+const name = `${day}-${time}-${slug}-${randomBytes(3).toString('hex')}.md`;
+const file = path.join(FRAGMENT_DIR, name);
+
+fs.mkdirSync(FRAGMENT_DIR, { recursive: true });
+fs.writeFileSync(
+  file,
+  `---
+status: pending
+date: ${date}
+issue: ${issueArg ?? ''}
+title: ${JSON.stringify(titleArg)}
+---
+
+TODO: what changed and why.
+
+Verification: TODO — what you ran, with the numbers.
+`,
+);
+
+console.log(path.relative(REPO_ROOT, file));