@isonimus/stele 0.1.2

package/scripts/build-index.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Generates adr/INDEX.md from ADR frontmatter (ADR-0001: every file is immutable or
+// generated; this one is generated). It is never hand-edited — the pre-commit hook
+// regenerates it and fails if the working copy is stale, so the index cannot drift from
+// the corpus it summarises.
+//
+//   node scripts/build-index.mjs [repo-root]     (default: cwd)  — writes adr/INDEX.md
+//   --check                                       — exit 1 if INDEX.md is out of date
+//   --stdout                                      — print, don't write
+//
+// Zero dependencies, plain Node ESM — same rationale as lint-docs.mjs (ADR-0003).
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadDocs } from './lint-docs.mjs';
+
+const pad = (v) => String(v).trim().padStart(4, '0');
+
+/** Escape a cell so a title containing `|` cannot break the markdown table. */
+const cell = (s) => String(s).replace(/\|/g, '\\|');
+
+/**
+ * Builds the INDEX.md text from a repo's ADR corpus. Pure: takes loaded docs, returns a
+ * string, touches no filesystem — so the same function serves both write and --check.
+ */
+export function renderIndex(docs) {
+  const adrs = docs
+    .filter((d) => d.ok && d.data.id !== undefined)
+    .map((d) => ({
+      id: pad(d.data.id),
+      title: d.data.title ?? '',
+      type: d.data.type ?? '',
+      status: d.data.status ?? '',
+      supersedes: (d.data.supersedes ?? []).map(pad),
+      superseded_by: (d.data.superseded_by ?? []).map(pad),
+    }))
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  const byType = (t) => adrs.filter((a) => a.type === t);
+  const active = (list) => list.filter((a) => a.status !== 'superseded');
+
+  const out = [];
+  out.push('# ADR Index');
+  out.push('');
+  out.push('<!-- GENERATED by scripts/build-index.mjs — do not edit by hand (ADR-0001).');
+  out.push('     Regenerate with `npm run index`; the pre-commit hook keeps it current. -->');
+  out.push('');
+  out.push(`${adrs.length} decision(s): ${byType('architecture').length} architecture, ` +
+    `${byType('slice').length} slice, ${byType('batch').length} batch.`);
+
+  const section = (heading, list) => {
+    out.push('');
+    out.push(`## ${heading}`);
+    out.push('');
+    if (!list.length) {
+      out.push('_None._');
+      return;
+    }
+    out.push('| id | title | status |');
+    out.push('| --- | --- | --- |');
+    for (const a of list) {
+      out.push(`| ${a.id} | ${cell(a.title)} | ${a.status} |`);
+    }
+  };
+
+  section('Architecture', active(byType('architecture')));
+  section('Slices', active(byType('slice')));
+  const batches = active(byType('batch'));
+  if (batches.length) section('Batches', batches);
+
+  // Supersession graph — every edge, derived from superseded_by. Rule 4 guarantees these
+  // are bidirectional in a green corpus, so one direction is enough to draw the graph.
+  const edges = [];
+  for (const a of adrs) {
+    for (const target of a.superseded_by) edges.push([a.id, target]);
+  }
+  edges.sort((x, y) => x[0].localeCompare(y[0]) || x[1].localeCompare(y[1]));
+
+  out.push('');
+  out.push('## Supersession');
+  out.push('');
+  if (!edges.length) {
+    out.push('_None._');
+  } else {
+    const titleOf = new Map(adrs.map((a) => [a.id, a.title]));
+    for (const [from, to] of edges) {
+      out.push(`- ${from} → ${to}  (${cell(titleOf.get(to) ?? 'unknown')})`);
+    }
+  }
+
+  out.push('');
+  return out.join('\n');
+}
+
+function indexPath(root) {
+  const dir = ['adr', 'slices'].map((d) => join(root, d)).find(existsSync) ?? join(root, 'adr');
+  return join(dir, 'INDEX.md');
+}
+
+function main(argv) {
+  const check = argv.includes('--check');
+  const toStdout = argv.includes('--stdout');
+  const root = argv.find((a) => !a.startsWith('--')) ?? process.cwd();
+
+  const text = renderIndex(loadDocs(root));
+  const path = indexPath(root);
+
+  if (toStdout) {
+    process.stdout.write(text);
+    return 0;
+  }
+
+  if (check) {
+    const current = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    if (current !== text) {
+      console.error(`${path} is out of date — run \`npm run index\` and commit the result.`);
+      return 1;
+    }
+    return 0;
+  }
+
+  writeFileSync(path, text);
+  console.log(`wrote ${path}`);
+  return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exit(main(process.argv.slice(2)));
+}

