@erclx/canon 4.0.0

package/src/commands/demo.ts

@@ -0,0 +1,389 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname, extname, join, relative, resolve } from 'node:path'
+import type { Command } from 'commander'
+import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
+import { parseDraft } from '@/demo/beats'
+import { compilePlan, parsePlan, unresolved } from '@/demo/compile'
+import { convertToMp4, INSTALL_CONVERTER } from '@/demo/container'
+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'
+
+/**
+ * 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 canon-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:',
+        '  canon demo compile .claude/.tmp/screencast/inline-edit.md',
+        '  canon 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 canon 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}`,
+        '',
+        'Writes mp4 beside the webm when ffmpeg is on PATH, and skips it',
+        `otherwise without failing the run. Install it with: ${INSTALL_CONVERTER}`,
+        '',
+        'Exit codes:',
+        '  0  the recording and the still were written',
+        '  1  refused, with the reason on stderr',
+        '',
+        'Examples:',
+        '  canon demo run demos/inline-edit.json',
+        '  canon 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('canon 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('canon 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`,
+  )
+
+  let mp4Path: string | undefined
+  let mp4Reason: string | undefined
+  if (result.videoPath) {
+    logStep('Container')
+    const converted = await convertToMp4(result.videoPath)
+    if (converted.status === 'converted') {
+      mp4Path = converted.mp4Path
+      logInfo(display(mp4Path))
+    } else if (converted.status === 'skipped') {
+      mp4Reason = converted.reason
+      logWarn('ffmpeg is not installed, so no mp4 was written.')
+      logWarn(`Install it with: ${INSTALL_CONVERTER}`)
+    } else {
+      mp4Reason = converted.reason
+      logWarn(`mp4 conversion failed: ${converted.reason}`)
+    }
+  }
+
+  outro()
+
+  emit(opts.json, {
+    plan: source,
+    video: result.videoPath ?? null,
+    mp4: mp4Path ?? null,
+    still: result.stillPath ?? null,
+    steps: result.steps,
+    durationMs: result.durationMs,
+    ...(mp4Reason ? { mp4Reason } : {}),
+  })
+  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 (isEngineMissing(error)) return undefined
+    throw error
+  }
+}
+
+/**
+ * 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/deps.ts

@@ -0,0 +1,173 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import {
+  type Advisory,
+  auditDependencies,
+  type AuditRefusal,
+  countBySeverity,
+  SEVERITIES,
+} from '@/deps/audit'
+import {
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/ui'
+
+interface AuditCommandOptions {
+  readonly json?: boolean
+}
+
+/** What a reader does about each way the advisory list fails to arrive. */
+const REFUSALS: Record<AuditRefusal, string> = {
+  'no-manifest': 'No package.json here, so there is no dependency set to read.',
+  'no-lockfile':
+    'No lockfile beside the manifest, so no dependency set is resolved yet. Install first.',
+  'no-record':
+    'The advisory lookup returned no record. Check the network, then re-run.',
+}
+
+export function register(program: Command): void {
+  const deps = program
+    .command('deps')
+    .description('Read the installed dependency set for published advisories')
+    .helpOption('-h, --help', 'Show this help message')
+
+  deps
+    .command('audit')
+    .description('Report advisories against the dependencies already resolved')
+    .argument('[path]', 'Project to audit, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Scope:',
+        "  The resolved dependency set, read through the runtime's own",
+        '  advisory command. This reaches a network, so a lookup that fails',
+        '  refuses rather than reporting a clean tree.',
+        '',
+        'Exit codes:',
+        '  0  no advisory against the resolved set',
+        '  1  refused, with the reason on stderr',
+        '  2  at least one advisory was published',
+        '',
+        'Examples:',
+        '  canon deps audit',
+        '  canon deps audit --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: AuditCommandOptions) => {
+      process.exitCode = await runAudit(path, opts)
+    })
+}
+
+function severityLine(counts: Record<string, number>): string {
+  return SEVERITIES.filter((severity) => counts[severity] !== 0)
+    .map((severity) => `${counts[severity]} ${severity}`)
+    .join(', ')
+}
+
+/**
+ * Groups by package, since one dependency commonly carries several advisories
+ * and a flat list reads as more distinct upgrades than the tree actually owes.
+ */
+function byPackage(advisories: readonly Advisory[]): Map<string, Advisory[]> {
+  const grouped = new Map<string, Advisory[]>()
+
+  for (const advisory of advisories) {
+    const held = grouped.get(advisory.package) ?? []
+    held.push(advisory)
+    grouped.set(advisory.package, held)
+  }
+
+  return grouped
+}
+
+async function runAudit(
+  path: string | undefined,
+  opts: AuditCommandOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon deps audit')
+
+  const audit = await auditDependencies(root)
+
+  if (audit.kind === 'refused') {
+    logStep('Refused')
+    logWarn(REFUSALS[audit.reason])
+    if (audit.message !== undefined) logWarn(audit.message)
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: audit.reason,
+          message: audit.message ?? REFUSALS[audit.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  const counts = countBySeverity(audit.advisories)
+
+  logStep('Advisories')
+  if (audit.advisories.length === 0) {
+    logInfo('No advisory against the resolved dependency set.')
+  } else {
+    const grouped = byPackage(audit.advisories)
+    const total = audit.advisories.length
+
+    logWarn(
+      `${total} ${total === 1 ? 'advisory' : 'advisories'} across ${plural(grouped.size, 'package')}: ${severityLine(counts)}`,
+    )
+
+    // Piped rather than logged line by line, since every one of these is a
+    // finding and the timeline's own tick would mark each as something that
+    // passed. The frame stays, and the list inside it stays unmarked.
+    pipeOutput(
+      [...grouped]
+        .map(([name, held]) =>
+          [
+            `${name}: ${severityLine(countBySeverity(held))}`,
+            ...held.flatMap((advisory) => [
+              `  ${advisory.severity.padEnd(8)} ${advisory.title}`,
+              `  ${' '.repeat(8)} ${advisory.url}`,
+            ]),
+          ].join('\n'),
+        )
+        .join('\n'),
+    )
+  }
+
+  // Stated whichever way the count went. An advisory arrives when someone
+  // publishes one, so this number moves with no edit here, and a report that
+  // does not date itself reads as a fact about the tree rather than about a day.
+  logStep('Reading')
+  logInfo(
+    'Measured against the advisory index at run time, not at commit time.',
+  )
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        severities: counts,
+        advisories: audit.advisories,
+      })}\n`,
+    )
+  }
+
+  return audit.advisories.length === 0 ? 0 : 2
+}

package/src/commands/design.ts

@@ -0,0 +1,36 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { renderDesignDoc } from '@/design/render'
+import { palette } from '@/ui'
+
+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)
+      const { GREEN, GREY, NC, RED, WHITE } = palette(process.stderr)
+      if (!existsSync(sourcePath)) {
+        process.stderr.write(
+          `${GREY}┌${NC}\n${GREY}│${NC} ${RED}✗${NC} ${opts.source} not found\n${GREY}└${NC}\n`,
+        )
+        process.exitCode = 1
+        return
+      }
+      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,60 @@
+import type { Command } from 'commander'
+import { registerPassThroughVerbs } from '@/commands/pass-through'
+import { listTopics, readTopic, resolveTopic } from '@/docs/read'
+import { execScript } from '@/exec'
+import { PROJECT_ROOT } from '@/project-root'
+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:',
+        '  canon docs list',
+        '  canon docs list --json',
+        '  canon docs agents',
+        '',
+      ].join('\n'),
+    )
+    .action(async (topic: string | undefined) => {
+      if (topic === undefined) {
+        intro('canon 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('canon 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 'canon 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)
+}