@erclx/aitk 0.8.0

package/src/claude/gitignore.ts

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { mergeSections } from '@/tooling/gitignore'
+import { type Manifest, resolveChain } from '@/tooling/manifest'
+
+export const CLAUDE_STACK = 'claude'
+
+export interface GitignoreEntry {
+  readonly entry: string
+  readonly present: boolean
+}
+
+export function claudeChain(root: string): Manifest[] {
+  return resolveChain(root, CLAUDE_STACK)
+}
+
+/**
+ * Previews the gitignore merge without writing. The answer comes from
+ * `mergeSections`, the same function the apply step runs, so the preview can
+ * never disagree with what lands.
+ *
+ * The bash matched the manifest's `[gitignore]` table with a line regex that
+ * required the array to open and close on one line, and it re-parsed TOML that
+ * `loadManifest` already reads. Routing through the manifest loader drops both
+ * problems.
+ */
+export function planGitignore(
+  chain: readonly Manifest[],
+  target: string,
+): GitignoreEntry[] {
+  const path = join(target, '.gitignore')
+  const content = existsSync(path) ? readFileSync(path, 'utf8') : ''
+  const entries: GitignoreEntry[] = []
+
+  for (const manifest of chain) {
+    const added = new Set(mergeSections(content, manifest.gitignore).added)
+    for (const section of manifest.gitignore) {
+      for (const entry of section.entries) {
+        entries.push({ entry, present: !added.has(entry) })
+      }
+    }
+  }
+
+  return entries
+}
+
+export function pendingEntries(
+  entries: readonly GitignoreEntry[],
+): GitignoreEntry[] {
+  return entries.filter((entry) => !entry.present)
+}

package/src/claude/seeds-list.ts

@@ -0,0 +1,47 @@
+import { readFile } from 'node:fs/promises'
+import { relative } from 'node:path'
+import { planSeeds } from '@/claude/seeds'
+
+export interface SeedListing {
+  readonly name: string
+  readonly source: string
+  readonly target: string
+  readonly src: string
+}
+
+export interface SeedListingWithContent {
+  readonly name: string
+  readonly source: string
+  readonly target: string
+  readonly content: string
+}
+
+/**
+ * Reads the same plan `aitk claude init` applies. The bash re-globbed the seeds
+ * directory with its own hard-coded subdirectory list, which had drifted: it
+ * never listed `.claude/context/`, so a seed init installs went unreported.
+ *
+ * The target is irrelevant to a listing, so it resolves against the source
+ * root and only the source-side fields are read.
+ */
+export function listSeeds(root: string): SeedListing[] {
+  return planSeeds(root, root).map(({ seed }) => ({
+    name: seed.scanLabel,
+    source: relative(root, seed.src),
+    target: seed.applyLabel,
+    src: seed.src,
+  }))
+}
+
+export async function readSeedContents(
+  listings: readonly SeedListing[],
+): Promise<SeedListingWithContent[]> {
+  return Promise.all(
+    listings.map(async ({ name, source, target, src }) => ({
+      name,
+      source,
+      target,
+      content: await readFile(src, 'utf8'),
+    })),
+  )
+}

package/src/claude/seeds.ts