package/scripts/init-method.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+// Installs the method kit into a git repo (ADR-0006). Dry-run by default.
+//
+//   node scripts/init-method.mjs <repo-root> [--apply] [--check] [--update]
+//
+// The load-bearing rule lives in installHook(): the pre-commit hook is linked ONLY
+// against a corpus the linter calls clean. An unwired scripts/*-verify.mjs is an R11
+// error, so a repo can be red on arrival — and a hook installed on a red corpus blocks
+// every commit, which is the tool bricking the repo it was meant to protect.
+//
+// The linter always runs against the REPO ROOT. Pointed at a subdirectory holding no
+// documents it would report "0 document(s) — ok" (the reason rule 10 exists), certifying
+// an install that checks nothing.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, lstatSync, readlinkSync, symlinkSync, unlinkSync, readdirSync, realpathSync } from 'node:fs';
+import { join, dirname, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { lint, loadDocs } from './lint-docs.mjs';
+import { renderIndex } from './build-index.mjs';
+
+const TOOLKIT = dirname(dirname(fileURLToPath(import.meta.url)));
+
+/** Machinery vendored into every installed repo: target path ← toolkit path. Copies
+ *  rather than symlinks, because a symlink into this checkout resolves on one machine
+ *  only. These must stay byte-identical — a locally edited linter is a silently
+ *  different linter, so `--check` calls any difference a problem. */
+const VENDORED = [
+  ['scripts/lint-docs.mjs', 'scripts/lint-docs.mjs'],
+  ['scripts/build-index.mjs', 'scripts/build-index.mjs'],
+  ['.claude/hooks/pre-commit', '.claude/hooks/pre-commit'],
+];
+
+const COMMANDS_DIR = '.claude/commands';
+
+/**
+ * The slash commands, vendored too (ADR-0007) — same target path as toolkit path.
+ *
+ * Read from disk rather than listed, so a new command reaches installed repos without
+ * anyone remembering to extend an array here.
+ */
+const commandFiles = (toolkit) =>
+  readdirSync(join(toolkit, COMMANDS_DIR))
+    .filter((name) => name.endsWith('.md'))
+    .sort()
+    .map((name) => `${COMMANDS_DIR}/${name}`);
+
+/** Scaffolded once and never overwritten: target path ← template path. */
+const SCAFFOLD = [
+  ['CLAUDE.md', 'templates/CLAUDE.md'],
+  ['LEDGER.md', 'templates/LEDGER.md'],
+];
+
+/** What .git/hooks/pre-commit must point at to count as installed. */
+const HOOK_LINK_TARGET = '../../.claude/hooks/pre-commit';
+
+/** A repo using the `pre-commit` framework gets the checks composed into its config
+ *  instead of a symlink, because that framework owns the same file (ADR-0008). */
+const FRAMEWORK_CONFIG = '.pre-commit-config.yaml';
+
+/** Identifies our block on re-runs, so composing is idempotent. */
+const FRAMEWORK_HOOK_ID = 'stele-docs';
+
+/** Appended verbatim. Mirrors .claude/hooks/pre-commit — the same two commands. */
+const FRAMEWORK_BLOCK = `
+  # Doc invariants (stele:ADR-0003, composed by /init-method per stele:ADR-0008).
+  # Zero-dependency and language: system, so there is nothing to install but node.
+  - repo: local
+    hooks:
+      - id: ${FRAMEWORK_HOOK_ID}
+        name: doc invariants hold
+        entry: node scripts/lint-docs.mjs .
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: stele-index
+        name: adr/INDEX.md matches the corpus
+        entry: node scripts/build-index.mjs --check .
+        language: system
+        pass_filenames: false
+        always_run: true
+`;
+
+const read = (path) => readFileSync(path, 'utf8');
+
+/** existsSync follows symlinks, so a broken link reads as absent — the silent-vanish
+ *  state ADR-0006 names. lstat is what distinguishes the two. */
+function isSymlink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/** The linter's error findings for a repo.
+ *  Always the repo ROOT: pointed at a subdirectory holding no documents the linter
+ *  reports "0 document(s) — ok", certifying an install that checks nothing (rule 10). */
+const lintErrors = (target) => lint(target).findings.filter((f) => f.severity === 'error');
+
+/** True when the target's copy is byte-identical to the toolkit's. */
+const matches = (targetPath, toolkitPath) =>
+  existsSync(targetPath) && read(targetPath) === read(toolkitPath);
+
+function vendor({ target, toolkit, apply, report }) {
+  for (const [dest, src] of VENDORED) {
+    const to = join(target, dest);
+    const from = join(toolkit, src);
+    if (matches(to, from)) {
+      report('ok', to, 'current');
+      continue;
+    }
+    const verb = existsSync(to) ? 'update' : 'copy';
+    if (!apply) {
+      report('would', to, `${verb} from toolkit`);
+      continue;
+    }
+    mkdirSync(dirname(to), { recursive: true });
+    copyFileSync(from, to);
+    report('wrote', to, `${verb}d from toolkit`);
+  }
+}
+
+/**
+ * Slash commands, which are prose and therefore adaptable (ADR-0007).
+ *
+ * Copy-if-absent, unlike vendor(): a repo that has tailored `/slice` to its own workflow
+ * must not have that overwritten by an install. `--update` is the explicit way to take
+ * the toolkit's version back.
+ */
+function vendorCommands({ target, toolkit, apply, force, report }) {
+  for (const path of commandFiles(toolkit)) {
+    const to = join(target, path);
+    const from = join(toolkit, path);
+    if (matches(to, from)) {
+      report('ok', to, 'current');
+      continue;
+    }
+    if (existsSync(to) && !force) {
+      report('keep', to, 'differs from the toolkit — left as it is; `--update` takes the toolkit version');
+      continue;
+    }
+    const verb = existsSync(to) ? 'overwrite' : 'copy';
+    if (!apply) {
+      report('would', to, `${verb} from toolkit`);
+      continue;
+    }
+    mkdirSync(dirname(to), { recursive: true });
+    copyFileSync(from, to);
+    report('wrote', to, `${verb === 'copy' ? 'copied' : 'overwritten'} from toolkit`);
+  }
+}
+
+function scaffold({ target, toolkit, apply, report }) {
+  const adr = join(target, 'adr');
+  if (!existsSync(adr)) {
+    if (apply) mkdirSync(adr, { recursive: true });
+    report(apply ? 'wrote' : 'would', adr, 'create adr/');
+  }
+
+  for (const [dest, src] of SCAFFOLD) {
+    const to = join(target, dest);
+    if (existsSync(to)) {
+      // A repo's own conventions outrank a template; never merge, never overwrite.
+      report('keep', to, 'already exists — left as it is');
+      continue;
+    }
+    if (!apply) {
+      report('would', to, `scaffold from ${src}`);
+      continue;
+    }
+    writeFileSync(to, read(join(toolkit, src)));
+    report('wrote', to, `scaffolded from ${src} — fill its {{PLACEHOLDER}} fields`);
+  }
+}
+
+function buildIndex({ target, apply, report }) {
+  const path = join(target, 'adr', 'INDEX.md');
+  const docs = loadDocs(target).filter((d) => d.ok);
+  const wanted = renderIndex(docs);
+  if (existsSync(path) && read(path) === wanted) return report('ok', path, 'current');
+  if (!apply) return report('would', path, 'generate index');
+  writeFileSync(path, wanted);
+  report('wrote', path, `generated — ${docs.length} decision(s)`);
+}
+
+/**
+ * Links the hook, but only onto a clean corpus.
+ *
+ * The refusal is the decision (ADR-0006). A warning here would be a rule enforced by
+ * memory, which is the failure this whole kit exists to fix.
+ */
+function installHook({ target, apply, report }) {
+  // A dry run over a repo with no adr/ cannot judge the corpus: the linter would report
+  // R10 "no adr/ — is this the repo root?" against a directory --apply creates two steps
+  // earlier. Refusing on that would be a plan that contradicts what applying does.
+  if (!apply && !existsSync(join(target, 'adr'))) {
+    return report('would', join(target, '.git', 'hooks', 'pre-commit'), 'decide once adr/ exists — a dry run cannot check a corpus that has not been scaffolded yet');
+  }
+
+  const errors = lintErrors(target);
+  if (errors.length > 0) {
+    for (const f of errors) report('problem', f.path, f.message);
+    report('problem', target, `${errors.length} lint error(s) — REFUSING to install the pre-commit hook. A hook on a red corpus blocks every commit. Fix these (an unwired scripts/*-verify.mjs is wired by adding it to package.json), then re-run.`);
+    return;
+  }
+
+  if (existsSync(join(target, FRAMEWORK_CONFIG))) return composeHook({ target, apply, report });
+
+  const path = join(target, '.git', 'hooks', 'pre-commit');
+  if (isSymlink(path) && readlinkSync(path) === HOOK_LINK_TARGET && existsSync(path)) {
+    return report('ok', path, 'hook installed');
+  }
+  if (existsSync(path) && !isSymlink(path)) {
+    return report('problem', path, 'a hook already exists here and is not ours — left untouched.');
+  }
+  if (!apply) return report('would', path, `link → ${HOOK_LINK_TARGET}`);
+
+  mkdirSync(dirname(path), { recursive: true });
+  if (isSymlink(path)) unlinkSync(path);
+  symlinkSync(HOOK_LINK_TARGET, path);
+  report('wrote', path, `linked → ${HOOK_LINK_TARGET}`);
+}
+
+/**
+ * Joins the pre-commit framework instead of taking .git/hooks/pre-commit (ADR-0008).
+ *
+ * A symlink here would work until the next `pre-commit install`, which replaces the file
+ * with no error and takes the doc checks with it — a guarantee a third party can revoke
+ * silently is not a guarantee.
+ */
+function composeHook({ target, apply, report }) {
+  const path = join(target, FRAMEWORK_CONFIG);
+  const config = read(path);
+
+  // Refuse rather than guess: this is a textual append into a file we do not own.
+  if (!/^repos:/m.test(config)) {
+    return report('problem', path, 'no top-level `repos:` key — unrecognised shape, refusing to edit it. Add the stele-docs block by hand.');
+  }
+
+  if (config.includes(FRAMEWORK_HOOK_ID)) report('ok', path, 'doc checks composed into the framework');
+  else if (!apply) report('would', path, 'append the doc checks as a `repo: local` block');
+  else {
+    writeFileSync(path, `${config.replace(/\n*$/, '\n')}${FRAMEWORK_BLOCK}`);
+    report('wrote', path, 'appended the doc checks as a `repo: local` block');
+  }
+
+  frameworkInstalled({ target, report });
+}
+
+/** The framework's own dispatcher. Configured-but-not-installed means nothing runs at
+ *  all, while the config still reads as protection. */
+function frameworkInstalled({ target, report }) {
+  const hook = join(target, '.git', 'hooks', 'pre-commit');
+  if (existsSync(hook)) report('ok', hook, 'the framework dispatcher is installed');
+  else report('problem', hook, 'the pre-commit framework is configured but never installed — no hook runs at all, including its own. Run `pre-commit install`.');
+}
+
+function check({ target, toolkit, report }) {
+  for (const [dest, src] of VENDORED) {
+    const to = join(target, dest);
+    if (!existsSync(to)) report('problem', to, 'missing — run /init-method --apply');
+    else if (!matches(to, join(toolkit, src))) report('problem', to, 'drifted from the toolkit — run /init-method --update');
+    else report('ok', to, 'current');
+  }
+
+  // Commands are prose a repo may legitimately adapt, so their drift is informational
+  // (ADR-0007) — reported so it is visible, never counted against a clean check.
+  for (const path of commandFiles(toolkit)) {
+    const to = join(target, path);
+    if (!existsSync(to)) report('missing', to, 'not installed — run /init-method --apply');
+    else if (!matches(to, join(toolkit, path))) report('local', to, 'differs from the toolkit — kept; `--update` takes the toolkit version');
+    else report('ok', to, 'current');
+  }
+
+  // The framework's presence is the single discriminator, so --check cannot disagree
+  // with --apply about which install shape is in force (ADR-0008).
+  const framework = join(target, FRAMEWORK_CONFIG);
+  const hook = join(target, '.git', 'hooks', 'pre-commit');
+  if (existsSync(framework)) {
+    if (read(framework).includes(FRAMEWORK_HOOK_ID)) report('ok', framework, 'doc checks composed into the framework');
+    else report('problem', framework, 'the pre-commit framework runs here but not the doc checks — run /init-method --apply');
+    frameworkInstalled({ target, report });
+  } else if (!isSymlink(hook)) report('problem', hook, 'no hook installed — nothing checks commits');
+  else if (!existsSync(hook)) report('problem', hook, `broken symlink → ${readlinkSync(hook)}; commits are unchecked and silent about it`);
+  else report('ok', hook, 'hook installed and resolving');
+
+  const index = join(target, 'adr', 'INDEX.md');
+  const docs = loadDocs(target).filter((d) => d.ok);
+  if (!existsSync(index)) report('problem', index, 'missing — run /init-method --apply');
+  else if (read(index) !== renderIndex(docs)) report('problem', index, 'stale — regenerate it');
+  else report('ok', index, 'current');
+
+  const errors = lintErrors(target);
+  if (errors.length > 0) report('problem', target, `${errors.length} lint error(s) — the corpus is red`);
+  else report('ok', target, `corpus clean — ${docs.length} document(s)`);
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.target   repo to install into
+ * @param {string} [options.toolkit] this kit's root (overridable for tests)
+ * @param {'install'|'check'|'update'} [options.mode]
+ * @param {boolean} [options.apply]  false = dry run, the default
+ * @returns {{actions: Array<{status: string, path: string, message: string}>, problems: number}}
+ */
+export function initMethod({ target, toolkit = TOOLKIT, mode = 'install', apply = false }) {
+  const actions = [];
+  const report = (status, path, message) => actions.push({ status, path, message });
+
+  if (!existsSync(join(target, '.git'))) {
+    report('problem', target, 'not a git repository — the hook has nowhere to live. Run `git init` first.');
+    return { actions, problems: 1 };
+  }
+
+  if (mode === 'check') {
+    check({ target, toolkit, report });
+  } else if (mode === 'update') {
+    vendor({ target, toolkit, apply, report });
+    vendorCommands({ target, toolkit, apply, force: true, report });
+  } else {
+    scaffold({ target, toolkit, apply, report });
+    vendor({ target, toolkit, apply, report });
+    vendorCommands({ target, toolkit, apply, force: false, report });
+    buildIndex({ target, apply, report });
+    installHook({ target, apply, report });
+  }
+
+  return { actions, problems: actions.filter((a) => a.status === 'problem').length };
+}
+
+function main(argv) {
+  const flags = new Set(argv.filter((a) => a.startsWith('--')));
+  const positional = argv.filter((a) => !a.startsWith('--'));
+  const target = positional[0] ?? process.cwd();
+  const mode = flags.has('--check') ? 'check' : flags.has('--update') ? 'update' : 'install';
+  const apply = flags.has('--apply');
+
+  const { actions, problems } = initMethod({ target, mode, apply });
+
+  console.log(`\n${target} — /init-method ${mode}${apply || mode === 'check' ? '' : ' (dry run)'}`);
+  for (const a of actions) {
+    const where = a.path === target ? target : relative(target, a.path) || a.path;
+    console.log(`  ${a.status.toUpperCase().padStart(7)}  ${where}: ${a.message}`);
+  }
+  if (!apply && mode === 'install') {
+    console.log('\nNothing was written. Re-run with --apply to perform the install.');
+  }
+  console.log(`\n${problems} problem(s)`);
+  return problems > 0 ? 1 : 0;
+}
+
+// A bin is invoked through a symlink (npm links node_modules/.bin/stele → this file), so
+// process.argv[1] is the LINK path while import.meta.url resolves to the real file — a raw
+// `file://${argv[1]}` compare is false under npx and main() silently never runs, no-opping
+// the whole install (ADR-0015 amendment). Resolve both to real paths before comparing.
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}