@erclx/aitk 0.8.0

package/src/commands/claude.ts

@@ -0,0 +1,349 @@
+import { existsSync } from 'node:fs'
+import { chmod, readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import type { Command } from 'commander'
+import { claudeChain, pendingEntries, planGitignore } from '@/claude/gitignore'
+import {
+  applySeeds,
+  countByScope,
+  pendingSeeds,
+  planSeeds,
+  type Seed,
+} from '@/claude/seeds'
+import { listSeeds, readSeedContents } from '@/claude/seeds-list'
+import {
+  planSettings,
+  readSettings,
+  serializeSettings,
+  writeSettings,
+} from '@/claude/settings'
+import { copyPreservingMode } from '@/copy'
+import { execScript, PROJECT_ROOT } from '@/exec'
+import { isDirectory, resolveTarget } from '@/target'
+import { injectGitignore, pruneGitignore } from '@/tooling/inject'
+import {
+  intro,
+  isNonInteractive,
+  logAdd,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  select,
+} from '@/ui'
+
+const GREEN = '\x1b[0;32m'
+const GREY = '\x1b[0;90m'
+const NC = '\x1b[0m'
+
+interface SeedsListOptions {
+  readonly json?: boolean
+  readonly names?: boolean
+}
+
+const SEEDED_FILES: readonly string[] = [
+  'ARCHITECTURE.md',
+  'REQUIREMENTS.md',
+  'DESIGN.md',
+]
+const SEEDED_DIRS: readonly string[] = ['tasks', 'wireframes']
+const USER_DIR = join('tooling', 'claude', 'user')
+const STATUSLINE = 'statusline-command.sh'
+
+export function register(program: Command): void {
+  const claude = program
+    .command('claude')
+    .description('Claude workflow (init, seeds, sync, setup)')
+    .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Examples:',
+        '  aitk claude init',
+        '  aitk claude seeds list --json',
+        '  aitk claude sync ../my-app',
+        '',
+      ].join('\n'),
+    )
+
+  claude
+    .command('init')
+    .description('Seed .claude/ workflow docs into a project')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .action(async (target: string) => {
+      process.exitCode = await runInit(target)
+    })
+
+  claude
+    .command('sync')
+    .description('Reconcile .gitignore against the claude manifest')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .action(async (target: string) => {
+      process.exitCode = await runSync(target)
+    })
+
+  claude
+    .command('setup')
+    .description('One-shot user-level config (statusline, attribution)')
+    .argument('[dest]', 'User config directory', join(homedir(), '.claude'))
+    .helpOption('-h, --help', 'Show this help message')
+    .action(async (dest: string) => {
+      process.exitCode = await runSetup(dest)
+    })
+
+  const seeds = claude
+    .command('seeds')
+    .description('Seed doc sources (list)')
+    .argument('[subcommand]', "Only 'list' is supported")
+    .helpOption('-h, --help', 'Show this help message')
+    .action((subcommand: string | undefined) => {
+      intro('aitk claude')
+      logError(
+        subcommand === undefined
+          ? "Missing subcommand. Use 'list'."
+          : `Unknown subcommand: ${subcommand}. Use 'list'.`,
+      )
+      outro()
+      process.exitCode = 1
+    })
+
+  seeds
+    .command('list')
+    .description('List toolkit seed docs as installed by aitk claude init')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit JSON with name, source, target, content')
+    .option('--names', 'Only list target paths, one per line')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Notes:',
+        '  JSON is intended for skills that audit drift in target projects.',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: SeedsListOptions) => {
+      process.exitCode = await runSeedsList(opts)
+    })
+}
+
+function succeed(message: string): number {
+  outro()
+  process.stderr.write(`${GREEN}✓ ${message}${NC}\n`)
+  return 0
+}
+
+async function runInit(target: string): Promise<number> {
+  intro('aitk claude')
+
+  const resolved = resolveTarget(target, PROJECT_ROOT)
+  if (typeof resolved === 'number') return resolved
+
+  logStep('Scanning .claude/')
+  const seedEntries = planSeeds(PROJECT_ROOT, resolved)
+  for (const entry of seedEntries) {
+    if (entry.present) logInfo(entry.seed.scanLabel)
+    else logAdd(entry.seed.scanLabel)
+  }
+  const seeds = pendingSeeds(seedEntries)
+
+  logStep('Scanning .gitignore')
+  const chain = claudeChain(PROJECT_ROOT)
+  const gitignoreEntries = planGitignore(chain, resolved)
+  for (const entry of gitignoreEntries) {
+    if (entry.present) logInfo(entry.entry)
+    else logAdd(entry.entry)
+  }
+  const missing = pendingEntries(gitignoreEntries)
+
+  const total = seeds.length + missing.length
+  if (total === 0) return succeed('Claude already initialized')
+
+  const shouldApply = await select({
+    message: `Apply ${total} change(s) (${summarize(seeds, missing.length)})?`,
+    options: [
+      { value: true, label: 'Apply all' },
+      { value: false, label: 'Cancel' },
+    ],
+    nonInteractiveDefault: true,
+  })
+
+  if (!shouldApply) {
+    logWarn('Cancelled')
+    outro()
+    return 0
+  }
+
+  logStep('Applying changes')
+  for (const label of await applySeeds(seeds)) logAdd(label)
+  if (missing.length > 0) await injectGitignore(chain, resolved)
+
+  return succeed('Claude ready')
+}
+
+function summarize(seeds: readonly Seed[], gitignoreCount: number): string {
+  const counts = countByScope(seeds)
+  const parts: string[] = []
+  if (counts.claude > 0) parts.push(`${counts.claude} .claude`)
+  if (counts.root > 0) parts.push(`${counts.root} CLAUDE.md`)
+  if (gitignoreCount > 0) parts.push(`${gitignoreCount} .gitignore`)
+  return parts.join(', ')
+}
+
+async function runSync(target: string): Promise<number> {
+  intro('aitk claude')
+
+  const resolved = resolveTarget(target, PROJECT_ROOT)
+  if (typeof resolved === 'number') return resolved
+
+  logStep('Seeded')
+  for (const name of SEEDED_FILES) {
+    if (existsSync(join(resolved, '.claude', name))) logInfo(name)
+    else logWarn(`${name} missing. Run \`aitk claude init\``)
+  }
+  for (const name of SEEDED_DIRS) {
+    if (isDirectory(join(resolved, '.claude', name))) logInfo(`${name}/`)
+    else logWarn(`${name}/ missing. Run \`aitk claude init\``)
+  }
+
+  logStep('Scanning .gitignore')
+  const chain = claudeChain(PROJECT_ROOT)
+  const pruned = await pruneGitignore(chain, resolved)
+  const gitignoreEntries = planGitignore(chain, resolved)
+  for (const entry of gitignoreEntries) {
+    if (entry.present) logInfo(entry.entry)
+    else logAdd(entry.entry)
+  }
+  const missing = pendingEntries(gitignoreEntries)
+
+  if (missing.length === 0 && pruned.length === 0) {
+    return succeed('Claude workflow up to date')
+  }
+
+  if (missing.length > 0) {
+    if (isNonInteractive()) {
+      logInfo(`Applying ${missing.length} update(s) (non-interactive)`)
+    } else {
+      const shouldApply = await select({
+        message: `Apply ${missing.length} update(s) (${missing.length} .gitignore)?`,
+        options: [
+          { value: true, label: 'Apply all' },
+          { value: false, label: 'Cancel' },
+        ],
+      })
+
+      if (!shouldApply) {
+        logWarn('Cancelled')
+        outro()
+        return 0
+      }
+    }
+
+    logStep('Applying changes')
+    await injectGitignore(chain, resolved)
+  }
+
+  return succeed('Claude workflow synced')
+}
+
+/**
+ * Writes to the operator's own machine rather than a project, so the
+ * destination is a parameter. That lets a test cover the merge without
+ * pointing it at a real home directory.
+ */
+async function runSetup(dest: string): Promise<number> {
+  intro('aitk claude')
+
+  const resolved = resolve(dest)
+  if (resolved === join(PROJECT_ROOT, '.claude')) {
+    logError(
+      'Cannot run against the toolkit .claude/. Files here are the source of truth.',
+    )
+    outro()
+    return 1
+  }
+
+  const userDir = join(PROJECT_ROOT, USER_DIR)
+  const scriptSrc = join(userDir, STATUSLINE)
+  const scriptDest = join(resolved, STATUSLINE)
+  const settingsPath = join(resolved, 'settings.json')
+
+  logStep('Statusline script')
+  if (await sameContent(scriptSrc, scriptDest)) {
+    logInfo(STATUSLINE)
+  } else {
+    await copyPreservingMode(scriptSrc, scriptDest)
+    await chmod(scriptDest, 0o755)
+    logAdd(STATUSLINE)
+  }
+
+  logStep('Settings')
+  const template = await readSettings(join(userDir, 'settings.template.json'))
+
+  let current: Awaited<ReturnType<typeof readSettings>>
+  try {
+    current = await readSettings(settingsPath)
+  } catch (error) {
+    logError(error instanceof Error ? error.message : String(error))
+    logError('Fix the file by hand, or move it aside and rerun.')
+    outro()
+    return 1
+  }
+
+  const { value, indent } = current
+  const plan = planSettings(value, template.value, `bash ${scriptDest}`)
+
+  for (const key of plan.keys) {
+    if (key.changed) logAdd(key.label)
+    else logInfo(key.label)
+  }
+
+  if (plan.changed) {
+    await writeSettings(settingsPath, serializeSettings(plan.next, indent))
+  }
+
+  return succeed('Claude user config ready')
+}
+
+async function sameContent(src: string, dest: string): Promise<boolean> {
+  if (!existsSync(dest)) return false
+  const [left, right] = await Promise.all([
+    readFile(src, 'utf8'),
+    readFile(dest, 'utf8'),
+  ])
+  return left === right
+}
+
+/**
+ * `--json` and `--names` write to stdout so a skill can pipe them, while the
+ * human listing stays on the timeline. Only the human mode opens a frame.
+ */
+async function runSeedsList(opts: SeedsListOptions): Promise<number> {
+  const listings = listSeeds(PROJECT_ROOT)
+
+  if (opts.json) {
+    const withContent = await readSeedContents(listings)
+    process.stdout.write(`${JSON.stringify(withContent)}\n`)
+    return 0
+  }
+
+  if (opts.names) {
+    process.stdout.write(
+      listings.map((listing) => listing.target).join('\n') + '\n',
+    )
+    return 0
+  }
+
+  intro('aitk claude')
+  logStep('Seed docs')
+  for (const listing of listings) {
+    logInfo(`${listing.target} ${GREY}← ${listing.source}${NC}`)
+  }
+  outro()
+  return 0
+}

