@erclx/canon 4.0.0

package/src/commands/indexes.ts

@@ -0,0 +1,184 @@
+import { stat } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { $ } from 'bun'
+import type { Command } from 'commander'
+import { exitCodeFor, type RegenResult, regenOne } from '@/indexes/regen'
+import { gitEnv } from '@/git-env'
+import { findIndexedAncestor, isIgnored, listIndexes } from '@/indexes/walk'
+import { intro, logAdd, logInfo, logStep, logWarn, outro } from '@/ui'
+
+interface RegenCommandOptions {
+  readonly dryRun?: boolean
+  readonly json?: boolean
+  readonly root?: string
+  readonly stage?: boolean
+}
+
+export function register(program: Command): void {
+  const indexes = program
+    .command('indexes')
+    .description('Regenerate index.md files from sibling frontmatter')
+    .helpOption('-h, --help', 'Show this help message')
+
+  indexes
+    .command('regen')
+    .description('Regenerate index.md files from sibling frontmatter')
+    .argument(
+      '[paths...]',
+      'Paths to resolve up to their nearest indexed folder',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--dry-run', 'Report changes without writing')
+    .option('--json', 'Emit a machine-readable record per index on stdout')
+    .option('--root <path>', 'Walk-up boundary for positional paths')
+    .option('--no-stage', 'Skip the auto git add on modified indexes')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  no drift, nothing to do',
+        '  1  frontmatter error or missing index.md',
+        '  2  --dry-run found folders that would change',
+        '',
+        'Examples:',
+        '  canon indexes regen',
+        '  canon indexes regen --dry-run',
+        '  canon indexes regen --json docs/',
+        '',
+      ].join('\n'),
+    )
+    .action(async (paths: string[], opts: RegenCommandOptions) => {
+      process.exitCode = await runRegen(paths, opts)
+    })
+}
+
+async function runRegen(
+  paths: string[],
+  opts: RegenCommandOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const dryRun = opts.dryRun ?? false
+  const emitJson = opts.json ?? false
+
+  if (!(await isDirectory(root))) {
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ error: `root not a directory: ${root}` })}\n`,
+      )
+      return 1
+    }
+    process.stderr.write(`Root is not a directory: ${root}\n`)
+    return 1
+  }
+
+  const dirs =
+    paths.length > 0
+      ? collectFromPaths(paths, root)
+      : (await listIndexes(root)).map(dirname)
+
+  const shouldStage =
+    paths.length > 0 && opts.stage !== false && !dryRun && !emitJson
+
+  const results: RegenResult[] = []
+
+  if (!emitJson) {
+    intro('canon indexes')
+    logStep(dryRun ? 'Indexes (dry-run)' : 'Indexes')
+  }
+
+  for (const dir of dirs) {
+    const result = await regenOne(dir, { dryRun })
+    results.push(result)
+
+    for (const message of result.errors ?? []) {
+      process.stderr.write(`ERROR: ${message}\n`)
+    }
+
+    if (!emitJson) await reportResult(result, root, shouldStage)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        dryRun,
+        results: results.map(({ path, action, reason }) =>
+          reason ? { path, action, reason } : { path, action },
+        ),
+      })}\n`,
+    )
+  } else {
+    outro()
+  }
+
+  return exitCodeFor(results, { dryRun })
+}
+
+function collectFromPaths(paths: string[], root: string): string[] {
+  const dirs: string[] = []
+
+  for (const path of paths) {
+    const dir = findIndexedAncestor(resolve(root, path), root)
+    if (!dir) {
+      process.stderr.write(
+        `WARN: ${path} has no index.md ancestor under ${root}\n`,
+      )
+      continue
+    }
+    if (!dirs.includes(dir)) dirs.push(dir)
+  }
+
+  return dirs
+}
+
+async function reportResult(
+  result: RegenResult,
+  root: string,
+  shouldStage: boolean,
+): Promise<void> {
+  const rel = result.path.startsWith(`${root}/`)
+    ? result.path.slice(root.length + 1)
+    : result.path
+
+  switch (result.action) {
+    case 'written':
+      logAdd(rel)
+      if (shouldStage) await stage(result.path, rel, root)
+      break
+    case 'would-write':
+      logWarn(`${rel} would change`)
+      break
+    case 'unchanged':
+      logInfo(`${rel} unchanged`)
+      break
+    case 'skipped':
+      logInfo(`${rel} skipped (auto:false)`)
+      break
+    case 'error':
+      logWarn(`${rel} error`)
+      break
+  }
+}
+
+async function stage(path: string, rel: string, root: string): Promise<void> {
+  if (await isIgnored(root, path)) return
+
+  const staged = await $`git -C ${root} add -- ${path}`
+    .env(gitEnv())
+    .quiet()
+    .nothrow()
+    .then((result) => result.exitCode === 0)
+
+  if (staged) {
+    logInfo(`staged ${rel}`)
+  } else {
+    logWarn(`failed to stage ${rel}`)
+  }
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  return stat(path)
+    .then((info) => info.isDirectory())
+    .catch(() => false)
+}

