@ersbeth/codelife 0.0.0-stage → 0.11.1

package/scripts/mr/open.mjs

@@ -0,0 +1,219 @@
+// The branch's merge request, one command (R-206) — `/mr`, `/work` and `/work-feedback` all push through it.
+// Without `--send` it prints what the confirmation states and sends nothing: the commits leaving, the
+// held choices waiting, the members of the lot still open, how far the branch is behind its target,
+// whether a merge request opens or `!n` is updated — and the facts the description is written from
+// (R-208): the linked issues, the hand commits, the links' base, the run prefix. With `--send` it
+// checks again, refuses a branch behind its target whose merge changes its tree, runs the push tier,
+// pushes with the upstream set — never forced — and creates the merge request or, when the branch
+// has one, replaces the tagged region of its description and nothing outside it. A refusal prints
+// `- stop:` and exits 1, nothing sent.
+// `codelife mr open [<description file>] [--send] [--wrap | --append]`, from the repository's root.
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { packageManager, script } from '../package-manager.mjs';
+import { gist, prep, said, tasks } from '../prepare-lib.mjs';
+import { generatedPaths, git, logged, paths } from '../verify/lib.mjs';
+
+const args = process.argv.slice(2);
+const send = args.includes('--send'), wrap = args.includes('--wrap'), append = args.includes('--append');
+const files = args.filter((a) => !['--send', '--wrap', '--append'].includes(a));
+if (files.length > 1 || files.some((a) => a.startsWith('-')) || (wrap && append) || ((wrap || append) && !files.length)) {
+  console.error('usage: codelife mr open [<description file>] [--send] [--wrap | --append]');
+  process.exit(2);
+}
+const { say, stop, done, op, must, title, kind } = prep('mr open');
+const here = dirname(fileURLToPath(import.meta.url));
+const short = (sha) => sha.slice(0, 8);
+// A marker counts alone on its own line, and the region runs to the last one: a text may quote a marker.
+const REGION = /^<!-- codelife:begin -->[ \t]*$[\s\S]*^<!-- codelife:end -->[ \t]*$/m;
+
+if (kind() === 'none') stop('tracker.kind: none — a merge request has no file-based equivalent; nothing opened');
+const branch = git('branch', '--show-current').out;
+if (!branch) stop('HEAD is detached; nothing to open');
+if (/^(develop|main|support\/.+)$/.test(branch)) stop(`on ${branch}, a line of the repository: there is nothing to open`);
+const parent = op('git', 'parent');
+const [target, extra] = parent.stdout.trim().split(' ');
+if (parent.status !== 0 || target === 'tie' || target === 'none') stop(`the branch's parent cannot be derived — ${said(parent)}`);
+if (target === 'finished') stop(`${branch}'s work is merged into ${extra}; nothing to open`);
+const tip = `origin/${target}`;
+say(`target: ${branch} into ${target}`);
+
+// The description, when one is given: it carries the region and the template's headings, in order.
+// A refusal says what is expected, read from the template: its markers and its whole list.
+// A first line `# <title>` is the merge request's title, and the description is what follows it.
+let file = files[0], body = '', given = '';
+if (file) {
+  try { body = readFileSync(file, 'utf8'); } catch (e) { stop(`the description cannot be read — ${e.message}`); }
+  const head = body.match(/^# (.+)\n+/);
+  if (head) { given = head[1].trim(); body = body.slice(head[0].length); }
+  const heads = (s) => s.split('\n').filter((l) => l.startsWith('## '));
+  const wanted = heads(readFileSync(join(here, '../methods/description.md'), 'utf8'));
+  const expects = `it must hold <!-- codelife:begin --> … <!-- codelife:end --> around, in this order, the lead and ${wanted.map((h) => `"${h}"`).join(', ')}; nothing sent`;
+  if (!REGION.test(body)) stop(`${file} carries no region — ${expects}`);
+  const have = heads(body.match(REGION)[0]);
+  let at = 0;
+  for (const h of wanted) {
+    at = have.indexOf(h, at) + 1;
+    if (!at) stop(`${file} lacks the heading "${h}", or has it out of order — ${expects}`);
+  }
+}
+
+// Behind its target, and what the merge would do.
+const f = git('fetch', '-q', 'origin', target);
+if (f.status) stop(`git fetch origin ${target} failed — ${f.err}`);
+const missing = git('log', '--format=%H%x09%s', `HEAD..${tip}`).out.split('\n').filter(Boolean).map((l) => l.split('\t'));
+const merge = git('merge-tree', '--write-tree', 'HEAD', tip);
+if (merge.status > 1) stop(`git merge-tree failed — ${merge.err}`);
+const conflict = merge.status === 1;
+const unchanged = !conflict && merge.out.split('\n')[0] === git('rev-parse', 'HEAD^{tree}').out;
+say(`behind: ${missing.length} commit${missing.length === 1 ? '' : 's'} behind ${tip}${!missing.length ? ''
+  : conflict ? ` — a merge conflicts: stop, nothing merged; \`git merge ${tip}\` brings it in, by hand`
+  : unchanged ? ' — a merge leaves its tree unchanged, so it counts as up to date'
+  : ` — a merge changes its tree: ask to merge it in, \`git merge ${tip}\`, a red after it the branch merged with its target; on a no, nothing leaves`}`);
+for (const [sha, subject] of missing) say(`missing: ${short(sha)} ${subject}`);
+
+// What leaves, and which held choices wait: `git.held`'s range and rules, the one place they are written.
+const held = op('git', 'held', [target]);
+const [first, ...rows] = held.stdout.trim().split('\n');
+if (held.status !== 0 || !first.startsWith('range: ')) stop(`which held choices wait is unknown — ${held.stdout.trim() || said(held)}`);
+const range = first.slice('range: '.length);
+const up = git('rev-parse', '--abbrev-ref', '@{u}');
+const own = up.status === 0 && up.out === `origin/${branch}`;
+const leaving = JSON.parse(must('git', 'log_since', [range]));
+say(`commits leaving: ${leaving.length} — to origin/${branch}`);
+say(`range base: ${range}`);
+const waits = rows.map((r) => r.split('\t')).filter((r) => r[0] === 'waits'), replaced = rows.map((r) => r.split('\t')).filter((r) => r[0] === 'replaced');
+say(`held choices: ${waits.length}`);
+// The later commits that touch a held commit's files: what a refusal names, as they may rest on it.
+const later = (sha) => {
+  const files = paths('diff-tree', '--no-commit-id', '--name-only', '-r', sha);
+  return files.length ? git('--literal-pathspecs', 'log', '--no-merges', '--format=%h', `${sha}..HEAD`, '--', ...files).out.split('\n').filter(Boolean) : [];
+};
+for (const [, sha, closes, line] of waits) {
+  const on = later(sha);
+  say(`held: ${sha} — ${line}${closes ? ` — ${closes}` : ''}${on.length ? ` — later commits on its files: ${on.join(', ')}` : ''}`);
+}
+for (const [, sha, by, line] of replaced) say(`replaced: ${sha} — ${line} — replaced by ${by}`);
+
+// The members of a lot still open, each with its last STATUS.
+const number = branch.match(/^(?:feature|fix|hotfix|lot)\/(\d+)-/)?.[1];
+const seen = new Map();
+const view = (n) => (seen.get(n) ?? seen.set(n, JSON.parse(must('tracker', 'view', [n]))).get(n));
+// peek — the issue, or null when it cannot be read: a fact of the description never stops the run.
+const peek = (n) => {
+  if (!seen.has(n)) { const r = op('tracker', 'view', [n]); seen.set(n, r.status === 0 ? JSON.parse(r.stdout) : null); }
+  return seen.get(n);
+};
+const umbrella = /^lot\//.test(branch) && number ? view(number) : null;
+const listed = umbrella ? tasks(umbrella.body).map((t) => t.n) : [];
+// A member is open when its issue is, whatever its line says (R-193).
+const members = listed.map((n) => ({ n, issue: view(n) })).filter((m) => !/^closed$/i.test(m.issue.state));
+say(`open members: ${members.length}`);
+for (const { n, issue } of members) {
+  const closing = issue.comments.filter((c) => c.body.startsWith('codelife: closing —')).at(-1);
+  say(`open member: #${n} — ${gist(closing?.body ?? '') ?? 'no STATUS'}`);
+}
+
+// The merge request: opens, or is updated.
+const found = must('tracker', 'mr.find_for_branch', [branch]).split('\n').map((l) => l.match(/^(\d+) open$/)).find(Boolean);
+const mr = found?.[1];
+let described = '', mrTitle = '';
+if (mr) {
+  say(`merge request: !${mr} updated`);
+  if (!file && send) say('description: kept');
+  else {
+    // The description as it stands, in a file the session reads before it rewrites the region.
+    described = must('tracker', 'mr.description', [mr]);
+    const now = join(mkdtempSync(join(tmpdir(), 'mr-open-')), 'description.md');
+    writeFileSync(now, described);
+    if ((wrap || append) && REGION.test(described)) stop(`--wrap and --append answer a description with no region; !${mr}'s carries one, and only it is replaced`);
+    say(`${!file ? 'description: kept without a file' : REGION.test(described) ? 'description: carries the region, only it is replaced'
+      : 'description: carries no region — ask whether to wrap and rewrite it (--wrap) or to append below it (--append)'} — it reads in ${now}`);
+  }
+} else {
+  if (wrap || append) stop('--wrap and --append answer an existing description with no region; this branch has no merge request yet');
+  if (!file && send) {
+    console.error('usage: codelife mr open <description file> --send — a merge request to create needs its description');
+    process.exit(2);
+  }
+  // With no file the dry run goes on, so that the facts the description is written from are printed.
+  if (!given && !number && file) stop(`${branch} carries no issue number; the title cannot be derived`);
+  mrTitle = given || (number ? title('title.sentence_of.mjs', (umbrella ?? view(number)).title) : '');
+  if (!mrTitle && file) stop(`the title of #${number} cannot be derived; nothing sent`);
+  say(`merge request: opens, visible to colleagues, into ${target}`);
+  say(`title: ${mrTitle || `none — ${branch} carries no issue number, so the description opens on \`# <title>\``}`);
+  // A branch whose commits close several issues and that no umbrella names: one issue's title is not the whole.
+  const closed = new Set(leaving.flatMap((c) => c.closes));
+  if (!given && number && !umbrella && closed.size > 1) say(`title: #${number}'s alone, though the commits close ${closed.size} issues — a first line \`# <title>\` in the description gives another`);
+}
+
+// What the description is written from (R-208), in the dry run alone: every issue the branch's commits
+// cite, a lot's members and its umbrella, each with its title; the commits no unit's `closing` comment
+// cites, which are the hand commits; the base a link to a document takes; the run prefix; the generated
+// outputs the diff touches, which are never read; the numbers Debt noticed cites, read back (R-209).
+const facts = () => {
+  const mine = JSON.parse(must('git', 'log_since', [tip])).reverse();
+  const merges = new Set(git('log', '--merges', '--format=%H', `${tip}..HEAD`).out.split('\n').filter(Boolean));
+  const nums = (list) => list.map((x) => x.match(/^#(\d+)$/)?.[1]).filter(Boolean);
+  const closing = [...new Set(mine.flatMap((c) => nums(c.closes)))];
+  const citing = [...new Set([...mine.flatMap((c) => nums(c.refs)), ...listed])].filter((n) => !closing.includes(n) && !(umbrella && n === number));
+  const sentence = (n) => { const i = peek(n); return i ? title('title.sentence_of.mjs', i.title) : '(cannot be read)'; };
+  for (const n of closing) say(`linked: Closes #${n} — ${sentence(n)}`);
+  for (const n of citing) say(`linked: Refs #${n} — ${sentence(n)}`);
+  if (umbrella) say(`linked: Lot: #${number} — ${title('title.sentence_of.mjs', umbrella.title)}`);
+  const reviewed = (c) => nums(c.closes).some((n) => (peek(n)?.comments ?? []).some((k) => k.body.startsWith('codelife: closing —')
+    && (k.body.match(/\b[0-9a-f]{7,40}\b/g) ?? []).some((h) => c.sha.startsWith(h))));
+  const hand = mine.filter((c) => !merges.has(c.sha) && !reviewed(c));
+  say(`hand commits: ${hand.length}`);
+  for (const c of hand) say(`hand commit: ${short(c.sha)} ${c.subject}`);
+  const url = git('remote', 'get-url', 'origin').out;
+  const at = url.match(/^[^@/]+@([^:/]+):(.+?)(?:\.git)?$/) || url.match(/^https?:\/\/(?:[^@/]+@)?([^/:]+)(?::\d+)?\/(.+?)(?:\.git)?$/);
+  if (at) {
+    const base = `https://${at[1]}/${at[2]}/${kind() === 'gh' ? '' : '-/'}blob`;
+    say(`links: ${base}/${target}/<path> — a document this branch adds or rewrites: ${base}/${branch}/<path>`);
+  }
+  const pm = packageManager('.');
+  if (pm) say(`run: ${script(pm, '').slice(0, -1).join(' ')}`);
+  const outputs = generatedPaths(), touched = paths('diff', '--name-only', `${tip}...HEAD`)
+    .filter((p) => outputs.some((o) => p === o || p.startsWith(`${o}/`)));
+  if (touched.length) say(`generated: ${touched.join(', ')} — never read`);
+  const debt = (body.match(REGION)?.[0].split(/^## Debt noticed[ \t]*$/m)[1] ?? '').split(/^## /m)[0];
+  for (const n of new Set(debt.match(/#\d+\b/g)?.map((x) => x.slice(1)) ?? [])) say(`debt: #${n} — ${sentence(n)}`);
+  // An update whose only new commit merges the target in keeps its description (R-212).
+  const fresh = own ? git('log', '--first-parent', '--format=%H %P', '@{u}..HEAD').out.split('\n').filter(Boolean) : [];
+  if (mr && fresh.length && fresh.every((l) => { const p = l.split(' ')[2]; return p && git('merge-base', '--is-ancestor', p, tip).status === 0; })) {
+    say('description: only the target\'s merge is new — keep it: run without a file');
+  }
+};
+
+const dirty = git('status', '--porcelain').out;
+say(`tree: ${dirty ? 'not clean' : 'clean'}`);
+if (!send) { facts(); done(); }
+
+// --send: every check again, then the push tier, the push, the merge request.
+if (missing.length && conflict) stop(`a merge of ${tip} conflicts; nothing sent — \`git merge ${tip}\` brings it in, by hand`);
+if (missing.length && !unchanged) stop(`${branch} is behind ${tip} and a merge changes its tree: ${missing.map(([s, m]) => `${short(s)} ${m}`).join('; ')}; nothing sent`);
+if (dirty) stop('the tree is not clean; nothing sent');
+if (mr && file && !REGION.test(described) && !wrap && !append) stop(`!${mr}'s description carries no region; nothing sent until it is decided: --wrap rewrites it whole, --append keeps it and adds the region below`);
+const tier = logged('the push tier', process.execPath, [join(here, '../verify.mjs'), 'push', tip]);
+if (tier.status !== 0) stop(`failed: the push tier — ${tier.out.trim()}`);
+if (git('status', '--porcelain').out) stop('the push tier left changes in the tree, a regenerated output staged; commit them and run again — nothing pushed');
+say('push tier: green');
+if (!own || +git('rev-list', '--count', '@{u}..HEAD').out > 0) {
+  const p = git('push', '-u', 'origin', branch);
+  if (p.status) stop(`git push failed — ${p.err}`);
+  say(`pushed: origin/${branch}`);
+}
+const dir = mkdtempSync(join(tmpdir(), 'mr-open-'));
+if (!mr) {
+  writeFileSync(join(dir, 'title'), mrTitle); writeFileSync(join(dir, 'body'), body);
+  say(`merge request: ${must('tracker', 'mr.create', [branch, target, join(dir, 'title'), join(dir, 'body')]).trim()}`);
+} else if (file) {
+  // Only a description with no region reads the answer: the file replaces it whole, or goes below it.
+  writeFileSync(join(dir, 'body'), REGION.test(described) ? described.replace(REGION, () => body.match(REGION)[0]) : append ? `${described.trimEnd()}\n\n${body}` : body);
+  const url = must('tracker', 'mr.update_description', [mr, join(dir, 'body')]).trim();
+  say(`merge request: !${mr} updated${url ? ` — ${url}` : ''}`);
+} else say(`merge request: !${mr} kept, its description untouched`);
+done();

package/scripts/node-floor.mjs

@@ -0,0 +1,19 @@
+// The check of `node`'s floor, imported first by every script of the package: an ES module's
+// imports run before the importer's body, so a `node` that is too old is named here instead of
+// failing later on an API the script uses. The floor is the `engines.node` of the package.json
+// beside `scripts/`, so it is written once; a package.json that declares none checks nothing.
+// It cannot name a floor for a syntax the old `node` fails to parse in the importer itself, which
+// is why the scripts stay within what the floor parses.
+import { readFileSync } from 'node:fs'
+
+let floor
+try {
+  const range = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).engines?.node
+  floor = /^>=\s*(\d+)\.(\d+)\.(\d+)$/.exec(range ?? '')?.slice(1).map(Number)
+} catch { /* no readable package.json: nothing to check against */ }
+
+const have = process.versions.node.split('.').map(Number)
+if (floor && (have[0] - floor[0] || have[1] - floor[1] || have[2] - floor[2]) < 0) {
+  console.error(`codelife: node ${process.versions.node} is below ${floor.join('.')}, the lowest version this package runs on`)
+  process.exit(2)
+}

package/scripts/onboard/prep.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// `codelife onboard prep` (K-3 — onboard): everything /onboard reads before it proposes a passage —
+// the kind and the set it makes, each document present or absent and when it last changed against
+// the code, the facts the documents are measured against, and what is known wrong: the open bugs and
+// the notes still pending. Reads only; one `### onboard prep` block; a `- stop:` line and exit 1.
+import '../node-floor.mjs'
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { check, contract, entries } from '../contract.mjs'
+import { unfinished } from '../brainstorm/lib.mjs'
+import { git, json, pkg, read, said, say, sh } from '../setup/lib.mjs'
+import { at, dir } from '../port/lib.mjs'
+
+if (process.argv.length > 2) { console.error('usage: codelife onboard prep'); process.exit(2) }
+console.log('### onboard prep')
+const stop = (why) => { say('stop', why); process.exit(1) }
+if (git('rev-parse', '--show-toplevel').status !== 0) stop('not a git repository')
+const c = contract()
+if (!c) stop('no contract — run /setup first')
+const { invalid } = check(c)
+if (invalid.length) stop(`the contract is invalid — ${invalid.join('; ')}: /setup`)
+const kind = c.data.kind
+const pj = json('package.json') ?? {}
+
+// The workspace packages: each directory a `packages` glob of package.json or pnpm-workspace.yaml names.
+const globs = [...(Array.isArray(pj.workspaces) ? pj.workspaces : pj.workspaces?.packages ?? []),
+  ...[...(read('pnpm-workspace.yaml') ?? '').matchAll(/^\s*-\s*['"]?([^'"\s#]+)/gm)].map((m) => m[1])]
+const subdirs = (d) => { try { return readdirSync(d, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => join(d, e.name)) } catch { return [] } }
+const packages = [...new Set(globs.filter((g) => !g.startsWith('!')).flatMap((g) => (g.endsWith('/*') ? subdirs(g.slice(0, -2)) : [g.replace(/\/$/, '')])))]
+  .filter((d) => existsSync(join(d, 'package.json'))).sort()
+
+// The set the kind makes: the three root documents, a library's consumer SKILL.md, a package's brief where one exists.
+const set = [['readme', 'README.md'], ['contributing', 'CONTRIBUTING.md'], ['claude', 'CLAUDE.md'],
+  ...(kind === 'lib' ? [['skill', at('SKILL.md')]] : []),
+  ...packages.filter((p) => existsSync(join(p, 'CLAUDE.md'))).map((p) => [p.split('/').pop(), join(p, 'CLAUDE.md')])]
+const dirty = git('status', '--porcelain', '--', ...set.map(([, p]) => p)).stdout.trim()
+if (dirty) stop(`a document of the set has changes not committed — a passage's commit would sweep them in: commit or stash them first\n${dirty}`)
+
+const date = (...spec) => git('log', '-1', '--format=%cs', '--', ...spec).stdout.trim()
+const code = date('.', ':(exclude,glob)**/*.md')
+say('kind', `${kind} — the set: ${set.map(([n]) => n).join(', ')}${kind === 'lib' ? '' : ` (no consumer SKILL.md under kind ${kind})`}`)
+for (const [name, path] of set) {
+  if (!existsSync(path)) { say(`document ${name}`, `${path} — absent`); continue }
+  const last = date(path)
+  const notes = [last ? `last changed ${last}${code && last < code ? `, before the code (${code})` : ''}` : 'never committed']
+  if (name === 'skill') {
+    const skill = read(path).match(/^---\n[\s\S]*?^name:[ \t]*(.*)$/m)?.[1].trim().replace(/^(['"])(.*)\1$/, '$2')
+    if (!/^[a-z0-9-]{1,64}$/.test(skill ?? '')) notes.push(`its frontmatter name ${skill ? `\`${skill}\` is` : 'is missing,'} not a skill name — lowercase letters, digits and hyphens`)
+    const files = json(at('package.json'))?.files
+    if (Array.isArray(files) && !files.some((f) => /^(\.\/)?SKILL\.md$/.test(f))) notes.push(`not in ${at('package.json')} files, so it does not ship`)
+  }
+  say(`document ${name}`, `${path} — present, ${notes.join('; ')}`)
+}
+
+// The facts the documents are measured against, each read from where it lives.
+const p = json(at('package.json')) ?? pj
+say('package', `${p.name ?? '(no name)'}${dir() === '.' ? '' : ` in ${dir()}`}${p.private ? ', private' : ''} — ${p.description ?? 'no description'}`)
+const entry = Object.entries({ main: p.main, module: p.module, types: p.types, exports: p.exports && Object.keys(typeof p.exports === 'string' ? { '.': 0 } : p.exports).join(' '), bin: p.bin && (typeof p.bin === 'string' ? p.bin : Object.keys(p.bin).join(' ')) })
+  .filter(([, v]) => v).map(([k, v]) => `${k} ${v}`)
+if (existsSync('index.html')) entry.push(`index.html → ${read('index.html').match(/<script[^>]*src="([^"]+)"/)?.[1] ?? 'no script'}`)
+say('entry', entry.join(' · ') || 'none in the manifest')
+if (packages.length) say('packages', packages.map((d) => `${d}${existsSync(join(d, 'CLAUDE.md')) ? ' (its own CLAUDE.md)' : ''}`).join(' · '))
+const tracked = git('ls-files', '-z').stdout.split('\0').filter(Boolean).filter((f) => !/(^|\/)(dist|node_modules)\//.test(f))
+const byDir = (files) => Object.entries(files.reduce((o, f) => { const d = f.includes('/') ? f.slice(0, f.lastIndexOf('/')) : '.'; o[d] = (o[d] ?? 0) + 1; return o }, {}))
+  .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 20).map(([d, n]) => `${d} ${n}`).join(' · ')
+const test = (f) => /\.(test|spec)\.[cm]?[jt]sx?$/.test(f) || /(^|\/)(tests?|__tests__)\//.test(f)
+const source = tracked.filter((f) => /\.([cm]?[jt]sx?|vue|svelte)$/.test(f))
+say('modules', byDir(source.filter((f) => !test(f))) || 'no source file')
+say('tests', byDir(source.filter(test)) || 'no test file')
+const hooks = ['.githooks', '.husky'].filter(existsSync).map((h) => `${h}: ${readdirSync(h).filter((f) => !f.startsWith('.') && f !== '_').join(' ')}`)
+say('hooks', hooks.join(' · ') || 'none')
+const version = c.data.release?.version_file
+const sections = [...(read('CHANGELOG.md') ?? '').matchAll(/^## \[([^\]]+)\]/gm)].slice(0, 5).map((m) => m[1])
+say('release', `${version} carries ${json(version)?.version ?? 'a version'}; changelog ${sections.length ? sections.join(' · ') : 'without a section'}`)
+const generated = entries('generated').flatMap((g) => g.path)
+if (generated.length) say('generated', generated.join(' '))
+const licence = readdirSync('.').find((f) => /^(LICEN[CS]E|COPYING)(\.|$)/i.test(f))
+say('licence', `${pj.license ?? p.license ?? 'none in the manifest'}${licence ? `, ${licence}` : ', no licence file'}`)
+
+// What is known wrong: the open bugs, by title, then the notes still pending.
+const forge = c.data.tracker?.kind ?? 'none'
+let bugs
+if (forge === 'none') bugs = (existsSync('issues') ? readdirSync('issues').filter((f) => /^\d+-.*\.md$/.test(f)).sort() : []).map((f) => read(join('issues', f)))
+  .filter((t) => /^status:[ \t]*open\b/m.test(t) && /^nature:[ \t]*bug\b/m.test(t)).map((t) => `#${t.match(/^id:[ \t]*(\d+)/m)?.[1]}\t${t.match(/^# (.*)$/m)?.[1]}`)
+else {
+  const r = sh(process.execPath, [join(pkg, 'scripts/tracker/list.mjs'), '--label', 'bug'])
+  bugs = r.status === 0 ? r.stdout.split('\n').filter((l) => l.startsWith('#')).map((l) => l.split('\t').slice(0, 2).join('\t')) : null
+  if (!bugs) say('known', `not read — ${said(r)}`)
+}
+if (bugs) { say('known', `${bugs.length} open bug${bugs.length === 1 ? '' : 's'}`); for (const b of bugs) console.log(`  ${b.replace('\t', ' ')}`) }
+const notes = existsSync('docs/brainstorm') ? unfinished(['docs/brainstorm']).filter((l) => /^[^:]+:\d+: # /.test(l)) : []
+say('notes', notes.length ? `${notes.length} pending` : 'none pending')
+for (const n of notes) console.log(`  ${n.replace(/:\d+: # /, ' — ')}`)

package/scripts/overview/codelife-line.mjs

@@ -0,0 +1,33 @@
+// The one line /overview prints about a newer codelife: the newest `@ersbeth/codelife` published
+// past pnpm's release-age window, against the repository's version, naming /setup when it is newer.
+// `node codelife-line.mjs`, from the repository's root. The repository's version is the one its
+// session loads, `node_modules/@ersbeth/codelife/package.json`'s. The window is
+// `minimum-release-age` as the repository's pnpm reads it, in minutes, and pnpm's default of a day
+// when it sets none; a prerelease is no release to move to. A version or a registry that cannot be
+// read is said, its error quoted, and never read as the repository being current.
+import '../node-floor.mjs';
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+
+const sh = (command) => spawnSync(command, { shell: true, encoding: 'utf8' });
+let have;
+try {
+  have = JSON.parse(readFileSync('node_modules/@ersbeth/codelife/package.json', 'utf8')).version;
+  if (!/^\d+\.\d+\.\d+/.test(have)) throw new Error(`no version in it: '${have}'`);
+} catch (e) {
+  console.log(`codelife: the repository's version could not be read — ${e.message}`);
+  process.exit(0);
+}
+const set = sh('pnpm config get minimum-release-age').stdout.trim();
+const window = set === '' || set === 'undefined' ? 1440 : Number(set);
+const view = sh('pnpm view @ersbeth/codelife time --json');
+if (view.status !== 0) {
+  console.log(`codelife: the published version could not be read — ${`${view.stdout} ${view.stderr}`.trim().replace(/\s+/g, ' ')}`);
+} else {
+  const cutoff = Date.now() - window * 60000;
+  let latest = have;
+  for (const [v, at] of Object.entries(JSON.parse(view.stdout)))
+    if (/^\d+\.\d+\.\d+$/.test(v) && Date.parse(at) <= cutoff && v.localeCompare(latest, 'en', { numeric: true }) > 0) latest = v;
+  console.log(latest === have ? `codelife: ${have}, the latest published past the release-age window`
+    : `codelife: ${latest} is published past the release-age window, this repository is on ${have} — /setup`);
+}

package/scripts/overview/next.mjs

@@ -0,0 +1,76 @@
+// /overview's Next (K-6's R-173): the first rule that holds, in a fixed order from blocking to
+// optional, over what `codelife overview` read. Pure, so every case of the table is a test.
+//
+// Each source of the state is `{ ok: <value> }` or `{ unreadable: '<source> — <error>' }`. A rule
+// holds on what was read; at the first rule that does not hold and whose sources include an
+// unreadable one, the table stops: no lower rule is reached on a failed read, the last least of all.
+//
+// The state: contract { status, lines } · base [<item to do>] · connected bool (null under `none`) ·
+// plans, stops [{ n, to, why }] (`to` the number /work takes; a stop waiting for a case has
+// `waits`) · held { to, why } | null · campaign <folder> | null · untagged <version> | null ·
+// notes [<slug>] · due <why> | null · mrs [{ n, own, reviewed }] · ahead <why> | null ·
+// lots { start: [<umbrella>], lacked: [<umbrella>] } · orphans [{ n, left }].
+import '../node-floor.mjs';
+
+// The rules, in order. `reads` names the state's sources a rule's condition reads; `skills` the
+// commands it can name, which tests/overview.test.mjs holds to the menu.
+export const RULES = [
+  { row: 1, reads: ['contract', 'base'], skills: ['/setup'], test: ({ contract, base }) =>
+    contract && contract.status !== 'ok' ? `the contract is ${contract.status}: ${contract.lines[0]}`
+      : base?.length ? `a base item is left to do: ${base[0]}` : null, next: () => '/setup' },
+  { row: 2, reads: ['connected'], skills: ['/setup'], test: ({ connected }) =>
+    connected === false ? 'this machine is not connected to the forge' : null, next: () => '/setup' },
+  { row: 3, reads: ['plans'], skills: ['/work'], test: ({ plans }) =>
+    plans?.length ? [plans[0], `#${plans[0].n} carries a plan with no closing comment`] : null,
+    next: ([p]) => `/work ${p.to}` },
+  { row: 3, reads: ['stops'], skills: ['/work', '/roadmap'], test: ({ stops }) =>
+    stops?.length ? [stops[0], `#${stops[0].n}: ${stops[0].why}`] : null,
+    next: ([s]) => (s.waits ? '/roadmap' : `/work ${s.to}`) },
+  { row: 3, reads: ['held'], skills: ['/work'], test: ({ held }) => (held ? [held, held.why] : null),
+    next: ([h]) => `/work ${h.to}` },
+  { row: 3, reads: ['campaign'], skills: ['/audit'], test: ({ campaign }) =>
+    campaign ? `the campaign ${campaign} is in progress` : null, next: () => '/audit' },
+  { row: 3, reads: ['untagged'], skills: ['/release'], test: ({ untagged }) =>
+    untagged ? `the version ${untagged} carries no tag` : null, next: () => '/release' },
+  { row: 3, reads: ['notes'], skills: ['/brainstorm'], test: ({ notes }) =>
+    notes?.length ? [notes[0], `docs/brainstorm/ holds ${notes.length === 1 ? 'a note' : `${notes.length} notes`}`] : null,
+    next: ([slug]) => `/brainstorm ${slug}` },
+  { row: 4, reads: ['due'], skills: ['/audit'], test: ({ due }) => due ?? null, next: () => '/audit' },
+  { row: 5, reads: ['mrs'], skills: ['/review-mr'], test: ({ mrs }) => {
+    const m = mrs?.find((x) => !x.own && !x.reviewed);
+    return m ? [m, `!${m.n}, another account's, has no review`] : null;
+  }, next: ([m]) => `/review-mr ${m.n}` },
+  { row: 6, reads: ['ahead'], skills: ['/roadmap'], test: ({ ahead }) => ahead ?? null, next: () => '/roadmap' },
+  { row: 7, reads: ['lots'], skills: ['/work'], test: ({ lots }) => {
+    if (!lots) return null;
+    const [first, ...rest] = lots.start.length ? lots.start : lots.lacked;
+    if (!first) return null;
+    const beside = lots.start.length ? rest : [];
+    return [first, `lot #${first} can start${beside.length ? `, and beside it ${beside.map((n) => `#${n}`).join(', ')}` : ''}${lots.start.length ? '' : ' — no lot of the order can, and the order lacks it'}`];
+  }, next: ([n]) => `/work ${n}` },
+  { row: 8, reads: ['orphans'], skills: ['/roadmap', '/work'], test: ({ orphans }) => {
+    if (!orphans?.length) return null;
+    const fresh = orphans.find((o) => !o.left);
+    if (fresh) return [null, `#${fresh.n} is an orphan the roadmap does not leave alone`];
+    const low = [...orphans].sort((a, b) => a.n - b.n)[0];
+    return [low, `#${low.n}, an orphan the last /roadmap left alone, is work of its own`];
+  }, next: ([o]) => (o ? `/work ${o.n}` : '/roadmap') },
+  { row: 9, reads: [], skills: ['/brainstorm'], test: () => 'nothing is due, half-done or orphan: the next subject is yours', next: () => '/brainstorm' },
+];
+
+// next(state) — { row, next, why }: the first rule that holds, or the stop at a failed read.
+export const next = (state) => {
+  for (const rule of RULES) {
+    const values = {}, failed = [];
+    for (const k of rule.reads) {
+      if (state[k] && 'unreadable' in state[k]) failed.push(state[k].unreadable);
+      else values[k] = state[k]?.ok;
+    }
+    const hit = rule.test(values);
+    if (hit) {
+      const [arg, why] = Array.isArray(hit) ? hit : [null, hit];
+      return { row: rule.row, next: rule.next([arg]), why };
+    }
+    if (failed.length) return { row: rule.row, next: '/overview', why: `cannot conclude past row ${rule.row}: ${failed[0]} — run /overview again once it answers` };
+  }
+};