@erclx/aitk 0.8.0

package/src/commands/tooling.ts

@@ -0,0 +1,432 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { execScript, PROJECT_ROOT } from '@/exec'
+import {
+  applyReferences,
+  injectConfigs,
+  injectGitignore,
+  injectManifest,
+  injectSeeds,
+  pruneGitignore,
+} from '@/tooling/inject'
+import { buildStackSummaries, describeStack } from '@/tooling/list'
+import {
+  isStackExcluded,
+  listStacks,
+  type Manifest,
+  resolveChain,
+  stackExists,
+} from '@/tooling/manifest'
+import { scan, type ScanResult } from '@/tooling/scan'
+import { intro, logAdd, logInfo, logStep, logWarn, outro, select } from '@/ui'
+
+const GREEN = '\x1b[0;32m'
+const NC = '\x1b[0m'
+
+const PASS_THROUGH_VERBS = ['ref', 'create', 'verify'] as const
+
+interface SyncOptions {
+  readonly ref?: boolean
+  readonly skip?: string
+}
+
+interface InjectOptions {
+  readonly configs?: boolean
+  readonly seeds?: boolean
+  readonly manifest?: boolean
+  readonly gitignore?: boolean
+  readonly nested?: boolean
+}
+
+interface PruneOptions {
+  readonly nested?: boolean
+}
+
+interface ListOptions {
+  readonly json?: boolean
+}
+
+type Prepared =
+  | { readonly ok: true; readonly chain: Manifest[]; readonly target: string }
+  | { readonly ok: false; readonly error: string }
+
+export function register(program: Command): void {
+  const tooling = program
+    .command('tooling')
+    .description('Manage tooling stacks (sync, ref, create)')
+    .helpOption('-h, --help', 'Show this help message')
+
+  tooling
+    .command('sync')
+    .description('Sync configs, seeds, deps, scripts, and gitignore entries')
+    .argument('[stack]', 'Tooling stack name (e.g. base, vite-react)')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--no-ref', 'Skip dropping reference docs')
+    .option('--skip <stack>', 'Drop a layer from the extends chain')
+    .action(
+      async (stack: string | undefined, target: string, opts: SyncOptions) => {
+        process.exitCode = await runSync(stack, target, opts)
+      },
+    )
+
+  tooling
+    .command('inject')
+    .description('Apply one stack to a target without scanning or prompting')
+    .argument('<stack>', 'Tooling stack name')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--configs', 'Copy stack configs')
+    .option('--seeds', 'Merge stack seeds')
+    .option('--manifest', 'Install deps, apply scripts, merge gitignore')
+    .option('--gitignore', 'Merge gitignore entries only')
+    .option('--nested', 'Suppress the frame when a caller already opened one')
+    .action(async (stack: string, target: string, opts: InjectOptions) => {
+      process.exitCode = await runInject(stack, target, opts)
+    })
+
+  tooling
+    .command('prune-gitignore')
+    .description('Remove managed gitignore entries no longer in the manifest')
+    .argument('<stack>', 'Tooling stack name')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--nested', 'Suppress the frame when a caller already opened one')
+    .action(async (stack: string, target: string, opts: PruneOptions) => {
+      process.exitCode = await runPrune(stack, target, opts)
+    })
+
+  tooling
+    .command('list')
+    .description('List installable tooling stacks')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit machine-readable JSON')
+    .action((opts: ListOptions) => {
+      process.exitCode = runList(opts)
+    })
+
+  for (const verb of PASS_THROUGH_VERBS) {
+    tooling
+      .command(verb)
+      .description(`Run the tooling ${verb} command`)
+      .allowUnknownOption()
+      .allowExcessArguments(true)
+      .passThroughOptions()
+      .helpOption(false)
+      .action(async (_opts: unknown, cmd: Command) => {
+        await execScript(`tooling/${verb}.sh`, cmd.args)
+      })
+  }
+}
+
+/**
+ * `JSON.stringify` replaces a `printf` that interpolated manifest fields into a
+ * JSON string literal unescaped, so a stack name or description carrying a
+ * quote emitted output a consuming skill could not parse.
+ *
+ * The frame opens after the `--json` return. The bash emitted a closing `└`
+ * from its EXIT trap with no `┌` above it, because the hand-rolled
+ * pass-through loop below skips the `intro` the shared helper carries.
+ */
+function runList(opts: ListOptions): number {
+  const stacks = buildStackSummaries(PROJECT_ROOT)
+
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({ stacks })}\n`)
+    return 0
+  }
+
+  intro('aitk tooling list')
+  logStep('Stacks')
+  for (const summary of stacks) logInfo(describeStack(summary))
+  outro()
+  return 0
+}
+
+/**
+ * Resolves the chain and rejects the same inputs the bash rejected, so a bad
+ * stack name fails before anything touches the target.
+ *
+ * The excluded-stack guard is deliberately not here. It lived in the sync
+ * entry point, so `aitk claude` can still drive injection for the `claude`
+ * stack the way it drove `merge_gitignore` before.
+ */
+function prepare(stack: string, target: string, skip?: string): Prepared {
+  if (!stackExists(PROJECT_ROOT, stack)) {
+    return { ok: false, error: `Stack not found: ${stack}` }
+  }
+
+  if (skip !== undefined) {
+    if (skip === stack) {
+      return {
+        ok: false,
+        error: `Cannot --skip the stack being synced: ${skip}`,
+      }
+    }
+    if (!stackExists(PROJECT_ROOT, skip)) {
+      return { ok: false, error: `Stack to skip not found: ${skip}` }
+    }
+  }
+
+  const resolved = resolve(target)
+  if (resolved === PROJECT_ROOT) {
+    return {
+      ok: false,
+      error:
+        'Cannot run against toolkit root. Files here are the source of truth.',
+    }
+  }
+
+  return {
+    ok: true,
+    chain: resolveChain(PROJECT_ROOT, stack, { skipStack: skip }),
+    target: resolved,
+  }
+}
+
+async function runSync(
+  stack: string | undefined,
+  target: string,
+  opts: SyncOptions,
+): Promise<number> {
+  intro('aitk tooling sync')
+
+  const selected = stack ?? (await promptForStack())
+  if (selected === undefined) {
+    logWarn('No tooling stacks found')
+    outro()
+    return 1
+  }
+
+  if (isStackExcluded(selected)) {
+    logWarn(
+      'Claude is managed by `aitk claude`, not `aitk tooling`. Run `aitk claude sync` instead.',
+    )
+    outro()
+    return 1
+  }
+
+  const prepared = prepare(selected, target, opts.skip)
+  if (!prepared.ok) {
+    logWarn(prepared.error)
+    outro()
+    return 1
+  }
+
+  const includeReferences = opts.ref !== false
+  const result = scan(prepared.chain, prepared.target, { includeReferences })
+
+  report(result, includeReferences)
+
+  if (result.totalChanges === 0) {
+    outro()
+    process.stderr.write(`${GREEN}✓ Everything up to date${NC}\n`)
+    return 0
+  }
+
+  const shouldApply = await select({
+    message: `Apply ${result.totalChanges} changes (${summarize(result)})?`,
+    options: [
+      { value: true, label: 'Apply all' },
+      { value: false, label: 'Cancel' },
+    ],
+    nonInteractiveDefault: true,
+  })
+
+  if (!shouldApply) {
+    logWarn('Sync cancelled')
+    outro()
+    return 0
+  }
+
+  if (result.configs.some((entry) => entry.state !== 'matching')) {
+    await injectConfigs(prepared.chain, prepared.target)
+  }
+
+  await injectSeeds(prepared.chain, prepared.target)
+  await injectManifest(prepared.chain, prepared.target)
+
+  const pending = result.references
+    .filter((entry) => entry.state === 'pending')
+    .map((entry) => entry.stack)
+
+  if (pending.length > 0) {
+    logStep('Applying references')
+    await applyReferences(prepared.chain, prepared.target, pending)
+  }
+
+  outro()
+  process.stderr.write(`${GREEN}✓ Tooling sync complete${NC}\n`)
+  return 0
+}
+
+async function runInject(
+  stack: string,
+  target: string,
+  opts: InjectOptions,
+): Promise<number> {
+  const framed = opts.nested !== true
+  if (framed) intro('aitk tooling inject')
+
+  const prepared = prepare(stack, target)
+  if (!prepared.ok) {
+    logWarn(prepared.error)
+    if (framed) outro()
+    return 1
+  }
+
+  const applyAll =
+    !opts.configs && !opts.seeds && !opts.manifest && !opts.gitignore
+
+  if (opts.configs || applyAll) {
+    await injectConfigs(prepared.chain, prepared.target)
+  }
+  if (opts.seeds || applyAll) {
+    await injectSeeds(prepared.chain, prepared.target)
+  }
+  if (opts.manifest || applyAll) {
+    await injectManifest(prepared.chain, prepared.target)
+  } else if (opts.gitignore) {
+    await injectGitignore(prepared.chain, prepared.target)
+  }
+
+  if (framed) outro()
+  return 0
+}
+
+/**
+ * Emits the number of pruned entries on stdout so a caller can branch on it
+ * without parsing the timeline, replacing the bash nameref return.
+ */
+async function runPrune(
+  stack: string,
+  target: string,
+  opts: PruneOptions,
+): Promise<number> {
+  const framed = opts.nested !== true
+  if (framed) intro('aitk tooling prune-gitignore')
+
+  const prepared = prepare(stack, target)
+  if (!prepared.ok) {
+    logWarn(prepared.error)
+    if (framed) outro()
+    return 1
+  }
+
+  const removed = await pruneGitignore(prepared.chain, prepared.target)
+  if (framed) outro()
+
+  process.stdout.write(`${removed.length}\n`)
+  return 0
+}
+
+async function promptForStack(): Promise<string | undefined> {
+  const stacks = listStacks(PROJECT_ROOT)
+  if (stacks.length === 0) return undefined
+
+  return select({
+    message: 'Select tooling stack:',
+    options: stacks.map((name) => ({ value: name, label: name })),
+    nonInteractiveDefault: true,
+  })
+}
+
+function report(result: ScanResult, includeReferences: boolean): void {
+  logStep('Scanning configs')
+  for (const entry of result.configs) {
+    if (entry.state === 'matching') logInfo(entry.rel)
+  }
+  for (const entry of result.configs) {
+    if (entry.state === 'drifted') logWarn(entry.rel)
+  }
+  for (const entry of result.configs) {
+    if (entry.state === 'new') logAdd(entry.rel)
+  }
+
+  logStep('Scanning seeds')
+  for (const entry of result.seeds) {
+    if (entry.state === 'present') logInfo(entry.rel)
+  }
+  for (const entry of result.seeds) {
+    if (entry.state === 'missing') logAdd(entry.rel)
+  }
+
+  if (result.hasPackageJson) {
+    reportPackage(result)
+  } else {
+    logWarn(
+      "Skipped scripts and deps: no package.json found (run 'bun init' to enable)",
+    )
+  }
+
+  logStep('Scanning gitignore')
+  for (const entry of result.gitignore) {
+    if (entry.state === 'present') logInfo(entry.entry)
+  }
+  for (const entry of result.gitignore) {
+    if (entry.state === 'missing') logAdd(entry.entry)
+  }
+
+  if (!includeReferences) return
+
+  logStep('Scanning references')
+  for (const entry of result.references) {
+    if (entry.state === 'matching') logInfo(`.claude/tooling/${entry.stack}.md`)
+  }
+  for (const entry of result.references) {
+    if (entry.state === 'pending') logAdd(`.claude/tooling/${entry.stack}.md`)
+  }
+}
+
+function reportPackage(result: ScanResult): void {
+  if (result.scripts.length > 0) {
+    logStep('Scanning scripts')
+    for (const entry of result.scripts) {
+      if (entry.state === 'matching') logInfo(entry.key)
+    }
+    for (const entry of result.scripts) {
+      if (entry.state === 'drifted') logWarn(entry.key)
+    }
+    for (const entry of result.scripts) {
+      if (entry.state === 'missing') logAdd(entry.key)
+    }
+  }
+
+  if (result.deps.length > 0) {
+    logStep('Scanning dependencies')
+    for (const entry of result.deps) {
+      if (entry.state === 'present') logInfo(entry.name)
+    }
+    for (const entry of result.deps) {
+      if (entry.state === 'missing') logAdd(entry.spec)
+    }
+  }
+}
+
+function summarize(result: ScanResult): string {
+  const parts: string[] = []
+  const add = (count: number, label: string): void => {
+    if (count > 0) parts.push(`${count} ${label}`)
+  }
+
+  add(
+    result.configs.filter((entry) => entry.state !== 'matching').length,
+    'configs',
+  )
+  add(result.seeds.filter((entry) => entry.state === 'missing').length, 'seeds')
+  add(
+    result.scripts.filter((entry) => entry.state !== 'matching').length,
+    'scripts',
+  )
+  add(result.deps.filter((entry) => entry.state === 'missing').length, 'deps')
+  add(
+    result.gitignore.filter((entry) => entry.state === 'missing').length,
+    'gitignore',
+  )
+  add(
+    result.references.filter((entry) => entry.state === 'pending').length,
+    'refs',
+  )
+
+  return parts.join(', ')
+}

package/src/commands/transcripts.ts

@@ -0,0 +1,48 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { ensureYtDlp, fetchOne } from '@/transcripts/fetch'
+
+const GREY = '\x1b[0;90m'
+const WHITE = '\x1b[1;37m'
+const RED = '\x1b[0;31m'
+const GREEN = '\x1b[0;32m'
+const NC = '\x1b[0m'
+
+interface TranscriptOptions {
+  out: string
+  keepTimestamps?: boolean
+}
+
+export function register(program: Command): void {
+  program
+    .command('transcripts <url>')
+    .description('Fetch a YouTube transcript with metadata frontmatter')
+    .option('-o, --out <path>', 'Output directory', 'transcripts')
+    .option(
+      '--keep-timestamps',
+      'Prefix each line with [mm:ss] instead of prose',
+    )
+    .action(async (url: string, opts: TranscriptOptions) => {
+      const outDir = resolve(process.cwd(), opts.out)
+      process.stderr.write(
+        `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}aitk transcripts${NC}\n`,
+      )
+      try {
+        ensureYtDlp()
+        const target = await fetchOne(url, {
+          outDir,
+          keepTimestamps: opts.keepTimestamps ?? false,
+        })
+        process.stdout.write(`${target}\n`)
+        process.stderr.write(
+          `${GREY}│${NC} ${GREEN}✓${NC} ${target}\n${GREY}└${NC}\n`,
+        )
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        process.stderr.write(
+          `${GREY}│${NC} ${RED}✗${NC} ${message}\n${GREY}└${NC}\n`,
+        )
+        process.exit(1)
+      }
+    })
+}

package/src/commands/wiki.ts

@@ -0,0 +1,101 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { PROJECT_ROOT } from '@/exec'
+import {
+  intro,
+  logAdd,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  select,
+} from '@/ui'
+import {
+  applyWikiInit,
+  isWikiTarget,
+  LEGACY_WIKI_DIR_REL,
+  planWikiInit,
+  WIKI_DIR_REL,
+  WIKI_INDEX_REL,
+} from '@/wiki/init'
+
+const GREEN = '\x1b[0;32m'
+const NC = '\x1b[0m'
+
+export function register(program: Command): void {
+  const wiki = program
+    .command('wiki')
+    .description('Wiki commands (init)')
+    .helpOption('-h, --help', 'Show this help message')
+
+  wiki
+    .command('init')
+    .description('Scaffold .claude/wiki/ with a stub index.md')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .action(async (target: string) => {
+      process.exitCode = await runInit(target)
+    })
+}
+
+async function runInit(target: string): Promise<number> {
+  intro('aitk wiki')
+
+  const resolved = resolve(target)
+
+  if (!isWikiTarget(resolved)) {
+    logError(`Target directory not found: ${target}`)
+    outro()
+    return 1
+  }
+
+  if (resolved === PROJECT_ROOT) {
+    logError(
+      'Cannot run against toolkit root. Files here are the source of truth.',
+    )
+    outro()
+    return 1
+  }
+
+  const plan = planWikiInit(resolved)
+
+  logStep(`Scanning ${WIKI_DIR_REL}`)
+  if (plan.changes.includes('dir')) logAdd(WIKI_DIR_REL)
+  if (plan.hasIndex) logInfo(WIKI_INDEX_REL)
+  else logAdd(WIKI_INDEX_REL)
+
+  if (plan.hasLegacyWiki) {
+    logWarn(`${LEGACY_WIKI_DIR_REL} found at the target root, not migrated`)
+  }
+
+  const count = plan.changes.length
+  if (count === 0) {
+    outro()
+    process.stderr.write(`${GREEN}✓ Wiki already initialized${NC}\n`)
+    return 0
+  }
+
+  const shouldApply = await select({
+    message: `Apply ${count} change(s)?`,
+    options: [
+      { value: true, label: 'Apply all' },
+      { value: false, label: 'Cancel' },
+    ],
+    nonInteractiveDefault: true,
+  })
+
+  if (!shouldApply) {
+    logWarn('Cancelled')
+    outro()
+    return 0
+  }
+
+  logStep('Applying changes')
+  await applyWikiInit(resolved, plan)
+  if (plan.changes.includes('index')) logAdd(WIKI_INDEX_REL)
+
+  outro()
+  process.stderr.write(`${GREEN}✓ Wiki ready${NC}\n`)
+  return 0
+}

package/src/copy.ts

@@ -0,0 +1,30 @@
+import { chmod, copyFile, mkdir, stat } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+/**
+ * Copies with `cp` semantics. Two behaviors matter and neither is the default
+ * in the obvious alternatives. `Bun.write` drops the executable bit, which
+ * would land husky hooks and `scripts/verify.sh` non-executable. Plain
+ * `copyFile` imposes the source mode on an existing destination, so a file the
+ * target deliberately restricted to 600, or an earlier stack set executable,
+ * comes back at the source's mode. `cp` leaves an existing destination's mode
+ * alone.
+ *
+ * Every domain that writes into a target routes through here. The tooling
+ * inject path found the trap first, and the sync engine inherits it for every
+ * adapter.
+ */
+export async function copyPreservingMode(
+  src: string,
+  dest: string,
+): Promise<void> {
+  await mkdir(dirname(dest), { recursive: true })
+
+  const existingMode = await stat(dest)
+    .then((info) => info.mode)
+    .catch(() => undefined)
+
+  await copyFile(src, dest)
+
+  if (existingMode !== undefined) await chmod(dest, existingMode)
+}

package/src/design/parse.ts

@@ -0,0 +1,79 @@
+import { readFileSync } from 'node:fs'
+
+export type Row = Record<string, string>
+
+export interface DesignDoc {
+  personality: string
+  color: Row[]
+  typography: Row[]
+  spacing: Row[]
+  borders: Row[]
+  motion: string
+  iconography: string
+}
+
+export function parseDesignDoc(path: string): DesignDoc {
+  const raw = readFileSync(path, 'utf8')
+  const sections = splitSections(raw)
+  return {
+    personality: prose(sections['Personality']),
+    color: table(sections['Color']),
+    typography: table(sections['Typography']),
+    spacing: table(sections['Spacing']),
+    borders: table(sections['Borders']),
+    motion: prose(sections['Motion']),
+    iconography: prose(sections['Iconography']),
+  }
+}
+
+function splitSections(raw: string): Record<string, string> {
+  const out: Record<string, string> = {}
+  const lines = raw.split('\n')
+  let current: string | null = null
+  let buffer: string[] = []
+  for (const line of lines) {
+    const match = line.match(/^##\s+(.+?)\s*$/)
+    if (match) {
+      if (current) out[current] = buffer.join('\n')
+      current = match[1]
+      buffer = []
+    } else if (current) {
+      buffer.push(line)
+    }
+  }
+  if (current) out[current] = buffer.join('\n')
+  return out
+}
+
+function prose(body: string | undefined): string {
+  if (!body) return ''
+  return body
+    .split('\n')
+    .filter((l) => l.trim() && !l.startsWith('|') && !l.startsWith('<'))
+    .join('\n')
+    .trim()
+}
+
+function table(body: string | undefined): Row[] {
+  if (!body) return []
+  const rows = body.split('\n').filter((l) => l.trim().startsWith('|'))
+  if (rows.length < 2) return []
+  const headers = splitRow(rows[0])
+  const data = rows.slice(2)
+  return data.map((line) => {
+    const cells = splitRow(line)
+    const row: Row = {}
+    headers.forEach((h, i) => {
+      row[h] = (cells[i] ?? '').trim()
+    })
+    return row
+  })
+}
+
+function splitRow(line: string): string[] {
+  return line
+    .replace(/^\s*\|/, '')
+    .replace(/\|\s*$/, '')
+    .split('|')
+    .map((c) => c.trim().replace(/\s*\?\s*verify\s*$/, ''))
+}