@erclx/aitk 3.6.0 → 3.8.0

package/src/commands/demo.ts

@@ -0,0 +1,373 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname, extname, join, relative, resolve } from 'node:path'
+import type { Command } from 'commander'
+import { parseDraft } from '@/demo/beats'
+import { compilePlan, parsePlan, unresolved } from '@/demo/compile'
+import { DEFAULT_CURSORS } from '@/demo/cursors'
+import { loadCursorTheme } from '@/demo/theme'
+import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+const DEFAULT_OUT = 'demos'
+const INSTALL_BROWSER = 'bunx playwright install chromium'
+
+/**
+ * Holds wiring only. Every browser reference sits behind `loadDriver`, because
+ * `src/cli.ts` imports this module at startup and resolving the engine there
+ * would put a browser launch in front of every other command.
+ */
+type Driver = typeof import('@/demo/drive')
+
+interface CompileOptions {
+  readonly out: string
+  readonly slug?: string
+  readonly force?: boolean
+  readonly json?: boolean
+}
+
+interface RunOptions {
+  readonly out?: string
+  readonly cursor?: string
+  readonly video: boolean
+  readonly still: boolean
+  readonly json?: boolean
+}
+
+export function register(program: Command): void {
+  const demo = program
+    .command('demo')
+    .description('Drive a running application and record what it did')
+    .helpOption('-h, --help', 'Show this help message')
+
+  demo
+    .command('compile')
+    .description('Turn a screencast draft into a plan a run can drive')
+    .argument('<draft>', 'Screencast draft written by claude-screencast')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('-o, --out <dir>', 'Directory the plan is written to', DEFAULT_OUT)
+    .option('-s, --slug <slug>', 'Plan name, defaulting to the draft filename')
+    .option('--force', 'Overwrite a plan that already exists')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'The plan is committed rather than scratch. It carries the target, the',
+        'wait condition, and the timing a beat lacks, and the timing is a',
+        'starting point you tune, which is why a recompile refuses to overwrite.',
+        '',
+        'Exit codes:',
+        '  0  a plan was written',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  aitk demo compile .claude/.tmp/screencast/inline-edit.md',
+        '  aitk demo compile draft.md --out demos --force',
+        '',
+      ].join('\n'),
+    )
+    .action(async (draft: string, opts: CompileOptions) => {
+      process.exitCode = runCompile(draft, opts)
+    })
+
+  demo
+    .command('run')
+    .description('Drive the application a plan names and write the recording')
+    .argument('<plan>', 'Plan written by aitk demo compile')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('-o, --out <dir>', 'Directory to write into, overriding the plan')
+    .option(
+      '-c, --cursor <dir>',
+      'Cursor theme folder to draw the pointer from',
+    )
+    .option('--no-video', 'Skip the recording and write only the still')
+    .option('--no-still', 'Skip the still and write only the recording')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Needs a browser binary. Install it with:',
+        `  ${INSTALL_BROWSER}`,
+        '',
+        'Exit codes:',
+        '  0  the recording and the still were written',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  aitk demo run demos/inline-edit.json',
+        '  aitk demo run demos/inline-edit.json --cursor ~/cursors/theme',
+        '',
+      ].join('\n'),
+    )
+    .action(async (plan: string, opts: RunOptions) => {
+      process.exitCode = await runDrive(plan, opts)
+    })
+}
+
+function runCompile(draftPath: string, opts: CompileOptions): number {
+  intro('aitk demo compile')
+
+  const source = resolve(process.cwd(), draftPath)
+  if (!existsSync(source)) {
+    logStep('Draft')
+    logError(`${draftPath} not found`)
+    outro()
+    emit(opts.json, { draft: source, reason: 'draft-missing' })
+    return 1
+  }
+
+  const parsed = parseDraft(readFileSync(source, 'utf8'))
+  if (parsed.status === 'failed') {
+    logStep('Draft')
+    logError(`${display(source)}: ${parsed.reason}`)
+    outro()
+    emit(opts.json, {
+      draft: source,
+      reason: 'draft-unreadable',
+      message: parsed.reason,
+    })
+    return 1
+  }
+
+  const slug = opts.slug ?? basename(source, extname(source))
+  const target = resolve(process.cwd(), opts.out, `${slug}.json`)
+
+  if (existsSync(target) && !opts.force) {
+    logStep('Plan')
+    logError(`${display(target)} already exists`)
+    // Stated rather than implied, because the value at risk is timing the
+    // operator tuned by watching a recording and the draft cannot reproduce it.
+    logWarn('Pass --force to overwrite it, losing any timing tuned by hand.')
+    outro()
+    emit(opts.json, { plan: target, reason: 'plan-exists' })
+    return 1
+  }
+
+  const plan = compilePlan(parsed.draft, { slug, outDir: opts.out })
+  mkdirSync(dirname(target), { recursive: true })
+  writeFileSync(target, `${JSON.stringify(plan, null, 2)}\n`)
+
+  logStep('Draft')
+  logInfo(`${display(source)}  ${plural(parsed.draft.beats.length, 'beat')}`)
+
+  logStep('Plan')
+  logInfo(display(target))
+
+  const outstanding = unresolved(plan)
+  logStep('Outstanding')
+  if (outstanding.length === 0) {
+    logInfo('Nothing to fill, so the plan runs as written.')
+  } else {
+    logWarn(
+      `${plural(outstanding.length, 'field')} the draft could not supply:`,
+    )
+    for (const field of outstanding) logWarn(`  ${field}`)
+  }
+  outro()
+
+  emit(opts.json, {
+    draft: source,
+    plan: target,
+    beats: parsed.draft.beats.length,
+    unresolved: outstanding,
+  })
+  return 0
+}
+
+async function runDrive(planPath: string, opts: RunOptions): Promise<number> {
+  intro('aitk demo run')
+
+  const source = resolve(process.cwd(), planPath)
+  if (!existsSync(source)) {
+    logStep('Plan')
+    logError(`${planPath} not found`)
+    outro()
+    emit(opts.json, { plan: source, reason: 'plan-missing' })
+    return 1
+  }
+
+  const parsed = parsePlan(readFileSync(source, 'utf8'))
+  if (parsed.status === 'failed') {
+    logStep('Plan')
+    logError(`${display(source)}: ${parsed.reason}`)
+    outro()
+    emit(opts.json, {
+      plan: source,
+      reason: 'plan-unreadable',
+      message: parsed.reason,
+    })
+    return 1
+  }
+
+  if (!opts.video && !opts.still) {
+    logStep('Output')
+    logError('--no-video and --no-still together leave nothing to write')
+    outro()
+    emit(opts.json, { plan: source, reason: 'no-output-requested' })
+    return 1
+  }
+
+  const outstanding = unresolved(parsed.plan)
+  if (outstanding.length) {
+    logStep('Plan')
+    logError(
+      `${display(source)} has ${plural(outstanding.length, 'field')} to fill`,
+    )
+    for (const field of outstanding) logWarn(`  ${field}`)
+    outro()
+    emit(opts.json, {
+      plan: source,
+      reason: 'plan-unresolved',
+      unresolved: outstanding,
+    })
+    return 1
+  }
+
+  logStep('Plan')
+  logInfo(`${display(source)}  ${plural(parsed.plan.steps.length, 'step')}`)
+
+  const cursors = resolveCursors(opts.cursor)
+  if (cursors.status === 'failed') {
+    logError(cursors.reason)
+    outro()
+    emit(opts.json, { plan: source, reason: 'cursor-unreadable' })
+    return 1
+  }
+  logInfo(cursors.label)
+
+  const driver = await loadDriver()
+  if (!driver) {
+    logStep('Browser')
+    logError('the browser engine is not installed in this project')
+    logWarn(`Install it with: ${INSTALL_BROWSER}`)
+    outro()
+    emit(opts.json, {
+      plan: source,
+      reason: 'engine-missing',
+      install: INSTALL_BROWSER,
+    })
+    return 1
+  }
+
+  logStep('Recording')
+  const result = await driver.drive({
+    plan: parsed.plan,
+    cursors: cursors.value,
+    ...(opts.video
+      ? { videoPath: outputPath(parsed.plan.output.video, opts.out) }
+      : {}),
+    ...(opts.still
+      ? { stillPath: outputPath(parsed.plan.output.still, opts.out) }
+      : {}),
+  })
+
+  if (result.status === 'failed') {
+    logError(result.message.split('\n')[0] ?? 'the run failed')
+    if (result.reason === 'browser-missing') {
+      logWarn(`Install the browser binary with: ${INSTALL_BROWSER}`)
+    }
+    outro()
+    emit(opts.json, {
+      plan: source,
+      reason: result.reason,
+      message: result.message,
+      ...(result.reason === 'browser-missing'
+        ? { install: INSTALL_BROWSER }
+        : {}),
+    })
+    return 1
+  }
+
+  if (result.videoPath) logInfo(display(result.videoPath))
+  if (result.stillPath) logInfo(`${display(result.stillPath)}  still`)
+  logInfo(
+    `${result.steps} steps in ${Math.round(result.durationMs / 100) / 10}s`,
+  )
+  outro()
+
+  emit(opts.json, {
+    plan: source,
+    video: result.videoPath ?? null,
+    still: result.stillPath ?? null,
+    steps: result.steps,
+    durationMs: result.durationMs,
+  })
+  return 0
+}
+
+type CursorChoice =
+  | { status: 'ready'; value: typeof DEFAULT_CURSORS; label: string }
+  | { status: 'failed'; reason: string }
+
+/**
+ * A theme contributes per state rather than per folder, so a folder carrying an
+ * arrow and no hand still supplies its arrow and the bundled artwork covers the
+ * rest.
+ */
+function resolveCursors(dir: string | undefined): CursorChoice {
+  if (!dir) {
+    return {
+      status: 'ready',
+      value: DEFAULT_CURSORS,
+      label: 'pointer drawn from the bundled artwork',
+    }
+  }
+
+  const loaded = loadCursorTheme(resolve(process.cwd(), dir), DEFAULT_CURSORS)
+  if (loaded.status === 'failed')
+    return { status: 'failed', reason: loaded.reason }
+
+  return {
+    status: 'ready',
+    value: loaded.cursors,
+    label: `pointer drawn from ${display(resolve(process.cwd(), dir))} for ${loaded.states.join(', ')}`,
+  }
+}
+
+/**
+ * Reports absence only when the module or its engine cannot be resolved, which
+ * is the case a target hits before installing the browser package. Any other
+ * import failure is a defect inside the driver and propagates, rather than
+ * being reported as a missing dependency.
+ */
+async function loadDriver(): Promise<Driver | undefined> {
+  try {
+    return await import('@/demo/drive')
+  } catch (error) {
+    if (isModuleNotFound(error)) return undefined
+    throw error
+  }
+}
+
+function isModuleNotFound(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'code' in error &&
+    error.code === 'ERR_MODULE_NOT_FOUND'
+  )
+}
+
+/**
+ * Resolves where one artifact lands. `--out` replaces the directory the plan
+ * names rather than acting as a root the plan's own directory hangs off, which
+ * would nest the output path inside itself on every run that passes both.
+ */
+function outputPath(planned: string, out: string | undefined): string {
+  const relativePath = out ? join(out, basename(planned)) : planned
+  return resolve(process.cwd(), relativePath)
+}
+
+function emit(json: boolean | undefined, record: unknown): void {
+  if (json) process.stdout.write(`${JSON.stringify(record)}\n`)
+}
+
+/**
+ * Keeps a path clickable in the operator's terminal. A path outside the project
+ * reports absolute, since a relative path to it is a run of `..` segments no
+ * editor resolves.
+ */
+function display(path: string): string {
+  const fromCwd = relative(process.cwd(), path)
+  return fromCwd.startsWith('..') ? path : fromCwd
+}