@@ -0,0 +1,124 @@
+import { existsSync } from 'node:fs'
+import { chmod } from 'node:fs/promises'
+import { join } from 'node:path'
+import { copyPreservingMode } from '@/copy'
+
+const SEEDS_DIR = join('tooling', 'claude', 'seeds')
+const CLAUDE_DIR = '.claude'
+const CLAUDE_MD = 'CLAUDE.md'
+const HOOKS = 'hooks'
+const SUBDIRS: readonly string[] = [HOOKS, 'context', 'tasks', 'wireframes']
+
+export type SeedScope = 'claude' | 'root'
+
+export interface Seed {
+  readonly src: string
+  readonly dest: string
+  readonly scanLabel: string
+  readonly applyLabel: string
+  readonly scope: SeedScope
+  readonly executable: boolean
+}
+
+export interface SeedEntry {
+  readonly seed: Seed
+  readonly present: boolean
+}
+
+export interface SeedCounts {
+  readonly claude: number
+  readonly root: number
+}
+
+function seedsRoot(root: string): string {
+  return join(root, SEEDS_DIR)
+}
+
+/**
+ * Lists a single directory level, sorted the way `find -maxdepth 1 -type f |
+ * sort` was. Bun.Glob skips dotfiles without `dot`, and every path here sits
+ * under `.claude`, so omitting it would match nothing.
+ */
+function listLevel(dir: string): string[] {
+  if (!existsSync(dir)) return []
+  return [
+    ...new Bun.Glob('*').scanSync({ cwd: dir, onlyFiles: true, dot: true }),
+  ].sort()
+}
+
+/**
+ * Builds the seed list in the order the bash scanned it: the `.claude` root
+ * level, then each subdirectory, then the project-level `CLAUDE.md`. Order is
+ * load-bearing because it is also the order the timeline prints.
+ */
+export function planSeeds(root: string, target: string): SeedEntry[] {
+  const source = join(seedsRoot(root), CLAUDE_DIR)
+  const destDir = join(target, CLAUDE_DIR)
+  const seeds: Seed[] = []
+
+  for (const name of listLevel(source)) {
+    seeds.push({
+      src: join(source, name),
+      dest: join(destDir, name),
+      scanLabel: name,
+      applyLabel: join(CLAUDE_DIR, name),
+      scope: 'claude',
+      executable: false,
+    })
+  }
+
+  for (const subdir of SUBDIRS) {
+    for (const name of listLevel(join(source, subdir))) {
+      const rel = `${subdir}/${name}`
+      seeds.push({
+        src: join(source, subdir, name),
+        dest: join(destDir, subdir, name),
+        scanLabel: rel,
+        applyLabel: join(CLAUDE_DIR, subdir, name),
+        scope: 'claude',
+        executable: subdir === HOOKS,
+      })
+    }
+  }
+
+  const claudeMd = join(seedsRoot(root), CLAUDE_MD)
+  if (existsSync(claudeMd)) {
+    seeds.push({
+      src: claudeMd,
+      dest: join(target, CLAUDE_MD),
+      scanLabel: CLAUDE_MD,
+      applyLabel: CLAUDE_MD,
+      scope: 'root',
+      executable: false,
+    })
+  }
+
+  return seeds.map((seed) => ({ seed, present: existsSync(seed.dest) }))
+}
+
+export function pendingSeeds(entries: readonly SeedEntry[]): Seed[] {
+  return entries.filter((entry) => !entry.present).map((entry) => entry.seed)
+}
+
+export function countByScope(seeds: readonly Seed[]): SeedCounts {
+  return {
+    claude: seeds.filter((seed) => seed.scope === 'claude').length,
+    root: seeds.filter((seed) => seed.scope === 'root').length,
+  }
+}
+
+/**
+ * Copies each pending seed. Hooks get the executable bit the way `chmod +x`
+ * granted it, added on top of whatever mode the destination already carried.
+ */
+export async function applySeeds(seeds: readonly Seed[]): Promise<string[]> {
+  const applied: string[] = []
+
+  for (const seed of seeds) {
+    await copyPreservingMode(seed.src, seed.dest)
+    if (seed.executable) await chmod(seed.dest, 0o755)
+    applied.push(seed.applyLabel)
+  }
+
+  return applied
+}

package/src/claude/settings.ts

