@erclx/aitk 0.8.0

package/src/tasks/archive.ts

@@ -0,0 +1,304 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { join, relative, resolve, sep } from 'node:path'
+import { regenOne } from '@/indexes/regen'
+
+const TASKS_DIR = join('.claude', 'tasks')
+const ARCHIVE_DIR = join('.claude', '.tmp', 'task-archive')
+const PLANS_DIR = join('.claude', 'plans')
+
+/**
+ * Generated and hand-maintained siblings that sit on the board without being
+ * tasks. The post-merge hook skips the same two names.
+ */
+const RESERVED_STEMS = ['index', 'priority'] as const
+
+export const ARCHIVE_REFUSALS = [
+  'no-board',
+  'no-match',
+  'ambiguous',
+  'no-outcomes',
+  'open-outcomes',
+  'plan-unswept',
+] as const
+
+export type ArchiveRefusal = (typeof ARCHIVE_REFUSALS)[number]
+
+export type TaskSelector =
+  | { readonly kind: 'stem'; readonly stem: string }
+  | { readonly kind: 'pull-request'; readonly number: number }
+
+export interface ArchiveSuccess {
+  readonly ok: true
+  readonly stem: string
+  readonly from: string
+  readonly to: string
+  readonly priorityRowRemoved: boolean
+  readonly indexRegenerated: boolean
+}
+
+export interface ArchiveRefused {
+  readonly ok: false
+  readonly reason: ArchiveRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+export type ArchiveOutcome = ArchiveSuccess | ArchiveRefused
+
+export interface TaskOutcomes {
+  readonly open: readonly string[]
+  readonly closed: readonly string[]
+}
+
+export function tasksDir(root: string): string {
+  return join(root, TASKS_DIR)
+}
+
+export function archiveDir(root: string): string {
+  return join(root, ARCHIVE_DIR)
+}
+
+/**
+ * Splits a task's outcome list by checkbox state. The board format puts every
+ * outcome at the top level of `## Outcomes`, so an anchored match is enough and
+ * no heading tracking is needed.
+ */
+export function readOutcomes(text: string): TaskOutcomes {
+  const open: string[] = []
+  const closed: string[] = []
+
+  for (const line of text.split('\n')) {
+    const match = /^- \[([ xX])\] ?(.*)$/.exec(line)
+    if (!match) continue
+
+    const [, box, body] = match
+    if (box === ' ') {
+      open.push(body.trim())
+    } else {
+      closed.push(body.trim())
+    }
+  }
+
+  return { open, closed }
+}
+
+/**
+ * Reads the `Pull request:` line `git-pr` writes when a pull request opens.
+ * The number is a bare `#NNN` the way `Issue:` is, since neither is a path and
+ * a full URL would write the remote into a gitignored file.
+ */
+export function readPullRequest(text: string): number | undefined {
+  const match = /^Pull request:\s*#(\d+)\s*$/m.exec(text)
+  return match ? Number(match[1]) : undefined
+}
+
+/**
+ * Reads the `Plan:` target out of a markdown link, falling back to the older
+ * bare-path form. The path is returned as written, relative to the board.
+ */
+export function readPlanTarget(text: string): string | undefined {
+  const match = /^Plan:\s*(?:\[[^\]]*\]\(([^)]+)\)|(\S+))\s*$/m.exec(text)
+  if (!match) return undefined
+  return match[1] ?? match[2]
+}
+
+/**
+ * Drops the archived task's row from the ordering table. Rows are matched by
+ * the link they carry rather than by a line pattern, because a row holds links
+ * and prose that a stream edit against it would rewrite in place.
+ */
+export function removePriorityRow(
+  text: string,
+  stem: string,
+): { readonly text: string; readonly removed: boolean } {
+  const target = `](${stem}.md)`
+  const lines = text.split('\n')
+  const kept = lines.filter((line) => !isRowFor(line, target))
+
+  return { text: kept.join('\n'), removed: kept.length !== lines.length }
+}
+
+/**
+ * A row is about a task when its first cell links to it. A later cell naming
+ * another task is a reference, such as a blocker pointing at what it waits on,
+ * and matching anywhere in the line would delete that task's row alongside it.
+ */
+function isRowFor(line: string, target: string): boolean {
+  const trimmed = line.trimStart()
+  if (!trimmed.startsWith('|')) return false
+
+  const [, first] = trimmed.split('|')
+  return first !== undefined && first.includes(target)
+}
+
+/**
+ * Tests containment rather than a string prefix, so a sibling whose name merely
+ * extends the folder's is not read as being inside it.
+ */
+function isUnder(path: string, dir: string): boolean {
+  return path === dir || path.startsWith(`${dir}${sep}`)
+}
+
+/**
+ * Resolves the `Plan:` target against the board and against the project root
+ * both, which is how `claude-docs` reads the same line. It accepts `../plans/x.md`
+ * and `.claude/plans/x.md` as one file, so a gate reading only the first form
+ * would pass the second and strand the plan this exists to protect.
+ */
+function isLivePlan(target: string, dir: string, root: string): boolean {
+  const plans = join(root, PLANS_DIR)
+
+  return (
+    isUnder(resolve(dir, target), plans) ||
+    isUnder(resolve(root, target), plans)
+  )
+}
+
+async function listTaskStems(dir: string): Promise<string[]> {
+  const entries = await readdir(dir)
+  const reserved: readonly string[] = RESERVED_STEMS
+
+  return entries
+    .filter((entry) => entry.endsWith('.md'))
+    .map((entry) => entry.slice(0, -'.md'.length))
+    .filter((stem) => !reserved.includes(stem))
+    .sort()
+}
+
+async function matchByPullRequest(
+  dir: string,
+  stems: readonly string[],
+  number: number,
+): Promise<string[]> {
+  const read = await Promise.all(
+    stems.map(async (stem) => ({
+      stem,
+      number: readPullRequest(await readFile(join(dir, `${stem}.md`), 'utf8')),
+    })),
+  )
+
+  return read.filter((entry) => entry.number === number).map(({ stem }) => stem)
+}
+
+function refuse(
+  reason: ArchiveRefusal,
+  message: string,
+  detail: readonly string[] = [],
+): ArchiveRefused {
+  return { ok: false, reason, message, detail }
+}
+
+async function resolveStem(
+  dir: string,
+  selector: TaskSelector,
+): Promise<string | ArchiveRefused> {
+  const stems = await listTaskStems(dir)
+
+  if (selector.kind === 'stem') {
+    if (!stems.includes(selector.stem)) {
+      return refuse(
+        'no-match',
+        `No task named ${selector.stem} on the board.`,
+        stems,
+      )
+    }
+    return selector.stem
+  }
+
+  const matched = await matchByPullRequest(dir, stems, selector.number)
+
+  if (matched.length === 0) {
+    return refuse('no-match', `No task names pull request #${selector.number}.`)
+  }
+
+  if (matched.length > 1) {
+    return refuse(
+      'ambiguous',
+      `${matched.length} tasks name pull request #${selector.number}. One task, one pull request.`,
+      matched,
+    )
+  }
+
+  return matched[0]
+}
+
+/**
+ * Archives one task as a single unit: the move, the ordering-row removal, and
+ * the index regen. The hook and `claude-tasks` both call this, so every gate
+ * refuses rather than reports. A caller with nobody watching cannot act on a
+ * warning, and two callers gating differently is the drift this exists to stop.
+ */
+export async function archiveTask(
+  root: string,
+  selector: TaskSelector,
+): Promise<ArchiveOutcome> {
+  const dir = tasksDir(root)
+
+  if (!existsSync(dir)) {
+    return refuse('no-board', `No task board at ${relative(root, dir)}.`)
+  }
+
+  const resolved = await resolveStem(dir, selector)
+  if (typeof resolved !== 'string') return resolved
+
+  const stem = resolved
+  const from = join(dir, `${stem}.md`)
+  const text = await readFile(from, 'utf8')
+
+  const { open, closed } = readOutcomes(text)
+
+  if (open.length > 0) {
+    return refuse(
+      'open-outcomes',
+      `${stem} has ${open.length} open outcome(s). Close them or cut them from the task, then archive.`,
+      open,
+    )
+  }
+
+  if (closed.length === 0) {
+    return refuse(
+      'no-outcomes',
+      `${stem} carries no outcomes, so nothing marks it shipped.`,
+    )
+  }
+
+  const planTarget = readPlanTarget(text)
+  if (planTarget && isLivePlan(planTarget, dir, root)) {
+    return refuse(
+      'plan-unswept',
+      `${stem} still points at a live plan. Run /claude-docs to sweep it first, then archive.`,
+      [planTarget],
+    )
+  }
+
+  const destination = archiveDir(root)
+  await mkdir(destination, { recursive: true })
+  const to = join(destination, `${stem}.md`)
+  await rename(from, to)
+
+  const priorityRowRemoved = await clearPriorityRow(dir, stem)
+  const regen = await regenOne(dir, { dryRun: false })
+
+  return {
+    ok: true,
+    stem,
+    from,
+    to,
+    priorityRowRemoved,
+    indexRegenerated: regen.action === 'written',
+  }
+}
+
+async function clearPriorityRow(dir: string, stem: string): Promise<boolean> {
+  const path = join(dir, 'priority.md')
+  if (!existsSync(path)) return false
+
+  const { text, removed } = removePriorityRow(
+    await readFile(path, 'utf8'),
+    stem,
+  )
+  if (removed) await writeFile(path, text)
+
+  return removed
+}

