create-afe-project 0.0.0-stage → 1.0.0

package/src/answers.js

@@ -0,0 +1,147 @@
+// Collects the answers to the template's questions, and reads and writes the answers file that
+// records them with the template version.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import * as p from '@clack/prompts';
+import { parse as parseYaml } from 'yaml';
+import { ANSWERS_FILE, LEGACY_ANSWERS_FILE, QUESTIONS, computed } from './config.js';
+
+export class UsageError extends Error {}
+
+/**
+ * Turns a `--data` string into the type of its question.
+ * @param {string} name
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function coerce(name, value) {
+  const q = QUESTIONS.find((x) => x.name === name);
+  if (!q) throw new UsageError(`unknown question: ${name}`);
+  if (q.type === 'bool' && typeof value === 'string') {
+    if (/^(true|yes|y|1)$/i.test(value)) return true;
+    if (/^(false|no|n|0)$/i.test(value)) return false;
+    throw new UsageError(`${name}: expected true or false, got ${value}`);
+  }
+  if (q.type === 'choice' && !q.choices.some((c) => c.value === value)) {
+    throw new UsageError(`${name}: expected one of ${q.choices.map((c) => c.value).join(', ')}`);
+  }
+  return value;
+}
+
+function check(q, value) {
+  const error = q.validate?.(String(value));
+  if (error) throw new UsageError(`${q.name}: ${error}`);
+}
+
+async function ask(q, initial) {
+  let value;
+  if (q.type === 'bool') {
+    value = await p.confirm({ message: q.help, initialValue: initial ?? q.default });
+  } else if (q.type === 'choice') {
+    value = await p.select({
+      message: q.help,
+      options: q.choices.map((c) => ({ value: c.value, label: c.label })),
+      initialValue: initial ?? q.default,
+    });
+  } else {
+    const start = initial ?? q.default;
+    value = await p.text({
+      message: q.help,
+      initialValue: start,
+      placeholder: start,
+      validate: (v) => q.validate?.(v ?? ''),
+    });
+  }
+  if (p.isCancel(value)) {
+    p.cancel('Cancelled; nothing was written.');
+    process.exit(130);
+  }
+  return value;
+}
+
+/**
+ * Answers every question in order. A value from `given` is taken without asking; then, with
+ * `useDefaults`, the previous answer or the question's default; a question with neither is asked,
+ * or fails when `interactive` is false. A question whose `when` is false is not answered.
+ * @param {{ given?: Record<string, unknown>, previous?: Record<string, unknown>,
+ *   useDefaults?: boolean, interactive?: boolean }} options
+ * @returns {Promise<{ answers: Record<string, unknown>, context: Record<string, unknown> }>}
+ *   the answers to record, and the rendering context with every question and computed value
+ */
+export async function collectAnswers({ given = {}, previous = {}, useDefaults = false, interactive = true }) {
+  for (const name of Object.keys(given)) coerce(name, given[name]);
+  const answers = {};
+  const context = {};
+  for (const q of QUESTIONS) {
+    if (q.when && !q.when(context)) {
+      context[q.name] = q.default ?? '';
+      continue;
+    }
+    let value;
+    if (q.name in given) {
+      value = coerce(q.name, given[q.name]);
+    } else if (useDefaults && (q.name in previous || 'default' in q)) {
+      value = q.name in previous ? previous[q.name] : q.default;
+    } else if (interactive) {
+      value = await ask(q, previous[q.name]);
+    } else {
+      throw new UsageError(`${q.name} has no answer; pass --data ${q.name}=<value> or run in a terminal`);
+    }
+    check(q, value);
+    answers[q.name] = value;
+    context[q.name] = value;
+  }
+  return { answers, context: { ...context, ...computed(context) } };
+}
+
+/**
+ * Reads the recorded answers of a project: the answers file, or a Copier answers file of a project
+ * generated before the template moved to npm.
+ * @param {string} dir
+ * @returns {{ version: string | null, answers: Record<string, unknown>, legacy: boolean } | null}
+ */
+export function readAnswers(dir) {
+  const file = join(dir, ANSWERS_FILE);
+  if (existsSync(file)) {
+    const { _version = null, ...rest } = JSON.parse(readFileSync(file, 'utf8'));
+    return { version: _version, answers: strip(rest), legacy: false };
+  }
+  const legacy = join(dir, LEGACY_ANSWERS_FILE);
+  if (existsSync(legacy)) {
+    const data = parseYaml(readFileSync(legacy, 'utf8')) ?? {};
+    const commit = typeof data._commit === 'string' ? data._commit.replace(/^v/, '').split('-')[0] : null;
+    return { version: commit, answers: strip(data), legacy: true };
+  }
+  return null;
+}
+
+function strip(data) {
+  return Object.fromEntries(Object.entries(data).filter(([k]) => !k.startsWith('_')));
+}
+
+/**
+ * @param {string} dir
+ * @param {string} version
+ * @param {Record<string, unknown>} answers
+ */
+export function writeAnswers(dir, version, answers) {
+  const data = {
+    _note: 'Written by create-afe-project; never edit by hand (docs/documentation-rules.md, section 9).',
+    _version: version,
+    ...answers,
+  };
+  writeFileSync(join(dir, ANSWERS_FILE), `${JSON.stringify(data, null, 2)}\n`);
+}
+
+/**
+ * Compares two versions MAJOR.MINOR.PATCH; a missing version is the lowest.
+ * @param {string | null} a
+ * @param {string | null} b
+ * @returns {number}
+ */
+export function compareVersions(a, b) {
+  const parts = (v) => (v ?? '0.0.0').split('.').map((n) => Number.parseInt(n, 10) || 0);
+  const [x, y] = [parts(a), parts(b)];
+  for (let i = 0; i < 3; i += 1) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+  return 0;
+}

