@erclx/aitk 0.8.0

package/src/commands/gov.ts

@@ -0,0 +1,268 @@
+import { existsSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { basename, dirname, join, resolve } from 'node:path'
+import type { Command } from 'commander'
+import { registerPassThroughVerbs } from '@/commands/pass-through'
+import { PROJECT_ROOT } from '@/exec'
+import { createGovAdapter } from '@/gov/adapter'
+import { hasStandards, installRules, lookupRules } from '@/gov/install'
+import { buildRulesPayload, listRuleFiles } from '@/gov/payload'
+import {
+  govStackExists,
+  listGovStacks,
+  mergeExtraRules,
+  resolveRules,
+} from '@/gov/stacks'
+import { recordStamp, runDomainSync } from '@/sync/engine'
+import { resolveTarget } from '@/target'
+import {
+  intro,
+  isNonInteractive,
+  logAdd,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  select,
+} from '@/ui'
+
+const GREEN = '\x1b[0;32m'
+const NC = '\x1b[0m'
+
+const PAYLOAD_REL = join('.claude', '.tmp', 'gov', 'rules.md')
+const RULES_REL = join('.claude', 'rules')
+
+const PASS_THROUGH_VERBS = ['list'] as const
+
+interface InstallOptions {
+  readonly add?: string
+}
+
+export function register(program: Command): void {
+  const gov = program
+    .command('gov')
+    .description('Governance commands (install, sync, build, list)')
+    .helpOption('-h, --help', 'Show this help message')
+
+  gov
+    .command('install')
+    .description('Install a governance stack into .claude/rules/')
+    .argument('[stack]', 'Stack name (e.g. base, node, react)')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--add <rules>', 'Comma-separated rules to layer on the stack')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Examples:',
+        '  aitk gov install react',
+        '  aitk gov install node ../my-app',
+        '  aitk gov install astro --add 200-react,260-shadcn ../my-app',
+        '',
+      ].join('\n'),
+    )
+    .action(
+      async (
+        stack: string | undefined,
+        target: string,
+        opts: InstallOptions,
+      ) => {
+        process.exitCode = await runInstall(stack, target, opts)
+      },
+    )
+
+  gov
+    .command('sync')
+    .description('Update rules already installed under .claude/rules/')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .action(async (target: string) => {
+      process.exitCode = await runDomainSync(
+        createGovAdapter(PROJECT_ROOT),
+        target,
+        { protectedRoot: PROJECT_ROOT },
+      )
+    })
+
+  gov
+    .command('build')
+    .description('Concatenate installed rules into .claude/.tmp/gov/rules.md')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .action(async (target: string) => {
+      process.exitCode = await runBuild(target)
+    })
+
+  registerPassThroughVerbs(gov, 'gov', PASS_THROUGH_VERBS)
+}
+
+/**
+ * Renders the target-relative path the prompt quotes, keeping the argument the
+ * caller typed rather than the absolute path it resolves to.
+ */
+function displayPath(target: string, rel: string): string {
+  const trimmed = target.replace(/\/$/, '').replace(/^\.\//, '')
+  return trimmed === '' || trimmed === '.' ? rel : `${trimmed}/${rel}`
+}
+
+/**
+ * Refuses rather than picking. `select_option` returned `options[0]` under
+ * `AITK_NON_INTERACTIVE=1`, so a headless `aitk gov install` with no stack
+ * installed whichever stack sorted first, measured as 26 astro rules into an
+ * empty directory. Every documented agent path already passes the argument.
+ */
+async function chooseStack(root: string): Promise<string | number> {
+  const stacks = listGovStacks(root)
+
+  if (stacks.length === 0) {
+    logError('No stacks found in governance/stacks/')
+    outro()
+    return 1
+  }
+
+  if (isNonInteractive()) {
+    logError(
+      `Stack argument is required in non-interactive mode. One of: ${stacks.join(', ')}.`,
+    )
+    outro()
+    return 1
+  }
+
+  return select({
+    message: 'Select stack to install:',
+    options: stacks.map((stack) => ({ value: stack, label: stack })),
+  })
+}
+
+async function runInstall(
+  stack: string | undefined,
+  target: string,
+  opts: InstallOptions,
+): Promise<number> {
+  intro('aitk gov install')
+
+  const resolved = resolveTarget(target, PROJECT_ROOT)
+  if (typeof resolved === 'number') return resolved
+
+  let selected = stack
+  if (selected === undefined) {
+    const choice = await chooseStack(PROJECT_ROOT)
+    if (typeof choice === 'number') return choice
+    selected = choice
+  }
+
+  if (!govStackExists(PROJECT_ROOT, selected)) {
+    logError(`Stack not found: ${selected}`)
+    outro()
+    return 1
+  }
+
+  const resolution = resolveRules(PROJECT_ROOT, selected)
+  if (!resolution.ok) {
+    logError(`Stack not found: ${resolution.missingStack}`)
+    outro()
+    return 1
+  }
+
+  const add = opts.add ?? ''
+  const rules =
+    add === '' ? resolution.rules : mergeExtraRules(resolution.rules, add)
+
+  if (rules.length === 0) {
+    logWarn(`No rules defined for stack: ${selected}`)
+    outro()
+    return 0
+  }
+
+  logStep(
+    add === ''
+      ? `Resolving stack: ${selected}`
+      : `Resolving stack: ${selected} + extras`,
+  )
+
+  const { found, missing } = lookupRules(PROJECT_ROOT, rules)
+  for (const rule of missing) logWarn(`${rule} (source not found, skipping)`)
+  for (const source of found) logInfo(source.rule)
+
+  const shouldInstall = await select({
+    message: `Install ${found.length} rules to ${displayPath(target, RULES_REL)}?`,
+    options: [
+      { value: true, label: 'Yes' },
+      { value: false, label: 'No' },
+    ],
+    nonInteractiveDefault: true,
+  })
+
+  if (!shouldInstall) {
+    logWarn('Cancelled')
+    outro()
+    return 0
+  }
+
+  logStep('Installing rules')
+  for (const rel of await installRules(found, resolved)) logAdd(rel)
+  await recordStamp(createGovAdapter(PROJECT_ROOT), resolved, new Date())
+
+  if (!hasStandards(resolved)) {
+    logWarn(
+      `Rules reference .claude/standards/. Run 'aitk standards install ${target}' or 'aitk init' so the references resolve.`,
+    )
+  }
+
+  outro()
+  process.stderr.write(`${GREEN}✓ Rules installed${NC}\n`)
+  return 0
+}
+
+/**
+ * Emits the rules payload the `gov-*` skills read. The output lands in the
+ * target's scratch directory rather than stdout because the file is the
+ * contract, and the skills point at the path.
+ */
+async function runBuild(target: string): Promise<number> {
+  intro('aitk gov build')
+
+  const resolved = resolve(target)
+  const rulesDir = join(resolved, RULES_REL)
+
+  if (!existsSync(rulesDir)) {
+    logError(`No rules found at ${rulesDir}. Run \`aitk gov install\` first.`)
+    outro()
+    return 1
+  }
+
+  const files = listRuleFiles(rulesDir)
+  logStep(`Reading ${RULES_REL} (${files.length} found)`)
+  for (const file of files) {
+    logInfo(basename(file))
+  }
+
+  const shouldBuild = await select({
+    message: `Build ${files.length} rules to ${PAYLOAD_REL}?`,
+    options: [
+      { value: true, label: 'Yes' },
+      { value: false, label: 'No' },
+    ],
+    nonInteractiveDefault: true,
+  })
+
+  if (!shouldBuild) {
+    logWarn('Cancelled')
+    outro()
+    return 0
+  }
+
+  logStep('Building rules payload')
+  const output = join(resolved, PAYLOAD_REL)
+  await mkdir(dirname(output), { recursive: true })
+  await writeFile(output, buildRulesPayload(files))
+  logAdd(PAYLOAD_REL)
+
+  outro()
+  process.stderr.write(
+    `${GREEN}✓ Rules built (${files.length} rules → ${PAYLOAD_REL})${NC}\n`,
+  )
+  return 0
+}

package/src/commands/indexes.ts

@@ -0,0 +1,182 @@
+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 { 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:',
+        '  aitk indexes regen',
+        '  aitk indexes regen --dry-run',
+        '  aitk 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('aitk 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}`
+    .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,117 @@
+import type { Command } from 'commander'
+import { cliPath, cliRun } from '@/cli-run'
+import { PROJECT_ROOT } from '@/exec'
+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, select } from '@/ui'
+
+const GREEN = '\x1b[0;32m'
+const YELLOW = '\x1b[0;33m'
+const NC = '\x1b[0m'
+
+interface InitOptions {
+  /** Always present: the option falls back to `DEFAULT_STACK`. */
+  readonly stack: string
+  readonly add?: string
+  readonly snippets: 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:',
+        '  aitk init',
+        '  aitk init ../my-app',
+        '  aitk init --stack astro --add 260-shadcn ../my-app',
+        '  aitk 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('aitk 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,
+    snippets: options.snippets,
+    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')
+
+  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/pass-through.ts

@@ -0,0 +1,39 @@
+import type { Command } from 'commander'
+import { execScript } from '@/exec'
+import { intro } from '@/ui'
+
+/**
+ * Registers the verbs a domain has not migrated yet, each forwarding to
+ * `scripts/<domain>/<verb>.sh`. Naming them instead of catching everything on
+ * the parent gives each verb its own `--help` and lets a migrated sibling sit
+ * alongside them.
+ */
+export function registerPassThroughVerbs(
+  parent: Command,
+  domain: string,
+  verbs: readonly string[],
+): void {
+  for (const verb of verbs) {
+    parent
+      .command(verb)
+      .description(`Run the ${domain} ${verb} command`)
+      .allowUnknownOption()
+      .allowExcessArguments(true)
+      .passThroughOptions()
+      .helpOption(false)
+      .action(async (_opts: unknown, cmd: Command) => {
+        if (!isHelpRequest(cmd.args)) intro(`aitk ${domain}`)
+        await execScript(`${domain}/${verb}.sh`, cmd.args)
+      })
+  }
+}
+
+/**
+ * Commander resolves `--help` before an action runs, so a pass-through verb
+ * that keeps the built-in help option prints a one-line stub instead of the
+ * script's usage. Disabling it lets the flag reach the script, which owns the
+ * real flag surface, and this guard keeps the frame from opening around it.
+ */
+function isHelpRequest(args: readonly string[]): boolean {
+  return args.includes('-h') || args.includes('--help')
+}