@erclx/aitk 0.8.0

package/src/indexes/regen.ts

@@ -0,0 +1,84 @@
+import { existsSync } from 'node:fs'
+import { readField, readFrontmatter } from '@/indexes/frontmatter'
+import { computeIndex } from '@/indexes/render'
+import { INDEX_FILE } from '@/indexes/walk'
+
+export const REGEN_ACTIONS = [
+  'written',
+  'would-write',
+  'unchanged',
+  'skipped',
+  'error',
+] as const
+
+export type RegenAction = (typeof REGEN_ACTIONS)[number]
+
+export interface RegenResult {
+  readonly path: string
+  readonly action: RegenAction
+  readonly reason?: string
+  readonly errors?: string[]
+}
+
+export interface RegenOptions {
+  readonly dryRun: boolean
+}
+
+/**
+ * Regenerates one folder's index and reports what happened.
+ *
+ * A folder marked `auto: false` is skipped rather than errored, which is how
+ * hand-maintained catalogs opt out of the walker.
+ */
+export async function regenOne(
+  dir: string,
+  options: RegenOptions,
+): Promise<RegenResult> {
+  const path = `${dir}/${INDEX_FILE}`
+
+  if (!existsSync(path)) {
+    return { path, action: 'error', reason: 'no index.md' }
+  }
+
+  const auto = readField(await readFrontmatter(path), 'auto')
+  if (auto === 'false') {
+    return { path, action: 'skipped', reason: 'auto:false' }
+  }
+
+  const rendered = await computeIndex(dir)
+  if (!rendered.ok) {
+    return {
+      path,
+      action: 'error',
+      reason: 'frontmatter',
+      errors: rendered.errors,
+    }
+  }
+
+  if (rendered.content === (await Bun.file(path).text())) {
+    return { path, action: 'unchanged' }
+  }
+
+  if (options.dryRun) {
+    return { path, action: 'would-write' }
+  }
+
+  await Bun.write(path, rendered.content)
+  return { path, action: 'written' }
+}
+
+/**
+ * Maps a run's results onto the documented exit codes: 0 clean, 1 error,
+ * 2 drift found under `--dry-run`. Skills branch on the JSON instead, but the
+ * codes are load-bearing for `bun run check`.
+ */
+export function exitCodeFor(
+  results: readonly RegenResult[],
+  options: RegenOptions,
+): 0 | 1 | 2 {
+  if (results.some((result) => result.action === 'error')) return 1
+  if (options.dryRun && results.some((r) => r.action === 'would-write')) {
+    return 2
+  }
+  return 0
+}

package/src/indexes/render.ts