package/src/commands/design.ts

@@ -0,0 +1,39 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { renderDesignDoc } from '@/design/render'
+
+const GREY = '\x1b[0;90m'
+const WHITE = '\x1b[1;37m'
+const RED = '\x1b[0;31m'
+const GREEN = '\x1b[0;32m'
+const NC = '\x1b[0m'
+
+export function register(program: Command): void {
+  const design = program
+    .command('design')
+    .description('Design system commands (render)')
+
+  design
+    .command('render')
+    .description('Render DESIGN.md tokens to HTML and CSS preview')
+    .option('-s, --source <path>', 'Source DESIGN.md path', '.claude/DESIGN.md')
+    .option('-o, --out <path>', 'Output directory', '.claude/review/design')
+    .action((opts: { source: string; out: string }) => {
+      const sourcePath = resolve(process.cwd(), opts.source)
+      const outDir = resolve(process.cwd(), opts.out)
+      if (!existsSync(sourcePath)) {
+        process.stderr.write(
+          `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${opts.source} not found\n${GREY}└${NC}\n`,
+        )
+        process.exit(1)
+      }
+      process.stderr.write(
+        `${GREY}┌${NC}\n${GREY}│${NC} ${WHITE}Render design tokens${NC}\n`,
+      )
+      const result = renderDesignDoc(sourcePath, outDir)
+      process.stderr.write(
+        `${GREY}│${NC} ${GREEN}✓${NC} ${result.htmlPath}\n${GREY}│${NC} ${GREEN}✓${NC} ${result.cssPath}\n${GREY}└${NC}\n`,
+      )
+    })
+}

