@ersbeth/codelife 0.0.0-stage → 0.11.1

package/scripts/contract.mjs

@@ -0,0 +1,179 @@
+// The one reader of the project contract, `.claude/codelife.md` (K-19 — The project contract): its
+// frontmatter and its prose sections. Every script that needs a field calls it (#1077). It reads the
+// block form /setup writes, and a flow mapping or a flow list where one stands for a value —
+// `tracker: { kind: glab }`, `- { path: dist/, when: [src/**] }` — the subset of YAML a contract
+// uses, never a document YAML at large. `check` is what /setup and /overview hold a contract to.
+import './node-floor.mjs'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const SCHEMA = 2
+export const FILE = '.claude/codelife.md'
+const KEYS = ['codelife', 'kind', 'tracker', 'app', 'guards', 'generated', 'release']
+const PROSE = ['Setup', 'Never', 'Raise before doing', 'Tracker notes']
+
+// scan <text> <fn> — calls fn(c, i) on each character outside quotes, with the bracket depth.
+const scan = (text, fn) => {
+  let quote = '', depth = 0
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i]
+    if (quote) { if (c === quote) quote = ''; continue }
+    if (c === '"' || c === "'") { quote = c; continue }
+    if (fn(c, i, depth) === false) return
+    if (c === '[' || c === '{') depth++
+    else if (c === ']' || c === '}') depth--
+  }
+  return depth
+}
+// uncomment <line> — the line without a `#` comment: one at its start or after a space, outside quotes.
+const uncomment = (line) => {
+  let end = line.length
+  scan(line, (c, i) => { if (c === '#' && (i === 0 || /\s/.test(line[i - 1]))) { end = i; return false } })
+  return line.slice(0, end).trimEnd()
+}
+// split <text> — the items of a flow collection's inside, at its top-level commas.
+const split = (text) => {
+  const out = []
+  let from = 0
+  scan(text, (c, i, depth) => { if (c === ',' && !depth) { out.push(text.slice(from, i)); from = i + 1 } })
+  return [...out, text.slice(from)].map((s) => s.trim()).filter(Boolean)
+}
+const pair = (text) => { const m = /^([\w.-]+):(?:\s+(.*))?$/.exec(text); return m && [m[1], m[2] ?? ''] }
+// value <text> — a scalar, a flow list as an array, a flow mapping as an object.
+const value = (text) => {
+  const t = text.trim()
+  if (t.startsWith('[')) return split(t.slice(1, t.lastIndexOf(']'))).map(value)
+  if (t.startsWith('{')) return Object.fromEntries(split(t.slice(1, t.lastIndexOf('}'))).map((p) => pair(p) ?? [p, '']).map(([k, v]) => [k, value(v)]))
+  return t.replace(/^(['"])(.*)\1$/, '$2')
+}
+
+// lines <front> — the frontmatter's logical lines, { indent, text }: comments and blank lines gone,
+// a flow collection open across several lines joined into one.
+const logical = (front) => {
+  const out = []
+  for (const raw of front.split('\n')) {
+    const text = uncomment(raw)
+    const open = out.at(-1)
+    if (open?.open) { open.text += ` ${text.trim()}`; open.open = scan(open.text, () => {}) > 0; continue }
+    if (!text.trim()) continue
+    out.push({ indent: text.length - text.trimStart().length, text: text.trim(), open: scan(text, () => {}) > 0 })
+  }
+  return out
+}
+
+// block <lines> <at> <indent> — the node whose lines start at `at`, indented deeper than `indent`:
+// a list when its first line opens on `- `, a mapping otherwise. Returns [node, next index].
+const block = (ls, at, indent) => {
+  const first = ls[at]
+  if (!first || first.indent <= indent) return ['', at]
+  const deep = first.indent
+  if (first.text.startsWith('- ') || first.text === '-') {
+    const list = []
+    while (ls[at]?.indent === deep && /^-( |$)/.test(ls[at].text)) {
+      const item = ls[at].text.slice(2).trim()
+      const kv = !/^[[{'"]/.test(item) && pair(item)
+      if (!kv) { list.push(value(item)); at++; continue }
+      // a mapping item: its first pair on the dash's line, the rest indented past the dash
+      const inner = [{ indent: deep + 2, text: item }]
+      for (at++; ls[at] && ls[at].indent > deep; at++) inner.push(ls[at])
+      list.push(block(inner, 0, deep)[0])
+    }
+    return [list, at]
+  }
+  const map = {}
+  while (ls[at]?.indent === deep) {
+    const kv = pair(ls[at].text)
+    if (!kv) { at++; continue }
+    const [k, v] = kv
+    if (/^[>|][+-]?$/.test(v)) {                     // a folded or literal scalar: the deeper lines
+      const body = []
+      for (at++; ls[at] && ls[at].indent > deep; at++) body.push(ls[at].text)
+      map[k] = body.join(v.startsWith('>') ? ' ' : '\n')
+    } else if (v) { map[k] = value(v); at++ }
+    else [map[k], at] = block(ls, at + 1, deep)
+  }
+  return [map, at]
+}
+
+// parse <text> — { front, prose, data, sections } of a contract's text, read past one leading
+// `generated by codelife` marker line; `data` is {} when it opens on no frontmatter. A `## ` line
+// inside a fenced block is no heading.
+export const parse = (text) => {
+  const body = text.replace(/^<!-- generated by codelife\b.*-->[ \t]*\r?\n/, '')
+  const parts = body.split(/^---[ \t]*$/m)
+  const front = body.startsWith('---') ? parts[1] ?? '' : ''
+  const prose = body.startsWith('---') ? parts.slice(2).join('---') : body
+  const unfenced = prose.replace(/^(`{3,}|~{3,}).*\n[\s\S]*?^\1.*$/gm, (m) => m.replace(/[^\n]/g, ' '))
+  const sections = new Map([...unfenced.matchAll(/^## (.*?)[ \t]*$/gm)].map((m, i, all) =>
+    [m[1], prose.slice(m.index + m[0].length, all[i + 1]?.index ?? prose.length).trim()]))
+  return { front, prose, data: block(logical(front), 0, -1)[0] || {}, sections }
+}
+
+// contract [root] — the parsed contract of the repository at root, or null when it has none.
+export const contract = (root = '.') => {
+  const p = join(root, FILE)
+  if (!existsSync(p)) return null
+  const text = readFileSync(p, 'utf8')
+  return { text, ...parse(text) }
+}
+
+// valid [root] — the parsed contract, or the one line that stops a run (R-8): `no contract …` when
+// the file is absent, its first invalid line when it is invalid. A stale field stops nothing (R-9).
+export const valid = (root = '.') => {
+  const c = contract(root)
+  if (!c) return { stop: `no contract at ${FILE} — \`/setup\` writes one` }
+  const [first] = check(c, root).invalid
+  return first ? { stop: `the contract is invalid — ${first}; \`/setup\` rewrites it` } : { contract: c }
+}
+
+// field <path> [root] — one value by its dotted path, `tracker.kind`; undefined when absent, the
+// contract too. An invalid contract stops the run on valid()'s line (R-8), whichever field is read.
+export const field = (path, root = '.') => {
+  const v = valid(root)
+  if (v.stop && existsSync(join(root, FILE))) { console.error(`- stop: ${v.stop}`); process.exit(1) }
+  return path.split('.').reduce((o, k) => (o && typeof o === 'object' ? o[k] : undefined), v.contract?.data)
+}
+
+// entries <key> [root] — guards[] or generated[], each entry's values as lists: a scalar is a list of one.
+const list = (v) => (v === undefined || v === '' ? [] : Array.isArray(v) ? v : [v])
+export const entries = (key, root) => list(field(key, root)).filter((e) => e && typeof e === 'object')
+  .map((e) => Object.fromEntries(Object.entries(e).map(([k, v]) => [k, list(v)])))
+
+// check <parsed> [root] — { invalid, stale }: the lines that make a contract invalid, the order
+// R-8 holds them in, then the fields whose referent moved (R-9).
+export const check = (c, root = '.') => {
+  const invalid = [], stale = []
+  const d = c.data
+  const schema = d.codelife
+  for (const k of Object.keys(d).filter((k) => !KEYS.includes(k))) (Number(schema) < SCHEMA ? stale : invalid).push(`${k}: a key schema ${SCHEMA} does not know`)
+  for (const [k, v] of [['codelife', schema], ['kind', d.kind], ['tracker.kind', d.tracker?.kind], ['release.version_file', d.release?.version_file]]) if (!v) invalid.push(`${k}: missing — the contract was not written by /setup`)
+  if (schema && !/^\d+$/.test(schema)) invalid.push(`codelife: '${schema}' is no integer`)
+  else if (Number(schema) > SCHEMA) invalid.push(`codelife: written for schema ${schema}, the plugin reads ${SCHEMA} — the plugin is too old to read it`)
+  else if (schema && Number(schema) < SCHEMA) stale.push(`codelife: written for schema ${schema}, the plugin reads ${SCHEMA}`)
+  if (d.kind && !['lib', 'app', 'none'].includes(d.kind)) invalid.push(`kind: '${d.kind}' is none of lib, app, none`)
+  if (d.tracker?.kind && !['glab', 'gh', 'none'].includes(d.tracker.kind)) invalid.push(`tracker.kind: '${d.tracker.kind}' is none of glab, gh, none`)
+  if ('app' in d && d.kind !== 'app') invalid.push(`app: under kind ${d.kind}, which runs nothing`)
+  // The shape of each block: the keys it may hold, and the lists an entry of guards[] or generated[] needs.
+  for (const [k, allowed] of [['tracker', ['kind']], ['release', ['version_file']], ['app', ['url', 'start']]])
+    if (k in d) for (const x of typeof d[k] === 'object' && d[k] ? Object.keys(d[k]).filter((x) => !allowed.includes(x)) : ['']) invalid.push(`${k}${x && `.${x}`}: ${x ? `not a key of ${k}, which holds ${allowed.join(' and ')}` : `holds ${allowed.join(' and ')}`}`)
+  for (const [k, needed, optional] of [['guards', ['when', 'run'], ['note']], ['generated', ['path', 'command', 'when'], []]])
+    list(d[k]).forEach((e, i) => {
+      if (!e || typeof e !== 'object') return invalid.push(`${k}[${i}]: an entry holds ${needed.join(', ')}`)
+      for (const x of needed.filter((x) => !(x in e))) invalid.push(`${k}[${i}].${x}: missing`)
+      for (const x of Object.keys(e).filter((x) => ![...needed, ...optional].includes(x))) invalid.push(`${k}[${i}].${x}: not a key of an entry`)
+    })
+  for (const h of c.sections.keys()) if (!PROSE.includes(h)) invalid.push(`## ${h}: none of the four prose sections`)
+  const at = (p) => existsSync(join(root, p))
+  if (d.release?.version_file && !at(d.release.version_file)) stale.push(`release.version_file: ${d.release.version_file} is gone`)
+  const each = (key) => list(d[key]).filter((e) => e && typeof e === 'object').map((e) => Object.fromEntries(Object.entries(e).map(([k, v]) => [k, list(v)])))
+  for (const p of each('generated').flatMap((g) => g.path ?? [])) if (!at(p)) stale.push(`generated: ${p} is gone`)
+  let pj = null
+  try { pj = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) } catch { /* none */ }
+  for (const cmd of each('guards').flatMap((g) => g.run ?? [])) {
+    const words = cmd.split(/\s+/)
+    const script = /^(pnpm|npm|yarn)$/.test(words[0]) ? (words[1] === 'run' ? words[2] : words[1]) : null
+    if (script && !['install', 'exec', 'dlx', 'test'].includes(script) && !pj?.scripts?.[script]) stale.push(`guards: \`${cmd}\` — no script ${script} in package.json`)
+    for (const w of words.slice(1).filter((w) => /^[\w.][\w./-]*\.(mjs|cjs|js|sh|ts)$|\//.test(w) && !w.startsWith('-') && !w.includes('*'))) if (!at(w)) stale.push(`guards: \`${cmd}\` — ${w} is gone`)
+  }
+  return { invalid, stale }
+}

package/scripts/former-form.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+// The one place that knows the FORMER form of a repository set up by codelife: copies of the
+// scripts, the whole hooks, a `postinstall`, a marketplace declared in `.claude/settings.json`.
+// `/setup` migrates such a repository to the package by calling this file, and nothing else names
+// the former form, so retiring the recognition is deleting this file once picoflow, codelife and
+// three-js-mesh-colors are migrated (K-1 — setup, R-153).
+//
+//   node former-form.mjs detect [repo]            what the repository still carries, as JSON
+//   node former-form.mjs settings [repo]          the marketplace lines of .claude/settings.json
+//   node former-form.mjs migrate <group> [repo]   group: hooks | changelog
+//
+// Every function takes the repository as a path and touches only it; the one exception is the
+// uninstall of the former copy on the machine, which hooks does through `claude`. The package
+// itself is never migrated: its scripts/ are the originals the others are copies of.
+import './node-floor.mjs'
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { field } from './contract.mjs'
+
+const PKG = '@ersbeth/codelife'
+const FROM_PACKAGE = `node_modules/${PKG}/scripts/`
+const HOOKS = ['pre-commit', 'pre-push', 'commit-msg']
+const PREPARE = `node ${FROM_PACKAGE}install.mjs`
+const KEY = 'codelife@codelife'
+
+const read = (p) => { try { return readFileSync(p, 'utf8') } catch { return null } }
+
+// A JSON file is rewritten only when printing it back reproduces it byte for byte, so every key
+// that is not ours stays as it was; a file that does not round-trip is reported, never reformatted.
+function readJson(p) {
+  const text = read(p)
+  if (text === null) return null
+  let data
+  try { data = JSON.parse(text) } catch { return { text, data: null } }
+  const indent = /^[ \t]+(?=")/m.exec(text)?.[0] ?? '  '
+  const eol = text.endsWith('\n') ? '\n' : ''
+  const print = (d) => JSON.stringify(d, null, indent) + eol
+  return { text, data, print, exact: print(data) === text }
+}
+
+const isPackage = (repo) => readJson(join(repo, 'package.json'))?.data?.name === PKG
+const kindOf = (repo) => field('kind', repo)
+const providesMarketplace = (repo) => readJson(join(repo, '.claude-plugin/marketplace.json'))?.data?.name === 'codelife'
+
+// Replaces the lines that declared the marketplace and enabled the plugin by one that turns a
+// former copy off: project settings outrank a person's, so the copy is off for everyone who clones.
+// A repository that never had the former form gets nothing, and one that provides the marketplace
+// itself keeps its settings: the published copy is never the one under edit.
+export function mergeSettings(repo) {
+  const p = join(repo, '.claude/settings.json')
+  const file = readJson(p)
+  if (!file?.data) return { status: file ? 'unreadable' : 'absent' }
+  const s = file.data
+  if (providesMarketplace(repo)) return { status: 'provides-marketplace' }
+  const declared = s.extraKnownMarketplaces?.codelife !== undefined
+  const enabled = s.enabledPlugins?.[KEY] !== undefined && s.enabledPlugins[KEY] !== false
+  if (!declared && !enabled) return { status: 'unchanged' }
+  if (!file.exact) return { status: 'not-round-trip', note: `${p} would be reformatted by an automatic edit: replace the marketplace and plugin lines by "${KEY}": false under enabledPlugins by hand` }
+  if (declared) {
+    delete s.extraKnownMarketplaces.codelife
+    if (!Object.keys(s.extraKnownMarketplaces).length) delete s.extraKnownMarketplaces
+  }
+  s.enabledPlugins = { ...s.enabledPlugins, [KEY]: false }
+  writeFileSync(p, file.print(s))
+  return { status: 'migrated' }
+}
+
+// What each group of the former form is made of; a group is the /setup item that deletes it. The
+// `scripts` item runs before the package is installed and cannot call this file, so the
+// `.mcp.json` it might have owned goes with `hooks`, the item that installs the package.
+function copies(repo) {
+  const has = (f) => existsSync(join(repo, f))
+  const full = HOOKS.map((h) => `.githooks/${h}`).filter((f) => has(f) && !read(join(repo, f)).includes(FROM_PACKAGE))
+  const own = !has('scripts/changelog.mjs') ? [] : ['scripts/changelog.mjs', 'scripts/node-floor.mjs'].filter(has)
+  return {
+    hooks: [...full, ...['scripts/spec-form.mjs', ...(kindOf(repo) === 'app' ? [] : ['.mcp.json'])].filter(has)],
+    changelog: [...['scripts/changelog.sh', 'cliff.toml'].filter(has), ...own],
+  }
+}
+
+export function detect(repo) {
+  if (isPackage(repo)) return { package: true, hooks: [], changelog: [], postinstall: false, marketplace: false }
+  const pkg = readJson(join(repo, 'package.json'))?.data
+  const s = readJson(join(repo, '.claude/settings.json'))?.data
+  return {
+    ...copies(repo),
+    postinstall: typeof pkg?.scripts?.postinstall === 'string' && /hooksPath|\.githooks|install\.mjs|codelife/.test(pkg.scripts.postinstall),
+    marketplace: s?.extraKnownMarketplaces?.codelife !== undefined || (s?.enabledPlugins?.[KEY] !== undefined && s.enabledPlugins[KEY] !== false),
+  }
+}
+
+// The contract's guards[] and generated[] name the commands the copies were run by; they name the
+// package's now. Only the frontmatter's command lines are touched, in the commit of the copy gone.
+export function rewriteContract(repo, group) {
+  const p = join(repo, '.claude/codelife.md')
+  const text = read(p)
+  if (text === null) return false
+  const rules = {
+    hooks: [/(?<![\w/.-])(?:\.\/)?scripts\/spec-form\.mjs/g, `${FROM_PACKAGE}spec-form.mjs`],
+    changelog: [/(?:\b(?:bash|sh|node) +)?(?<![\w/.-])(?:\.\/)?scripts\/changelog\.(?:sh|mjs)/g, `node ${FROM_PACKAGE}changelog.mjs`],
+  }[group]
+  if (!rules) return false
+  const end = text.indexOf('\n---', 4)
+  const out = text.slice(0, end).replace(...rules) + text.slice(end)
+  if (out !== text) writeFileSync(p, out)
+  return out !== text
+}
+
+// `postinstall` runs in whoever installs a dependency; the package's install belongs to `prepare`.
+export function rewritePrepare(repo) {
+  const p = join(repo, 'package.json')
+  const file = readJson(p)
+  if (!detect(repo).postinstall) return 'unchanged'
+  if (!file.exact) return 'not-round-trip'
+  const scripts = file.data.scripts
+  delete scripts.postinstall
+  scripts.prepare = !scripts.prepare ? PREPARE : scripts.prepare.includes(FROM_PACKAGE) ? scripts.prepare : `${scripts.prepare} && ${PREPARE}`
+  writeFileSync(p, file.print(file.data))
+  return 'migrated'
+}
+
+function ignoreLink(repo) {
+  const p = join(repo, '.gitignore')
+  const text = read(p) ?? ''
+  if (/^\/?\.claude\/skills\/codelife\/?$/m.test(text)) return false
+  writeFileSync(p, `${text}${text === '' || text.endsWith('\n') ? '' : '\n'}.claude/skills/codelife\n`)
+  return true
+}
+
+// Deletes one group's copies and rewrites what named them. `hooks` also leaves the repository the
+// package's way: its `prepare`, the ignored link, the settings line and the former copy on this
+// machine, which `claude` removes. The uninstall's exact form is unverified, so its failure is a
+// note, not a stop.
+export function migrate(repo, group, { claude = 'claude' } = {}) {
+  const report = { removed: [], rewritten: [], notes: [] }
+  if (isPackage(repo)) return report
+  const found = detect(repo)
+  for (const f of found[group] ?? []) { rmSync(join(repo, f)); report.removed.push(f) }
+  if (rewriteContract(repo, group)) report.rewritten.push('.claude/codelife.md')
+  if (group === 'hooks') {
+    const prepare = rewritePrepare(repo)
+    if (prepare === 'migrated') report.rewritten.push('package.json')
+    if (prepare === 'not-round-trip') report.notes.push('package.json would be reformatted by an automatic edit: replace postinstall by the prepare line by hand')
+    if (ignoreLink(repo)) report.rewritten.push('.gitignore')
+    const settings = mergeSettings(repo)
+    if (settings.status === 'migrated') report.rewritten.push('.claude/settings.json')
+    if (settings.note) report.notes.push(settings.note)
+    if (found.marketplace) {
+      const r = spawnSync(claude, ['plugin', 'uninstall', KEY], { cwd: repo, encoding: 'utf8', stdio: 'pipe' })
+      report.notes.push(r.status === 0 ? `uninstalled ${KEY} from this machine` : `could not uninstall ${KEY} (${r.error?.code ?? `exit ${r.status}`}): run \`claude plugin uninstall ${KEY}\` yourself — unverified form`)
+    }
+  }
+  return report
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const [cmd, a, b] = process.argv.slice(2)
+  const out = {
+    detect: () => detect(a ?? '.'),
+    settings: () => mergeSettings(a ?? '.'),
+    migrate: () => migrate(b ?? '.', a),
+  }[cmd]
+  if (!out || (cmd === 'migrate' && !['hooks', 'changelog'].includes(a))) {
+    console.error('usage: former-form.mjs detect [repo] | settings [repo] | migrate <hooks|changelog> [repo]')
+    process.exit(2)
+  }
+  console.log(JSON.stringify(out(), null, 2))
+}

package/scripts/git/branches.mjs

@@ -0,0 +1,6 @@
+// git.branches(glob): the local branches and origin's, as this clone last fetched them, whose name
+// the glob matches — one per line, a remote one as `origin/<name>`. Reads only; the forge is not read.
+import { arg, git } from './lib.mjs';
+
+const glob = arg(0, '<glob>');
+process.stdout.write(git('for-each-ref', '--format=%(refname:short)', `refs/heads/${glob}`, `refs/remotes/origin/${glob}`));

package/scripts/git/commit.mjs

@@ -0,0 +1,40 @@
+// git.commit(message file, paths): check, touching nothing; stage the paths; commit the index whole
+// from the file, with no stdin for a hook to wait on; print what is left (R-84, C-142). The contract —
+// what it refuses, what it prints, its exit codes — is `codelife help commit`'s.
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { arg, die, records } from './lib.mjs';
+
+const msg = arg(0, '<message file> <path>...'), paths = process.argv.slice(3);
+if (!paths.length) die('usage: node commit.mjs <message file> <path>...', 2);
+if (!existsSync(msg)) die(`no message file ${msg}`, 2);
+if (paths.some((p) => p.includes('\n'))) { console.log('unreadable'); process.exit(2); }
+
+const git = (args, stdio = ['ignore', 'pipe', 'inherit']) =>
+  spawnSync('git', ['--literal-pathspecs', ...args], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024, stdio });
+const read = (...a) => { const r = git(a); if (r.status !== 0) die(`git ${a.join(' ')} failed`, 2); return r.stdout; };
+const names = (rs) => { const out = []; for (let i = 0; i < rs.length; i++) { out.push(rs[i].slice(3)); if (/[RC]/.test(rs[i].slice(0, 2))) i++; } return out; };
+const changed = (...p) => names(records(read('status', '--porcelain', '-z', '--untracked-files=all', ...p)));
+
+// A merge, cherry-pick or revert stages what it brings: only outside one is a staged stray a mistake.
+const midway = ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD'].some((h) => git(['rev-parse', '-q', '--verify', h], 'ignore').status === 0);
+if (!midway) {
+  const staged = (...p) => records(read('diff', '--cached', '--no-renames', '--name-only', '-z', ...p));
+  const covered = new Set(staged('--', ...paths)), stray = staged().filter((f) => !covered.has(f));
+  if (stray.length) die(stray.map((f) => `staged beforehand: ${f}`).join('\n'), 2);
+}
+// A deletion `git rm` already staged is that path's change — a file's, or a folder's gone from the
+// disk — and `git add` would find nothing to match.
+const removed = records(read('diff', '--cached', '--no-renames', '--diff-filter=D', '--name-only', '-z', '--', ...paths));
+const adds = paths.filter((p) => !removed.some((f) => f === p || (!existsSync(p) && f.startsWith(`${p.replace(/\/+$/, '')}/`))));
+if (adds.length && git(['add', '--dry-run', '--', ...adds], ['ignore', 'ignore', 'inherit']).status !== 0) process.exit(2);
+
+if (adds.length && git(['add', '--', ...adds], ['ignore', 'inherit', 'inherit']).status !== 0) process.exit(2);
+const c = git(['commit', '-q', '-F', msg], ['ignore', 'inherit', 'inherit']);
+if (c.status !== 0) process.exit(c.status === null ? 2 : 1);
+
+console.log(read('log', '-1', '--format=%h %s').trim());
+const mine = changed('--', ...paths);
+const say = (label, f) => console.log(f.includes('\n') ? `unreadable: ${label}` : `${label}: ${f}`);
+for (const f of mine) say('left unstaged', f);
+for (const f of changed()) if (!mine.includes(f)) say('not committed', f);

package/scripts/git/diff.mjs

@@ -0,0 +1,17 @@
+// git.diff(base, head): each file of `<base>...<head>` as JSON — `{ status, path, old?, added, removed }`,
+// the status read from --name-status (`A`, `D`, `R100`…), the counts from --numstat (`-` for a binary).
+import { arg, git, records } from './lib.mjs';
+
+const range = `${arg(0, '<base> <head>')}...${arg(1, '<base> <head>')}`;
+const files = [], counts = new Map();
+const s = records(git('diff', '--name-status', '-z', range));
+for (let i = 0; i < s.length; i++) {
+  const status = s[i];
+  files.push(/^[RC]/.test(status) ? { status, old: s[++i], path: s[++i] } : { status, path: s[++i] });
+}
+const c = records(git('diff', '--numstat', '-z', range));
+for (let i = 0; i < c.length; i++) {
+  const [added, removed, path] = c[i].split('\t');
+  counts.set(path || (i += 2, c[i]), { added, removed });
+}
+console.log(JSON.stringify(files.map((f) => ({ ...f, ...counts.get(f.path) }))));

package/scripts/git/diff_lines.mjs

@@ -0,0 +1,5 @@
+// git.diff_lines(base, head, file): `git diff -U0 <base>...<head>` of one file, as git prints it —
+// its `@@` headers give the lines it may be commented on. The path on stdin, a rename's old one first.
+import { arg, git, stdinPaths } from './lib.mjs';
+
+process.stdout.write(git('--literal-pathspecs', 'diff', '-U0', `${arg(0, '<base> <head>')}...${arg(1, '<base> <head>')}`, '--', ...stdinPaths()));

package/scripts/git/held.mjs

@@ -0,0 +1,53 @@
+// git.held(): the held commits that still wait — the commits of the range that no branch of
+// `origin` holds, so a target merged in brings none, whose footer carries a `Held:` trailer and
+// which no later commit of the range names in a `Replaces:` trailer, by its hash or a prefix of 7 or more. The range
+// is the branch's upstream to HEAD — when it is the branch's own, `origin/<branch>` — or, with none, `origin/<target>` to HEAD, the
+// target the optional argument names, else the parent's. Prints `range: <ref>`, then one
+// `waits\t<hash>\t<issues cited>\t<Held: line>` per commit that waits and one `replaced\t<hash>\t<by>\t<Held: line>`
+// per one a later commit redid, oldest first. `could not tell: <why>`, exit 1, when the range cannot be read.
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { git } from './lib.mjs';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const tell = (why) => {
+  console.log(`could not tell: ${why}`);
+  process.exit(1);
+};
+const node = (script) => spawnSync(process.execPath, [join(here, script)], { encoding: 'utf8' });
+const branch = git('branch', '--show-current').trim();
+// An upstream that is not the branch's own on `origin` — a local line, another branch — is no range.
+const own = branch && git('for-each-ref', '--format=%(upstream:short)', `refs/heads/${branch}`).trim() === `origin/${branch}`;
+const upstream = own ? `origin/${branch}` : '';
+let ref = upstream;
+if (!ref) {
+  let name = process.argv[2];
+  if (!name) {
+    const p = node('parent.mjs');
+    [name] = p.stdout.trim().split(' ');
+    if (p.status !== 0 || name === 'finished') tell(p.stdout.trim() || p.stderr.trim() || 'the parent cannot be derived');
+  }
+  ref = `origin/${name}`;
+}
+const resolves = (r) => spawnSync('git', ['rev-parse', '--verify', '--quiet', `${r}^{commit}`]).status === 0;
+if (!resolves(ref)) {
+  // An upstream the merge deleted: a branch HEAD of which `origin/develop` or `origin/main` holds has
+  // nothing left to wait. Deleted unmerged, its pushed commits would read as waiting: could not tell.
+  const merged = upstream && ['origin/develop', 'origin/main'].find((m) => resolves(m) && spawnSync('git', ['merge-base', '--is-ancestor', 'HEAD', m]).status === 0);
+  if (merged) {
+    console.log(`range: none — ${branch} is merged into ${merged}, its upstream gone`);
+    process.exit(0);
+  }
+  tell(`${ref} is no commit git can resolve${upstream ? ' — its upstream is gone' : ''}`);
+}
+const log = spawnSync(process.execPath, [join(here, 'log_since.mjs'), ref], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+if (log.status !== 0) tell(log.stderr.trim() || log.stdout.trim());
+const unpushed = new Set(git('rev-list', 'HEAD', '--not', '--remotes=origin').split('\n'));
+const range = JSON.parse(log.stdout).reverse().filter((c) => unpushed.has(c.sha));
+const redone = (h) => range.find((c) => c.replaces.some((r) => /^[0-9a-f]{7,40}$/i.test(r) && h.sha.startsWith(r.toLowerCase())));
+console.log(`range: ${ref}`);
+for (const h of range.filter((c) => c.held.length)) {
+  const by = redone(h);
+  console.log(by ? `replaced\t${h.sha}\t${by.sha}\tHeld: ${h.held.join(' ')}` : `waits\t${h.sha}\t${h.closes.join(' ')}\tHeld: ${h.held.join(' ')}`);
+}

package/scripts/git/is_ancestor.mjs

@@ -0,0 +1,28 @@
+// git.is_ancestor(a, b): `contained`, `not contained`, `unresolved: <why>`, `no origin` or
+// `could not tell: <git's answer>`; exit 0 for the first two only. A deleted branch and a branch
+// with its own commits are opposite answers, so an unresolvable ref is never `not contained`.
+// A `b` naming a branch of `origin` is read from the forge first, never from the last fetch.
+import { spawnSync } from 'node:child_process';
+import { arg } from './lib.mjs';
+
+const a = arg(0, '<a> <b>'), b = arg(1, '<a> <b>');
+const g = (...args) => spawnSync('git', args, { encoding: 'utf8', input: '' });
+const said = (r) => (r.stderr || r.stdout || r.error?.message || '').trim();
+const end = (line, code = 1) => {
+  console.log(line);
+  process.exit(code);
+};
+if (b.startsWith('origin/')) {
+  const branch = b.slice('origin/'.length);
+  if (g('remote', 'get-url', 'origin').status !== 0) end('no origin');
+  const ls = g('ls-remote', '--exit-code', '--heads', 'origin', branch);
+  if (ls.status === 2) end(`unresolved: origin has no branch ${branch}`);
+  if (ls.status !== 0) end(`could not tell: ${said(ls)}`);
+  const f = g('fetch', 'origin', `+refs/heads/${branch}:refs/remotes/origin/${branch}`);
+  if (f.status !== 0) end(`could not tell: ${said(f)}`);
+}
+for (const ref of [a, b]) if (g('rev-parse', '--verify', '--quiet', `${ref}^{commit}`).status !== 0) end(`unresolved: ${ref} names no commit`);
+const r = g('merge-base', '--is-ancestor', a, b);
+if (r.status === 0) end('contained', 0);
+if (r.status === 1) end('not contained', 0);
+end(`could not tell: ${said(r)}`);

package/scripts/git/lib.mjs

@@ -0,0 +1,20 @@
+// What the scripts under scripts/git/ share — each runs one read or write of git, named after it.
+// From the repository's root. A
+// path a caller holds — a name the merge request chose — reaches a script on stdin, NUL-separated,
+// never as an argument; `commit`'s reach it on its command line.
+import '../node-floor.mjs';
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+export const die = (why, code = 1) => {
+  console.error(why);
+  process.exit(code);
+};
+export const git = (...args) => {
+  const r = spawnSync('git', args, { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+  if (r.status !== 0) die(`git ${args.join(' ')}: ${r.stderr.trim()}`);
+  return r.stdout;
+};
+export const records = (text) => text.split('\0').filter(Boolean);
+export const stdinPaths = () => records(readFileSync(0, 'utf8'));
+export const arg = (i, what) => process.argv[2 + i] || die(`usage: node ${process.argv[1].split('/').pop()} ${what}`, 2);

package/scripts/git/log_since.mjs

@@ -0,0 +1,27 @@
+// git.log_since(ref, tip?): each commit of `<ref>..<tip>`, `HEAD` when no tip is given, as JSON,
+// `{ sha, subject, type, scope, breaking, closes, refs, held, replaces, answers }`, `type` null for a subject that does not parse as a Conventional Commit, the trailers each a list (a `Held:` line stays whole, it is a sentence) — an
+// `Answers: pass <k>: <n>, <m>` one row each, `pass <k> <n>`, so a re-run knows which pass's <n>.
+// With an issue number in place of the tip — `codelife log since <ref> <n>` — one `<sha> <subject>`
+// line per commit whose `Closes:` or `Refs:` footer cites #n, exit 1 when none does (R-201).
+import { arg, git } from './lib.mjs';
+
+const ref = arg(0, '<ref> [<tip> | <issue>]');
+const cites = /^\d+$/.test(process.argv[3] ?? '') ? `#${process.argv[3]}` : null, range = [`${ref}..${cites ? 'HEAD' : process.argv[3] ?? 'HEAD'}`];
+const trailer = (body, key) => [...body.matchAll(new RegExp(`^${key}:[ \\t]*(.+)$`, 'gim'))].flatMap((m) => {
+  if (key === 'Held') return [m[1].trim()];
+  const pass = m[1].match(/^pass (\d+):\s*/i);
+  return m[1].slice(pass ? pass[0].length : 0).split(/[ ,]+/).filter(Boolean).map((x) => (pass ? `pass ${pass[1]} ${x}` : x));
+});
+const commits = git('log', '--format=%H%x1f%s%x1f%b%x1e', ...range).split('\x1e').map((r) => r.trim()).filter(Boolean).map((r) => {
+  const [sha, subject, body = ''] = r.split('\x1f');
+  const cc = subject.match(/^(\w+)(?:\(([^)]+)\))?(!)?: (.+)$/);
+  return { sha, subject, type: cc?.[1] ?? null, scope: cc?.[2] ?? null, breaking: !!cc?.[3] || /^BREAKING CHANGE:/m.test(body),
+    closes: trailer(body, 'Closes'), refs: trailer(body, 'Refs'), held: trailer(body, 'Held'), replaces: trailer(body, 'Replaces'),
+    answers: trailer(body, 'Answers') };
+});
+if (!cites) console.log(JSON.stringify(commits));
+else {
+  const mine = commits.filter((c) => [...c.closes, ...c.refs].includes(cites));
+  for (const c of mine) console.log(`${c.sha.slice(0, 8)} ${c.subject}`);
+  if (!mine.length) { console.error(`no commit of ${ref}..HEAD cites ${cites}`); process.exit(1); }
+}

package/scripts/git/parent.mjs

@@ -0,0 +1,51 @@
+// git.parent(): the branch the current one was cut from, by merge base — `<branch> <commits ahead>`;
+// `finished <line>` when its own commits are merged into a line; `tie <candidates…>` or `none`, exit 1.
+// The candidates are the lines — `develop`, `main`, `support/*` — and the other work branches, each
+// read local and on `origin`: a branch cut from `origin/develop` names `develop` while the local one is
+// ahead, and a branch cut from another lot's branch names that branch.
+import { spawnSync } from 'node:child_process';
+import { git } from './lib.mjs';
+
+const holds = (a, b) => spawnSync('git', ['merge-base', '--is-ancestor', a, b]).status === 0;
+const sha = (ref) => git('rev-parse', `${ref}^{commit}`).trim();
+const head = sha('HEAD');
+const self = spawnSync('git', ['symbolic-ref', '-q', '--short', 'HEAD'], { encoding: 'utf8' }).stdout.trim();
+const isLine = (n) => /^(develop|main|support\/.+)$/.test(n);
+const refs = git('for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/remotes/origin').split('\n')
+  .map((ref) => ({ ref, name: ref.replace(/^refs\/(heads|remotes\/origin)\//, '') }))
+  .filter(({ ref, name }) => ref && name !== self && name !== 'HEAD' && (isLine(name) || /^(feature|fix|hotfix|lot)\//.test(name)));
+const lines = refs.filter((r) => isLine(r.name));
+
+// Merge commits everywhere: merged work reaches a line as a merge's second parent, so its tip lies in
+// the line off every line's first-parent history; a branch with no commit of its own lies on it.
+const firstParents = new Set(lines.flatMap((r) => git('rev-list', '--first-parent', r.ref).split('\n')));
+const mergedInto = (c) => (firstParents.has(c) ? undefined : lines.find((r) => holds(c, r.ref))?.name);
+const done = mergedInto(head);
+if (done) {
+  console.log(`finished ${done}`);
+  process.exit(0);
+}
+
+// Each candidate stands at its merge base with HEAD, so a line that moved on since the cut is still
+// at the commit the branch left it. A work branch whose merge base is HEAD holds HEAD already: it was
+// cut from this one, not this one's base. One already merged stands for the line that holds it.
+const found = refs.flatMap((r) => {
+  const base = git('merge-base', r.ref, 'HEAD').trim();
+  if (base === head && !isLine(r.name)) return [];
+  const name = isLine(r.name) ? r.name : mergedInto(sha(r.ref)) ?? r.name;
+  return [{ name, tip: base, at: sha(r.ref) === base, ahead: +git('rev-list', '--count', `${base}..HEAD`) }];
+});
+const fewest = Math.min(...found.map((c) => c.ahead));
+let best = [...new Map(found.filter((c) => c.ahead === fewest).map((c) => [c.name, c])).values()];
+// Candidates at one merge base are not a tie: a line before a work branch, then the branch's own prefix,
+// then one still at that base, as a support line is at its tag while `main` moved past it.
+if (new Set(best.map((c) => c.tip)).size === 1) {
+  for (const keep of [(c) => isLine(c.name), (c) => (c.name === 'develop') !== self.startsWith('hotfix/'), (c) => c.at]) {
+    if (best.some(keep)) best = best.filter(keep);
+  }
+}
+if (best.length !== 1) {
+  console.log(best.length ? `tie ${best.map((c) => c.name).join(' ')}` : 'none');
+  process.exit(1);
+}
+console.log(`${best[0].name} ${best[0].ahead}`);

package/scripts/git/show.mjs

@@ -0,0 +1,4 @@
+// git.show(ref, path): the file at `ref`, not the tree's — `git show '<ref>:<path>'`. The path on stdin.
+import { arg, git, stdinPaths } from './lib.mjs';
+
+process.stdout.write(git('show', `${arg(0, '<ref> < <path>')}:${stdinPaths()[0]}`));