package/src/tooling/gitignore.ts

@@ -0,0 +1,122 @@
+import type { GitignoreSection } from '@/tooling/manifest'
+
+export interface MergeResult {
+  readonly content: string
+  readonly added: readonly string[]
+}
+
+export interface PruneResult {
+  readonly content: string
+  readonly removed: readonly string[]
+}
+
+/**
+ * Splits a gitignore body the way `while IFS= read -r line` did, so a file
+ * with or without a trailing newline yields the same logical lines.
+ */
+function toLines(content: string): string[] {
+  if (content === '') return []
+  const lines = content.split('\n')
+  if (lines[lines.length - 1] === '') lines.pop()
+  return lines
+}
+
+function fromLines(lines: readonly string[]): string {
+  if (lines.length === 0) return ''
+  return `${lines.join('\n')}\n`
+}
+
+function withoutTrailingSlash(entry: string): string {
+  return entry.endsWith('/') ? entry.slice(0, -1) : entry
+}
+
+function hasEntry(lines: readonly string[], entry: string): boolean {
+  return lines.includes(entry) || lines.includes(withoutTrailingSlash(entry))
+}
+
+/**
+ * Appends every manifest entry the file does not already carry.
+ *
+ * Two behaviors are load-bearing and preserved from `merge_gitignore`. The
+ * section header is written only when the whole section is missing, so a
+ * partially present section appends its entries bare at the end of the file.
+ * Presence is re-checked against the growing file, so an entry added by an
+ * earlier section or an earlier stack in the chain is not added twice.
+ */
+export function mergeSections(
+  content: string,
+  sections: readonly GitignoreSection[],
+): MergeResult {
+  let next = content
+  const added: string[] = []
+
+  for (const section of sections) {
+    const lines = toLines(next)
+    const missing = section.entries.filter((entry) => !hasEntry(lines, entry))
+    if (missing.length === 0) continue
+
+    if (missing.length === section.entries.length) {
+      next += `\n${section.header}\n`
+    }
+
+    for (const entry of missing) {
+      next += `${entry}\n`
+      added.push(entry)
+    }
+  }
+
+  return { content: next, added }
+}
+
+/**
+ * Drops entries that sit under a managed header but are no longer in the
+ * manifest. A section runs from its header line until the first blank line or
+ * the next comment, matching `prune_gitignore_section`.
+ */
+export function pruneSections(
+  content: string,
+  sections: readonly GitignoreSection[],
+): PruneResult {
+  let lines = toLines(content)
+  const removed: string[] = []
+
+  for (const section of sections) {
+    const kept: string[] = []
+    let inSection = false
+
+    for (const line of lines) {
+      if (line === section.header) {
+        inSection = true
+        kept.push(line)
+        continue
+      }
+
+      if (!inSection) {
+        kept.push(line)
+        continue
+      }
+
+      if (line === '' || line.startsWith('#')) {
+        inSection = false
+        kept.push(line)
+        continue
+      }
+
+      const isAllowed = section.entries.some(
+        (entry) =>
+          line === entry ||
+          withoutTrailingSlash(line) === withoutTrailingSlash(entry),
+      )
+
+      if (isAllowed) {
+        kept.push(line)
+      } else {
+        removed.push(line)
+      }
+    }
+
+    lines = kept
+  }
+
+  return { content: removed.length > 0 ? fromLines(lines) : content, removed }
+}