@@ -0,0 +1,151 @@
+import { existsSync } from 'node:fs'
+import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+const DEFAULT_INDENT = '  '
+const INDENT = /^([ \t]+)\S/m
+
+export type SettingsRecord = Record<string, unknown>
+
+export interface SettingsKey {
+  readonly label: string
+  readonly changed: boolean
+}
+
+export interface SettingsPlan {
+  readonly keys: readonly SettingsKey[]
+  readonly next: SettingsRecord
+  readonly changed: boolean
+}
+
+/**
+ * Reads the indentation of the first indented line. Rewriting an operator's
+ * settings file at a different width is a diff they did not ask for, and this
+ * verb is the only one in the toolkit that writes outside a target.
+ */
+export function detectIndent(source: string): string {
+  return INDENT.exec(source)?.[1] ?? DEFAULT_INDENT
+}
+
+export function serializeSettings(
+  value: SettingsRecord,
+  indent: string,
+): string {
+  return `${JSON.stringify(value, null, indent)}\n`
+}
+
+/**
+ * Parses a settings file, treating an absent one as empty. A malformed one
+ * throws rather than resolving to empty, because the alternative silently
+ * replaces a file the operator owns with a generated one.
+ */
+export async function readSettings(
+  path: string,
+): Promise<{ value: SettingsRecord; indent: string }> {
+  if (!existsSync(path)) return { value: {}, indent: DEFAULT_INDENT }
+
+  const source = await readFile(path, 'utf8')
+  const indent = detectIndent(source)
+  if (source.trim() === '') return { value: {}, indent }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(source)
+  } catch (cause) {
+    throw new Error(`${path} is not valid JSON`, { cause })
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${path} is not a JSON object`)
+  }
+
+  return { value: parsed as SettingsRecord, indent }
+}
+
+function asRecord(value: unknown): SettingsRecord {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return {}
+  }
+  return value as SettingsRecord
+}
+
+function asStrings(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((entry): entry is string => typeof entry === 'string')
+}
+
+function equals(left: unknown, right: unknown): boolean {
+  return Bun.deepEquals(left, right)
+}
+
+/**
+ * Unions two permission lists into the sorted, deduplicated shape `jq unique`
+ * produced. The sort is load-bearing, since the comparison that decides
+ * whether to write runs against the sorted result.
+ */
+function mergeList(current: unknown, incoming: unknown): string[] {
+  return [...new Set([...asStrings(current), ...asStrings(incoming)])].sort()
+}
+
+/**
+ * Applies the four settings the toolkit owns, leaving every other key in
+ * place. Each key reports whether it changed so the caller prints `+` or `✓`
+ * per key, matching the four separate `jq` passes this replaced.
+ */
+export function planSettings(
+  current: SettingsRecord,
+  template: SettingsRecord,
+  statusLineCommand: string,
+): SettingsPlan {
+  const next: SettingsRecord = { ...current }
+  const keys: SettingsKey[] = []
+
+  const statusLine = asRecord(next.statusLine)
+  const statusLineChanged = statusLine.command !== statusLineCommand
+  if (statusLineChanged) {
+    next.statusLine = { type: 'command', command: statusLineCommand }
+  }
+  keys.push({ label: 'statusLine', changed: statusLineChanged })
+
+  const attribution = template.attribution
+  const attributionChanged = !equals(next.attribution, attribution)
+  if (attributionChanged) next.attribution = attribution
+  keys.push({ label: 'attribution', changed: attributionChanged })
+
+  const permissions = asRecord(next.permissions)
+  const merged: SettingsRecord = { ...permissions }
+  const templatePermissions = asRecord(template.permissions)
+
+  for (const field of ['allow', 'deny'] as const) {
+    const union = mergeList(permissions[field], templatePermissions[field])
+    const changed = !equals(asStrings(permissions[field]), union)
+    if (changed) merged[field] = union
+    keys.push({ label: `permissions.${field}`, changed })
+  }
+
+  if (keys.some((key) => key.label.startsWith('permissions.') && key.changed)) {
+    next.permissions = merged
+  }
+
+  return { keys, next, changed: keys.some((key) => key.changed) }
+}
+
+/**
+ * Writes in place, restoring the file's existing mode. The bash wrote through
+ * `mktemp` and `mv`, which handed the destination the temp file's 600 and
+ * silently tightened a settings file the operator had left at 644.
+ */
+export async function writeSettings(
+  path: string,
+  content: string,
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+
+  const mode = await stat(path)
+    .then((info) => info.mode)
+    .catch(() => undefined)
+
+  await writeFile(path, content)
+
+  if (mode !== undefined) await chmod(path, mode)
+}

package/src/cli-run.ts

@@ -0,0 +1,43 @@
+import { join } from 'node:path'
+import { execa } from 'execa'
+
+export interface CliRunOptions {
+  /** Sets `AITK_NON_INTERACTIVE=1` for the child. Defaults to false. */
+  readonly nonInteractive?: boolean
+  /** Defaults to `inherit`, so a child prompt still reaches the operator. */
+  readonly stdin?: 'ignore' | 'inherit'
+}
+
+export function cliPath(root: string): string {
+  return join(root, 'src', 'cli.ts')
+}
+
+/**
+ * Spawns an `aitk` subcommand as its own process, by path rather than through
+ * the global binary, so a linked worktree exercises its own code.
+ *
+ * Both callers want a separately failable child rather than an in-process call:
+ * `aitk init` reports each domain's outcome independently, and `aitk sync`
+ * relies on each domain opening its own frame. Returns whether the child
+ * succeeded rather than throwing, because a failed domain is a reportable
+ * outcome and not an abort.
+ */
+export function cliRun(
+  path: string,
+  args: readonly string[],
+  options: CliRunOptions = {},
+): () => Promise<boolean> {
+  return async () => {
+    const env = options.nonInteractive
+      ? { ...process.env, AITK_NON_INTERACTIVE: '1' }
+      : process.env
+
+    const result = await execa('bun', [path, ...args], {
+      stdio: [options.stdin ?? 'inherit', 'inherit', 'inherit'],
+      env,
+      reject: false,
+    })
+
+    return result.exitCode === 0
+  }
+}

package/src/cli.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env bun
+
+import { Command } from 'commander'
+import { register as init } from '@/commands/init'
+import { register as sandbox } from '@/commands/sandbox'
+import { register as sync } from '@/commands/sync'
+import { register as gov } from '@/commands/gov'
+import { register as standards } from '@/commands/standards'
+import { register as snippets } from '@/commands/snippets'
+import { register as tooling } from '@/commands/tooling'
+import { register as claude } from '@/commands/claude'
+import { register as wiki } from '@/commands/wiki'
+import { register as indexes } from '@/commands/indexes'
+import { register as docs } from '@/commands/docs'
+import { register as design } from '@/commands/design'
+import { register as slides } from '@/commands/slides'
+import { register as feedback } from '@/commands/feedback'
+import { register as transcripts } from '@/commands/transcripts'
+import { register as tasks } from '@/commands/tasks'
+
+const GREY = '\x1b[0;90m'
+const WHITE = '\x1b[1;37m'
+const NC = '\x1b[0m'
+
+function showHelp(): void {
+  const lines = [
+    `${GREY}┌${NC}`,
+    `${GREY}├${NC} ${WHITE}Usage:${NC} aitk [command]`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Commands:${NC}`,
+    `${GREY}│${NC}    init [path]        ${GREY}# Bootstrap a project with toolkit domains${NC}`,
+    `${GREY}│${NC}    sync [path]        ${GREY}# Sync all installed domains in a project${NC}`,
+    `${GREY}│${NC}    sandbox [cat:cmd]  ${GREY}# Provision and run sandbox scenarios${NC}`,
+    `${GREY}│${NC}    gov [command]      ${GREY}# Governance commands (install, sync)${NC}`,
+    `${GREY}│${NC}    standards [cmd]    ${GREY}# Standards commands (install, sync)${NC}`,
+    `${GREY}│${NC}    snippets [cmd]     ${GREY}# Snippets commands (install, sync)${NC}`,
+    `${GREY}│${NC}    tooling [cmd]      ${GREY}# Manage tooling stacks (sync, ref, create)${NC}`,
+    `${GREY}│${NC}    claude [cmd]       ${GREY}# Claude workflow (init, sync, setup)${NC}`,
+    `${GREY}│${NC}    wiki [cmd]         ${GREY}# Wiki commands (init)${NC}`,
+    `${GREY}│${NC}    indexes [cmd]      ${GREY}# Regenerate index.md files (regen)${NC}`,
+    `${GREY}│${NC}    docs [cmd|topic]   ${GREY}# Emit toolkit reference docs (list, <topic>)${NC}`,
+    `${GREY}│${NC}    design [cmd]       ${GREY}# Design system commands (render)${NC}`,
+    `${GREY}│${NC}    slides [cmd]       ${GREY}# Slide deck commands (render, list)${NC}`,
+    `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .claude/review/${NC}`,
+    `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
+    `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Sandbox:${NC}`,
+    `${GREY}│${NC}    aitk sandbox             ${GREY}# Interactive scenario picker${NC}`,
+    `${GREY}│${NC}    aitk sandbox git:commit  ${GREY}# Run specific scenario${NC}`,
+    `${GREY}│${NC}    aitk sandbox reset       ${GREY}# Reset sandbox to baseline${NC}`,
+    `${GREY}│${NC}    aitk sandbox clean       ${GREY}# Wipe the sandbox${NC}`,
+    `${GREY}│${NC}`,
+    `${GREY}│${NC}  ${WHITE}Examples:${NC}`,
+    `${GREY}│${NC}    aitk sync ../my-app`,
+    `${GREY}│${NC}    aitk sandbox git:commit`,
+    `${GREY}│${NC}    aitk gov install react`,
+    `${GREY}│${NC}    aitk gov sync ../my-app`,
+    `${GREY}│${NC}    aitk standards sync ../my-app`,
+    `${GREY}│${NC}    aitk snippets install base ../my-app`,
+    `${GREY}│${NC}    aitk snippets sync ../my-app`,
+    `${GREY}│${NC}    aitk init ../my-app`,
+    `${GREY}│${NC}    aitk tooling sync base`,
+    `${GREY}│${NC}    aitk tooling create`,
+    `${GREY}│${NC}    aitk claude init`,
+    `${GREY}│${NC}    aitk indexes regen`,
+    `${GREY}│${NC}    aitk indexes regen --dry-run --json`,
+    `${GREY}│${NC}    aitk docs list --json`,
+    `${GREY}│${NC}    aitk docs agents`,
+    `${GREY}│${NC}    aitk design render`,
+    `${GREY}│${NC}    aitk slides render`,
+    `${GREY}│${NC}    aitk slides list --json`,
+    `${GREY}│${NC}    pbpaste | aitk feedback`,
+    `${GREY}│${NC}    aitk transcripts https://youtu.be/VIDEO_ID`,
+    `${GREY}│${NC}    aitk tasks archive --pull-request 673 --json`,
+    `${GREY}└${NC}`,
+  ]
+  console.log(lines.join('\n'))
+}
+
+const program = new Command()
+program
+  .name('aitk')
+  .version('0.1.0')
+  .enablePositionalOptions()
+  .helpOption(false)
+program.action(() => showHelp())
+program.on('option:help', () => {
+  showHelp()
+  process.exit(0)
+})
+program.option('-h, --help', 'Show help')
+
+init(program)
+sandbox(program)
+sync(program)
+gov(program)
+standards(program)
+snippets(program)
+tooling(program)
+claude(program)
+wiki(program)
+indexes(program)
+docs(program)
+design(program)
+slides(program)
+feedback(program)
+transcripts(program)
+tasks(program)
+
+program.parse()