package/src/config.js

@@ -0,0 +1,152 @@
+// The template's questions, file classes, tasks, and migrations: what copier.yml held before the
+// template moved to npm. Maintainers: docs/maintaining.md.
+
+export const ANSWERS_FILE = '.afe-answers.json';
+export const LEGACY_ANSWERS_FILE = '.copier-answers.yml';
+export const TEMPLATE_URL = 'https://github.com/dev-oleksandrv/create-afe-project';
+
+// Template files whose name differs from the generated one, because npm never publishes the
+// generated name.
+export const RENAMES = { _gitignore: '.gitignore' };
+
+// Seeded files: created once, owned by the project afterwards (docs/documentation-rules.md,
+// section 9, in a generated project). An update creates a missing one and never changes one.
+export const SEEDED = [
+  'README.md',
+  'CLAUDE.md',
+  '.gitignore',
+  'docs/README.md',
+  '.claude/path-classes',
+  '.claude/harness.conf',
+  '.claude/settings.project.json',
+];
+
+// Generated files: the Claude Code settings, the ownership manifest, and the decision index are
+// rebuilt after every create and update, in this order.
+export const TASKS = [
+  'scripts/gen-settings.sh',
+  'scripts/check-template.sh --write',
+  'scripts/gen-decisions-index.sh > docs/decisions/README.md',
+];
+
+const LABELS = /^\[\s*"[A-Za-z0-9_.:-]+"(\s*,\s*"[A-Za-z0-9_.:-]+")*\s*\]$/;
+
+// The wizard, in order. `when` decides whether a question is asked; an unasked question takes no
+// answer. `validate` returns an error message or nothing.
+export const QUESTIONS = [
+  {
+    name: 'project_name',
+    type: 'str',
+    help: 'Project name (for example: acme)',
+    validate: (v) => (v.trim() ? undefined : 'Required'),
+  },
+  {
+    name: 'project_description',
+    type: 'str',
+    help: 'What is the project? One sentence, ending with a period',
+    validate: (v) => (v.trim().endsWith('.') ? undefined : 'End the sentence with a period'),
+  },
+  {
+    name: 'github_repo',
+    type: 'str',
+    help: 'GitHub repository (owner/name)',
+    validate: (v) => (/^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/.test(v) ? undefined : 'Use the form owner/name'),
+  },
+  {
+    name: 'ci_runner',
+    type: 'choice',
+    help: 'Where should CI run? (the repository variable CI_RUNS_ON can change it later)',
+    choices: [
+      { label: "On GitHub's servers (ubuntu-latest)", value: 'github-hosted' },
+      { label: 'On your own Linux machine (self-hosted runner)', value: 'self-hosted' },
+    ],
+    default: 'github-hosted',
+  },
+  {
+    name: 'self_hosted_labels',
+    type: 'str',
+    help: 'Labels of your runner, as a JSON array (for example: ["self-hosted", "linux"])',
+    default: '["self-hosted"]',
+    when: (a) => a.ci_runner === 'self-hosted',
+    validate: (v) =>
+      LABELS.test(v) ? undefined : 'Enter a JSON array of quoted labels, such as ["self-hosted", "linux"]',
+  },
+  {
+    name: 'docs_review',
+    type: 'bool',
+    help: 'Let Claude check every pull request for outdated or broken docs? (needs the Claude GitHub App and the CLAUDE_CODE_OAUTH_TOKEN secret)',
+    default: true,
+  },
+  {
+    name: 'code_review',
+    type: 'bool',
+    help: 'Let Claude review pull requests that change code? (needs the same GitHub App and secret)',
+    default: true,
+  },
+  {
+    name: 'dual_review',
+    type: 'bool',
+    help: 'Have Claude Code review each branch before its pull request opens? (uses the Codex CLI if installed, otherwise Claude)',
+    default: false,
+  },
+  {
+    name: 'secret_scan',
+    type: 'bool',
+    help: 'Scan pull requests and pushes to main for leaked secrets? (gitleaks in CI; nothing to install)',
+    default: true,
+  },
+  {
+    name: 'acceptance_check',
+    type: 'bool',
+    help: 'Require a test for every requirement ID a pull request lists under Acceptance? (you set TEST_GLOBS in .claude/harness.conf later)',
+    default: false,
+  },
+  {
+    name: 'fail_without_change',
+    type: 'bool',
+    help: 'Require every new or changed test to fail without the change? (you set FWC_TEST in .claude/harness.conf later)',
+    default: false,
+  },
+];
+
+// Values the templates use that are derived from the answers, never asked.
+export function computed(answers) {
+  return {
+    ci_runs_on_default:
+      answers.ci_runner === 'self-hosted' ? answers.self_hosted_labels : '["ubuntu-latest"]',
+    template_url: TEMPLATE_URL,
+  };
+}
+
+export function messageAfterCreate(a, commit = { done: false }) {
+  const steps = [];
+  steps.push(
+    commit.done
+      ? 'the generated files are committed on main'
+      : `commit the generated files on main (the one direct commit that docs/contributing.md allows; not made here: ${commit.reason ?? 'not asked'})`,
+  );
+  steps.push('add the remote origin, push, and run git remote set-head origin -a');
+  steps.push('protect main with scripts/protect-branch.sh');
+  steps.push('set up the CI runner');
+  if (a.docs_review || a.code_review) steps.push('add the CLAUDE_CODE_OAUTH_TOKEN secret and install the Claude GitHub App');
+  if (a.dual_review) steps.push('optionally install and sign in to the Codex CLI');
+  steps.push('turn on secret scanning and push protection (Settings, Code security)');
+  steps.push('run scripts/check.sh');
+  steps.push('run /afe-init in Claude Code to set up the code and its checks');
+  return `${a.project_name} is ready. Next:\n${steps.map((s, i) => `  ${i + 1}. ${s}`).join('\n')}`;
+}
+
+// Migrations of an update, by the version that introduces them. `before` runs before the template
+// files are written, `after` after them; both run in the project directory, as bash commands.
+// A migration runs when its version is above the project's recorded version and at most the
+// package's.
+export const MIGRATIONS = [
+  // 0.5.0 replaces the seeded .claude/protected-paths, which the update deletes, with
+  // .claude/path-classes: its glob lines are kept as class approval, and the file is removed.
+  {
+    version: '0.5.0',
+    before: '[ ! -f .claude/protected-paths ] || cp .claude/protected-paths .claude/protected-paths.pre-0.5',
+    after:
+      "[ ! -f .claude/protected-paths.pre-0.5 ] || { grep -v -E '^[[:space:]]*(#|$)' .claude/protected-paths.pre-0.5 | sed 's/^/approval /' >> .claude/path-classes; rm -f .claude/protected-paths.pre-0.5 .claude/protected-paths; }",
+  },
+];