package/src/tooling/inject.ts

@@ -0,0 +1,214 @@
+import { existsSync } from 'node:fs'
+import {
+  copyFile,
+  mkdir,
+  readFile,
+  rm,
+  rmdir,
+  writeFile,
+} from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { $ } from 'bun'
+import { copyPreservingMode } from '@/copy'
+import { mergeSections, pruneSections } from '@/tooling/gitignore'
+import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
+import {
+  applyScripts,
+  collectDeps,
+  readPackage,
+  serializePackage,
+} from '@/tooling/package'
+import { logAdd, logRemove, logStep } from '@/ui'
+
+export async function injectConfigs(
+  chain: readonly Manifest[],
+  target: string,
+): Promise<string[]> {
+  const applied: string[] = []
+
+  for (const manifest of ancestorsFirst(chain)) {
+    const files = listFiles(manifest.configsDir)
+    if (files.length === 0) continue
+
+    logStep(`Applying ${manifest.name} configs`)
+    for (const rel of files) {
+      await copyPreservingMode(
+        join(manifest.configsDir, rel),
+        join(target, rel),
+      )
+      logAdd(rel)
+      applied.push(rel)
+    }
+  }
+
+  return applied
+}
+
+/**
+ * Copies a seed when the target lacks it. When the target already has one and
+ * the seed is a `.txt` word list, missing lines are appended and the file is
+ * re-sorted. Every other existing file is left untouched.
+ */
+async function mergeSeedFile(src: string, dest: string): Promise<void> {
+  await mkdir(dirname(dest), { recursive: true })
+
+  if (!existsSync(dest)) {
+    await copyFile(src, dest)
+    return
+  }
+
+  if (!src.endsWith('.txt')) return
+
+  const existing = (await readFile(dest, 'utf8')).split('\n')
+  const incoming = (await readFile(src, 'utf8')).split('\n')
+  const missing = incoming.filter(
+    (word) => word !== '' && !existing.includes(word),
+  )
+
+  if (missing.length === 0) return
+
+  const merged = [...existing.filter((line) => line !== ''), ...missing].sort()
+  await writeFile(dest, `${merged.join('\n')}\n`)
+}
+
+export async function injectSeeds(
+  chain: readonly Manifest[],
+  target: string,
+): Promise<string[]> {
+  const applied: string[] = []
+
+  for (const manifest of ancestorsFirst(chain)) {
+    const files = listFiles(manifest.seedsDir)
+    if (files.length === 0) continue
+
+    logStep(`Applying ${manifest.name} seeds`)
+    for (const rel of files) {
+      await mergeSeedFile(join(manifest.seedsDir, rel), join(target, rel))
+      logAdd(rel)
+      applied.push(rel)
+    }
+  }
+
+  return applied
+}
+
+export async function injectGitignore(
+  chain: readonly Manifest[],
+  target: string,
+): Promise<string[]> {
+  const path = join(target, '.gitignore')
+  const added: string[] = []
+
+  for (const manifest of ancestorsFirst(chain)) {
+    if (manifest.gitignore.length === 0) continue
+
+    const content = existsSync(path) ? await readFile(path, 'utf8') : ''
+    const result = mergeSections(content, manifest.gitignore)
+    if (result.added.length === 0) continue
+
+    logStep(`Applying ${manifest.name} gitignore`)
+    await writeFile(path, result.content)
+    for (const entry of result.added) {
+      logAdd(entry)
+      added.push(entry)
+    }
+  }
+
+  if (added.length === 0 && !existsSync(path)) await writeFile(path, '')
+
+  return added
+}
+
+export async function pruneGitignore(
+  chain: readonly Manifest[],
+  target: string,
+): Promise<string[]> {
+  const path = join(target, '.gitignore')
+  if (!existsSync(path)) return []
+
+  const removed: string[] = []
+
+  for (const manifest of ancestorsFirst(chain)) {
+    if (manifest.gitignore.length === 0) continue
+
+    const content = await readFile(path, 'utf8')
+    const result = pruneSections(content, manifest.gitignore)
+    if (result.removed.length === 0) continue
+
+    await writeFile(path, result.content)
+    for (const entry of result.removed) {
+      logRemove(entry)
+      removed.push(entry)
+    }
+  }
+
+  return removed
+}
+
+/**
+ * Installs missing dev dependencies, fills package scripts, and merges
+ * gitignore entries. This is the `inject_tooling_manifest` sequence, which
+ * assumed a target that already has a package.json.
+ */
+export async function injectManifest(
+  chain: readonly Manifest[],
+  target: string,
+): Promise<void> {
+  const packagePath = join(target, 'package.json')
+  const pkg = readPackage(packagePath)
+
+  if (pkg) {
+    const missing = collectDeps(chain, pkg)
+      .filter((dep) => dep.state === 'missing')
+      .map((dep) => dep.spec)
+
+    if (missing.length > 0) {
+      logStep('Installing missing dependencies')
+      await $`bun add -D ${missing}`.cwd(target)
+      for (const spec of missing) logAdd(spec)
+    }
+
+    const fresh = readPackage(packagePath)
+    if (fresh) {
+      const result = applyScripts(fresh, chain)
+      if (result.added.length > 0 || result.overridden.length > 0) {
+        logStep('Applying scripts')
+        for (const key of result.added) logAdd(key)
+        for (const key of result.overridden) logAdd(key)
+        await writeFile(packagePath, serializePackage(result.pkg))
+      }
+    }
+  }
+
+  await injectGitignore(chain, target)
+}
+
+/**
+ * Drops reference docs into `.claude/tooling/`, clearing the legacy
+ * `tooling/` location the earlier layout used.
+ */
+export async function applyReferences(
+  chain: readonly Manifest[],
+  target: string,
+  stacks: readonly string[],
+): Promise<string[]> {
+  const destDir = join(target, '.claude', 'tooling')
+  await mkdir(destDir, { recursive: true })
+
+  const applied: string[] = []
+  const byName = new Map(chain.map((manifest) => [manifest.name, manifest]))
+
+  for (const stack of stacks) {
+    const manifest = byName.get(stack)
+    if (!manifest) continue
+
+    await copyFile(manifest.referenceFile, join(destDir, `${stack}.md`))
+    logAdd(`.claude/tooling/${stack}.md`)
+    applied.push(stack)
+    await rm(join(target, 'tooling', `${stack}.md`), { force: true })
+  }
+
+  await rmdir(join(target, 'tooling')).catch(() => {})
+
+  return applied
+}