@@ -0,0 +1,181 @@
+import { basename, dirname, resolve } from 'node:path'
+import { readField, readFrontmatter } from '@/indexes/frontmatter'
+import { INDEX_FILE, listIndexes } from '@/indexes/walk'
+
+export interface IndexEntry {
+  readonly name: string
+  readonly title: string
+  readonly description: string
+  readonly category?: string
+}
+
+export interface SubCatalog {
+  readonly name: string
+  readonly title: string
+  readonly subtitle: string
+}
+
+export type RenderResult =
+  | { readonly ok: true; readonly content: string }
+  | { readonly ok: false; readonly errors: string[] }
+
+interface IndexHead {
+  readonly raw: string
+  readonly title: string
+  readonly subtitle: string
+}
+
+/**
+ * Builds a folder's `index.md` from its own frontmatter plus every sibling's.
+ *
+ * Frontmatter is re-emitted verbatim rather than re-serialized, so key order
+ * and any `auto: false` marker survive a regeneration untouched.
+ */
+export async function computeIndex(dir: string): Promise<RenderResult> {
+  const indexPath = `${dir}/${INDEX_FILE}`
+  const head = await readIndexHead(indexPath)
+  if (!head.ok) return head
+
+  const entries = await collectEntries(dir)
+  if (!entries.ok) return entries
+
+  const subCatalogs = await collectSubCatalogs(dir)
+
+  return {
+    ok: true,
+    content: renderIndex(head.head, entries.entries, subCatalogs),
+  }
+}
+
+async function readIndexHead(
+  indexPath: string,
+): Promise<{ ok: true; head: IndexHead } | { ok: false; errors: string[] }> {
+  const frontmatter = await readFrontmatter(indexPath)
+  const title = readField(frontmatter, 'title')
+  const subtitle = readField(frontmatter, 'subtitle')
+
+  const errors: string[] = []
+  if (!title) errors.push(`missing frontmatter field "title" in ${indexPath}`)
+  if (!subtitle) {
+    errors.push(`missing frontmatter field "subtitle" in ${indexPath}`)
+  }
+  if (!frontmatter || !title || !subtitle) return { ok: false, errors }
+
+  return { ok: true, head: { raw: frontmatter.raw, title, subtitle } }
+}
+
+async function collectEntries(
+  dir: string,
+): Promise<
+  { ok: true; entries: IndexEntry[] } | { ok: false; errors: string[] }
+> {
+  const glob = new Bun.Glob('*.md')
+  const paths: string[] = []
+
+  for await (const rel of glob.scan({ cwd: dir, onlyFiles: true, dot: true })) {
+    if (rel === INDEX_FILE) continue
+    paths.push(resolve(dir, rel))
+  }
+  paths.sort()
+
+  const entries: IndexEntry[] = []
+  const errors: string[] = []
+
+  for (const path of paths) {
+    const frontmatter = await readFrontmatter(path)
+    const title = readField(frontmatter, 'title')
+    const description = readField(frontmatter, 'description')
+
+    if (!title) errors.push(`missing frontmatter field "title" in ${path}`)
+    if (!description) {
+      errors.push(`missing frontmatter field "description" in ${path}`)
+    }
+    if (!title || !description) continue
+
+    entries.push({
+      name: basename(path),
+      title,
+      description,
+      category: readField(frontmatter, 'category'),
+    })
+  }
+
+  if (errors.length > 0) {
+    errors.push(`${errors.length} missing frontmatter field(s) in ${dir}`)
+    return { ok: false, errors }
+  }
+
+  return { ok: true, entries }
+}
+
+/**
+ * Reuses the shared walker so nested discovery inherits the same prune and
+ * gitignore rules, then keeps only direct children of this folder.
+ */
+async function collectSubCatalogs(dir: string): Promise<SubCatalog[]> {
+  const nested = await listIndexes(dir)
+  const catalogs: SubCatalog[] = []
+
+  for (const indexPath of nested.sort()) {
+    const childDir = dirname(indexPath)
+    if (dirname(childDir) !== resolve(dir)) continue
+
+    const frontmatter = await readFrontmatter(indexPath)
+    const title = readField(frontmatter, 'title')
+    const subtitle = readField(frontmatter, 'subtitle')
+
+    if (!title || !subtitle) {
+      process.stderr.write(
+        `WARNING: skipping nested index ${childDir}/${INDEX_FILE} (missing title or subtitle)\n`,
+      )
+      continue
+    }
+
+    catalogs.push({ name: basename(childDir), title, subtitle })
+  }
+
+  return catalogs
+}
+
+function renderIndex(
+  head: IndexHead,
+  entries: IndexEntry[],
+  subCatalogs: SubCatalog[],
+): string {
+  const hasCategories = entries.some((entry) => Boolean(entry.category))
+
+  let out = `${head.raw}\n\n# ${head.title}\n\n${head.subtitle}\n`
+  if (entries.length > 0 || subCatalogs.length > 0) out += '\n'
+
+  if (hasCategories) {
+    const categories = [
+      ...new Set(entries.map((entry) => entry.category).filter(Boolean)),
+    ].sort() as string[]
+
+    categories.forEach((category, position) => {
+      if (position > 0) out += '\n'
+      out += `## ${category}\n\n`
+      for (const entry of entries) {
+        if (entry.category !== category) continue
+        out += formatEntry(entry)
+      }
+    })
+  } else {
+    for (const entry of entries) {
+      out += formatEntry(entry)
+    }
+  }
+
+  if (subCatalogs.length > 0) {
+    if (hasCategories) out += '\n## Sub-catalogs\n\n'
+    for (const catalog of subCatalogs) {
+      out += `- [${catalog.title}](${catalog.name}/${INDEX_FILE}): ${catalog.subtitle}\n`
+    }
+  }
+
+  return out
+}
+
+function formatEntry(entry: IndexEntry): string {
+  return `- [${entry.title}](${entry.name}): ${entry.description}\n`
+}

package/src/indexes/walk.ts