package/src/project.js

@@ -0,0 +1,217 @@
+// Creates a project from the template, and updates a project to the template of this package.
+import { execFileSync, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { UsageError, collectAnswers, compareVersions, readAnswers, writeAnswers } from './answers.js';
+import { LEGACY_ANSWERS_FILE, MIGRATIONS, SEEDED, TASKS, messageAfterCreate } from './config.js';
+import { renderTemplate } from './render.js';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const TEMPLATE_DIR = join(ROOT, 'template');
+export const VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
+
+const OWNED_LIST = '.template/owned.txt';
+const MANIFEST = '.template/owned.sha256';
+const START = '<!-- project:start -->';
+const END = '<!-- project:end -->';
+
+function writeFile(dir, rel, { content, mode }) {
+  const target = join(dir, rel);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content);
+  chmodSync(target, mode & 0o777);
+}
+
+function run(dir, command, quiet) {
+  const r = spawnSync('bash', ['-c', command], {
+    cwd: dir,
+    stdio: ['ignore', quiet ? 'pipe' : 'inherit', quiet ? 'pipe' : 'inherit'],
+    encoding: 'utf8',
+  });
+  if (r.status !== 0) {
+    const output = quiet ? `\n${r.stdout ?? ''}${r.stderr ?? ''}` : '';
+    throw new Error(`\`${command}\` failed with exit code ${r.status}${output}`);
+  }
+}
+
+function runTasks(dir, quiet) {
+  for (const task of TASKS) run(dir, task, quiet);
+}
+
+function listed(text) {
+  return text
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#'));
+}
+
+/** Lines of AGENTS.md inside its project block; throws unless there is exactly one. */
+function projectBlock(text) {
+  const lines = text.split('\n');
+  const s = lines.filter((l) => l === START).length;
+  const e = lines.filter((l) => l === END).length;
+  const si = lines.indexOf(START);
+  const ei = lines.indexOf(END);
+  if (s !== 1 || e !== 1 || si > ei) {
+    throw new UsageError(`AGENTS.md needs exactly one '${START}' line followed by one '${END}' line`);
+  }
+  return lines.slice(si + 1, ei);
+}
+
+function withBlock(rendered, block) {
+  const lines = rendered.split('\n');
+  const si = lines.indexOf(START);
+  const ei = lines.indexOf(END);
+  return [...lines.slice(0, si + 1), ...block, ...lines.slice(ei)].join('\n');
+}
+
+/** The content that the manifest hash covers, as scripts/check-template.sh computes it. */
+function hashed(rel, text) {
+  if (rel !== 'AGENTS.md') return text;
+  let skip = false;
+  const kept = [];
+  for (const line of text.split('\n')) {
+    if (line === START) {
+      kept.push(line);
+      skip = true;
+    } else if (line === END) {
+      skip = false;
+      kept.push(line);
+    } else if (!skip) kept.push(line);
+  }
+  return kept.join('\n');
+}
+
+const sha256 = (text) => createHash('sha256').update(text).digest('hex');
+
+/** Template-owned files whose content no longer matches the recorded manifest. */
+function editedOwnedFiles(dir) {
+  const manifest = join(dir, MANIFEST);
+  if (!existsSync(manifest)) return [];
+  const edited = [];
+  for (const line of listed(readFileSync(manifest, 'utf8'))) {
+    const [hash, rel] = line.split(/\s+/, 2);
+    const file = join(dir, rel);
+    if (existsSync(file) && sha256(hashed(rel, readFileSync(file, 'utf8'))) !== hash) edited.push(rel);
+  }
+  return edited;
+}
+
+function isDirty(dir) {
+  try {
+    return execFileSync('git', ['status', '--porcelain'], { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() !== '';
+  } catch {
+    return false; // not a Git repository
+  }
+}
+
+/**
+ * Creates a project in `dir`.
+ * @param {string} dir
+ * @param {{ given?: Record<string, unknown>, useDefaults?: boolean, interactive?: boolean,
+ *   force?: boolean, quiet?: boolean, log?: (msg: string) => void }} options
+ * @returns {Promise<{ answers: Record<string, unknown>, message: string }>}
+ */
+export async function create(dir, { given, useDefaults, interactive, force = false, quiet = false, git = true, log = () => {} }) {
+  const empty = !existsSync(dir) || readdirSync(dir).every((n) => n === '.git');
+  if (!empty && !force) {
+    throw new UsageError(`${dir} is not empty; choose an empty directory, or pass --force to write into it`);
+  }
+  const { answers, context } = await collectAnswers({ given, useDefaults, interactive });
+  mkdirSync(dir, { recursive: true });
+  for (const [rel, file] of renderTemplate(TEMPLATE_DIR, context)) writeFile(dir, rel, file);
+  writeAnswers(dir, VERSION, answers);
+  log('Writing generated files');
+  runTasks(dir, quiet);
+  let commit = { done: false, reason: 'skipped with --no-git' };
+  if (git) {
+    log('Making the initial commit');
+    commit = empty ? initialCommit(dir) : { done: false, reason: 'the directory was not empty' };
+  }
+  return { answers, commit, message: messageAfterCreate(answers, commit) };
+}
+
+/**
+ * Commits the generated files as the first commit on `main`: the one direct commit to `main` that
+ * docs/contributing.md, section 1, allows. Runs only in a new repository, or in one without
+ * commits (an empty clone); never throws.
+ * @param {string} dir
+ * @returns {{ done: boolean, reason?: string }}
+ */
+export function initialCommit(dir) {
+  const git = (...args) => spawnSync('git', args, { cwd: dir, encoding: 'utf8' });
+  const failed = (r) => r.error || r.status !== 0;
+  const why = (r) => (r.error ? r.error.message : (r.stderr || r.stdout || '').trim().split('\n')[0]);
+  if (existsSync(join(dir, '.git'))) {
+    if (!failed(git('rev-parse', '--verify', '--quiet', 'HEAD'))) return { done: false, reason: 'the repository already has commits' };
+    const r = git('symbolic-ref', 'HEAD', 'refs/heads/main');
+    if (failed(r)) return { done: false, reason: why(r) };
+  } else {
+    const r = git('init', '--quiet', '--initial-branch=main');
+    if (failed(r)) return { done: false, reason: `git init failed: ${why(r)}` };
+  }
+  for (const args of [['add', '--all'], ['commit', '--quiet', '-m', `Template: create the project with create-afe-project ${VERSION}`]]) {
+    const r = git(...args);
+    if (failed(r)) return { done: false, reason: `git ${args[0]} failed: ${why(r)}` };
+  }
+  return { done: true };
+}
+
+/**
+ * Updates the project in `dir` to this package's template. Template-owned files are replaced, the
+ * project block of AGENTS.md is kept, files the template no longer owns are removed, missing
+ * seeded files are created and existing ones never changed, the migrations between the two
+ * versions run, and the generated files are rebuilt.
+ * @param {string} dir
+ * @param {{ given?: Record<string, unknown>, useDefaults?: boolean, interactive?: boolean,
+ *   allowDirty?: boolean, quiet?: boolean }} options
+ */
+export async function update(dir, { given, useDefaults, interactive, allowDirty = false, quiet = false }) {
+  const recorded = readAnswers(dir);
+  if (!recorded) throw new UsageError(`${dir} has no answers file; is it a project created by create-afe-project?`);
+  if (compareVersions(recorded.version, VERSION) > 0) {
+    throw new UsageError(`the project follows template ${recorded.version}, newer than this package (${VERSION}); run npx create-afe-project@latest update`);
+  }
+  if (!allowDirty && isDirty(dir)) {
+    throw new UsageError('the working tree has uncommitted changes; commit or stash them, or pass --allow-dirty');
+  }
+  const agentsFile = join(dir, 'AGENTS.md');
+  const block = existsSync(agentsFile) ? projectBlock(readFileSync(agentsFile, 'utf8')) : null;
+
+  const { answers, context } = await collectAnswers({ given, previous: recorded.answers, useDefaults, interactive });
+  const rendered = renderTemplate(TEMPLATE_DIR, context);
+  const newOwned = listed(String(rendered.get(OWNED_LIST).content));
+  const oldOwnedFile = join(dir, OWNED_LIST);
+  const oldOwned = existsSync(oldOwnedFile) ? listed(readFileSync(oldOwnedFile, 'utf8')) : [];
+  const edited = editedOwnedFiles(dir);
+  const pending = MIGRATIONS.filter(
+    (m) => compareVersions(m.version, recorded.version) > 0 && compareVersions(m.version, VERSION) <= 0,
+  );
+
+  for (const m of pending) if (m.before) run(dir, m.before, quiet);
+
+  const removed = oldOwned.filter((rel) => !newOwned.includes(rel) && existsSync(join(dir, rel)));
+  for (const rel of removed) rmSync(join(dir, rel));
+
+  const seeded = [];
+  const unowned = [];
+  for (const [rel, file] of rendered) {
+    const exists = existsSync(join(dir, rel));
+    if (newOwned.includes(rel)) {
+      const content = rel === 'AGENTS.md' && block ? withBlock(String(file.content), block) : file.content;
+      writeFile(dir, rel, { ...file, content });
+    } else if (!exists) {
+      writeFile(dir, rel, file);
+      (SEEDED.includes(rel) ? seeded : unowned).push(rel);
+    }
+  }
+  writeAnswers(dir, VERSION, answers);
+  if (recorded.legacy) rmSync(join(dir, LEGACY_ANSWERS_FILE));
+
+  for (const m of pending) if (m.after) run(dir, m.after, quiet);
+  runTasks(dir, quiet);
+
+  return { from: recorded.version, to: VERSION, removed, edited, seeded, unowned, migrations: pending.map((m) => m.version), legacy: recorded.legacy };
+}

package/src/render.js

@@ -0,0 +1,51 @@
+// Renders template/ with the answers: Jinja syntax through Nunjucks, as Copier did. A file whose
+// name ends in .jinja is rendered and loses the suffix; any other file is copied as it is. Every
+// path segment is rendered too, and a segment that renders empty drops the file or directory, so
+// a module's files use a conditional name such as `{% if code_review %}review-code{% endif %}`.
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import nunjucks from 'nunjucks';
+import { RENAMES } from './config.js';
+
+const SUFFIX = '.jinja';
+const env = new nunjucks.Environment(null, { autoescape: false, throwOnUndefined: true });
+
+/**
+ * @param {string} text
+ * @param {Record<string, unknown>} context
+ * @returns {string}
+ */
+export function renderString(text, context) {
+  return env.renderString(text, context);
+}
+
+/**
+ * Renders every file of the template directory.
+ * @param {string} templateDir
+ * @param {Record<string, unknown>} context
+ * @returns {Map<string, { content: Buffer | string, mode: number }>} by relative output path
+ */
+export function renderTemplate(templateDir, context) {
+  const out = new Map();
+  const walk = (srcDir, outPrefix) => {
+    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+      const src = join(srcDir, entry.name);
+      const templated = entry.isFile() && entry.name.endsWith(SUFFIX);
+      let name = renderString(templated ? entry.name.slice(0, -SUFFIX.length) : entry.name, context);
+      if (!name) continue;
+      if (entry.isDirectory()) {
+        walk(src, outPrefix ? `${outPrefix}/${name}` : name);
+        continue;
+      }
+      const { mode } = statSync(src);
+      let content = readFileSync(src);
+      if (templated) {
+        content = renderString(content.toString('utf8'), context);
+      }
+      name = RENAMES[name] ?? name;
+      out.set(outPrefix ? `${outPrefix}/${name}` : name, { content, mode });
+    }
+  };
+  walk(templateDir, '');
+  return out;
+}

package/template/.claude/harness.conf

@@ -0,0 +1,47 @@
+# Harness settings of this project (docs/contributing.md, section 3; docs/testing-rules.md,
+# section 3): one KEY=value per line. Scripts read the values and never run this file; an empty
+# value leaves a setting unset. This file belongs to the project; a change to it is class gate.
+
+# Environment commands, run by scripts/env.sh setup|fast|e2e|reset (check is scripts/check.sh):
+# set up a working environment, a fast check, end-to-end tests, return to a known-good state.
+SETUP=
+CHECK_FAST=scripts/check-docs.sh
+E2E=
+RESET=
+
+# The check after every edit (.claude/hooks/post-edit-check.sh): a command that gets the changed
+# file as its last argument and takes seconds, such as a formatter check and the linter on that
+# file; and the files it applies to, as shell globs separated by spaces (empty: every file).
+# Empty CHECK_EDIT: no check after edits.
+CHECK_EDIT=
+CHECK_EDIT_GLOBS=
+
+# Ralph loop: the most runs of scripts/check.sh before the agent stops and reports the failure.
+RALPH_MAX_ITERATIONS=5
+
+# Santa loop (the dual-review skill): the most review rounds for a change of class high before
+# the open blockers go to the owner; 3 to 5.
+REVIEW_MAX_ROUNDS=3
+
+# A warning, not a failure, when a pull request changes more lines than this, generated files
+# left out (docs/contributing.md, section 1). Empty: no warning.
+DIFF_WARN_LINES=400
+
+# Identifiers that requirements, criteria, and the specifications of checks define, as an
+# extended regular expression. The "Acceptance and test plan" section and the tests carry them.
+ID_PATTERN=(REQ|AC|INV)-[0-9]+
+
+# Test files, as shell globs separated by spaces, for example `tests/* src/*_test.go`. Empty: the
+# Acceptance check and the fail-without-change driver skip.
+TEST_GLOBS=
+
+# fail-without-change: the files besides the tests to copy onto the base, such as test helpers
+# and runner configuration (shell globs); the command that installs dependencies there (empty:
+# SETUP); the test
+# command, which the driver runs with one test file as its last argument; and an optional
+# command that receives the log file and the test file and exits 0 when the base failed for the
+# expected reason.
+FWC_TOOLCHAIN_GLOBS=
+FWC_INSTALL=
+FWC_TEST=
+FWC_CLASSIFIER=

package/template/.claude/hooks/post-edit-check.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# PostToolUse hook (Edit, Write, MultiEdit): the check after every edit (docs/testing-rules.md,
+# section 4). It runs the project's fast per-file check, CHECK_EDIT of .claude/harness.conf, with
+# the changed file as its last argument, and sends a failure back to the agent in the same
+# session (exit 2), before the Stop hooks and CI. CHECK_EDIT_GLOBS (shell globs separated by
+# spaces, * also matches /) limits it to matching files; empty: every file. An empty CHECK_EDIT,
+# a file outside the project, or a deleted file runs nothing. Keep the command to seconds: it runs
+# after every edit.
+set -uo pipefail
+root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+[ -n "$root" ] || exit 0
+cd "$root" || exit 0
+. scripts/lib/harness-conf.sh 2>/dev/null || exit 0
+cmd=$(conf_get CHECK_EDIT)
+[ -n "$cmd" ] || exit 0
+file=$(node scripts/lib/json.mjs get tool_input.file_path 2>/dev/null) || exit 0
+[ -n "$file" ] && [ -f "$file" ] || exit 0
+root=$(pwd -P)
+abs=$(cd "$(dirname "$file")" 2>/dev/null && printf '%s/%s' "$(pwd -P)" "$(basename "$file")") || exit 0
+case "$abs" in "$root"/*) rel=${abs#"$root"/} ;; *) exit 0 ;; esac
+
+globs=$(conf_get CHECK_EDIT_GLOBS)
+if [ -n "$globs" ]; then
+  match=
+  set -f
+  for g in $globs; do
+    # shellcheck disable=SC2254
+    case "$rel" in $g) match=1; break ;; esac
+  done
+  set +f
+  [ -n "$match" ] || exit 0
+fi
+
+out=$(bash -c "$cmd \"\$1\"" check-edit "$rel" 2>&1)
+code=$?
+[ "$code" -eq 0 ] && exit 0
+printf 'CHECK_EDIT failed on %s (exit %s); fix it before you go on:\n%s\n' "$rel" "$code" "$(printf '%s\n' "$out" | tail -n 40)" >&2
+exit 2