package/src/tooling/list.ts

@@ -0,0 +1,39 @@
+import { listStacks, loadManifest } from '@/tooling/manifest'
+
+export interface StackSummary {
+  readonly name: string
+  readonly extends: string | null
+  readonly devDeps: number
+  readonly scripts: number
+  readonly gitignoreGroups: number
+}
+
+/**
+ * Summarizes each installable stack. The counts come from `loadManifest`
+ * rather than the three `awk` programs the bash carried, so the list and the
+ * sync it previews read the same parse.
+ */
+export function buildStackSummaries(root: string): StackSummary[] {
+  const summaries: StackSummary[] = []
+
+  for (const stack of listStacks(root)) {
+    const manifest = loadManifest(root, stack)
+    if (!manifest) continue
+
+    summaries.push({
+      name: manifest.name,
+      extends: manifest.parent ?? null,
+      devDeps: manifest.devPackages.length,
+      scripts: Object.keys(manifest.scripts).length,
+      gitignoreGroups: manifest.gitignore.length,
+    })
+  }
+
+  return summaries
+}
+
+export function describeStack(summary: StackSummary): string {
+  const counts = `${summary.devDeps} dev deps, ${summary.scripts} scripts, ${summary.gitignoreGroups} gitignore groups`
+  const prefix = summary.extends === null ? '' : `extends: ${summary.extends}, `
+  return `${summary.name} (${prefix}${counts})`
+}