create-afe-project 0.0.0-stage → 2.0.0

package/bin/create-afe-project.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// Command line of create-afe-project: create a project, or update one to this package's template.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import * as p from '@clack/prompts';
+import { UsageError } from '../src/answers.js';
+import { VERSION, create, update } from '../src/project.js';
+
+const HELP = `create-afe-project ${VERSION}
+
+Usage:
+  npm create afe-project@latest [directory] [-- options]
+  npx create-afe-project@latest [directory] [options]   create a project
+  npx create-afe-project@latest update [options]        update the project in the current directory
+
+Options:
+  --defaults           do not ask: take --data, then the recorded answers, then the defaults
+  --data key=value     answer a question; repeatable
+  --data-file <file>   answers from a JSON file; --data wins over it
+  --force              create: write into a directory that is not empty
+  --no-git             create: do not make the initial Git commit on main
+  --allow-dirty        update: run with uncommitted changes
+  --quiet              print only errors and the result
+  -h, --help           print this help
+  -v, --version        print the version
+`;
+
+function given(values) {
+  const data = values['data-file'] ? JSON.parse(readFileSync(values['data-file'], 'utf8')) : {};
+  for (const pair of values.data ?? []) {
+    const i = pair.indexOf('=');
+    if (i < 1) throw new UsageError(`--data expects key=value, got ${pair}`);
+    data[pair.slice(0, i)] = pair.slice(i + 1);
+  }
+  return Object.fromEntries(Object.entries(data).filter(([k]) => !k.startsWith('_')));
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      defaults: { type: 'boolean' },
+      data: { type: 'string', multiple: true },
+      'data-file': { type: 'string' },
+      force: { type: 'boolean' },
+      'no-git': { type: 'boolean' },
+      'allow-dirty': { type: 'boolean' },
+      quiet: { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' },
+      version: { type: 'boolean', short: 'v' },
+    },
+  });
+  if (values.help) return void process.stdout.write(HELP);
+  if (values.version) return void process.stdout.write(`${VERSION}\n`);
+
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY) && !values.defaults;
+  const quiet = Boolean(values.quiet);
+  const common = { given: given(values), useDefaults: Boolean(values.defaults), interactive, quiet };
+  if (interactive) p.intro(`create-afe-project ${VERSION}`);
+
+  if (positionals[0] === 'update') {
+    if (positionals.length > 1) throw new UsageError('update takes no directory; run it in the project');
+    const r = await update(process.cwd(), { ...common, allowDirty: Boolean(values['allow-dirty']) });
+    const lines = [`Updated the template from ${r.from ?? 'an unrecorded version'} to ${r.to}.`];
+    if (r.legacy) lines.push('Converted .copier-answers.yml to .afe-answers.json.');
+    if (r.migrations.length) lines.push(`Migrations run: ${r.migrations.join(', ')}.`);
+    if (r.removed.length) lines.push(`Removed, no longer template-owned: ${r.removed.join(', ')}.`);
+    if (r.seeded.length) lines.push(`Created missing seeded files: ${r.seeded.join(', ')}.`);
+    if (r.unowned.length) lines.push(`Created files without an owner class (a template defect): ${r.unowned.join(', ')}.`);
+    if (r.edited.length) {
+      lines.push(`Replaced local edits of template-owned files; review them in git diff: ${r.edited.join(', ')}.`);
+    }
+    lines.push('Next: scripts/check.sh, then a pull request (docs/contributing.md, section 5).');
+    return void (interactive ? p.outro(lines.join('\n')) : console.log(lines.join('\n')));
+  }
+
+  if (positionals.length > 1) throw new UsageError('expected at most one directory');
+  let dir = positionals[0];
+  if (!dir) {
+    if (!interactive) throw new UsageError('name the directory to create the project in');
+    dir = await p.text({ message: 'Where should the project go? (a new or empty directory)', placeholder: 'my-project', validate: (v) => (v?.trim() ? undefined : 'Required') });
+    if (p.isCancel(dir)) {
+      p.cancel('Cancelled; nothing was written.');
+      process.exit(130);
+    }
+  }
+  if (interactive) {
+    p.note(
+      'A few questions about the project, then yes/no questions that turn optional checks on.\n' +
+        'Press Enter to keep a default. To change an answer later, run\n' +
+        'npx create-afe-project@latest update in the project.',
+    );
+  }
+  const spinner = interactive && !quiet ? p.spinner() : null;
+  let spinning = false;
+  const { message } = await create(resolve(dir), {
+    ...common,
+    force: Boolean(values.force),
+    git: !values['no-git'],
+    quiet: quiet || interactive,
+    // Start the spinner once: a second start() leaves its first timer running, and the process
+    // never exits.
+    log: (msg) => {
+      if (!spinner) return;
+      if (spinning) spinner.message(msg);
+      else spinner.start(msg);
+      spinning = true;
+    },
+  });
+  spinner?.stop('Generated files written');
+  if (interactive) p.outro(message);
+  else console.log(message);
+}
+
+main().catch((error) => {
+  if (error instanceof UsageError || error?.code?.startsWith?.('ERR_PARSE_ARGS')) {
+    console.error(`create-afe-project: ${error.message}\nRun create-afe-project --help for usage.`);
+    process.exit(2);
+  }
+  console.error(`create-afe-project: ${error.message}`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "create-afe-project",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "Create and update agent-friendly repositories: documentation rules, decision records, checks, and Claude Code hooks and skills.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-afe-project": "bin/create-afe-project.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "template/",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "changeset": "changeset",
+    "version-packages": "changeset version && npm install --package-lock-only --ignore-scripts && scripts/sync-self.sh"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dev-oleksandrv/create-afe-project.git"
+  },
+  "keywords": [
+    "create",
+    "scaffold",
+    "template",
+    "agents",
+    "claude-code",
+    "afe"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "nunjucks": "^3.2.4",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "1.0.1",
+    "@changesets/cli": "3.0.3"
+  }
+}

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,151 @@
+// 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 and apply the repository settings with scripts/protect-branch.sh (merge commits only, head branches deleted, secret scanning where the plan offers it)');
+  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('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; }",
+  },
+];