@ersbeth/codelife 0.0.0-stage → 0.11.1

package/scripts/roadmap/write.mjs

@@ -0,0 +1,53 @@
+// /roadmap's last write (R-263): the roadmap's body from its template — the mark at the HEAD the run
+// folder read, the orphans left alone, the open lots in the confirmed order with what each waits for
+// (R-264) — every line held to the shape every reader parses before anything is sent. Rewrites the
+// roadmap the folder found, or creates the first one. `codelife roadmap write <run folder> <order
+// file> [<left alone file>]`: one `#<n> <sentence>[ — after #<a>, #<b>]` per line, in order.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { prep, said } from '../prepare-lib.mjs';
+import { orderLine } from '../read-roadmap/lib.mjs';
+
+const [dir, orderFile, leftFile] = process.argv.slice(2);
+if (!dir || !orderFile || !existsSync(join(dir, 'roadmap.json'))) {
+  console.error('usage: codelife roadmap write <run folder> <order file> [<left alone file>]');
+  process.exit(2);
+}
+const { say, stop, done, must } = prep('write');
+const pkg = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const map = JSON.parse(readFileSync(join(dir, 'roadmap.json'), 'utf8'));
+const issues = JSON.parse(readFileSync(join(dir, 'issues.json'), 'utf8'));
+const lines = (f) => (f ? readFileSync(f, 'utf8') : '').split('\n').map((l) => l.trim()).filter(Boolean);
+
+const order = lines(orderFile).map((l, i) => `${i + 1}. ${l.replace(/^\d+\. /, '')}`);
+const lots = [];
+for (const l of order) {
+  const o = orderLine(l);
+  if (!o) stop(`a line out of shape, nothing sent: ${l}`);
+  if (lots.includes(o.lot)) stop(`#${o.lot} is listed twice, nothing sent`);
+  lots.push(o.lot);
+}
+for (const l of lines(leftFile)) if (!/^#\d+ \S/.test(l)) stop(`a left-alone line out of shape, nothing sent: ${l}`);
+// The orphans an argument kept out of this run's scope, left alone before, stay left alone.
+const kept = lines(join(dir, 'kept.txt')).map((n) => `#${n} ${issues.find((i) => i.n === n)?.title ?? ''}`.trim());
+const left = [...lines(leftFile), ...kept.filter((k) => !lines(leftFile).some((l) => l.split(' ')[0] === k.split(' ')[0]))];
+
+const template = readFileSync(join(pkg, 'scripts/roadmap/roadmap.md'), 'utf8').replace(/^<!--[\s\S]*?-->\n+/, '');
+const body = template
+  .replace('`<commit>`', `\`${map.head.slice(0, 8)}\``)
+  .replace(/^- #<n> <the issue's sentence>$/m, left.length ? left.map((l) => `- ${l}`).join('\n') : '*None.*')
+  .replace(/^1\. #<n> .*\n2\. #<n> .*$/m, order.length ? order.join('\n') : '*None.*');
+const file = join(dir, 'roadmap.md');
+if (map.n) {
+  writeFileSync(file, body);
+  must('tracker', 'issue.update', [map.n, file]);
+  say(`roadmap: #${map.n}, rewritten — mark ${map.head.slice(0, 8)}, ${order.length} lots, ${left.length} left alone`);
+} else {
+  writeFileSync(file, `# What remains to implement, in order\n\n${body}`);
+  const r = spawnSync(process.execPath, [join(pkg, 'scripts/tracker/create.mjs'), '-', '-', 'roadmap', file], { encoding: 'utf8' });
+  if (r.status !== 0) stop(`the roadmap was not created — ${said(r)}`);
+  say(`roadmap: ${r.stdout.trim().replace(/^created /, '')}, created — mark ${map.head.slice(0, 8)}, ${order.length} lots, ${left.length} left alone`);
+}
+done();

package/scripts/search.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// `codelife search <terms file>` (K-7 — new-issue, R-179): what is already known about a subject,
+// before anything is filed or designed — the open issues, what docs/spec/ decided — a rule's heading,
+// a refusal line, matched on its text and not its path —, then the notes of docs/brainstorm/ still
+// pending, by their title and their Open items; each term searched alone
+// as a whole word, regardless of case, each pass ranked by how many terms a line matched, the most
+// first. One term per line of the file, never typed into a command: a term can quote someone else's
+// text. Run from the repository's root; prints one `### search` block.
+import './node-floor.mjs'
+import { existsSync, readFileSync } from 'node:fs'
+import { decided, unfinished } from './brainstorm/lib.mjs'
+import { kind, matching, rank, word } from './tracker/lib.mjs'
+import { matching as filed } from './tracker/none.mjs'
+
+const SHOWN = 10
+const file = process.argv[2]
+if (!file) { console.error('usage: codelife search <terms file>'); process.exit(2) }
+const terms = [...new Set(readFileSync(file, 'utf8').split('\n').map((t) => t.trim()).filter(Boolean))]
+if (!terms.length) { console.error(`${file}: no term, one per line`); process.exit(2) }
+
+const none = kind() === 'none'
+const decisions = existsSync('docs/spec') ? decided(['docs/spec']) : []
+const open = rank(terms.flatMap((t) => none ? filed(t) : matching(t)))
+const text = (lines) => rank(terms.flatMap((t) => { const holds = word(t); return lines.filter((l) => holds(l.slice(l.indexOf(': ') + 2))) }))
+const spec = text(decisions)
+const notes = text(existsSync('docs/brainstorm') ? unfinished(['docs/brainstorm']) : [])
+const pass = (name, lines) => [`- ${name}: ${lines.length} matched${lines.length > SHOWN ? `, the first ${SHOWN} shown` : ''}`, ...lines.slice(0, SHOWN)]
+console.log(['### search', `- terms: ${terms.map((t) => `\`${t}\``).join(', ')}`,
+  ...pass('open issues', open), ...pass('decided', spec), ...pass('unfinished notes', notes)].join('\n'))

package/scripts/setup/contract.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// `codelife setup contract <file>` (K-1 — setup, R-149; K-19 R-13): the contract you confirmed,
+// held to the schema by the one reader's check, then written to .claude/codelife.md — the file
+// itself when it is the one you edited — and .claude/settings.json settled for a former marketplace
+// copy. An invalid draft writes nothing: its lines, and exit 1.
+import '../node-floor.mjs'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { check, FILE, parse } from '../contract.mjs'
+import { mergeSettings } from '../former-form.mjs'
+import { say } from './lib.mjs'
+
+const [file] = process.argv.slice(2)
+if (!file || process.argv.length > 3) { console.error('usage: codelife setup contract <file>'); process.exit(2) }
+const text = readFileSync(file, 'utf8')
+const { invalid, stale } = check({ ...parse(text) })
+for (const l of invalid) say('invalid', l)
+for (const l of stale) say('stale', l)
+if (invalid.length) process.exit(1)
+if (resolve(file) !== resolve(FILE)) { mkdirSync('.claude', { recursive: true }); writeFileSync(FILE, text) }
+const paths = [FILE]
+const s = mergeSettings('.')
+if (s.status === 'migrated') paths.push('.claude/settings.json')
+say('settings', { migrated: 'the former marketplace lines replaced by "codelife@codelife": false', 'provides-marketplace': 'left: this repository provides the marketplace itself — a session here runs `claude --plugin-dir <its source>`', 'not-round-trip': s.note }[s.status] ?? 'nothing to change')
+say('paths', paths.join(' '))

package/scripts/setup/item.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+// `codelife setup item <name> [--write] [--test <file>]` (K-1 — setup, R-151): one base item. Without
+// --write it reads only and prints what it would do, an existing file's difference included; with it,
+// it does that, then runs the item's own check. It never commits: the `- paths:` line is what
+// `codelife commit` takes, one item to one commit. A `- stop:` line exits 1, with nothing written.
+import '../node-floor.mjs'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { contract } from '../contract.mjs'
+import { detect, migrate } from '../former-form.mjs'
+import { packageManager } from '../package-manager.mjs'
+import { blank, develop, folderTemplate, forgeCall, git, hookTemplate, installed, isPackage, json, LABELS, labels, MARKER, names, origin, read, said, say, sh, templates, writer } from './lib.mjs'
+
+const args = process.argv.slice(2)
+const name = args[0], write = args.includes('--write'), test = args[args.indexOf('--test') + 1]
+const ITEMS = ['labels', 'templates', 'scripts', 'hooks', 'folders', 'changelog', 'develop']
+if (!ITEMS.includes(name) || args.slice(1).some((a, i, all) => a !== '--write' && a !== '--test' && all[i - 1] !== '--test')) {
+  console.error(`usage: codelife setup item <${ITEMS.join('|')}> [--write] [--test <file>]`); process.exit(2)
+}
+const forge = contract()?.data.tracker?.kind ?? 'none'
+const { paths, failed, stop, done, put, scripts } = writer(write, test)
+
+const items = {
+  labels() {
+    if (forge === 'none') stop('tracker.kind none — the labels live in the issues/ files, nothing to create')
+    const l = labels(forge)
+    if (l.error) stop(`the labels could not be read — ${l.error}`)
+    const missing = LABELS().filter((x) => !l.names.includes(x))
+    say('missing', missing.join(', ') || 'none')
+    const others = l.names.filter((x) => !LABELS().includes(x))
+    if (others.length) say('kept', `the project's own labels, left as they are: ${others.join(', ')}`)
+    if (!write) return
+    for (const x of missing) {
+      const r = forgeCall(forge, forge === 'glab' ? ['label', 'create', '--name', x] : ['label', 'create', x])
+      say(r.status === 0 ? 'created' : 'by hand', r.status === 0 ? x : `${x} — ${said(r)}`)
+    }
+    const after = labels(forge).names ?? []
+    for (const x of LABELS().filter((y) => !after.includes(y))) failed.push(`${x} is not on the tracker`)
+  },
+  templates() {
+    if (forge === 'none') stop('tracker.kind none — an issues/ file takes the same shape when it is created')
+    for (const { at, want } of templates(forge)) put(at, want)
+  },
+  folders() {
+    for (const p of names('Folders')) {
+      if (existsSync(p)) continue
+      if (p.endsWith('/')) { say('create', `${p} — kept by a .gitkeep`); if (write) { mkdirSync(p, { recursive: true }); writeFileSync(join(p, '.gitkeep'), ''); paths.push(join(p, '.gitkeep')) } }
+      else put(p, p.startsWith('docs/spec/') ? blank(readFileSync(folderTemplate(p), 'utf8'), json('package.json')?.name ?? basename(process.cwd())) : readFileSync(folderTemplate(p), 'utf8'))
+    }
+    if (write) for (const p of names('Folders').filter((x) => !existsSync(x))) failed.push(`${p} is missing`)
+  },
+  scripts() {
+    const pj = json('package.json')
+    if (!pj) stop('no package.json — write it with the five scripts you confirmed, then run this again')
+    const five = names('Scripts')
+    for (const s of five) say(s, pj.scripts?.[s] ? `\`${pj.scripts[s]}\`${/^echo ['"]?nothing to run/.test(pj.scripts[s]) ? ' — nothing to run: say it, and look once for a real check at this tier' : ''}` : 'missing')
+    const missing = five.filter((s) => !pj.scripts?.[s])
+    const node = process.versions.node
+    const lock = existsSync('pnpm-lock.yaml') && !pj.packageManager ? `pnpm@${sh('pnpm', ['--version']).stdout.trim()}` : null
+    const ignore = read('.gitignore') ?? ''
+    const ignored = /^\/?node_modules\/?$/m.test(ignore)
+    if (!pj.engines?.node) say('engines', `node >=${node}, the runtime this run is on`)
+    if (lock) say('packageManager', lock)
+    if (!ignored) say('.gitignore', 'node_modules/ — the prepare line makes an install happen here')
+    if (!write) return
+    if (missing.length) stop(`${missing.join(', ')} missing from package.json — write the mapping you confirmed first`)
+    if (!pj.engines?.node || lock) {
+      const text = readFileSync('package.json', 'utf8'), indent = /^[ \t]+(?=")/m.exec(text)?.[0] ?? '  '
+      if (!pj.engines?.node) pj.engines = { ...pj.engines, node: `>=${node}` }
+      if (lock) pj.packageManager = lock
+      writeFileSync('package.json', `${JSON.stringify(pj, null, indent)}\n`); paths.push('package.json')
+    }
+    if (!ignored) { writeFileSync('.gitignore', `${ignore}${ignore && !ignore.endsWith('\n') ? '\n' : ''}node_modules/\n`); paths.push('.gitignore') }
+    if (!test) say('test:one', 'not run — give a test file with --test <file>')
+    if (scripts([...five.filter((s) => s !== 'test:one'), ...(test ? ['test:one'] : [])])) failed.push('a script is red: the repository is red before codelife arrives — /setup does not fix its tests')
+  },
+  hooks() {
+    if (!installed()) stop(`the package @ersbeth/codelife is not installed — install it on your yes, then run this again`)
+    if (isPackage()) stop('this repository is the package itself: its hooks call scripts/ directly and stay its own')
+    const former = detect('.')
+    const own = (h) => (isPackage() ? `scripts/${h}.mjs` : `node_modules/@ersbeth/codelife/scripts/${h}.mjs`)
+    if (former.hooks.length || former.postinstall || former.marketplace) say('former form', `${[...former.hooks, ...(former.postinstall ? ['postinstall'] : []), ...(former.marketplace ? ['the marketplace'] : [])].join(', ')} — removed for the package's, the contract's guards[] rewritten`)
+    const pm = packageManager('.') || 'npm'
+    const pj = json('package.json') ?? stop('no package.json — the scripts item comes first')
+    const prepare = `node ${own('install')}`
+    if (!pj.scripts?.prepare?.includes(own('install'))) say('prepare', `\`${prepare}\`${pj.scripts?.prepare ? `, after the prepare already there` : ''}`)
+    const setup = contract()?.sections.get('Setup') ?? ''
+    if (!setup.includes('core.hooksPath')) say('## Setup', 'the line that wires a new clone, written into the contract')
+    if (write) {
+      // A hook over a red tier refuses every commit, its own included (C-830): both tiers first.
+      if (scripts(['verify:commit', 'verify:push'])) stop('a tier is red — nothing written: the repository is red before its hooks')
+      if (former.hooks.length || former.postinstall || former.marketplace) {
+        const r = migrate('.', 'hooks')
+        for (const [k, v] of Object.entries(r)) for (const x of v) say(k, x)
+        paths.push(...r.removed, ...r.rewritten)
+      }
+    }
+    for (const h of names('Hooks')) put(`.githooks/${h}`, hookTemplate(h), 0o755)
+    if (!write) return
+    const fresh = json('package.json')
+    if (!fresh.scripts?.prepare?.includes(own('install'))) {
+      const text = readFileSync('package.json', 'utf8'), indent = /^[ \t]+(?=")/m.exec(text)?.[0] ?? '  '
+      fresh.scripts = { ...fresh.scripts, prepare: fresh.scripts?.prepare ? `${fresh.scripts.prepare} && ${prepare}` : prepare }
+      writeFileSync('package.json', `${JSON.stringify(fresh, null, indent)}\n`)
+    }
+    if (!paths.includes('package.json')) paths.push('package.json')
+    if (!setup.includes('core.hooksPath')) {
+      const text = read('.claude/codelife.md')
+      const line = `Wire a new clone once: \`${pm === 'npm' ? 'npm run prepare' : `${pm} prepare`}\` — an install runs it too. It sets the local keys \`core.hooksPath\` (the hooks of \`.githooks/\`), \`fetch.prune\` and an ssh keepalive; until it runs, no hook holds a commit or a push here.`
+      writeFileSync('.claude/codelife.md', /^## Setup[ \t]*$/m.test(text) ? text.replace(/^## Setup[ \t]*\n/m, `## Setup\n\n${line}\n`) : `${text.replace(/\n*$/, '\n')}\n## Setup\n\n${line}\n`)
+      paths.push('.claude/codelife.md')
+    }
+    const install = sh(process.execPath, [own('install')], { stdio: 'inherit' })
+    if (install.status !== 0) failed.push(`${prepare} failed`)
+    // The checks (R-151): the keys, the refusal of a bad message, the form script, the link.
+    if (git('config', 'core.hooksPath').stdout.trim() !== '.githooks') failed.push('core.hooksPath is not .githooks')
+    if (git('config', 'fetch.prune').stdout.trim() !== 'true') failed.push('fetch.prune is not true')
+    const wip = git('commit', '--allow-empty', '-m', 'wip')
+    if (wip.status === 0) { git('reset', '--soft', 'HEAD~1'); failed.push('`git commit -m wip` was not refused — the commit-msg hook does not hold') }
+    else say('refused', '`git commit --allow-empty -m wip`, as it should be')
+    if (sh(process.execPath, [own('spec-form')]).status !== 2) failed.push(`node ${own('spec-form')} does not print its usage`)
+    if (!isPackage() && !existsSync('.claude/skills/codelife')) failed.push('.claude/skills/codelife is not linked')
+  },
+  changelog() {
+    if (!installed()) stop('the package is not installed — the hooks item comes first')
+    const former = detect('.').changelog
+    if (former.length) say('former form', `${former.join(', ')} — removed for the package's generator`)
+    const text = read('CHANGELOG.md')
+    const gen = isPackage() ? 'scripts/changelog.mjs' : 'node_modules/@ersbeth/codelife/scripts/changelog.mjs'
+    if (text?.includes(MARKER)) say('marker', 'there')
+    else if (text === null) say('write', 'CHANGELOG.md — generated from the commits, the marker below')
+    else {
+      if (/^## \[Unreleased\]/m.test(text)) stop('CHANGELOG.md has a hand-written [Unreleased] section: fold its entries into the commits git-cliff renders — an entry with no commit is named — show it, remove it on your yes, then run this again')
+      say('convert', 'CHANGELOG.md — the generated part above the marker from the last tag, the hand-written file below it untouched')
+    }
+    if (!write) return
+    if (former.length) {
+      const r = migrate('.', 'changelog')
+      for (const [k, v] of Object.entries(r)) for (const x of v) say(k, x)
+      paths.push(...r.removed, ...r.rewritten)
+    }
+    if (!text?.includes(MARKER)) writeFileSync('CHANGELOG.md', `${MARKER}\n${text ? `\n${text}` : ''}`)
+    const r = sh(process.execPath, [gen])
+    if (r.status !== 0) failed.push(`${gen}: ${said(r)}`)
+    const c = sh(process.execPath, [gen, '--check'])
+    if (c.status !== 0 || c.stdout !== read('CHANGELOG.md')) failed.push(`node ${gen} --check does not reproduce CHANGELOG.md`)
+    paths.push('CHANGELOG.md')
+  },
+  develop() {
+    const d = develop()
+    const o = origin()
+    const dflt = git('symbolic-ref', '--short', 'refs/remotes/origin/HEAD').stdout.trim().replace(/^origin\//, '')
+    if (dflt && dflt !== 'main') stop(`the default branch is ${dflt}, not main — rename it yourself in the forge's settings${o ? ` (${o.forge === 'gh' ? `https://github.com/${o.project}/settings` : `https://${o.host}/${o.project}/-/settings/repository`})` : ''}`)
+    say('develop', { absent: 'none — created from main', behind: `${d.why[0]} — fast-forwarded`, level: 'level with main or ahead of it — nothing to do', diverged: d.why[0], unknown: d.why[0] }[d.state])
+    if (d.state === 'diverged' || d.state === 'unknown') stop(d.why[0])
+    if (!write || d.state === 'level') return
+    const local = git('rev-parse', '--verify', '--quiet', 'develop').status === 0
+    const r = !local ? git('branch', 'develop', 'main')
+      : git('branch', '--show-current').stdout.trim() === 'develop' ? git('merge', '--ff-only', 'main') : git('fetch', '.', 'main:develop')
+    if (r.status !== 0) failed.push(`develop could not be moved — ${said(r)}`)
+    else if (develop().state !== 'level') failed.push('develop is still behind main')
+    else say('push', '`git push -u origin develop` — yours to run, with `! ` before it')
+  },
+}
+items[name]()
+done()

package/scripts/setup/lib.mjs

@@ -0,0 +1,205 @@
+// What `codelife setup prep`, `codelife setup item` and `codelife overview` share: the forge read
+// from `origin` without a contract, the connection to its host, and the state of each base item of
+// target-base.md, read from the tree, git and the tracker at each call (K-1 — setup, R-153). Nothing
+// is recorded: an item's state is what this file finds.
+import '../node-floor.mjs'
+import { spawnSync } from 'node:child_process'
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { env, parseOrigin, TOKENS } from '../tracker/lib.mjs'
+import { detect } from '../former-form.mjs'
+import { packageManager, script } from '../package-manager.mjs'
+import { runChecks } from '../verify/lib.mjs'
+
+export const pkg = join(dirname(fileURLToPath(import.meta.url)), '..', '..')
+const MAX = 256 * 1024 * 1024
+// The changelog's generated/history marker, spelled in scripts/changelog.mjs alone and read from it.
+export const MARKER = readFileSync(join(pkg, 'scripts/changelog.mjs'), 'utf8').match(/^const marker = '(.+)'$/m)[1]
+export const read = (p) => { try { return readFileSync(p, 'utf8') } catch { return null } }
+export const said = (r) => `${r.stdout ?? ''}${r.stderr ?? ''}`.trim() || r.error?.message || ''
+export const sh = (file, args, opts = {}) => spawnSync(file, args, { encoding: 'utf8', input: '', maxBuffer: MAX, ...opts })
+export const git = (...a) => sh('git', a)
+export const say = (key, value) => console.log(`- ${key}: ${value}`)
+export const json = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return null } }
+
+// origin — { host, project, forge }: the forge is the host's kind, never the machine's (R-150) —
+// `?` for a host neither GitLab's nor GitHub's; null without an origin.
+export const origin = () => {
+  const r = git('remote', 'get-url', 'origin')
+  const o = r.status === 0 ? parseOrigin(r.stdout.trim()) : null
+  if (!o) return null
+  return { ...o, forge: o.host === 'github.com' ? 'gh' : o.host === 'gitlab.com' || o.host.startsWith('gitlab.') ? 'glab' : '?' }
+}
+
+// forgeCall <forge> <args> — the CLI with the user's token variables stripped (tracker/lib.mjs).
+export { TOKENS }
+export const forgeCall = (forge, args) => sh(forge, args, { env: env() })
+
+// auth <forge> <host> — { connected, line }: `connected, expires <date>`, `connected, expiry
+// unavailable`, `expired`, `not connected: <the CLI's words>`; a CLI absent from the path is not
+// connected (R-150).
+export const auth = (forge, host) => {
+  const s = forgeCall(forge, ['auth', 'status', '--hostname', host])
+  const out = said(s)
+  if (s.status !== 0 || !out.includes('✓')) return { connected: false, line: out.includes('401 Unauthorized') ? 'expired' : `not connected: ${out || `${forge} is not on the path`}` }
+  let expires
+  if (forge === 'glab') {
+    const t = forgeCall(forge, ['api', 'personal_access_tokens/self', '--hostname', host])
+    expires = t.status === 0 ? JSON.parse(t.stdout).expires_at || 'never' : ''
+  } else expires = forgeCall(forge, ['api', '-i', 'user']).stdout?.match(/^github-authentication-token-expiration:[ \t]*(.+)$/im)?.[1].trim()
+  return { connected: true, expires, line: expires ? `connected, expires ${expires}` : 'connected, expiry unavailable' }
+}
+
+// unmet <forge> <host> <project> <the project's JSON> — each forge setting codelife relies on that is
+// off, with the page that changes it (setup R-155): merge commits, and on GitHub the merged branch
+// deleted, which `gh pr create` cannot ask for as glab's `--remove-source-branch` does (R-72).
+export const unmet = (forge, host, project, j) => {
+  const at = forge === 'glab' ? `https://${host}/${project}/-/settings/merge_requests` : `https://github.com/${project}/settings`
+  return [...((forge === 'glab' ? j.merge_method === 'ff' : j.allow_merge_commit === false) ? ['forbids merge commits, which codelife merges with'] : []),
+    ...(forge === 'gh' && j.delete_branch_on_merge === false ? ['keeps a merged branch: turn on Automatically delete head branches'] : [])].map((x) => `${x} — ${at}`)
+}
+
+// The base, read from target-base.md's tables: a section's names, each backquoted name of a row's
+// first cell, so the definition is the one place that lists them.
+const base = () => readFileSync(join(pkg, 'scripts/target/target-base.md'), 'utf8')
+export const section = (text, heading) => text.split(new RegExp(`^## ${heading}[ \\t]*$`, 'm'))[1]?.split(/^## /m)[0] ?? ''
+export const names = (heading) => [...section(base(), heading).matchAll(/^\| (`[^|]*`) \|/gm)].flatMap((m) => [...m[1].matchAll(/`([^`]+)`/g)].map((x) => x[1]))
+export const LABELS = () => [...(section(base(), 'Tracker').match(/labels — (.*?) — /s)?.[1] ?? '').matchAll(/`([^`]+)`/g)].map((m) => m[1])
+
+// labels <forge> — the tracker's label names, or { error }.
+export const labels = (forge) => {
+  const l = forgeCall(forge, forge === 'glab' ? ['api', 'projects/:id/labels?per_page=100', '--paginate', '--output', 'ndjson'] : ['label', 'list', '--limit', '1000', '--json', 'name'])
+  if (l.status !== 0) return { error: said(l) }
+  return { names: forge === 'glab' ? l.stdout.split('\n').filter(Boolean).map((x) => JSON.parse(x).name) : JSON.parse(l.stdout).map((x) => x.name) }
+}
+
+// templates <forge> — each issue template at the forge's native location, in the form the forge
+// reads: GitLab's file and its `/label` quick action, GitHub's frontmatter (K-27).
+export const templates = (forge) => {
+  const dir = join(pkg, 'scripts/tracker/templates')
+  return readdirSync(dir).filter((f) => f.endsWith('.md')).sort().map((f) => {
+    const t = readFileSync(join(dir, f), 'utf8')
+    if (forge === 'glab') return { at: `.gitlab/issue_templates/${f}`, want: `${t}\n/label ~${t.match(/labels="([^"]+)"/)?.[1]}\n` }
+    const meta = Object.fromEntries([...(t.match(/^<!-- codelife: (.*) -->$/m)?.[1] ?? '').matchAll(/(\w+)="([^"]*)"/g)].map((m) => [m[1], m[2]]))
+    const body = t.split('\n').filter((x) => !x.startsWith('<!-- codelife:')).join('\n')
+    return { at: `.github/ISSUE_TEMPLATE/${f}`, want: `---\nname: ${meta.name}\nabout: ${meta.about}\nlabels: ${meta.labels}\n---\n${body}` }
+  })
+}
+
+// A hook's template, and where the folders' files come from.
+export const hookTemplate = (h) => read(join(pkg, 'scripts/target/templates/githooks', h))
+export const folderTemplate = (p) => join(pkg, 'scripts/target/templates', p.replace(/^docs\//, ''))
+// blank <template> <project> — a specification file as the base writes it: the project's name filled,
+// every line a `{{…}}` guidance touches gone, a span across lines included. A document left with its
+// guidance breaks the form the pre-commit hook holds, once the seven entries exist.
+export const blank = (text, project) => {
+  const out = []
+  let depth = 0
+  for (const line of text.replaceAll('{{project}}', project).split('\n')) {
+    const was = depth
+    depth += (line.match(/\{\{/g) ?? []).length - (line.match(/\}\}/g) ?? []).length
+    if (!was && !depth && !line.includes('{{')) out.push(line)
+  }
+  return out.join('\n').replace(/\n{3,}/g, '\n\n')
+}
+
+// The version this plugin is, and the one the repository installed.
+export const version = () => json(join(pkg, 'package.json')).version
+export const isPackage = () => json('package.json')?.name === '@ersbeth/codelife'
+export const installed = () => (isPackage() ? version() : json('node_modules/@ersbeth/codelife/package.json')?.version ?? null)
+
+// items <{ forge, connected }> — every base item in the order /setup plays it, each
+// { item, state: 'done' | 'to do' | 'not applicable' | 'not read', why: [] }.
+export const ITEMS = ['connect', 'labels', 'templates', 'scripts', 'hooks', 'folders', 'changelog', 'develop']
+export const items = ({ forge, connected }) => {
+  const tracked = forge === 'glab' || forge === 'gh'
+  const pj = json('package.json')
+  const former = detect('.')
+  const why = {
+    connect: !tracked ? null : connected ? [] : ['this machine is not connected to the host'],
+    labels: !tracked ? null : !connected ? undefined : (() => {
+      const l = labels(forge)
+      if (l.error) return [`the labels could not be read — ${l.error}`]
+      const missing = LABELS().filter((x) => !l.names.includes(x))
+      return missing.length ? [`missing ${missing.join(', ')}`] : []
+    })(),
+    templates: !tracked ? null : templates(forge).flatMap(({ at, want }) => {
+      const mine = read(at)
+      return mine === null ? [`${at} is missing`] : mine !== want ? [`${at} differs from this codelife's`] : []
+    }),
+    scripts: names('Scripts').filter((s) => !pj?.scripts?.[s]).map((s) => `${s} is missing from package.json`),
+    hooks: [
+      ...(installed() ? [] : ['the package @ersbeth/codelife is not installed']),
+      ...(git('config', 'core.hooksPath').stdout.trim() === '.githooks' ? [] : [`core.hooksPath is ${git('config', 'core.hooksPath').stdout.trim() || 'unset'}, not .githooks`]),
+      ...names('Hooks').flatMap((h) => {
+        const mine = read(`.githooks/${h}`)
+        // a hook of the repository's own, no marker, is kept: the item showed it, and its reason stays (R-151)
+        return mine === null ? [`.githooks/${h} is missing`] : /generated by codelife/.test(mine) && mine !== hookTemplate(h) ? [`.githooks/${h} differs from this codelife's`] : []
+      }),
+      ...(former.postinstall ? ['a postinstall wires the hooks, where the package\'s prepare should'] : []),
+      ...(former.marketplace ? ['.claude/settings.json still enables the former marketplace copy'] : []),
+    ],
+    folders: names('Folders').filter((p) => !existsSync(p)).map((p) => `${p} is missing`),
+    changelog: [
+      ...(former.changelog.length ? [`former copies: ${former.changelog.join(', ')}`] : []),
+      ...(!existsSync('CHANGELOG.md') ? ['CHANGELOG.md is missing'] : read('CHANGELOG.md').includes(MARKER) ? [] : ['CHANGELOG.md has no generated/history marker']),
+    ],
+    develop: develop().why,
+  }
+  return ITEMS.map((item) => {
+    const w = why[item]
+    return { item, state: w === null ? 'not applicable' : w === undefined ? 'not read' : w.length ? 'to do' : 'done', why: w ?? (item === 'labels' ? ['not connected'] : []) }
+  })
+}
+
+// writer <write> [test] — what an item verb of /setup or /port-toolchain shares: `put` shows what
+// writing a file changes — `write` when absent, `same`, or `differs` and the difference git prints —
+// and with --write writes it; `scripts` runs package.json scripts through the package manager,
+// `test:one` on the --test file, true when one is red or missing; `paths` and `failed` close the
+// block at `done`; `stop` exits 1 with nothing written.
+export const writer = (write, test) => {
+  const paths = [], failed = []
+  const stop = (why) => { say('stop', why); process.exit(1) }
+  const done = () => {
+    if (paths.length) say('paths', paths.join(' '))
+    if (failed.length) { for (const f of failed) say('failed', f); process.exit(1) }
+    process.exit(0)
+  }
+  const put = (path, text, mode) => {
+    const mine = read(path)
+    if (mine === text) return say('same', path)
+    if (mine === null) say('write', path)
+    else {
+      const tmp = join(dirname(path), `.${process.pid}.codelife`)
+      writeFileSync(tmp, text)
+      const diff = git('diff', '--no-index', '--', path, tmp).stdout.split('\n')
+      say('differs', `${path} — yours on -, codelife's on +\n${diff.slice(diff.findIndex((l) => l.startsWith('@@'))).join('\n')}`)
+      rmSync(tmp)
+    }
+    if (!write) return
+    mkdirSync(dirname(path), { recursive: true })
+    writeFileSync(path, text)
+    if (mode) chmodSync(path, mode)
+    paths.push(path)
+  }
+  const scripts = (list) => {
+    const pm = packageManager('.') || 'npm', pj = json('package.json')
+    return runChecks(list.map((s) => (pj?.scripts?.[s] ? { name: s, file: script(pm, s)[0], args: [...script(pm, s).slice(1), ...(s === 'test:one' ? [test] : [])], shell: process.platform === 'win32' }
+      : { name: s, missing: `no ${s} script` })), '- ')
+  }
+  return { paths, failed, stop, done, put, scripts }
+}
+
+// develop — where develop stands against main: { why, state: absent | behind | level | diverged | unknown }.
+export const develop = () => {
+  const has = (ref) => git('rev-parse', '--verify', '--quiet', `${ref}^{commit}`).status === 0
+  const dev = has('develop') ? 'develop' : has('origin/develop') ? 'origin/develop' : null
+  const main = has('main') ? 'main' : has('origin/main') ? 'origin/main' : null
+  if (!main) return { state: 'unknown', why: ['no main branch to read develop against'] }
+  if (!dev) return { state: 'absent', why: ['no develop branch'] }
+  const [d, m] = [git('rev-parse', dev).stdout.trim(), git('rev-parse', main).stdout.trim()]
+  if (d === m || git('merge-base', '--is-ancestor', m, d).status === 0) return { state: 'level', why: [] }
+  if (git('merge-base', '--is-ancestor', d, m).status === 0) return { state: 'behind', why: [`develop is ${git('rev-list', '--count', `${d}..${m}`).stdout.trim()} commits behind main`] }
+  return { state: 'diverged', why: ['develop and main have diverged — reported, never moved'] }
+}

package/scripts/setup/prep.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+// `codelife setup prep` (K-1 — setup, R-149): everything /setup states before it asks — the mode,
+// origin and the connection to its host, the guide when it is not connected, what the contract's
+// values are inferred from, the prose to read, the default branch and the merge method, the former
+// form, and each base item's state. Reads only; one `### setup prep` block; a `- stop:` line per
+// thing that stops the run, and exit 1.
+import '../node-floor.mjs'
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { check, contract } from '../contract.mjs'
+import { detect } from '../former-form.mjs'
+import { packageManager } from '../package-manager.mjs'
+import { auth, forgeCall, git, installed, items, json, origin, read, said, say, sh, TOKENS, unmet, version } from './lib.mjs'
+
+if (process.argv.length > 2) { console.error('usage: codelife setup prep'); process.exit(2) }
+if (git('rev-parse', '--show-toplevel').status !== 0) { console.log('### setup prep\n- stop: not a git repository — /setup runs in one'); process.exit(1) }
+const stops = []
+// The rights a token is created with, in the forge's own words (connection.md R-81): each serves a
+// verb, and none writes the repository's files.
+const RIGHTS = {
+  glab: ['Work Item: read', 'Work Item: create, update', 'Label: read', 'Label: create', 'Merge Request: read',
+    'Merge Request: create, update', 'Merge Request: approve', 'Release: create, read', 'Project: read', 'User: read',
+    'Personal Access Token: read, under the **User** tab'],
+  gh: ['Issues: read and write', 'Pull requests: read and write', 'Metadata: read'],
+}
+const ls = (glob) => git('ls-files', '-z', '--', glob).stdout.split('\0').filter((f) => f && !f.includes('node_modules/'))
+console.log('### setup prep')
+
+// The mode (R-153): no contract is a first run; a valid one, an update; an invalid one stops.
+const c = contract()
+if (!c) say('mode', 'first run — no .claude/codelife.md')
+else {
+  const { invalid, stale } = check(c)
+  if (invalid.length) stops.push(`the contract is invalid — ${invalid.join('; ')}: fix it, or say it may be rewritten`)
+  say('mode', `update — the contract is ${invalid.length ? 'invalid' : stale.length ? `stale: ${stale.join('; ')}` : 'current'}`)
+}
+
+// origin, its forge and the connection (R-150): the forge is the host's, never the machine's.
+const o = origin()
+const forge = c?.data.tracker?.kind ?? (o?.forge === '?' ? null : o?.forge ?? 'none')
+say('origin', o ? `${o.host} — ${o.project}` : 'none — tracker.kind none, to confirm')
+if (o?.forge === '?' && !c) say('tracker.kind', `to confirm — ${o.host} is neither GitLab's nor GitHub's: which CLI talks to it, glab or gh?`)
+else say('tracker.kind', `${forge}${c ? ' — the contract' : o ? ` — inferred from origin's host ${o.host}` : ''}`)
+let connected = false
+if (forge === 'glab' || forge === 'gh') {
+  const onPath = sh(forge, ['--version']).status === 0
+  if (!onPath) say('cli', `${forge} is not on the path — install it on your yes: \`brew install ${forge}\``)
+  const a = onPath ? auth(forge, o.host) : { connected: false, line: `not connected: ${forge} is not on the path` }
+  connected = a.connected
+  const left = a.expires && a.expires !== 'never' ? Math.floor((Date.parse(a.expires) - Date.now()) / 86400000) : null
+  say('connection', `${a.line}${left !== null && left <= 30 ? ` — in ${left} days: create the next token before then, nothing stops meanwhile` : ''}`)
+  for (const v of TOKENS.filter((k) => process.env[k])) say('token variable', `${v} is set in this shell — ignored here, but your terminal's ${forge} uses it: remove it where your shell profile or settings.local.json sets it`)
+  if (!connected) {
+    const ns = o.project.split('/').slice(0, -1).join('/') || o.project
+    const rights = RIGHTS[forge]
+    say('guide', forge === 'glab' ? `open https://${o.host}/-/user_settings/personal_access_tokens — Preferences → Access tokens → Add new token`
+      : 'open https://github.com/settings/personal-access-tokens/new — Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token')
+    say('guide', `name it \`codelife — ${o.host}/${ns}\`, bound to ${ns} alone, the expiry you accept`)
+    say('guide', `grant, all at once — a GitLab token cannot be edited later: ${rights.join('; ')}`)
+    say('guide', `copy the token, then in your own terminal: \`pbpaste | ${forge === 'glab' ? `glab auth login --hostname ${o.host} --stdin` : `gh auth login --hostname ${o.host} --with-token`}\`${forge === 'gh' ? ' — add `--insecure-storage` for a file you can read and delete rather than the Keychain' : ''}`)
+    stops.push(`this machine is not connected to ${o.host}: follow the guide, then run /setup again — nothing is written before`)
+  }
+}
+
+// What the contract's values are inferred from (R-149): each tagged by the file it comes from.
+const manifests = ls('*package.json').map((f) => ({ f, j: json(f) })).filter((m) => m.j)
+const libs = manifests.filter((m) => m.j.exports || m.j.main || m.j.module || m.j.types).map((m) => m.f)
+const roots = new Set(['', ...manifests.map((m) => m.f.replace(/package\.json$/, ''))])
+const apps = [...ls('*index.html').filter((f) => roots.has(f.replace(/(src\/|public\/)?index\.html$/, ''))), ...manifests.filter((m) => m.j.scripts?.start || m.j.scripts?.preview).map((m) => m.f)]
+say('kind', `${libs.length && !apps.length ? 'lib' : apps.length && !libs.length ? 'app' : libs.length ? 'lib or app' : 'none'} — to confirm${libs.length ? `; a package entry in ${libs.join(', ')}` : ''}${apps.length ? `; an application entry in ${apps.join(', ')}` : ''}`)
+if (c) say('kind', `the contract says ${c.data.kind}`)
+const versioned = [...manifests.map((m) => m.f), ...ls('*plugin.json')].filter((f) => json(f)?.version)
+const tags = git('tag', '--sort=-creatordate').stdout.split('\n').filter(Boolean).slice(0, 3)
+say('release.version_file', versioned.length === 1 ? `${versioned[0]} — inferred` : versioned.length ? `to confirm, one of ${versioned.join(', ')}${tags.length ? ` — the last tags: ${tags.join(', ')}` : ''}` : 'missing — no manifest carries a version')
+for (const dir of [...new Set(ls('*dist/*').concat(ls('*build/*'), ls('*api/*')).map((f) => f.match(/^(.*?(?:dist|build|api))\//)?.[1]).filter(Boolean))]) {
+  const owner = manifests.filter((m) => dir.startsWith(m.f.replace(/package\.json$/, ''))).sort((a, b) => b.f.length - a.f.length)[0]
+  const s = Object.entries(owner?.j.scripts ?? {}).filter(([k]) => /build|pack|generate/.test(k))
+  if (s.length) say('generated', `${dir}/ — tracked, and ${owner.f} builds it: ${s.map(([k, v]) => `${k}: ${v}`).join('; ')} — to confirm`)
+}
+const docs = existsSync('docs') ? readdirSync('docs').filter((f) => f.endsWith('.md')).map((f) => `docs/${f}`) : []
+for (const f of ['CLAUDE.md', 'CONTRIBUTING.md', ...docs]) say('prose', existsSync(f) ? `${f}, ${read(f).split('\n').length} lines — read it whole for guards[] and the four prose sections` : `${f} absent`)
+
+// The default branch and the merge method (R-155): what only you can change on the forge.
+const dflt = git('symbolic-ref', '--short', 'refs/remotes/origin/HEAD').stdout.trim().replace(/^origin\//, '')
+const settings = o && (forge === 'glab' ? `https://${o.host}/${o.project}/-/settings/repository` : `https://github.com/${o.project}/settings`)
+if (dflt && dflt !== 'main') stops.push(`the default branch is ${dflt}, not main — rename it yourself at ${settings} (Branch defaults), then run /setup again`)
+say('default branch', dflt || `not read — no origin/HEAD; the branch checked out is ${git('branch', '--show-current').stdout.trim() || 'detached'}`)
+if (connected) {
+  const p = forgeCall(forge, forge === 'glab' ? ['api', 'projects/:id'] : ['api', `repos/${o.project}`])
+  if (p.status !== 0) say('merge method', `not read — ${said(p)}`)
+  else {
+    const off = unmet(forge, o.host, o.project, JSON.parse(p.stdout))
+    for (const x of off.length ? off : ['nothing to change']) say('merge method', x)
+  }
+}
+
+// The package, the former form, the items (R-151, R-153).
+const pm = packageManager('.') || 'npm'
+const have = installed()
+say('package', have ? `@ersbeth/codelife ${have}${have !== version() ? `, this plugin is ${version()}` : ''}` : `not installed — \`${pm} ${pm === 'npm' ? 'install' : 'add'} -D @ersbeth/codelife@${version()}\` on your yes, before the hooks item`)
+const former = detect('.')
+const left = [...former.hooks, ...former.changelog, ...(former.postinstall ? ['a postinstall'] : []), ...(former.marketplace ? ['the marketplace in .claude/settings.json'] : [])]
+if (left.length) say('former form', `${left.join(', ')} — the hooks and changelog items migrate them`)
+for (const i of items({ forge, connected })) say(`item ${i.item}`, `${i.state}${i.why.length ? ` — ${i.why.join('; ')}` : ''}`)
+for (const s of stops) say('stop', s)
+process.exit(stops.length ? 1 : 0)