package/src/commands/feedback.ts

@@ -32,13 +32,20 @@ function isToolkitSource(): boolean {
   return existsSync(join(PROJECT_ROOT, '.claude'))
 }
 
+/**
+ * One producer, one subfolder. The review folder carries the output of four
+ * unrelated producers, and the filename prefix was doing the folder's job by
+ * hand, so each writes under its own name and the enclosing folder keeps the
+ * single ignore entry and the single backed-folder entry it already had.
+ */
 function writeLocal(body: string): string {
-  const reviewDir = join(PROJECT_ROOT, '.claude', 'review')
+  const relativeDir = join('.claude', 'review', 'feedback')
+  const reviewDir = join(PROJECT_ROOT, relativeDir)
   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}`)
+  frameSuccess('aitk feedback', join(relativeDir, filename))
   return filePath
 }
 
@@ -46,7 +53,7 @@ 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',
+      'Write toolkit feedback from stdin to .claude/review/feedback/, or open a GitHub issue with --github',
     )
     .option(
       '--github',

package/src/commands/tasks.ts

@@ -151,7 +151,7 @@ export function register(program: Command): void {
         'Locations:',
         '  unstated  the task carries no Plan: line',
         '  live      the target resolves inside .claude/plans/',
-        '  archived  the target resolves inside .claude/plans-archive/',
+        '  archived  the target resolves inside .claude/plans/archive/',
         '  outside   the target resolves somewhere else',
         '',
         'Exit codes:',

package/src/demo/beats.ts

@@ -0,0 +1,135 @@
+/**
+ * Reads the human-facing draft `claude-screencast` writes. Nothing here knows
+ * about a browser: the draft is prose aimed at a person, and turning it into
+ * something executable is `@/demo/compile`'s job.
+ */
+
+export interface Beat {
+  readonly index: number
+  readonly name: string
+  readonly onScreen: string
+  readonly action: string
+  readonly watchFor: string
+  readonly emphasis: string
+  readonly caption: string
+  readonly transitionOut?: string
+}
+
+export interface Draft {
+  readonly title: string
+  readonly beats: readonly Beat[]
+}
+
+export type DraftParse =
+  | { status: 'parsed'; draft: Draft }
+  | { status: 'failed'; reason: string }
+
+const TITLE = /^#\s+Screencast:\s*(.+)$/m
+const BEAT_SHEET = /^##\s+.*Beat sheet.*$/im
+const BEAT_HEADING = /^###\s+Beat\s+(\d+)\s*:\s*(.*)$/i
+const FIELD = /^-\s+([A-Za-z][A-Za-z\s]*?)\s*:\s*(.*)$/
+
+/**
+ * Labels are matched case-insensitively with whitespace collapsed, because the
+ * draft is hand-edited between being written and being compiled and a
+ * capitalization change there is not a reason to refuse the whole file.
+ */
+const FIELDS: Record<string, keyof Beat> = {
+  'on screen': 'onScreen',
+  action: 'action',
+  'watch for': 'watchFor',
+  emphasis: 'emphasis',
+  caption: 'caption',
+  'transition out': 'transitionOut',
+}
+
+export function parseDraft(markdown: string): DraftParse {
+  const sheet = beatSheetSection(markdown)
+  if (sheet === undefined) {
+    return {
+      status: 'failed',
+      reason: 'no "Beat sheet" section, so the draft carries no beats to run',
+    }
+  }
+
+  const beats = readBeats(sheet)
+  if (!beats.length) {
+    return {
+      status: 'failed',
+      reason: 'the beat sheet holds no "### Beat" heading',
+    }
+  }
+
+  return {
+    status: 'parsed',
+    draft: { title: TITLE.exec(markdown)?.[1]?.trim() ?? '', beats },
+  }
+}
+
+/**
+ * Returns the lines between the beat sheet heading and the next `##`, so a
+ * `### Beat` heading elsewhere in the draft cannot be read as a beat.
+ */
+function beatSheetSection(markdown: string): string[] | undefined {
+  const lines = markdown.split('\n')
+  const start = lines.findIndex((line) => BEAT_SHEET.test(line))
+  if (start === -1) return undefined
+
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex((line) => /^##\s/.test(line))
+  return end === -1 ? rest : rest.slice(0, end)
+}
+
+function readBeats(lines: string[]): Beat[] {
+  const beats: Beat[] = []
+  let open: Partial<Beat> | undefined
+
+  for (const line of lines) {
+    const heading = BEAT_HEADING.exec(line)
+    if (heading) {
+      if (open) beats.push(sealBeat(open))
+      open = {
+        index: Number(heading[1]),
+        name: (heading[2] ?? '').trim(),
+      }
+      continue
+    }
+
+    if (!open) continue
+    const field = FIELD.exec(line)
+    if (!field) continue
+
+    const key = FIELDS[normalizeLabel(field[1] ?? '')]
+    if (key) open = { ...open, [key]: (field[2] ?? '').trim() }
+  }
+
+  if (open) beats.push(sealBeat(open))
+  return beats
+}
+
+/**
+ * Fills the five required fields with empty strings rather than leaving them
+ * undefined, so a downstream reader distinguishes "the operator left it blank"
+ * from "the label was misspelt" by the presence of the key alone.
+ *
+ * `transitionOut` stays optional, because the draft adds it only when it is
+ * not the default and an empty one would claim a decision nobody made.
+ */
+function sealBeat(open: Partial<Beat>): Beat {
+  const beat: Beat = {
+    index: open.index ?? 0,
+    name: open.name ?? '',
+    onScreen: open.onScreen ?? '',
+    action: open.action ?? '',
+    watchFor: open.watchFor ?? '',
+    emphasis: open.emphasis ?? '',
+    caption: open.caption ?? '',
+  }
+  return open.transitionOut === undefined
+    ? beat
+    : { ...beat, transitionOut: open.transitionOut }
+}
+
+function normalizeLabel(label: string): string {
+  return label.trim().toLowerCase().replace(/\s+/g, ' ')
+}