@erclx/aitk 0.89.0 → 0.90.0

package/src/commands/intake.ts

@@ -0,0 +1,406 @@
+import { relative } from 'node:path'
+import type { Command } from 'commander'
+import {
+  type AnswerOutcome,
+  answerItems,
+  type IntakeRefused,
+  type ListOutcome,
+  listFolders,
+  type ReadOutcome,
+  readFolder,
+  type Selection,
+} from '@/intake/folder'
+import { isUnread } from '@/intake/items'
+import {
+  intro,
+  logAdd,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+} from '@/ui'
+import { mainWorktreeRoot } from '@/worktree'
+
+/**
+ * A selection as the command line spells it, splitting on the first `=`. The
+ * label accepts a letter suffix, matching the headings a cluster file carries,
+ * and everything after the separator is the answer, so one carrying its own
+ * `=` survives intact.
+ */
+const SELECTION = /^(\d+[a-z]*)=([\s\S]*)$/i
+
+interface ListCommandOptions {
+  readonly json?: boolean
+  readonly unread?: boolean
+  readonly root?: string
+}
+
+interface AnswerCommandOptions {
+  readonly cluster?: string
+  readonly json?: boolean
+  readonly root?: string
+  readonly set?: readonly string[]
+}
+
+export function register(program: Command): void {
+  const intake = program
+    .command('intake')
+    .description('Read and answer intake folders in .claude/intake/')
+    .helpOption('-h, --help', 'Show this help message')
+
+  intake
+    .command('list')
+    .description('List intake folders, or the items one folder holds')
+    .argument('[slug]', 'Intake folder name, as in toolkit-overview')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--unread',
+      'Keep only what is unread, as folders carrying one or as empty slots',
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Intake root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the folders or items were listed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'With no slug it reports per-folder counts. With one it reports every',
+        'item grouped by the cluster file holding it. An empty answer slot',
+        'means unread and never agreement, so a count is the report and no',
+        'verb here decides one.',
+        '',
+        'An item carrying no answer slot is counted apart from both, since the',
+        'answer verb cannot reach it and folding it into either count hides a',
+        'file that needs fixing.',
+        '',
+        'Examples:',
+        '  aitk intake list',
+        '  aitk intake list toolkit-overview --unread --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (slug: string | undefined, opts: ListCommandOptions) => {
+      process.exitCode = await runList(slug, opts)
+    })
+
+  intake
+    .command('answer')
+    .description("Write selections into a cluster's answer slots")
+    .argument('<slug>', 'Intake folder name, as in toolkit-overview')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--cluster <file>', 'Cluster file the items live in')
+    .option(
+      '--set <item=answer>',
+      'Answer to land on an item, repeatable',
+      collectSelection,
+      [] as string[],
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Intake root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  every named item now carries its answer',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Items are numbered per cluster file, so a selection names the cluster',
+        'and the number together. One call writes one cluster, which is what',
+        'keeps a batch from racing on the file every selection shares.',
+        '',
+        'An item already carrying an answer is refused rather than overwritten.',
+        'A filled slot is a decision already made.',
+        '',
+        'Examples:',
+        '  aitk intake answer toolkit-overview --cluster 05-coverage.md --set 3=ok',
+        '  aitk intake answer toolkit-overview --cluster 05-coverage.md --set 3=ok --set 4="not worth it" --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (slug: string, opts: AnswerCommandOptions) => {
+      process.exitCode = await runAnswer(slug, opts)
+    })
+}
+
+function collectSelection(value: string, previous: string[]): string[] {
+  return [...previous, value]
+}
+
+async function runList(
+  slug: string | undefined,
+  opts: ListCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const root = opts.root ?? (await mainWorktreeRoot())
+
+  if (slug === undefined) {
+    return reportList(
+      await listFolders(root),
+      emitJson,
+      root,
+      opts.unread ?? false,
+    )
+  }
+
+  return reportFolder(
+    await readFolder(root, slug),
+    emitJson,
+    root,
+    opts.unread ?? false,
+  )
+}
+
+async function runAnswer(
+  slug: string,
+  opts: AnswerCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (!opts.cluster) {
+    return reportRefusal(
+      'aitk intake answer',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: 'No cluster named. Pass --cluster <file>.',
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const raw = opts.set ?? []
+
+  if (raw.length === 0) {
+    return reportRefusal(
+      'aitk intake answer',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: 'No selection given. Pass --set <item>=<answer>.',
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const selections: Selection[] = []
+  const invalid: string[] = []
+
+  for (const entry of raw) {
+    const match = SELECTION.exec(entry)
+    const answer = match?.[2].trim()
+
+    if (!match || !answer) {
+      invalid.push(entry)
+      continue
+    }
+
+    selections.push({ label: match[1].toLowerCase(), answer })
+  }
+
+  if (invalid.length > 0) {
+    return reportRefusal(
+      'aitk intake answer',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: `Not an item and answer: ${invalid.join(', ')}`,
+        detail: invalid,
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const duplicated = selections
+    .map((selection) => selection.label)
+    .filter((label, index, all) => all.indexOf(label) !== index)
+
+  if (duplicated.length > 0) {
+    return reportRefusal(
+      'aitk intake answer',
+      {
+        ok: false,
+        reason: 'bad-input',
+        message: `Two answers for item ${[...new Set(duplicated)].join(', ')}.`,
+        detail: [],
+      },
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const outcome = await answerItems(root, slug, opts.cluster, selections)
+
+  return reportAnswer(outcome, emitJson, root)
+}
+
+function reportRefusal(
+  title: string,
+  refused: IntakeRefused,
+  emitJson: boolean,
+  root: string,
+): number {
+  // The framed branch reaches stderr through logError, so the bare write is
+  // what keeps the JSON mode from reporting the reason on stdout alone.
+  if (emitJson) {
+    process.stderr.write(`${refused.message}\n`)
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: false,
+        root,
+        reason: refused.reason,
+        message: refused.message,
+        detail: refused.detail,
+      })}\n`,
+    )
+    return 1
+  }
+
+  intro(title)
+  logStep('Refused')
+  logError(refused.message)
+  if (refused.detail.length > 0) pipeOutput(refused.detail.join('\n'))
+  outro()
+
+  return 1
+}
+
+function reportList(
+  outcome: ListOutcome,
+  emitJson: boolean,
+  root: string,
+  unreadOnly: boolean,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('aitk intake list', outcome, emitJson, root)
+  }
+
+  // Malformed items are counted over every folder rather than the filtered
+  // set, since a folder whose only defect is an item nobody can answer carries
+  // no unread count to survive the filter and is exactly what the warning is
+  // for.
+  const listed = unreadOnly
+    ? outcome.folders.filter((folder) => folder.unread > 0)
+    : outcome.folders
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, root, folders: listed })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk intake list')
+  logStep(listed.length > 0 ? 'Folders' : 'No folders')
+
+  for (const folder of listed) {
+    logInfo(
+      `${folder.slug}: ${folder.items} item(s), ${folder.open} open, ${folder.unread} unread`,
+    )
+  }
+
+  const malformed = outcome.folders.filter((folder) => folder.malformed > 0)
+
+  if (malformed.length > 0) {
+    logStep('Carrying no answer slot')
+    for (const folder of malformed) {
+      logWarn(
+        `${folder.slug}: ${folder.malformed} item(s), which none of these verbs can answer`,
+      )
+    }
+  }
+
+  outro()
+
+  return 0
+}
+
+function reportFolder(
+  outcome: ReadOutcome,
+  emitJson: boolean,
+  root: string,
+  unreadOnly: boolean,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('aitk intake list', outcome, emitJson, root)
+  }
+
+  const clusters = outcome.clusters
+    .map((cluster) => ({
+      cluster: cluster.cluster,
+      items: unreadOnly ? cluster.items.filter(isUnread) : cluster.items,
+    }))
+    .filter((cluster) => cluster.items.length > 0)
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, root, slug: outcome.slug, clusters })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk intake list')
+
+  for (const cluster of clusters) {
+    logStep(cluster.cluster)
+    for (const item of cluster.items) {
+      const state = isUnread(item) ? 'unread' : (item.answer ?? 'no slot')
+      logInfo(`${item.label}. ${item.title} (${state})`)
+    }
+  }
+
+  if (clusters.length === 0) {
+    logStep(unreadOnly ? 'Nothing unread' : 'No items')
+  }
+
+  outro()
+
+  return 0
+}
+
+function reportAnswer(
+  outcome: AnswerOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRefusal('aitk intake answer', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        slug: outcome.slug,
+        cluster: outcome.cluster,
+        path: relative(root, outcome.path),
+        answered: outcome.answered,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('aitk intake answer')
+  logStep('Answered')
+
+  for (const entry of outcome.answered) {
+    logInfo(`${entry.label}. ${entry.answer}`)
+  }
+
+  logAdd(relative(root, outcome.path))
+  outro()
+
+  return 0
+}

package/src/intake/folder.ts

@@ -0,0 +1,280 @@
+import { existsSync } from 'node:fs'
+import { readdir, readFile, writeFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import {
+  INDEX_FILE,
+  type IntakeItem,
+  isMalformed,
+  isUnread,
+  readItems,
+  writeAnswerLine,
+} from '@/intake/items'
+
+export const INTAKE_REFUSALS = [
+  'no-intake',
+  'no-folder',
+  'no-cluster',
+  'no-item',
+  'answered',
+  'bad-input',
+] as const
+
+export type IntakeRefusal = (typeof INTAKE_REFUSALS)[number]
+
+export interface IntakeRefused {
+  readonly ok: false
+  readonly reason: IntakeRefusal
+  readonly message: string
+  readonly detail: readonly string[]
+}
+
+export interface FolderSummary {
+  readonly slug: string
+  readonly items: number
+  readonly open: number
+  readonly unread: number
+  /** Items carrying no answer slot, which no route here can answer. */
+  readonly malformed: number
+}
+
+export interface ClusterItems {
+  readonly cluster: string
+  readonly items: readonly IntakeItem[]
+}
+
+export interface FolderListed {
+  readonly ok: true
+  readonly folders: readonly FolderSummary[]
+}
+
+export interface FolderRead {
+  readonly ok: true
+  readonly slug: string
+  readonly clusters: readonly ClusterItems[]
+}
+
+export interface AnswerWritten {
+  readonly ok: true
+  readonly slug: string
+  readonly cluster: string
+  readonly path: string
+  readonly answered: readonly Selection[]
+}
+
+export type ListOutcome = FolderListed | IntakeRefused
+export type ReadOutcome = FolderRead | IntakeRefused
+export type AnswerOutcome = AnswerWritten | IntakeRefused
+
+export interface Selection {
+  readonly label: string
+  readonly answer: string
+}
+
+function refuse(
+  reason: IntakeRefusal,
+  message: string,
+  detail: readonly string[] = [],
+): IntakeRefused {
+  return { ok: false, reason, message, detail }
+}
+
+export function intakeDir(root: string): string {
+  return join(root, '.claude', 'intake')
+}
+
+/**
+ * Cluster files in read order, which is the numbering the folder carries. The
+ * index is dropped because it answers nothing, so every remaining file is one a
+ * selection can land in.
+ */
+export async function listClusters(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+
+  return entries
+    .filter(
+      (entry) =>
+        entry.isFile() &&
+        entry.name.endsWith('.md') &&
+        entry.name !== INDEX_FILE,
+    )
+    .map((entry) => entry.name)
+    .sort()
+}
+
+async function listSlugs(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+async function openFolder(
+  root: string,
+  slug: string,
+): Promise<string | IntakeRefused> {
+  const dir = intakeDir(root)
+
+  if (!existsSync(dir)) {
+    return refuse('no-intake', `No intake at ${relative(root, dir)}.`)
+  }
+
+  const folder = join(dir, slug)
+
+  if (!existsSync(folder)) {
+    return refuse(
+      'no-folder',
+      `No intake folder named ${slug}.`,
+      await listSlugs(dir),
+    )
+  }
+
+  return folder
+}
+
+/** Counts per folder, which is what a session picks a folder to work from. */
+export async function listFolders(root: string): Promise<ListOutcome> {
+  const dir = intakeDir(root)
+
+  if (!existsSync(dir)) {
+    return refuse('no-intake', `No intake at ${relative(root, dir)}.`)
+  }
+
+  const slugs = await listSlugs(dir)
+
+  const folders = await Promise.all(
+    slugs.map(async (slug) => {
+      const clusters = await readClusters(join(dir, slug))
+      const items = clusters.flatMap((cluster) => cluster.items)
+
+      return {
+        slug,
+        items: items.length,
+        open: items.filter((item) => item.open !== undefined).length,
+        unread: items.filter(isUnread).length,
+        malformed: items.filter(isMalformed).length,
+      }
+    }),
+  )
+
+  return { ok: true, folders }
+}
+
+async function readClusters(folder: string): Promise<ClusterItems[]> {
+  const names = await listClusters(folder)
+
+  return Promise.all(
+    names.map(async (cluster) => ({
+      cluster,
+      items: readItems(await readFile(join(folder, cluster), 'utf8')),
+    })),
+  )
+}
+
+/** Every item in a folder, grouped by the cluster file that holds it. */
+export async function readFolder(
+  root: string,
+  slug: string,
+): Promise<ReadOutcome> {
+  const opened = await openFolder(root, slug)
+  if (typeof opened !== 'string') return opened
+
+  return { ok: true, slug, clusters: await readClusters(opened) }
+}
+
+/**
+ * Lands a batch of selections in one cluster file.
+ *
+ * The batch is scoped to a cluster and applied in one read-modify-write because
+ * the alternative is a call per selection, and four of those against the same
+ * file race on the read and drop every answer but the last.
+ */
+export async function answerItems(
+  root: string,
+  slug: string,
+  cluster: string,
+  selections: readonly Selection[],
+): Promise<AnswerOutcome> {
+  const opened = await openFolder(root, slug)
+  if (typeof opened !== 'string') return opened
+
+  const name = cluster.endsWith('.md') ? cluster : `${cluster}.md`
+
+  if (name === INDEX_FILE) {
+    return refuse(
+      'no-cluster',
+      `${INDEX_FILE} is the index and carries no answer slot.`,
+    )
+  }
+
+  const path = join(opened, name)
+
+  if (!existsSync(path)) {
+    return refuse(
+      'no-cluster',
+      `No cluster named ${name} in ${slug}.`,
+      await listClusters(opened),
+    )
+  }
+
+  const broken = selections.filter((selection) =>
+    /[\r\n]/.test(selection.answer),
+  )
+
+  if (broken.length > 0) {
+    return refuse(
+      'bad-input',
+      `An answer is one line, so item ${broken.map((entry) => entry.label).join(', ')} cannot carry a line break.`,
+      broken.map((entry) => entry.label),
+    )
+  }
+
+  let text = await readFile(path, 'utf8')
+  const items = readItems(text)
+
+  const find = (label: string) =>
+    items.find((item) => item.label === label.toLowerCase())
+
+  const missing = selections.filter(
+    (selection) => find(selection.label)?.answerLine === undefined,
+  )
+
+  if (missing.length > 0) {
+    return refuse(
+      'no-item',
+      `${name} carries no answer slot for item ${missing.map((entry) => entry.label).join(', ')}.`,
+      items.map((item) => `${item.label}. ${item.title}`),
+    )
+  }
+
+  const filled = selections.filter(
+    (selection) => find(selection.label)?.answer !== undefined,
+  )
+
+  if (filled.length > 0) {
+    return refuse(
+      'answered',
+      `${name} item ${filled.map((entry) => entry.label).join(', ')} already carries an answer.`,
+      filled.map(
+        (entry) => `${entry.label}. ${find(entry.label)?.answer ?? ''}`,
+      ),
+    )
+  }
+
+  for (const selection of selections) {
+    const item = find(selection.label)
+    if (item?.answerLine === undefined) continue
+    text = writeAnswerLine(text, item.answerLine, selection.answer)
+  }
+
+  await writeFile(path, text)
+
+  return {
+    ok: true,
+    slug,
+    cluster: name,
+    path,
+    answered: selections,
+  }
+}