package/src/commands/docs.ts

@@ -0,0 +1,59 @@
+import type { Command } from 'commander'
+import { registerPassThroughVerbs } from '@/commands/pass-through'
+import { listTopics, readTopic, resolveTopic } from '@/docs/read'
+import { execScript, PROJECT_ROOT } from '@/exec'
+import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
+
+export function register(program: Command): void {
+  const docs = program
+    .command('docs')
+    .description('Emit toolkit reference docs (list, <topic>)')
+    .argument('[topic]', 'Doc to print, by exact name')
+    .helpOption('-h, --help', 'Show this help message')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Examples:',
+        '  aitk docs list',
+        '  aitk docs list --json',
+        '  aitk docs agents',
+        '',
+      ].join('\n'),
+    )
+    .action(async (topic: string | undefined) => {
+      if (topic === undefined) {
+        intro('aitk docs')
+        await execScript('docs/list.sh', [])
+        return
+      }
+
+      process.exitCode = get(topic)
+    })
+
+  registerPassThroughVerbs(docs, 'docs', ['list'])
+}
+
+/**
+ * Writes the document body to stdout and every frame line to stderr, so a
+ * caller capturing the output with `$(...)` receives the document alone.
+ */
+function get(topic: string): number {
+  intro('aitk docs')
+
+  const resolved = resolveTopic(PROJECT_ROOT, topic)
+
+  if (!resolved) {
+    logWarn(`Unknown topic: ${topic}`)
+    logStep('Available topics')
+    for (const name of listTopics(PROJECT_ROOT)) logInfo(name)
+    logError("Run 'aitk docs list' for descriptions.")
+    outro()
+    return 1
+  }
+
+  logStep(resolved.rel)
+  process.stdout.write(readTopic(resolved))
+  outro()
+  return 0
+}