package/src/commands/init.ts

@@ -0,0 +1,113 @@
+import type { Command } from 'commander'
+import { cliPath, cliRun } from '@/cli-run'
+import { PROJECT_ROOT } from '@/project-root'
+import { applyInitOptions, flagsProvided } from '@/init/flags'
+import { type InitFlags, parseSkip, planInit } from '@/init/plan'
+import { runDomains } from '@/init/run'
+import { buildSteps } from '@/init/steps'
+import { resolveTarget } from '@/target'
+import { intro, logInfo, logStep, logWarn, outro, palette, select } from '@/ui'
+
+interface InitOptions {
+  /** Always present: the option falls back to `DEFAULT_STACK`. */
+  readonly stack: string
+  readonly add?: string
+  readonly skip?: string
+}
+
+export function register(program: Command): void {
+  const command = program
+    .command('init')
+    .description('Bootstrap a project with base tooling and toolkit domains')
+    .argument('[target]', 'Target directory', '.')
+
+  applyInitOptions(command)
+    .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Passing any option skips the confirmation prompt.',
+        '',
+        'Examples:',
+        '  canon init',
+        '  canon init ../my-app',
+        '  canon init --stack astro --add 260-shadcn ../my-app',
+        '  canon init --skip governance ../my-app',
+        '',
+      ].join('\n'),
+    )
+    .action(async (target: string, options: InitOptions, cmd: Command) => {
+      process.exitCode = await runInit(target, options, flagsProvided(cmd))
+    })
+}
+
+async function runInit(
+  target: string,
+  options: InitOptions,
+  skipPrompt: boolean,
+): Promise<number> {
+  intro('canon init')
+
+  const resolved = resolveTarget(target, PROJECT_ROOT)
+  if (typeof resolved === 'number') return resolved
+
+  const skip = parseSkip(options.skip)
+  for (const value of skip.unknown) {
+    logWarn(`Unknown --skip value: ${value} (ignoring)`)
+  }
+
+  const flags: InitFlags = {
+    stack: options.stack,
+    add: options.add,
+    skip,
+  }
+
+  const plan = planInit(flags)
+
+  logStep('Core domains')
+  for (const line of plan.preview) {
+    if (line.level === 'info') logInfo(line.text)
+    else logWarn(line.text)
+  }
+
+  if (!skipPrompt) {
+    const shouldInstall = await select({
+      message: `Install ${plan.total} domains to ${target}?`,
+      options: [
+        { value: true, label: 'Yes' },
+        { value: false, label: 'Cancel' },
+      ],
+      nonInteractiveDefault: true,
+    })
+
+    if (!shouldInstall) {
+      logWarn('Cancelled')
+      outro()
+      return 0
+    }
+  }
+
+  const path = cliPath(PROJECT_ROOT)
+  const child = (args: readonly string[]): (() => Promise<boolean>) =>
+    cliRun(path, args, { nonInteractive: true, stdin: 'ignore' })
+
+  const failed = await runDomains(buildSteps(target, resolved, flags, child))
+
+  outro()
+  process.stderr.write('\n')
+
+  const { GREEN, NC, YELLOW } = palette(process.stderr)
+
+  if (failed.length === 0) {
+    process.stderr.write(
+      `${GREEN}✓ Project initialized (${plan.total} domains)${NC}\n`,
+    )
+    return 0
+  }
+
+  process.stderr.write(
+    `${YELLOW}! Project initialized with ${failed.length} failure(s): ${failed.join(', ')}${NC}\n`,
+  )
+  return 1
+}

package/src/commands/intake.ts

