@ersbeth/codelife 0.0.0-bootstrap.0 → 0.11.1

package/scripts/overview/overview.mjs

@@ -0,0 +1,308 @@
+// `codelife overview` (K-6): where the repository stands, one screen, and the first rule of next.mjs
+// that holds. Reads the contract, the tree, git, `origin`, the tracker and the registry; writes
+// nothing, asks nothing, and never stops before the screen: a source that does not answer is printed
+// as *unreadable*, its error quoted, never as an empty section (R-177).
+import '../node-floor.mjs';
+import { execFile, spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { canStart, lotCount, orderLine, roadmap } from '../read-roadmap/lib.mjs';
+import { next } from './next.mjs';
+import { spellings } from '../tags.mjs';
+import { cadence } from '../audit/cadence.mjs';
+import { check, contract as readContract, SCHEMA } from '../contract.mjs';
+import { auth, items, unmet } from '../setup/lib.mjs';
+import { env, pool } from '../tracker/lib.mjs';
+import { state as portState } from '../port/lib.mjs';
+
+const pkg = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const MAX = 256 * 1024 * 1024;
+const said = (r) => `${r.stdout ?? ''}${r.stderr ?? ''}`.trim() || r.error?.message || '';
+const sh = (file, args, input = '') => spawnSync(file, args, { encoding: 'utf8', input, maxBuffer: MAX });
+const node = (script, args = [], input = '') => sh(process.execPath, [join(pkg, 'scripts', script), ...args], input);
+const git = (...a) => sh('git', a);
+const ok = (value) => ({ ok: value });
+const bad = (source, r) => ({ unreadable: `${source} — ${typeof r === 'string' ? r : said(r)}` });
+const read = (p) => { try { return readFileSync(p, 'utf8'); } catch { return null; } };
+const section = (text, heading) => text.split(new RegExp(`^## ${heading}[ \\t]*$`, 'm'))[1]?.split(/^## /m)[0] ?? '';
+const tag = (title) => (title.startsWith('[') && title.includes(']') ? title.slice(1, title.indexOf(']')) : '');
+const lotOf = (title) => tag(title).match(/(?:^| · )lot #(\d+)$/)?.[1] ?? null;
+const sentence = (title) => (title.startsWith('[') && title.includes('] ') ? title.slice(title.indexOf('] ') + 2) : title);
+const days = (date) => Math.floor((Date.now() - Date.parse(date)) / 86400000);
+const first = (body = '') => body.split('\n')[0];
+// The screen, its sections in R-172's order whatever order they are read in.
+const ORDER = ['Connection', 'Contract', 'Target', 'Audit', 'Issues', 'Merge requests', 'Resumption'];
+const sections = new Map(ORDER.map((s) => [s, []]));
+let current;
+const head = (name) => { current = sections.get(name); };
+// line(text, open) — a line of the current section; `open`, true or its own wording, also lists it
+// under **Left open**: what is stale, to do or unreadable, which the result block copies.
+const leftOpen = [];
+const line = (text, open) => { current.push(`- ${text}`); if (open) leftOpen.push(open === true ? text.trim() : open); };
+const print = (tail) => console.log(['### overview', ...ORDER.filter((s) => sections.get(s).length).flatMap((s) => ['', `**${s}**`, ...sections.get(s)]),
+  '', '**Left open**', ...(leftOpen.length ? leftOpen.map((l) => `- ${l}`) : ['- nothing']), '', tail].join('\n'));
+const state = {};
+
+// The contract (R-175), held by the one reader's check.
+const parsed = readContract();
+if (parsed === null) {
+  head('Contract');
+  line('no contract at `.claude/codelife.md`', true);
+  print('**Next**: `/setup` — a repository without a contract has nothing else to read (row 1)');
+  process.exit(0);
+}
+const contract = { schema: parsed.data.codelife, kind: parsed.data.kind ?? null, tracker: parsed.data.tracker?.kind ?? null, versionFile: parsed.data.release?.version_file ?? null };
+const forge = contract.tracker === 'glab' || contract.tracker === 'gh' ? contract.tracker : 'none';
+const pj = (() => { try { return JSON.parse(read('package.json')); } catch { return null; } })();
+{
+  const { invalid, stale } = check(parsed);
+  const status = invalid.length ? 'invalid' : stale.length ? 'stale' : 'ok';
+  state.contract = ok({ status, lines: [...invalid, ...stale] });
+  head('Contract');
+  line(status === 'ok' ? `current — schema ${contract.schema}, the plugin reads ${SCHEMA}` : `${status}:`);
+  for (const l of [...invalid, ...stale]) line(`  ${l}`, `contract: ${l}`);
+}
+
+// `origin`, the forge's heads, read once: what the forge has, not this clone's memory of it.
+const remote = git('remote', 'get-url', 'origin');
+const where = remote.status === 0 ? remote.stdout.trim().match(/^[^@/]+@([^:/]+):(.+?)(?:\.git)?$|^[a-z+]+:\/\/(?:[^@/]+@)?([^/:]+)(?::\d+)?\/(.+?)(?:\.git)?$/) : null;
+const host = where?.[1] ?? where?.[3], project = where?.[2] ?? where?.[4];
+const ls = git('ls-remote', '--heads', 'origin');
+const heads = ls.status === 0 ? new Map(ls.stdout.split('\n').filter(Boolean).map((l) => { const [sha, ref] = l.split('\t'); return [ref.replace('refs/heads/', ''), sha]; })) : null;
+
+// The connection (R-174), first, and the project's merge settings.
+head('Connection');
+let connected = null, account = null;
+const forgeCall = (args) => spawnSync(forge, args, { encoding: 'utf8', env: env(), input: '', maxBuffer: MAX });
+if (forge === 'none') {
+  line('tracker.kind none — nothing to connect; issues are the files of issues/');
+} else if (!host) {
+  connected = false;
+  line(`not connected → /setup: origin reads as no host — ${said(remote) || 'no origin'}`, true);
+} else {
+  const au = auth(forge, host);
+  connected = au.connected;
+  if (!connected) line(`not connected to ${host} → /setup: ${au.line}`, true);
+  else {
+    const a = node('tracker/account.mjs');
+    account = a.status === 0 ? a.stdout.trim() : null;
+    const exp = au.expires;
+    const left = exp && exp !== 'never' ? -days(exp) : null;
+    line(`connected as ${account ?? `an account unreadable — ${said(a)}`} on ${host}${left !== null && left < 30 ? `, expires in ${left} days — /setup to rotate` : ''}`, account === null || (left !== null && left < 30));
+    const p = forgeCall(forge === 'glab' ? ['api', 'projects/:id'] : ['api', `repos/${project}`]);
+    if (p.status !== 0) line(`the project's settings: unreadable — ${said(p)}`, true);
+    else for (const x of unmet(forge, host, project, JSON.parse(p.stdout))) line(`the project ${x}`, true);
+  }
+}
+state.connected = ok(connected);
+
+// The open issues, their fields and comments, by tracker/list.whole.mjs; an issue's state events
+// by tracker/view.mjs, only where its marks need them (#1150).
+let issues = null, issuesError = null;
+if (forge !== 'none' && !connected) issuesError = 'the tracker — this machine is not connected';
+else {
+  const l = node('tracker/list.whole.mjs');
+  if (l.status !== 0) issuesError = `the tracker's issues — ${said(l)}`;
+  else issues = JSON.parse(l.stdout).map((i) => ({ ...i, lot: lotOf(i.title), umbrella: i.labels.includes('lot') }));
+}
+const fromIssues = (fn) => (issues ? ok(fn(issues)) : { unreadable: issuesError });
+
+// The target (R-176, R-273): the kind, the base items left to do, the toolchain, the codelife line.
+head('Target');
+{
+  const todo = [];
+  let unread = null;
+  for (const i of items({ forge, connected }).filter((x) => x.item !== 'connect')) {
+    if (i.state === 'not read') line(`${i.item}: not read — not connected`);
+    else if (i.why[0]?.startsWith('the labels could not be read')) unread = `the tracker's labels — ${i.why[0].replace(/^.*? — /, '')}`;
+    else if (i.state === 'to do') for (const w of i.why) todo.push(`${i.item} — ${w}`);
+  }
+  state.base = unread ? { unreadable: unread } : ok(todo);
+  line(`kind: ${contract.kind}${contract.kind === 'none' ? ' — base only' : ''}`);
+  if (unread) line(`base: unreadable — ${unread}`, true);
+  line(todo.length ? 'base items to do:' : unread ? 'base, the tree side: done' : 'base: done');
+  for (const t of todo) line(`  ${t}`, `base: ${t}`);
+  // The toolchain: one line of information, never a Next — the port's own measure (K-20, R-19).
+  if (contract.kind === 'lib' || contract.kind === 'app') {
+    const t = portState({ forge, connected });
+    line(`toolchain: ${t.summary}`, /not read/.test(t.summary));
+  }
+  const c = node('overview/codelife-line.mjs');
+  const cl = c.stdout.trim() || `codelife: could not be read — ${said(c)}`;
+  line(cl, /could not be read|\/setup$/.test(cl));
+}
+
+// The audit: the campaign table's last row against the cadence, a campaign under way, its findings.
+head('Audit');
+{
+  const { last: lastRow, next: when, due } = cadence();
+  if (!lastRow) line('no campaign yet');
+  else {
+    line(`last campaign ${lastRow[0]} (${lastRow[2]}) on ${lastRow[1]}`);
+    if (when) line(`next full campaign due ${when}`);
+  }
+  if (due) line(`a campaign is due: ${due}`, true);
+  state.due = ok(due);
+  const progress = (existsSync('docs/audit') ? readdirSync('docs/audit') : []).filter((d) => /^A\d+-/.test(d) && /IN PROGRESS/i.test(read(`docs/audit/${d}/00-index.md`) ?? ''));
+  state.campaign = ok(progress[0] ?? null);
+  for (const d of progress) line(`in progress: docs/audit/${d}/`);
+  const n = lastRow?.[0].match(/^A(\d+)/)?.[1];
+  if (n) {
+    const f = fromIssues((all) => all.filter((i) => !i.umbrella && tag(i.title).startsWith(`audit:A${n}-`)));
+    line('unreadable' in f ? `findings of A${n} still open: unreadable — ${f.unreadable}` : `findings of A${n} still open: ${f.ok.length}`, 'unreadable' in f);
+  }
+}
+
+// The issues and the lots (R-172), by the roadmap's order; the roadmap's mark against docs/spec/.
+head('Issues');
+{
+  const r = roadmap();
+  const roadmaps = (r.roadmap.match(/#\d+/g) ?? []).map((x) => Number(x.slice(1)));
+  let order = [], left = [], outOfShape = null;
+  if (/^#\d+$/.test(r.roadmap) && issues) {
+    const body = issues.find((i) => i.n === roadmaps[0])?.body ?? '';
+    for (const l of section(body, 'The order').split('\n').filter((x) => /^\d+\. /.test(x))) {
+      const o = orderLine(l);
+      if (!o) { outOfShape = l; break; }
+      order.push(o);
+    }
+    left = [...section(body, 'Left alone').matchAll(/^- #(\d+)/gm)].map((m) => Number(m[1]));
+  }
+  // ahead: what docs/spec/ carries that the mark does not (row 6)
+  const last = git('log', '-1', '--format=%H', '--', 'docs/spec/').stdout.trim();
+  const since = (mark) => {
+    const log = git('log', '--format=%h %s', `${mark}..HEAD`, '--', 'docs/spec/').stdout.split('\n').filter(Boolean);
+    const spec = log.filter((l) => / docs\(spec\)/.test(l));
+    const shown = (spec.length ? spec : log);
+    return `${shown.length} commit${shown.length === 1 ? '' : 's'} on docs/spec/ since the mark — ${shown.slice(0, 3).join('; ')}${shown.length > 3 ? '; …' : ''}`;
+  };
+  if (r.roadmap.startsWith('could not tell')) state.ahead = bad('the roadmap', r.roadmap.replace(/^could not tell: /, ''));
+  else if (r.roadmap === 'none') state.ahead = ok(last ? 'no roadmap, and docs/spec/ has commits' : null);
+  else if (r.roadmap.startsWith('two')) state.ahead = ok(`two roadmaps, ${r.roadmap.slice(5)} — close the one you do not keep`);
+  else if (outOfShape) state.ahead = ok(`a line of the roadmap's order is out of shape: ${outOfShape}`);
+  else if (!r.sha) state.ahead = ok(`the roadmap's mark is ${r.mark}`);
+  else if (r.mark.endsWith('not contained')) state.ahead = ok(`the mark ${r.sha} is not in HEAD`);
+  else state.ahead = ok(last && git('merge-base', '--is-ancestor', last, r.sha).status !== 0 ? since(r.sha) : null);
+  line(`roadmap: ${r.roadmap}${r.sha ? `, mark ${r.sha.slice(0, 8)}` : r.mark !== 'none' ? `, mark ${r.mark}` : ''} — ${'unreadable' in state.ahead ? `unreadable: ${state.ahead.unreadable}` : state.ahead.ok ? `ahead: ${state.ahead.ok}` : 'current'}`, 'unreadable' in state.ahead || !!state.ahead.ok);
+  if (!issues) {
+    line(`issues: unreadable — ${issuesError}`, true);
+    for (const k of ['lots', 'orphans', 'plans', 'stops']) state[k] = { unreadable: issuesError };
+  } else {
+    const umbrellas = issues.filter((i) => i.umbrella && !roadmaps.includes(i.n));
+    const open = umbrellas.map((u) => String(u.n));
+    const orderRead = /^#\d+$/.test(r.roadmap) && !outOfShape;
+    const start = orderRead ? canStart(order, open).map(Number) : [];
+    const lacked = orderRead || r.roadmap === 'none' ? umbrellas.filter((u) => !order.some((o) => Number(o.lot) === u.n)).map((u) => u.n).sort((a, b) => a - b) : [];
+    state.lots = r.roadmap.startsWith('could not tell') ? { unreadable: `the roadmap — ${r.roadmap}` } : ok({ start, lacked });
+    const lotLine = (u, why) => {
+      const c = lotCount(u.body);
+      const branch = [...(heads?.keys() ?? []), ...git('for-each-ref', '--format=%(refname:short)', 'refs/heads/lot/').stdout.split('\n')].find((b) => b.startsWith(`lot/${u.n}-`));
+      line(`lot #${u.n} ${sentence(u.title)} — ${c.total - c.open} of ${c.total} done, ${c.effort}${branch ? ` — in progress on ${branch}` : ''} — ${why}`);
+    };
+    for (const o of order) { const u = umbrellas.find((x) => x.n === Number(o.lot)); if (u) lotLine(u, start.includes(u.n) ? 'can start' : `waits for ${o.after.filter((a) => open.includes(a)).map((a) => `#${a}`).join(', ')}`); }
+    for (const n of lacked) lotLine(umbrellas.find((u) => u.n === n), `not in the roadmap's order — can start, waiting for nothing`);
+    if (!orderRead && r.roadmap !== 'none') for (const u of umbrellas) lotLine(u, 'no order read — none can start');
+    if (!umbrellas.length) line('lots: none open');
+    const orphans = issues.filter((i) => !i.umbrella && !i.lot && !roadmaps.includes(i.n));
+    state.orphans = r.roadmap.startsWith('could not tell') ? { unreadable: `the roadmap — ${r.roadmap}` } : ok(orphans.map((o) => ({ n: o.n, left: left.includes(o.n) })));
+    const sev = (i) => i.labels.find((l) => l.startsWith('severity-'))?.slice(9) ?? 'no severity';
+    line(`orphans: ${orphans.length ? '' : 'none'}`);
+    for (const s of ['critical', 'high', 'mid', 'low', 'no severity']) for (const o of orphans.filter((i) => sev(i) === s)) line(`  ${s} — #${o.n} ${o.title}${left.includes(o.n) ? ' — left alone by the last /roadmap' : ''}`);
+    // the resumption artefacts the issues carry (R-177): the last plan, closing, lot-closing or refused
+    const plans = [], stops = [];
+    let unread = null;
+    for (const i of issues) {
+      const marks = i.comments.map((c) => ({ ...c, kind: first(c.body).match(/^codelife: (plan|closing|lot-closing|refused) — /)?.[1] })).filter((c) => c.kind);
+      const lastMark = marks.at(-1);
+      if (!lastMark) continue;
+      const to = i.lot ?? i.n;
+      if (lastMark.kind === 'plan') { plans.push({ n: i.n, to, why: 'a plan with no closing comment' }); continue; }
+      if (lastMark.kind === 'refused') { stops.push({ n: i.n, to, why: `a refused held choice — ${lastMark.body.split('\n').slice(1).find((x) => x.trim())?.trim() ?? 'no reason written'}` }); continue; }
+      const v = node('tracker/view.mjs', [String(i.n)]);
+      if (v.status !== 0) { unread ??= `#${i.n}'s state events — ${said(v)}`; continue; }
+      const closed = JSON.parse(v.stdout).events.some((e) => e.state === 'closed' && e.date >= lastMark.date);
+      if (closed) stops.push({ n: i.n, to, why: `reopened after its ${lastMark.kind}` });
+      else {
+        const waits = marks.filter((m) => m.kind === 'plan').at(-1)?.body.match(/^Waits for: (C-\d+)/m)?.[1];
+        stops.push({ n: i.n, to, waits, why: `a STATUS, the run that posted it having stopped${waits ? ` — waits for ${waits}` : ''}${i.lot ? ` — lot #${i.lot}` : ''}` });
+      }
+    }
+    state.plans = ok(plans);
+    state.stops = unread ? { unreadable: unread } : ok(stops);
+  }
+}
+
+// The merge requests (R-172): target, age, author, and whether a review pass was posted.
+head('Merge requests');
+if (forge === 'none') { line('not tracked'); state.mrs = ok([]); }
+else if (!connected) { line('unreadable — this machine is not connected', 'merge requests: unreadable — not connected'); state.mrs = { unreadable: 'the merge requests — not connected' }; }
+else {
+  const PASS = /^codelife: review — pass \d+ — [0-9a-f]{7,40}$/;
+  const l = forgeCall(forge === 'glab' ? ['api', 'projects/:id/merge_requests?state=opened&per_page=100', '--paginate', '--output', 'ndjson']
+    : ['pr', 'list', '--state', 'open', '--limit', '1000', '--json', 'number,title,baseRefName,createdAt,author']);
+  if (l.status !== 0) { line(`unreadable — ${said(l)}`, `merge requests: unreadable — ${said(l)}`); state.mrs = bad('the merge requests', l); }
+  else {
+    const mrs = (forge === 'glab' ? l.stdout.split('\n').filter(Boolean).map((x) => JSON.parse(x)).map((m) => ({ n: m.iid, title: m.title, target: m.target_branch, at: m.created_at, author: m.author?.username }))
+      : JSON.parse(l.stdout).map((m) => ({ n: m.number, title: m.title, target: m.baseRefName, at: m.createdAt, author: m.author?.login }))).sort((a, b) => a.n - b.n);
+    // In parallel, eight at a time, each call as forgeCall makes it: no token variable, stdin closed (#1098).
+    const notes = await pool(mrs, 8, (m) => new Promise((resolve) => execFile(forge, forge === 'glab'
+      ? ['api', `projects/:id/merge_requests/${m.n}/notes?per_page=100`, '--paginate', '--output', 'ndjson'] : ['pr', 'view', String(m.n), '--json', 'comments'],
+    { encoding: 'utf8', env: env(), maxBuffer: MAX }, (e, out, err) => resolve(e ? { error: (err || e.message).trim() } : { bodies: forge === 'glab' ? out.split('\n').filter(Boolean).map((x) => JSON.parse(x).body) : JSON.parse(out).comments.map((c) => c.body) }))).stdin.end());
+    const failed = notes.find((x) => x.error);
+    if (failed) { line(`unreadable — ${failed.error}`, `merge requests: unreadable — ${failed.error}`); state.mrs = { unreadable: `a merge request's comments — ${failed.error}` }; }
+    else {
+      state.mrs = ok(mrs.map((m, k) => ({ n: m.n, own: !!account && m.author === account, reviewed: notes[k].bodies.some((b) => PASS.test(first(b))) })));
+      if (!mrs.length) line('none open');
+      mrs.forEach((m, k) => line(`!${m.n} ${m.title} → ${m.target}, ${days(m.at)} days old, by ${m.author} — ${state.mrs.ok[k].own ? 'yours: it awaits your merge' : state.mrs.ok[k].reviewed ? 'reviewed' : 'no review'}`));
+    }
+  }
+}
+
+// The resumption artefacts (R-177): the issues' marks above, held commits, a campaign under way, a
+// version without its tag, the notes, and the branches merged into develop still on origin.
+head('Resumption');
+{
+  for (const k of ['plans', 'stops']) if (state[k].ok) for (const s of state[k].ok) line(`#${s.n}: ${s.why}`);
+  if (state.plans.unreadable) line(`the issues' comments: unreadable — ${issuesError}`, true);
+  else if (state.stops.unreadable) line(`the stopped runs: unreadable — ${state.stops.unreadable}`, true);
+  const branch = git('branch', '--show-current').stdout.trim();
+  if (!branch) { state.held = ok(null); }
+  else {
+    const h = node('git/held.mjs');
+    const waits = h.stdout.split('\n').filter((x) => x.startsWith('waits\t'));
+    if (h.status !== 0) { state.held = bad('the held commits', h.stdout.replace(/^could not tell: /, '').trim() || said(h)); line(`held commits: unreadable — ${state.held.unreadable}`, true); }
+    else if (!waits.length) state.held = ok(null);
+    else {
+      const to = branch.match(/^(?:lot|fix|feature|hotfix)\/(\d+)-/)?.[1] ?? waits[0].split('\t')[2].match(/\d+/)?.[0] ?? '<n>';
+      state.held = ok({ to, why: `${waits.length} held commit${waits.length === 1 ? '' : 's'} wait on ${branch}` });
+      for (const w of waits) { const [, hash, cited, held] = w.split('\t'); line(`held: ${hash.slice(0, 8)} ${cited} — ${held}`); }
+    }
+  }
+  if (state.campaign.ok) line(`campaign in progress: docs/audit/${state.campaign.ok}/`);
+  const vf = contract.versionFile, text = vf && read(vf);
+  let version = null, name = '';
+  if (text) { try { ({ version = null, name = '' } = JSON.parse(text)); } catch { version = text.match(/\d+\.\d+\.\d+/)?.[0] ?? null; } }
+  const untagged = version && version !== '0.0.0' && !git('tag', '-l', ...spellings(version, name)).stdout.trim() ? version : null;
+  state.untagged = ok(untagged);
+  if (untagged) line(`version ${untagged} in ${vf} carries no tag`);
+  const notes = (existsSync('docs/brainstorm') ? readdirSync('docs/brainstorm') : []).filter((f) => f.endsWith('.md') && f !== 'README.md' && statSync(`docs/brainstorm/${f}`).isFile()).sort();
+  state.notes = ok(notes.map((f) => f.replace(/\.md$/, '').replace(/^\d{4}-\d{2}-\d{2}-/, '')));
+  line(`notes in docs/brainstorm/: ${notes.length ? notes.join(', ') : 'none'}`);
+  if (!heads) line(`branches merged into develop still on origin: could not tell — ${said(ls)}`, true);
+  else if (!heads.has('develop')) line('branches merged into develop still on origin: none — origin has no develop');
+  else {
+    const base = heads.get('develop'), dflt = git('symbolic-ref', '--short', 'refs/remotes/origin/HEAD').stdout.trim().replace(/^origin\//, '');
+    const unknown = [], merged = [];
+    if (git('cat-file', '-e', `${base}^{commit}`).status !== 0) unknown.push('develop');
+    else for (const [name, sha] of heads) {
+      if (name === 'develop' || name === 'main' || name === dflt) continue;
+      if (git('cat-file', '-e', `${sha}^{commit}`).status !== 0) unknown.push(name);
+      else if (git('merge-base', '--is-ancestor', sha, base).status === 0) merged.push(name);
+    }
+    line(`branches merged into develop still on origin: ${unknown.length ? `could not tell — fetch first (${unknown.join(', ')})` : merged.length ? merged.join(', ') : 'none left'}`, unknown.length > 0 || merged.length > 0);
+  }
+}
+
+const n = next(state);
+print(`**Next**: \`${n.next}\` — ${n.why} (row ${n.row})`);

package/scripts/package-manager.mjs

@@ -0,0 +1,20 @@
+// The package manager of the repository at <repo>: `packageManager` first, the lockfile when the
+// field is absent. Imported by the hook scripts, which run a script or a binary through it; ''
+// when neither names one.
+import './node-floor.mjs'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export function packageManager(repo) {
+  let pm = ''
+  try { pm = (JSON.parse(readFileSync(join(repo, 'package.json'), 'utf8')).packageManager ?? '').replace(/@.*$/, '') } catch { /* no manifest */ }
+  const has = (f) => existsSync(join(repo, f))
+  if (pm === 'pnpm' || (!pm && has('pnpm-lock.yaml'))) return 'pnpm'
+  if (pm === 'yarn' || (!pm && has('yarn.lock'))) return 'yarn'
+  if (pm === 'npm' || (!pm && has('package-lock.json'))) return 'npm'
+  return ''
+}
+
+// The command that runs the `package.json` script <name>, or a binary of the repository.
+export const script = (pm, name) => (pm === 'npm' ? ['npm', 'run', name] : [pm, name])
+export const exec = (pm, ...cmd) => (pm === 'npm' ? ['npm', 'exec', '--', ...cmd] : [pm, 'exec', ...cmd])

package/scripts/port/item.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// `codelife port item <name> [--write | --check] [--test <file>] [--playground]` (K-2 —
+// port-toolchain, R-158): one toolchain item. Without a flag it reads only: the files it would write
+// from the plugin's templates, an existing file's difference included, and the checks it runs. With
+// --write it writes them, then runs the checks; with --check, the checks alone, once the item's work
+// by hand is done. It never commits: the `- paths:` line is what `codelife commit` takes.
+import '../node-floor.mjs'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { contract, entries } from '../contract.mjs'
+import { runChecks } from '../verify/lib.mjs'
+import { json, read, say, writer } from '../setup/lib.mjs'
+import { at, characterisation, dir, hasTypes, installed, ITEMS, pack, standard, templates } from './lib.mjs'
+
+const args = process.argv.slice(2)
+const name = args[0], write = args.includes('--write'), only = args.includes('--check'), playground = args.includes('--playground')
+const test = args.includes('--test') ? args[args.indexOf('--test') + 1] : undefined
+const known = ['--write', '--check', '--playground', '--test']
+if (!ITEMS.includes(name) || (write && only) || args.slice(1).some((a, i, all) => !known.includes(a) && all[i - 1] !== '--test')) {
+  console.error(`usage: codelife port item <${ITEMS.join('|')}> [--write | --check] [--test <file>] [--playground]`); process.exit(2)
+}
+console.log(`### port item ${name}`)
+const kind = contract()?.data.kind
+const { paths, failed, stop, done, put, scripts } = writer(write, test)
+if (kind !== 'lib' && kind !== 'app') stop(`kind: ${kind ?? 'unknown'} — there is no toolchain to port`)
+const pj = json(at('package.json')) ?? stop(`no ${at('package.json')}`)
+const template = (p) => readFileSync(join(templates, p), 'utf8').replaceAll('<package-name>', pj.name)
+const json2 = (text, obj) => `${JSON.stringify(obj, null, /^[ \t]+(?=")/m.exec(text)?.[0] ?? '  ')}\n`
+
+// The commands, through pnpm in the package's directory; the characterisation tests through the
+// runner the package has — vite-plus's once item d installed it.
+const exec = (label, ...cmd) => ({ name: label, file: 'pnpm', args: [...(dir() === '.' ? [] : ['--dir', dir()]), 'exec', ...cmd], shell: process.platform === 'win32' })
+const vp = Boolean(installed('vite-plus'))
+const tests = (folder) => (vp ? exec(`vp test run ${folder ?? ''}`.trim(), 'vp', 'test', 'run', ...(folder ? [folder] : [])) : exec(`vitest run ${folder ?? ''}`.trim(), 'vitest', 'run', ...(folder ? [folder] : [])))
+const floor = existsSync(at('test/characterisation')) ? [tests('test/characterisation')] : []
+const checks = {
+  a1: () => [{ name: 'pnpm install --frozen-lockfile', file: 'pnpm', args: ['install', '--frozen-lockfile'], shell: process.platform === 'win32' }],
+  a2: () => [tests()],
+  b: () => floor,
+  c: () => floor,
+  d: () => [kind === 'lib' ? exec('vp pack', 'vp', 'pack') : exec('vp build', 'vp', 'build'), ...floor],
+  e: () => [vp ? exec('vp check', 'vp', 'check') : exec('tsc --noEmit', 'tsc', '--noEmit'), ...floor],
+  "e'": () => [exec('vp check', 'vp', 'check'), ...floor],
+}
+
+// What each item writes from the plugin; an item absent here is done by hand, then --check.
+const writes = {
+  b() {
+    if (kind === 'app') return say('by hand', 'an application\'s characterisation — the build passing, a start-up smoke in Vitest browser mode, the pure modules snapshotted')
+    const types = hasTypes(pj)
+    for (const t of characterisation()) {
+      if (t === 'declarations.test.ts' && !types) continue
+      const text = template(`characterisation/${t}`)
+      put(at(`test/characterisation/${t}`), (types ? text.replace(/^\s*\/\/ <\/?declarations>\n/gm, '') : text.replace(/^\s*\/\/ <declarations>\n[\s\S]*?^\s*\/\/ <\/declarations>\n/gm, '')))
+    }
+    if (!types) say('left out', 'declarations.test.ts and the surface\'s declared-names case — the build ships no declaration file: file the issue that adds them from the first build that does')
+  },
+  d() {
+    if (kind === 'app') say('by hand', 'vite.config.ts carrying the framework\'s plugin — no template names a framework')
+    else put(at('vite.config.ts'), template('vite.config.ts'))
+    if (kind === 'lib' && playground) {
+      for (const f of ['index.html', 'main.ts']) put(at(`playground/${f}`), template(`playground/${f}`))
+      if (pj.scripts?.dev !== 'PLAYGROUND=1 vp dev') {
+        const text = read(at('package.json'))
+        say('dev', '`PLAYGROUND=1 vp dev` into the package\'s scripts')
+        put(at('package.json'), json2(text, { ...pj, scripts: { ...pj.scripts, dev: 'PLAYGROUND=1 vp dev' } }))
+      }
+    }
+    if (kind === 'lib') {
+      const g = pack()
+      const declared = entries('generated').find((e) => e.path.some((p) => p.replace(/\/$/, '') === g.path.replace(/\/$/, '')))
+      if (!declared?.command.some((c) => c.includes('vp pack'))) say('contract', `generated[] ${declared ? 'replaces its entry for' : 'declares'} ${g.path}: \`{ path: ${g.path}, command: ${g.command}, when: [${g.when}] }\` — edit .claude/codelife.md, then \`codelife setup contract .claude/codelife.md\`, in this item's commit`)
+    }
+  },
+  e() { put(at('tsconfig.json'), template('tsconfig.json')) },
+  f() {
+    const root = json('package.json'), want = standard(kind)
+    for (const [s, cmd] of Object.entries(want)) say(s, root?.scripts?.[s] === cmd ? `\`${cmd}\` — already` : `\`${root?.scripts?.[s] ?? 'nothing'}\` → \`${cmd}\``)
+    put('package.json', json2(read('package.json'), { ...root, scripts: { ...root?.scripts, ...want } }))
+  },
+}
+
+if (!only) writes[name]?.()
+if (!writes[name] && !only) say('by hand', 'this item has nothing to write from the plugin: do its work, then `codelife port item ' + name + ' --check`')
+if (!write && !only) {
+  for (const c of name === 'f' ? Object.keys(standard(kind)) : checks[name]()) say('check', typeof c === 'string' ? c : c.name)
+  if (name !== 'f') say('check', 'test:all')
+  done()
+}
+if (name === 'f') {
+  if (!test) say('test:one', 'not run — give a test file with --test <file>')
+  if (scripts(Object.keys(standard(kind)).filter((s) => s !== 'test:one' || test))) failed.push('a script is red — this item does not fix the repository\'s tests')
+} else if (runChecks(checks[name](), '- ') || scripts(['test:all'])) failed.push('a check is red — report it, and stop')
+done()

package/scripts/port/lib.mjs

@@ -0,0 +1,194 @@
+// What `codelife port prep`, `codelife port item`, `codelife port version` and `codelife overview`
+// share (K-2 — port-toolchain; K-20 — The target, R-19): the ported package, each toolchain item's
+// state read from the tree, the `port:` issues and what they make of an item to do, and the version
+// rule. Nothing is recorded: an item's state is what this file finds at each call.
+import '../node-floor.mjs'
+import { existsSync, readdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, dirname, join } from 'node:path'
+import { contract, entries } from '../contract.mjs'
+import { lines as noneLines } from '../tracker/none.mjs'
+import { git, json, pkg, read, said, section, sh } from '../setup/lib.mjs'
+
+// The items in the order the port plays them, and the items each one's precondition names.
+export const ITEMS = ['a1', 'a2', 'b', 'c', 'd', 'e', "e'", 'f']
+const PRE = { a1: [], a2: ['a1'], c: ['b'], d: ['b'], e: ['b'], "e'": ['e'], f: ['d', 'e', "e'"] }
+export const MARK = /generated by codelife/
+const RUNNERS = ['vitest', 'vite-plus', 'jest', 'mocha', 'ava', 'jasmine']
+const OLD_BUILD = /^(rollup|webpack|tsup|esbuild|parcel|vitest)\.config\.[cm]?[jt]s$|^vite\.config\.[cm]?js$/
+const OLD_LINT = /^(\.eslintrc(\..+)?|eslint\.config\..+|\.prettierrc(\..+)?|prettier\.config\..+|biome\.jsonc?)$/
+const OLD_LINT_DEPS = ['eslint', 'prettier', '@biomejs/biome']
+
+// The ported package: the directory of the contract's version file — the root, or a workspace's package.
+export const dir = () => dirname(contract()?.data.release?.version_file ?? 'package.json')
+export const at = (p) => (dir() === '.' ? p : join(dir(), p))
+export const deps = (pj) => ({ ...pj?.dependencies, ...pj?.devDependencies })
+export const templates = join(pkg, 'scripts/target/templates')
+export const characterisation = () => readdirSync(join(templates, 'characterisation')).sort()
+
+// The target's five commands, verbatim from the kind's `## Standard scripts` table.
+export const standard = (kind) => Object.fromEntries([...section(read(join(pkg, `scripts/target/target-${kind}.md`)) ?? '', 'Standard scripts')
+  .matchAll(/^\| `([^`]+)` \| `([^`]+)` \|/gm)].map((m) => [m[1], m[2]]))
+// The generated[] entry a library's build implies, and the command that runs from the root.
+export const pack = () => ({ path: `${at('dist')}/`, command: dir() === '.' ? 'pnpm exec vp pack' : `pnpm --dir ${dir()} exec vp pack`, when: [`${at('src')}/**`] })
+export const hasTypes = (pj) => Boolean(pj?.types ?? pj?.typings) || /\.d\.m?ts"/.test(JSON.stringify(pj?.exports ?? ''))
+
+// The version rule (R-162). view <args> — `pnpm view … --json` parsed, or { error }.
+const view = (...a) => {
+  const r = sh('pnpm', ['view', ...a, '--json'])
+  try { return r.status === 0 ? JSON.parse(r.stdout || 'null') : { error: said(r) || `pnpm view ${a.join(' ')} failed` } } catch { return { error: `pnpm view ${a.join(' ')} printed no JSON` } }
+}
+const parts = (v) => v.split('.').map(Number)
+const newer = (a, b) => { const [x, y] = [parts(a), parts(b)]; for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i]; return false }
+// window — the repository's minimumReleaseAge, in minutes: pnpm-workspace.yaml's, else pnpm's 1440.
+export const window = () => Number(read('pnpm-workspace.yaml')?.match(/^minimumReleaseAge:\s*(\d+)/m)?.[1] ?? 1440)
+// releases <tool> — { all, past, error }: its stable versions with their dates, newest first, and those
+// older than the window.
+export const releases = (tool) => {
+  const t = view(tool, 'time')
+  if (!t || t.error) return { error: t?.error ?? `no release of ${tool}` }
+  const all = Object.entries(t).filter(([v]) => /^\d+\.\d+\.\d+$/.test(v)).sort(([a], [b]) => (newer(a, b) ? -1 : 1)).map(([v, d]) => ({ v, date: d.slice(0, 10), at: Date.parse(d) }))
+  const limit = Date.now() - window() * 60000
+  return { all, past: all.filter((r) => r.at < limit) }
+}
+// vitePlus — { v, date, pins } for the newest vite-plus past the window, its exact pins; or { error }.
+export const vitePlus = () => {
+  const r = releases('vite-plus')
+  if (r.error || !r.past.length) return { error: r.error ?? 'every vite-plus release is inside the window' }
+  const m = view(`vite-plus@${r.past[0].v}`, 'dependencies', 'peerDependencies')
+  if (m?.error) return m
+  return { ...r.past[0], pins: { ...m?.dependencies, ...m?.peerDependencies } }
+}
+// carried <tool> — true when vite-plus carries it: Vitest and every @vitest/* package, Oxlint, Oxfmt, its Vite.
+export const carried = (tool) => /^(vitest|@vitest\/.+|oxlint|oxfmt|vite)$/.test(tool)
+// installed <name> — the version node_modules holds, in the package's directory or at the root.
+export const installed = (name) => json(join(at('node_modules'), name, 'package.json'))?.version ?? json(join('node_modules', name, 'package.json'))?.version ?? null
+// pin <tool> — the version the installed vite-plus pins, else the newest one past the window; or { error }.
+export const pin = (tool) => {
+  const local = json(join(at('node_modules'), 'vite-plus/package.json')) ?? json('node_modules/vite-plus/package.json')
+  const from = local ? { v: local.version, pins: { ...local.dependencies, ...local.peerDependencies } } : vitePlus()
+  return from.error ? from : { version: from.pins[tool], by: from.v }
+}
+// peers <tool> — each lockfile package's peerDependencies range on the tool, `[package, range]`.
+export const peers = (tool, lockfile = 'pnpm-lock.yaml') => {
+  const out = []
+  let section = '', name = '', inPeers = false
+  for (const line of (read(lockfile) ?? '').split('\n')) {
+    if (/^[a-z]/.test(line)) section = line.split(/\s+/)[0]
+    if (section !== 'packages:') continue
+    if (/^ {2}[^ ]/.test(line)) name = line.trim().replace(/:$/, '')
+    if (/^ {4}[^ ]/.test(line)) inPeers = line.trim().split(/\s+/)[0] === 'peerDependencies:'
+    if (inPeers && line.trim().split(/\s+/)[0] === `${tool}:`) out.push([name, line.replace(/^ +[^:]+: /, '').replace(/^(['"])(.*)\1$/, '$2')])
+  }
+  return out
+}
+// admitted <tool> — the versions every peer range in the lockfile admits, as the registry resolves
+// each range; or { error }. Without a range, every version.
+export const admitted = (tool, ranges) => {
+  let set = null
+  for (const [, range] of ranges) {
+    const v = view(`${tool}@${range}`, 'version')
+    if (v?.error) return v
+    const these = new Set([v ?? []].flat())
+    set = set ? new Set([...set].filter((x) => these.has(x))) : these
+  }
+  return { set }
+}
+
+// measure <kind> — each item's reasons to do: [] done, null not applicable, undefined not read.
+const measure = (kind) => {
+  const d = dir(), pj = json(at('package.json')), rootPj = json('package.json'), has = deps(pj)
+  const tracked = git('ls-files').stdout.split('\n').filter(Boolean)
+  const files = (where) => { try { return readdirSync(where) } catch { return [] } }
+  const configs = (re) => files(d).filter((f) => re.test(f))
+  const preset = (f) => read(at(f))?.includes('@ersbeth/codelife/presets')
+  const marked = tracked.filter((f) => f.includes('characterisation/') && MARK.test((read(f) ?? '').split('\n').slice(0, 3).join('\n')))
+  const vitest = installed('vitest') ?? has.vitest?.replace(/^[\^~=v]+/, '')
+  const why = {
+    a1: [
+      ...(/^pnpm@/.test(rootPj?.packageManager ?? '') ? [] : [`packageManager is ${rootPj?.packageManager ?? 'unset'}, not pnpm`]),
+      ...(existsSync('pnpm-lock.yaml') ? [] : ['no pnpm-lock.yaml']),
+      ...['package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock'].filter(existsSync).map((f) => `${f} is still there`),
+      ...(/^minimumReleaseAge:/m.test(read('pnpm-workspace.yaml') ?? '') ? [] : ['minimumReleaseAge is not set in pnpm-workspace.yaml']),
+      ...[...new Set(['package.json', at('package.json')])].flatMap((f) => Object.entries(deps(json(f))).filter(([, s]) => /^(file|link):/.test(s)).map(([n, s]) => `${f}: ${n} is ${s}, not workspace:*`)),
+      ...[...(read('.gitmodules') ?? '').matchAll(/^\s*path\s*=\s*(.+)$/gm)].map((m) => m[1].trim()).filter((p) => !p.startsWith('submodules/')).map((p) => `the submodule ${p} is not under submodules/`),
+    ],
+    a2: has.vitest || has['vite-plus'] ? [] : [`no Vitest in ${at('package.json')}`],
+    b: kind === 'app' ? (marked.length ? [] : ['no characterisation test'])
+      : characterisation().filter((t) => t !== 'declarations.test.ts' && !marked.some((f) => basename(f) === t)).map((t) => `characterisation/${t} is missing`),
+    c: !has.vitest ? null : (() => {
+      const p = pin('vitest')
+      if (p.error) return undefined
+      return vitest === p.version ? [] : [`vitest is ${vitest}, vite-plus ${p.by} pins ${p.version}`]
+    })(),
+    d: [
+      ...(has['vite-plus'] ? [] : [`no vite-plus in ${at('package.json')}`]),
+      ...(kind === 'lib' && !preset('vite.config.ts') ? [`${at('vite.config.ts')} does not call the package's preset`] : kind === 'app' && !existsSync(at('vite.config.ts')) ? [`no ${at('vite.config.ts')}`] : []),
+      ...configs(OLD_BUILD).map((f) => `${at(f)} is still there`),
+      ...(kind === 'lib' && !entries('generated').some((g) => g.path.some((p) => p.replace(/\/$/, '') === at('dist')) && g.command.some((c) => c.includes('vp pack')))
+        ? [`generated[] does not declare ${pack().path} by vp pack`] : []),
+    ],
+    e: [
+      ...(read(at('tsconfig.json'))?.includes('@ersbeth/codelife/presets/tsconfig.json') ? [] : [`${at('tsconfig.json')} does not extend the package's preset`]),
+      ...(() => { const js = tracked.filter((f) => f.startsWith(`${at('src')}/`) && /\.[cm]?jsx?$/.test(f)); return js.length ? [`${js.length} JavaScript files under ${at('src')}/`] : [] })(),
+    ],
+    "e'": [...(has['vite-plus'] ? [] : [`no vite-plus in ${at('package.json')} to run Oxlint and Oxfmt`]), ...configs(OLD_LINT).map((f) => `${at(f)} is still there`), ...OLD_LINT_DEPS.filter((n) => has[n]).map((n) => `${n} is still a dependency of ${at('package.json')}`)],
+    f: Object.entries(standard(kind)).filter(([s, cmd]) => rootPj?.scripts?.[s] !== cmd).map(([s, cmd]) => `${s} runs ${rootPj?.scripts?.[s] ? `\`${rootPj.scripts[s]}\`` : 'nothing'}, the target's is \`${cmd}\``),
+  }
+  return { why, runner: RUNNERS.some((r) => has[r]), traced: marked.length > 0 || preset('vite.config.ts') || preset('tsconfig.json') }
+}
+
+// portIssues <forge> <connected> — the `port:<item>` issues, open or closed: { byItem } or { error }.
+const portIssues = (forge, connected) => {
+  if (forge !== 'none' && !connected) return { error: 'this machine is not connected to the host' }
+  let listing
+  if (forge === 'none') listing = existsSync('issues') ? noneLines(true) : []
+  else {
+    const term = join(tmpdir(), `codelife-port-${process.pid}`)
+    writeFileSync(term, 'port:')
+    const r = sh(process.execPath, [join(pkg, 'scripts/tracker/search.mjs'), term, '--all'])
+    if (r.status !== 0) return { error: said(r) }
+    listing = r.stdout.split('\n')
+  }
+  const byItem = {}
+  for (const l of listing) {
+    const m = l.match(/^#?(\d+)\t\[([^\]]*)\]/)
+    const item = m?.[2].match(/(?:^|\s)port:(a1|a2|b|c|d|e'|e|f)(?=$|\s)/)?.[1]
+    if (!item || byItem[item]) continue
+    const v = sh(process.execPath, [join(pkg, 'scripts/tracker/view.mjs'), m[1], '--bare'])
+    if (v.status !== 0) return { error: `#${m[1]} — ${said(v)}` }
+    const j = JSON.parse(v.stdout)
+    byItem[item] = { n: Number(m[1]), open: !/^closed$/i.test(j.state ?? ''), wontfix: (j.labels ?? []).includes('wontfix') }
+  }
+  return { byItem }
+}
+
+// state <{ forge, connected }> — { items, summary, next }: each item { item, state, why, pre, issue },
+// its state done, not applicable, not read, to do, deferred, refused or blocked; the toolchain's
+// summary line; the first item to propose, or null.
+export const state = ({ forge, connected }) => {
+  const kind = contract()?.data.kind
+  if (kind !== 'lib' && kind !== 'app') return { items: [], summary: 'not applicable', next: null }
+  const { why, runner, traced } = measure(kind)
+  const issues = portIssues(forge, connected)
+  const items = []
+  for (const item of ITEMS) {
+    const w = why[item], pre = item === 'b' ? (runner ? [] : ['a2']) : PRE[item]
+    const issue = issues.byItem?.[item]
+    let s = w === null ? 'not applicable' : w === undefined ? 'not read' : w.length ? 'to do' : 'done'
+    const by = pre.filter((p) => ['deferred', 'refused', 'blocked'].includes(items.find((x) => x.item === p).state))
+    if (s === 'to do' && issue?.open) s = 'deferred'
+    else if (s === 'to do' && issue?.wontfix) s = 'refused'
+    else if (s === 'to do' && by.length) s = 'blocked'
+    items.push({ item, state: s, why: s === 'blocked' ? [`by ${by.join(', ')}`] : w ?? (s === 'not read' ? ['could not tell — the registry did not answer'] : []), pre, issue })
+  }
+  const named = (s) => items.filter((i) => i.state === s).map((i) => (i.issue && s !== 'blocked' ? `${i.item} (#${i.issue.n})` : i.item))
+  const left = ['to do', 'deferred', 'refused', 'blocked', 'not read'].filter((s) => named(s).length).map((s) => `${s} ${named(s).join(', ')}`)
+  const summary = !traced && !Object.keys(issues.byItem ?? {}).length
+    ? `not ported${issues.error ? ` — the port: issues not read, ${issues.error}` : ''}`
+    : !left.length ? 'current' : `ported — ${left.join(' · ')}${issues.error ? ` · the port: issues not read, ${issues.error}` : ''}`
+  const ready = (i) => i.pre.every((p) => ['done', 'not applicable'].includes(items.find((x) => x.item === p).state))
+  return { items, summary, next: items.find((i) => ['to do', 'deferred'].includes(i.state) && ready(i))?.item ?? null }
+}
+// shown <state> — the measure as `codelife port prep` prints it and CONF reads it: [key, value] per item, then the summary.
+export const shown = (s) => [...s.items.map((i) => [`item ${i.item}`, `${i.state}${i.issue && i.state !== 'done' ? ` #${i.issue.n}` : ''}${i.why.length && i.state !== 'done' ? ` — ${i.why.join('; ')}` : ''}`]), ['toolchain', s.summary]]