package/src/commands/feedback-format.ts

@@ -0,0 +1,23 @@
+const SLUG_FALLBACK = 'general'
+const SLUG_MAX_LENGTH = 40
+const TITLE_MAX_LENGTH = 72
+
+function surfaceField(body: string): string | undefined {
+  return body.match(/\*\*Surface:\*\*\s*([^\n]+)/i)?.[1]?.trim()
+}
+
+export function deriveSlug(body: string): string {
+  const slug = (surfaceField(body) ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, SLUG_MAX_LENGTH)
+    .replace(/-+$/g, '')
+  return slug || SLUG_FALLBACK
+}
+
+export function deriveTitle(body: string): string {
+  const surface = surfaceField(body)
+  const title = surface ? `feedback: ${surface}` : 'toolkit feedback'
+  return title.slice(0, TITLE_MAX_LENGTH)
+}

package/src/commands/feedback.ts

@@ -0,0 +1,103 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { Command } from 'commander'
+import { deriveSlug, deriveTitle } from '@/commands/feedback-format'
+import { PROJECT_ROOT } from '@/exec'
+import { createGithubIssue } from '@/github'
+import { frameError, frameSuccess } from '@/ui'
+
+const YELLOW = '\x1b[0;33m'
+const NC = '\x1b[0m'
+
+function readStdin(): Promise<string> {
+  return new Promise((resolveStream, rejectStream) => {
+    const chunks: Buffer[] = []
+    process.stdin.on('data', (chunk: Buffer) => chunks.push(chunk))
+    process.stdin.on('end', () =>
+      resolveStream(Buffer.concat(chunks).toString('utf8')),
+    )
+    process.stdin.on('error', rejectStream)
+  })
+}
+
+function timestamp(): string {
+  const d = new Date()
+  const pad = (n: number): string => n.toString().padStart(2, '0')
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`
+}
+
+/**
+ * A registry install ships no `.claude/`, so a local write would land inside
+ * `node_modules/` and report a project-relative path the operator cannot find.
+ * The toolkit source is the only root where local scratch reaches a maintainer.
+ */
+function isToolkitSource(): boolean {
+  return existsSync(join(PROJECT_ROOT, '.claude'))
+}
+
+function writeLocal(body: string): string {
+  const reviewDir = join(PROJECT_ROOT, '.claude', 'review')
+  mkdirSync(reviewDir, { recursive: true })
+  const filename = `feedback-${deriveSlug(body)}-${timestamp()}.md`
+  const filePath = join(reviewDir, filename)
+  writeFileSync(filePath, `${body}\n`, 'utf8')
+  frameSuccess('aitk feedback', `.claude/review/${filename}`)
+  return filePath
+}
+
+export function register(program: Command): void {
+  program
+    .command('feedback')
+    .description(
+      'Write toolkit feedback from stdin to .claude/review/, or open a GitHub issue with --github',
+    )
+    .option(
+      '--github',
+      'Open a GitHub issue on the toolkit repo instead of writing local scratch',
+    )
+    .action(async (opts: { github?: boolean }) => {
+      if (process.stdin.isTTY) {
+        frameError(
+          'No feedback on stdin. Pipe a markdown block: pbpaste | aitk feedback',
+        )
+        process.exit(1)
+      }
+      const body = (await readStdin()).trim()
+      if (!body) {
+        frameError('Empty feedback body. Provide a markdown block on stdin.')
+        process.exit(1)
+      }
+
+      if (opts.github) {
+        const url = await createGithubIssue({
+          title: deriveTitle(body),
+          body,
+          labels: ['feedback'],
+        })
+        if (url) {
+          frameSuccess('aitk feedback', url)
+          process.stdout.write(`${url}\n`)
+          return
+        }
+        if (!isToolkitSource()) {
+          frameError(
+            'gh unavailable and no toolkit source to fall back to. Install gh, or file it at https://github.com/erclx/aitk/issues/new',
+          )
+          process.exit(1)
+        }
+        process.stderr.write(
+          `${YELLOW}! gh unavailable, wrote local scratch instead${NC}\n`,
+        )
+      }
+
+      if (!isToolkitSource()) {
+        frameError(
+          'Local scratch needs the toolkit source. Re-run with --github to open an issue instead.',
+        )
+        process.exit(1)
+      }
+
+      const filePath = writeLocal(body)
+      process.stdout.write(`${filePath}\n`)
+    })
+}