@@ -0,0 +1,406 @@
+import { relative } from 'node:path'
+import type { Command } from 'commander'
+import {
+  type AnswerOutcome,
+  answerItems,
+  type IntakeRefused,
+  type ListOutcome,
+  listFolders,
+  type ReadOutcome,
+  readFolder,
+  type Selection,
+} from '@/intake/folder'
+import { isUnread } from '@/intake/items'
+import {
+  intro,
+  logAdd,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+} from '@/ui'
+import { mainWorktreeRoot } from '@/worktree'
+
+/**
+ * A selection as the command line spells it, splitting on the first `=`. The
+ * label accepts a letter suffix, matching the headings a cluster file carries,
+ * and everything after the separator is the answer, so one carrying its own
+ * `=` survives intact.
+ */
+const SELECTION = /^(\d+[a-z]*)=([\s\S]*)$/i
+
+interface ListCommandOptions {
+  readonly json?: boolean
+  readonly unread?: boolean
+  readonly root?: string
+}
+
+interface AnswerCommandOptions {
+  readonly cluster?: string
+  readonly json?: boolean
+  readonly root?: string
+  readonly set?: readonly string[]
+}
+
+export function register(program: Command): void {
+  const intake = program
+    .command('intake')
+    .description('Read and answer intake folders in .claude/intake/')
+    .helpOption('-h, --help', 'Show this help message')
+
+  intake
+    .command('list')
+    .description('List intake folders, or the items one folder holds')
+    .argument('[slug]', 'Intake folder name, as in toolkit-overview')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--unread',
+      'Keep only what is unread, as folders carrying one or as empty slots',
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Intake root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the folders or items were listed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'With no slug it reports per-folder counts. With one it reports every',
+        'item grouped by the cluster file holding it. An empty answer slot',
+        'means unread and never agreement, so a count is the report and no',
+        'verb here decides one.',
+        '',
+        'An item carrying no answer slot is counted apart from both, since the',
+        'answer verb cannot reach it and folding it into either count hides a',
+        'file that needs fixing.',
+        '',
+        'Examples:',
+        '  canon intake list',
+        '  canon intake list toolkit-overview --unread --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (slug: string | undefined, opts: ListCommandOptions) => {
+      process.exitCode = await runList(slug, opts)
+    })
+
+  intake
+    .command('answer')
+    .description("Write selections into a cluster's answer slots")
+    .argument('<slug>', 'Intake folder name, as in toolkit-overview')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--cluster <file>', 'Cluster file the items live in')
+    .option(
+      '--set <item=answer>',
+      'Answer to land on an item, repeatable',
+      collectSelection,
+      [] as string[],
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Intake root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  every named item now carries its answer',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Items are numbered per cluster file, so a selection names the cluster',
+        'and the number together. One call writes one cluster, which is what',
+        'keeps a batch from racing on the file every selection shares.',
+        '',
+        'An item already carrying an answer is refused rather than overwritten.',
+        'A filled slot is a decision already made.',
+        '',
+        'Examples:',
+        '  canon intake answer toolkit-overview --cluster 05-coverage.md --set 3=ok',
+        '  canon intake answer toolkit-overview --cluster 05-coverage.md --set 3=ok --set 4="not worth it" --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (slug: string, opts: AnswerCommandOptions) => {
+      process.exitCode = await runAnswer(slug, opts)
+    })
+}
+
+function collectSelection(value: string, previous: string[]): string[] {
+  return [...previous, value]
+}
+
+async function runList(
+  slug: string | undefined,
+  opts: ListCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const root = opts.root ?? (await mainWorktreeRoot())
+
+  if (slug === undefined) {
+    return reportList(
+      await listFolders(root),
+      emitJson,
+      root,
+      opts.unread ?? false,
+    )
+  }
+
+  return reportFolder(
+    await readFolder(root, slug),
+    emitJson,
+    root,
+    opts.unread ?? false,
+  )
+}
+
+async function runAnswer(
+  slug: string,
+  opts: AnswerCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (!opts.cluster) {
+    return reportRefusal(
+      'canon intake answer',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: 'No cluster named. Pass --cluster <file>.',
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const raw = opts.set ?? []
+
+  if (raw.length === 0) {
+    return reportRefusal(
+      'canon intake answer',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: 'No selection given. Pass --set <item>=<answer>.',
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const selections: Selection[] = []
+  const invalid: string[] = []
+
+  for (const entry of raw) {
+    const match = SELECTION.exec(entry)
+    const answer = match?.[2].trim()
+
+    if (!match || !answer) {
+      invalid.push(entry)
+      continue
+    }
+
+    selections.push({ label: match[1].toLowerCase(), answer })
+  }
+
+  if (invalid.length > 0) {
+    return reportRefusal(
+      'canon intake answer',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: `Not an item and answer: ${invalid.join(', ')}`,
+        detail: invalid,
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const duplicated = selections
+    .map((selection) => selection.label)
+    .filter((label, index, all) => all.indexOf(label) !== index)
+
+  if (duplicated.length > 0) {
+    return reportRefusal(
+      'canon intake answer',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: `Two answers for item ${[...new Set(duplicated)].join(', ')}.`,
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await answerItems(root, slug, opts.cluster, selections)
+
+  return reportAnswer(outcome, emitJson, root)
+}
+
+function reportRefusal(
+  title: string,
+  refused: IntakeRefused,
+  emitJson: boolean,
+  root: string,
+): number {
+  // The framed branch reaches stderr through logError, so the bare write is
+  // what keeps the JSON mode from reporting the reason on stdout alone.
+  if (emitJson) {
+    process.stderr.write(`${refused.message}\n`)
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: false,
+        root,
+        reason: refused.reason,
+        message: refused.message,
+        detail: refused.detail,
+      })}\n`,
+    )
+    return 1
+  }
+
+  intro(title)
+  logStep('Refused')
+  logError(refused.message)
+  if (refused.detail.length > 0) pipeOutput(refused.detail.join('\n'))
+  outro()
+
+  return 1
+}
+
+function reportList(
+  outcome: ListOutcome,
+  emitJson: boolean,
+  root: string,
+  unreadOnly: boolean,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('canon intake list', outcome, emitJson, root)
+  }
+
+  // Malformed items are counted over every folder rather than the filtered
+  // set, since a folder whose only defect is an item nobody can answer carries
+  // no unread count to survive the filter and is exactly what the warning is
+  // for.
+  const listed = unreadOnly
+    ? outcome.folders.filter((folder) => folder.unread > 0)
+    : outcome.folders
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, root, folders: listed })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon intake list')
+  logStep(listed.length > 0 ? 'Folders' : 'No folders')
+
+  for (const folder of listed) {
+    logInfo(
+      `${folder.slug}: ${folder.items} item(s), ${folder.open} open, ${folder.unread} unread`,
+    )
+  }
+
+  const malformed = outcome.folders.filter((folder) => folder.malformed > 0)
+
+  if (malformed.length > 0) {
+    logStep('Carrying no answer slot')
+    for (const folder of malformed) {
+      logWarn(
+        `${folder.slug}: ${folder.malformed} item(s), which none of these verbs can answer`,
+      )
+    }
+  }
+
+  outro()
+
+  return 0
+}
+
+function reportFolder(
+  outcome: ReadOutcome,
+  emitJson: boolean,
+  root: string,
+  unreadOnly: boolean,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('canon intake list', outcome, emitJson, root)
+  }
+
+  const clusters = outcome.clusters
+    .map((cluster) => ({
+      cluster: cluster.cluster,
+      items: unreadOnly ? cluster.items.filter(isUnread) : cluster.items,
+    }))
+    .filter((cluster) => cluster.items.length > 0)
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, root, slug: outcome.slug, clusters })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon intake list')
+
+  for (const cluster of clusters) {
+    logStep(cluster.cluster)
+    for (const item of cluster.items) {
+      const state = isUnread(item) ? 'unread' : (item.answer ?? 'no slot')
+      logInfo(`${item.label}. ${item.title} (${state})`)
+    }
+  }
+
+  if (clusters.length === 0) {
+    logStep(unreadOnly ? 'Nothing unread' : 'No items')
+  }
+
+  outro()
+
+  return 0
+}
+
+function reportAnswer(
+  outcome: AnswerOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('canon intake answer', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        slug: outcome.slug,
+        cluster: outcome.cluster,
+        path: relative(root, outcome.path),
+        answered: outcome.answered,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon intake answer')
+  logStep('Answered')
+
+  for (const entry of outcome.answered) {
+    logInfo(`${entry.label}. ${entry.answer}`)
+  }
+
+  logAdd(relative(root, outcome.path))
+  outro()
+
+  return 0
+}