@@ -0,0 +1,111 @@
+import { existsSync, statSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { $ } from 'bun'
+
+const INDEX_FILE = 'index.md'
+
+const PRUNED_SEGMENTS = ['node_modules', '.git']
+
+function isPruned(relativePath: string): boolean {
+  return relativePath
+    .split('/')
+    .some((segment) => PRUNED_SEGMENTS.includes(segment))
+}
+
+/**
+ * Lists every folder index under `root`.
+ *
+ * Vendored and git trees are pruned by path segment, since `Bun.Glob` has no
+ * exclude. Everything else is dropped via `git check-ignore`, so a project's
+ * own `.gitignore` governs what the walker sees. Outside a git repo the
+ * segment prune is the only filter that applies.
+ */
+export async function listIndexes(root: string): Promise<string[]> {
+  const glob = new Bun.Glob(`**/${INDEX_FILE}`)
+  const candidates: string[] = []
+
+  for await (const rel of glob.scan({
+    cwd: root,
+    onlyFiles: true,
+    dot: true,
+  })) {
+    if (isPruned(rel)) continue
+    candidates.push(resolve(root, rel))
+  }
+  candidates.sort()
+
+  if (candidates.length === 0) return []
+
+  const ignored = await listIgnored(root, candidates)
+  if (ignored.size === 0) return candidates
+
+  return candidates.filter((path) => !ignored.has(path))
+}
+
+async function listIgnored(
+  root: string,
+  candidates: string[],
+): Promise<Set<string>> {
+  const isRepo = await $`git -C ${root} rev-parse --git-dir`
+    .quiet()
+    .nothrow()
+    .then((result) => result.exitCode === 0)
+
+  if (!isRepo) return new Set()
+
+  const stdin = Buffer.from(`${candidates.join('\n')}\n`)
+
+  const result = await $`git -C ${root} check-ignore --stdin < ${stdin}`
+    .quiet()
+    .nothrow()
+
+  if (result.exitCode > 1) return new Set()
+
+  return new Set(
+    result
+      .text()
+      .split('\n')
+      .filter(Boolean)
+      .map((path) => resolve(root, path)),
+  )
+}
+
+/**
+ * Reports whether git ignores `path`.
+ *
+ * Positional regen reaches an ignored folder, because `findIndexedAncestor`
+ * walks the filesystem and never consults git. Staging what it writes there
+ * always fails, so the caller checks this first and skips the attempt rather
+ * than warning on a no-op.
+ */
+export async function isIgnored(root: string, path: string): Promise<boolean> {
+  const ignored = await listIgnored(root, [resolve(path)])
+  return ignored.has(resolve(path))
+}
+
+/**
+ * Walks up from `path` to the nearest folder holding an index, stopping at
+ * `root`. Returns undefined when the path escapes the boundary or nothing
+ * indexed is found.
+ */
+export function findIndexedAncestor(
+  path: string,
+  root: string,
+): string | undefined {
+  if (!existsSync(path)) return undefined
+
+  const rootAbs = resolve(root)
+  let dir = statSync(path).isDirectory()
+    ? resolve(path)
+    : dirname(resolve(path))
+
+  while (dir === rootAbs || dir.startsWith(`${rootAbs}/`)) {
+    if (existsSync(`${dir}/${INDEX_FILE}`)) return dir
+    if (dir === rootAbs) return undefined
+    dir = dirname(dir)
+  }
+
+  return undefined
+}
+
+export { INDEX_FILE, PRUNED_SEGMENTS }

package/src/init/flags.ts

@@ -0,0 +1,66 @@
+import type { Command } from 'commander'
+import { DEFAULT_STACK, SKIPPABLE_DOMAINS } from '@/init/plan'
+
+interface InitOptionSpec {
+  /** The option value key commander stores the parsed value under. */
+  readonly key: string
+  readonly flags: string
+  readonly description: string
+  readonly defaultValue?: string
+}
+
+/**
+ * The option surface of `aitk init`, declared once so the flag list and the
+ * provenance check cannot drift apart. Reading the key from the spec is what
+ * keeps a renamed flag from silently dropping out of `flagsProvided`.
+ */
+export const INIT_OPTIONS: readonly InitOptionSpec[] = [
+  {
+    key: 'stack',
+    flags: '--stack <name>',
+    description: 'Governance stack (e.g., base, astro, react)',
+    defaultValue: DEFAULT_STACK,
+  },
+  {
+    key: 'add',
+    flags: '--add <rules>',
+    description: 'Comma-separated governance rules to layer on',
+  },
+  {
+    key: 'snippets',
+    flags: '--snippets <category>',
+    description: "Snippets preset, category, or 'all'",
+    defaultValue: 'essentials',
+  },
+  {
+    key: 'skip',
+    flags: '--skip <list>',
+    description: `Skip core domains: ${SKIPPABLE_DOMAINS.join(', ')}`,
+  },
+]
+
+/** Declares every init option on the command, defaults included. */
+export function applyInitOptions(command: Command): Command {
+  for (const option of INIT_OPTIONS) {
+    if (option.defaultValue === undefined) {
+      command.option(option.flags, option.description)
+      continue
+    }
+
+    command.option(option.flags, option.description, option.defaultValue)
+  }
+
+  return command
+}
+
+/**
+ * Whether the operator passed any flag, which is what makes the command
+ * scriptable by suppressing the confirmation prompt. `--snippets` and `--stack`
+ * both carry defaults, so presence has to be read from where the value came
+ * from rather than from the value itself.
+ */
+export function flagsProvided(cmd: Command): boolean {
+  return INIT_OPTIONS.some(
+    (option) => cmd.getOptionValueSource(option.key) === 'cli',
+  )
+}

package/src/init/plan.ts

@@ -0,0 +1,128 @@
+export const SKIPPABLE_DOMAINS = ['wiki', 'standards', 'governance'] as const
+
+export type SkippableDomain = (typeof SKIPPABLE_DOMAINS)[number]
+
+/**
+ * The stack a caller gets without asking. Governance installs on every init so
+ * the standards that install alongside it arrive with the rules that route to
+ * them, and `--skip governance` is the one spelling for declining.
+ */
+export const DEFAULT_STACK = 'base'
+
+export interface SkipPlan {
+  readonly skipped: ReadonlySet<SkippableDomain>
+  /** Values that named nothing skippable. Warned about, never fatal. */
+  readonly unknown: readonly string[]
+}
+
+export type PreviewLevel = 'info' | 'warn'
+
+export interface PreviewLine {
+  readonly level: PreviewLevel
+  readonly text: string
+}
+
+export interface InitPlan {
+  readonly preview: readonly PreviewLine[]
+  readonly total: number
+}
+
+export interface InitFlags {
+  readonly stack?: string
+  readonly add?: string
+  readonly snippets: string
+  readonly skip: SkipPlan
+}
+
+/**
+ * Resolves the stack the run will install. An empty `--stack` reads as absent
+ * rather than as a way to decline, so the flag carries a real name or nothing
+ * and `--skip governance` stays the only spelling for opting out.
+ */
+export function resolveStack(stack: string | undefined): string {
+  return stack === undefined || stack === '' ? DEFAULT_STACK : stack
+}
+
+/**
+ * Reads the `--skip` list. An unrecognized value is reported and dropped rather
+ * than aborting, because the flag names optional domains and a typo should not
+ * cost the operator the whole init.
+ */
+export function parseSkip(csv: string | undefined): SkipPlan {
+  const skipped = new Set<SkippableDomain>()
+  const unknown: string[] = []
+
+  for (const raw of (csv ?? '').split(',')) {
+    const item = raw.trim()
+    if (item === '') continue
+
+    if (isSkippable(item)) skipped.add(item)
+    else unknown.push(item)
+  }
+
+  return { skipped, unknown }
+}
+
+/**
+ * Builds the preview and the count from one pass, so the two cannot disagree.
+ * Every `info` line is a domain that will run, which is what makes the count a
+ * filter rather than a second tally kept in step by hand. A skipped domain
+ * prints nothing at all and declined governance prints a warning, so neither
+ * reaches the total.
+ *
+ * Governance is the one skip that costs another domain something, so its
+ * warning names the consequence rather than only the action. Declining
+ * standards too removes that consequence, and the warning drops it.
+ *
+ * The skip also drops `--add`, which names rules the caller asked for. Input
+ * that goes nowhere is reported for the same reason `parseSkip` reports an
+ * unrecognized value, so the warning names the flag rather than dropping it
+ * without a word.
+ */
+export function planInit(flags: InitFlags): InitPlan {
+  const preview: PreviewLine[] = [
+    { level: 'info', text: 'base tooling (configs, seeds, deps, scripts)' },
+    { level: 'info', text: 'claude (workflow docs, settings)' },
+  ]
+
+  const stack = resolveStack(flags.stack)
+
+  if (flags.skip.skipped.has('governance')) {
+    const notes: string[] = []
+    if (flags.add !== undefined && flags.add !== '')
+      notes.push(`--add ${flags.add} not installed`)
+    if (!flags.skip.skipped.has('standards'))
+      notes.push('standards land without the rules that route to them')
+
+    const detail = notes.length === 0 ? '' : `, ${notes.join(', ')}`
+    preview.push({ level: 'warn', text: `governance (skipped${detail})` })
+  } else if (flags.add === undefined || flags.add === '') {
+    preview.push({ level: 'info', text: `governance (stack: ${stack})` })
+  } else {
+    preview.push({
+      level: 'info',
+      text: `governance (stack: ${stack}, extras: ${flags.add})`,
+    })
+  }
+
+  if (!flags.skip.skipped.has('standards')) {
+    preview.push({ level: 'info', text: 'standards (authoring conventions)' })
+  }
+
+  preview.push({ level: 'info', text: `snippets (${flags.snippets})` })
+
+  if (!flags.skip.skipped.has('wiki')) {
+    preview.push({
+      level: 'info',
+      text: 'wiki (.claude/wiki/ with a stub index)',
+    })
+  }
+
+  const total = preview.filter((line) => line.level === 'info').length
+
+  return { preview, total }
+}
+
+function isSkippable(value: string): value is SkippableDomain {
+  return (SKIPPABLE_DOMAINS as readonly string[]).includes(value)
+}

package/src/init/run.ts

@@ -0,0 +1,46 @@
+import { logInfo, logStep, logWarn } from '@/ui'
+
+/**
+ * A domain either runs or announces why it did not. Governance under
+ * `--skip governance` is the second kind: it reports in sequence so the
+ * timeline still accounts for every core domain, without counting as a failure.
+ */
+export type DomainStep =
+  | { readonly kind: 'run'; readonly label: string; run(): Promise<boolean> }
+  | { readonly kind: 'skip'; readonly label: string; readonly notice: string }
+
+/**
+ * Runs each step in order and returns the labels that failed.
+ *
+ * Partial failure is a first-class outcome rather than an error path. An init
+ * that aborts on the first failing domain would look tidier and leave the
+ * operator with no idea which of the remaining domains would have worked, so
+ * the run continues and the caller reports the failures at the end.
+ *
+ * The sequence is deliberate. Base tooling seeds the files the later domains
+ * install alongside, so these are not independent operations to batch.
+ */
+export async function runDomains(
+  steps: readonly DomainStep[],
+): Promise<string[]> {
+  const failed: string[] = []
+
+  for (const step of steps) {
+    logStep(step.label)
+
+    if (step.kind === 'skip') {
+      logWarn(step.notice)
+      continue
+    }
+
+    if (await step.run()) {
+      logInfo('Done')
+      continue
+    }
+
+    logWarn('Failed, run manually')
+    failed.push(step.label)
+  }
+
+  return failed
+}

package/src/init/steps.ts

@@ -0,0 +1,91 @@
+import { type InitFlags, resolveStack } from '@/init/plan'
+import type { DomainStep } from '@/init/run'
+
+/** Builds the child-process invocation for one domain. */
+export type RunFactory = (args: readonly string[]) => () => Promise<boolean>
+
+/**
+ * Orders the domains an init installs. Base tooling seeds the files the later
+ * domains install alongside, so the sequence is part of the contract rather
+ * than an arbitrary listing.
+ *
+ * The caller supplies the run factory so the list can be read for its labels
+ * and kinds without spawning anything.
+ */
+export function buildSteps(
+  target: string,
+  resolved: string,
+  flags: InitFlags,
+  child: RunFactory,
+): DomainStep[] {
+  const steps: DomainStep[] = [
+    {
+      kind: 'run',
+      label: 'Base tooling',
+      run: child(['tooling', 'sync', 'base', resolved]),
+    },
+    {
+      kind: 'run',
+      label: 'Claude workflow',
+      run: child(['claude', 'init', resolved]),
+    },
+  ]
+
+  const stack = resolveStack(flags.stack)
+
+  if (flags.skip.skipped.has('governance')) {
+    const recovery = govArgs(stack, flags.add, target).join(' ')
+    steps.push({
+      kind: 'skip',
+      label: 'Governance',
+      notice: `Skipped: --skip governance. Run 'aitk ${recovery}' to install rules.`,
+    })
+  } else {
+    steps.push({
+      kind: 'run',
+      label: 'Governance',
+      run: child(govArgs(stack, flags.add, resolved)),
+    })
+  }
+
+  if (!flags.skip.skipped.has('standards')) {
+    steps.push({
+      kind: 'run',
+      label: 'Standards',
+      run: child(['standards', 'install', resolved]),
+    })
+  }
+
+  steps.push({
+    kind: 'run',
+    label: 'Snippets',
+    run: child(['snippets', 'install', flags.snippets, resolved]),
+  })
+
+  if (!flags.skip.skipped.has('wiki')) {
+    steps.push({
+      kind: 'run',
+      label: 'Wiki',
+      run: child(['wiki', 'init', resolved]),
+    })
+  }
+
+  return steps
+}
+
+/**
+ * Builds the `gov install` argv. The run and the recovery command a skip prints
+ * come from here both, so the command a caller is told to paste installs what
+ * the run would have.
+ */
+function govArgs(
+  stack: string,
+  add: string | undefined,
+  path: string,
+): string[] {
+  const args = ['gov', 'install', stack]
+  if (add !== undefined && add !== '') args.push('--add', add)
+  args.push(path)
+
+  return args
+}