@erclx/canon 5.66.0 → 5.68.0

package/src/commands/records.ts

@@ -34,6 +34,7 @@ import {
   type StructureFinding,
   validateRecords,
 } from '@/records/validate'
+import type { SessionMapLength } from '@/records/session-map'
 import {
   intro,
   logError,
@@ -92,7 +93,7 @@ export function register(program: Command): void {
     .argument('<kind>', `Record folder: ${RECORD_KINDS.join(', ')}`)
     .argument(
       '[record]',
-      'One plan stem or folder slug, narrowing both findings and structure to it',
+      'One plan stem, folder slug, or session map stem, narrowing the report to it',
     )
     .helpOption('-h, --help', 'Show this help message')
     .option('--json', 'Add a machine-readable record on stdout')
@@ -105,6 +106,7 @@ export function register(program: Command): void {
         '  plans       filename, required sections, and the suggested-and-answer contract',
         '  groundwork  README and current-state files, numbering, dating, and a half-closed track',
         '  intake      overview file, numbering, dating, and the four bullets every item carries',
+        "  sessions    each session map's words against its cap, under `length` and never in the exit",
         '',
         'Structure, under `structure` and never in the exit:',
         "  S1 to S5 from the plan standard, read on plans, a track's README and",
@@ -128,6 +130,7 @@ export function register(program: Command): void {
         '  canon records validate plans',
         '  canon records validate plans feature-records-by-heading',
         '  canon records validate intake --json',
+        '  canon records validate sessions session-orchestrator',
         '',
       ].join('\n'),
     )
@@ -828,6 +831,7 @@ function report(
         records: outcome.records,
         findings: outcome.findings,
         structure: outcome.structure,
+        ...(outcome.length && { length: outcome.length }),
       })}\n`,
     )
   } else {
@@ -846,6 +850,14 @@ function report(
       logStep('Structure, reported and never in the exit')
       for (const entry of outcome.structure) logInfo(describeStructure(entry))
     }
+
+    if (outcome.length) {
+      logStep('Length, reported and never in the exit')
+      for (const entry of outcome.length) {
+        const log = entry.over ? logWarn : logInfo
+        log(describeLength(entry))
+      }
+    }
     outro()
   }
 
@@ -857,6 +869,11 @@ function describe(found: Finding): string {
   return `${scope}${found.subject} ${found.message}`
 }
 
+function describeLength(entry: SessionMapLength): string {
+  const verdict = entry.over ? 'over the cap' : 'within the cap'
+  return `${entry.record}: ${entry.words} of ${entry.cap} words, ${verdict}`
+}
+
 function describeStructure(entry: StructureFinding): string {
   const scope = entry.record === entry.subject ? '' : `${entry.record}/`
   return `${entry.criterion} ${scope}${entry.subject}:${entry.line} ${entry.message}`

package/src/commands/take.ts

@@ -0,0 +1,302 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { INSTALL_BROWSER, isEngineMissing } from '@/browser/engine'
+import { readTakePlan } from '@/take/plan'
+import type { TakePlanRefusal } from '@/take/plan'
+import type { TakeRefusal } from '@/take/film'
+import { renderReel } from '@/take/reel'
+import {
+  intro,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  plural,
+} from '@/cli/ui'
+
+/**
+ * Holds wiring only. Every browser reference sits behind `loadTake`, 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 Take = typeof import('@/take/film')
+
+interface RunOptions {
+  readonly out: string
+  readonly reel?: string
+  readonly json?: boolean
+}
+
+const INSTALL_FFMPEG =
+  'install FFmpeg from your package manager, such as apt install ffmpeg or brew install ffmpeg'
+
+/** What a reader does about each way the plan produced no take. */
+const PLAN_REFUSALS: Record<TakePlanRefusal, string> = {
+  'unreadable-plan':
+    'The plan file is not valid JSON, so no beat could be read.',
+  'no-beats': 'The plan names no beat, so there is nothing to film.',
+  'bad-beat':
+    'A beat is missing its name or carries a setup that is not a list.',
+  'no-steps': 'A beat names no step, so its take would film nothing.',
+  'unknown-route': 'A beat names a route this build does not record on.',
+  'bad-step': 'A step is missing something the take needs to perform it.',
+}
+
+const TAKE_REFUSALS: Record<TakeRefusal, string> = {
+  'ffmpeg-missing': 'FFmpeg is not installed, so no clip could be encoded.',
+  'browser-missing': 'The headless shell is not installed in this project.',
+  'server-unreachable': 'Nothing answered at the URL, so no beat was filmed.',
+  'target-missing': 'A step names a target the page does not carry.',
+  'take-failed': 'The take failed against a reachable page.',
+}
+
+export function register(program: Command): void {
+  program
+    .command('take')
+    .description(
+      'Film a web app beat by beat with a click log and camera track',
+    )
+    .argument('<url>', 'Address to film')
+    .argument('<plan>', 'JSON file naming the beats and their steps')
+    .requiredOption('--out <dir>', 'Folder the clips, logs, and tracks land in')
+    .helpOption('-h, --help', 'Show this help message')
+    .option(
+      '--reel <file>',
+      'Also join the beats into one animated WebP with the pointer drawn',
+    )
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Films each beat from a fresh load of the page into its own folder under',
+        '--out, numbered in plan order: clip.mp4, log.json, camera.json, and',
+        "still.jpg, the clip's closing frame. take.json beside them lists every",
+        'beat and the route that filmed it.',
+        '',
+        'A step beat is filmed by frame stepping in chrome-headless-shell, at',
+        '3840x2160 and exactly 60 fps, with the page clock advancing one frame',
+        'per step. A frame slower than 2 s falls back to a real-time screencast',
+        'at 1920x1080 for that beat, and the record says so. A screencast beat',
+        'skips the stepper.',
+        '',
+        'No cursor is drawn in a clip. The edit draws it from the log at a',
+        'constant size, and the camera track carries the cursor and click ring',
+        'per frame beside the view. Canon renders nothing past the clip, save',
+        'the reel below.',
+        '',
+        '--reel <file> joins every beat in plan order into one looping animated',
+        'WebP at 960 wide and 20 fps, keeping every third frame, with the cursor',
+        'and click ring drawn from each camera track. It carries no zoom, so a',
+        "reviewer sees the whole page. clip.mp4 stays each beat's raw take.",
+        '',
+        '  {',
+        '    "beats": [',
+        '      { "name": "open the kit",',
+        '        "setup": [{ "kind": "click", "target": "text=Design" }],',
+        '        "steps": [',
+        '          { "kind": "click", "target": "#kit" },',
+        '          { "kind": "wait", "ms": 400 }',
+        '        ] }',
+        '    ]',
+        '  }',
+        '',
+        'Step kinds:',
+        '  move <target>|<x,y>    glide the pointer to a target or a point',
+        '  click <target>         glide to the target and press it',
+        '  fill <target> <text>   press the target and type the text',
+        '  scroll <target> <dy>   glide to the target and wheel dy pixels',
+        '  wait <ms>              hold, for a state the page reaches on its own',
+        '',
+        'A target is a CSS selector, or text=<words> for the innermost element',
+        'whose whole text is those words. Setup steps run before the first kept',
+        'frame. Every beat opens and closes on a 0.6 s hold.',
+        '',
+        'Needs a reachable page, FFmpeg, and the headless shell. Install with:',
+        `  ${INSTALL_BROWSER}`,
+        '',
+        'Reasons:',
+        '  no-plan-file        nothing readable at the plan path',
+        '  unreadable-plan     the plan file is not valid JSON',
+        '  no-beats            the plan names no beat',
+        '  bad-beat            a beat has no name or a setup that is not a list',
+        '  no-steps            a beat names no step',
+        '  unknown-route       a beat names a route other than step or screencast',
+        '  bad-step            a step is missing what the take needs to perform it',
+        '  engine-missing      the browser engine is not installed in this project',
+        '  ffmpeg-missing      FFmpeg is not on the PATH',
+        '  browser-missing     the headless shell or browser binary is not installed',
+        '  server-unreachable  nothing answered at the URL',
+        '  target-missing      a step names a target the page does not carry',
+        '  take-failed         the take failed against a reachable page',
+        '  reel-failed         every beat was filmed and the reel did not encode',
+        '',
+        'Exit codes:',
+        '  0  every beat was filmed, and the reel written when asked for',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon take http://localhost:4173 plan.json --out .canon/tmp/demo/takes',
+        '  canon take http://localhost:4173 plan.json --out takes --json',
+        '  canon take http://localhost:4173 plan.json --out takes --reel takes/reel.webp',
+        '',
+      ].join('\n'),
+    )
+    .action(async (url: string, plan: string, opts: RunOptions) => {
+      process.exitCode = await runTake(url, plan, opts)
+    })
+}
+
+async function runTake(
+  url: string,
+  planPath: string,
+  opts: RunOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const path = resolve(planPath)
+
+  intro(`canon take ${url}`)
+
+  let source: string
+  try {
+    source = readFileSync(path, 'utf8')
+  } catch (error) {
+    return refuse(
+      emitJson,
+      url,
+      'no-plan-file',
+      `No plan file at ${path}. ${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+
+  const read = readTakePlan(source)
+  if (read.kind === 'refused') {
+    return refuse(
+      emitJson,
+      url,
+      read.reason,
+      `${PLAN_REFUSALS[read.reason]} ${read.detail}`,
+    )
+  }
+
+  const { plan } = read
+  logStep('Scope')
+  logInfo(
+    `${plural(plan.beats.length, 'beat')} into ${resolve(opts.out)}: ${plan.beats.map((beat) => beat.name).join(', ')}`,
+  )
+
+  const taker = await loadTake()
+  if (!taker) {
+    logStep('Browser')
+    logError('the browser engine is not installed in this project')
+    logWarn(`Install it with: ${INSTALL_BROWSER}`)
+    outro()
+    emit(emitJson, {
+      url,
+      plan: path,
+      reason: 'engine-missing',
+      install: INSTALL_BROWSER,
+    })
+    return 1
+  }
+
+  logStep('Filming')
+  const result = await taker.take({ url, plan, out: opts.out })
+
+  if (result.status === 'failed') {
+    logStep('Refused')
+    logWarn(TAKE_REFUSALS[result.reason])
+    if (result.beat) logWarn(`in beat ${result.beat}`)
+    if (result.reason === 'server-unreachable') {
+      logWarn(`Start whatever serves ${url}, then run this again.`)
+    }
+    if (result.reason === 'browser-missing') {
+      logWarn(`Install the headless shell with: ${INSTALL_BROWSER}`)
+    }
+    if (result.reason === 'ffmpeg-missing') logWarn(`Then ${INSTALL_FFMPEG}.`)
+    logWarn(result.message.split('\n')[0] ?? '')
+    outro()
+    emit(emitJson, {
+      url,
+      plan: path,
+      reason: result.reason,
+      message: result.message,
+      ...(result.beat ? { beat: result.beat } : {}),
+      ...(result.reason === 'browser-missing'
+        ? { install: INSTALL_BROWSER }
+        : {}),
+    })
+    return 1
+  }
+
+  for (const beat of result.beats) {
+    logInfo(
+      `${beat.dir}  ${beat.route}  ${plural(beat.frames, 'frame')}  ${beat.seconds} s`,
+    )
+    if (beat.fallback) logWarn(`  filmed by screencast: ${beat.fallback}`)
+  }
+
+  const filmed = {
+    url,
+    plan: path,
+    out: result.out,
+    beats: result.beats,
+    durationMs: result.durationMs,
+  }
+  if (!opts.reel) {
+    outro()
+    emit(emitJson, filmed)
+    return 0
+  }
+
+  logStep('Reel')
+  try {
+    const reel = await renderReel(result.out, result.beats, resolve(opts.reel))
+    logInfo(
+      `${reel.file}  ${plural(reel.frames, 'frame')}  ${reel.seconds} s  ${(reel.bytes / 1e6).toFixed(1)} MB`,
+    )
+    outro()
+    emit(emitJson, { ...filmed, reel })
+    return 0
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    logWarn('Every beat was filmed, and the reel did not encode.')
+    logWarn(message.split('\n')[0] ?? '')
+    outro()
+    emit(emitJson, { ...filmed, reason: 'reel-failed', message })
+    return 1
+  }
+}
+
+/**
+ * Frames a refusal on stderr and puts the record on stdout, so an operator
+ * reading the terminal sees the reason rather than a command that appeared to
+ * do nothing.
+ */
+function refuse(
+  emitJson: boolean,
+  url: string,
+  reason: string,
+  message: string,
+): number {
+  logStep('Refused')
+  logWarn(message)
+  outro()
+  emit(emitJson, { url, reason, message })
+  return 1
+}
+
+async function loadTake(): Promise<Take | undefined> {
+  try {
+    return await import('@/take/film')
+  } catch (error) {
+    if (isEngineMissing(error)) return undefined
+    throw error
+  }
+}
+
+function emit(json: boolean, record: unknown): void {
+  if (json) process.stdout.write(`${JSON.stringify(record)}\n`)
+}

package/src/context/requirements.ts

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
-import { bodyLines } from '@/markdown/scan'
+import { bodyLines, wordCount } from '@/markdown/scan'
 import { surfaceDir } from '@/roots/surface'
 
 /**
@@ -11,16 +11,6 @@ export function requirementsRel(root: string): string {
   return relative(root, surfaceDir(root, 'REQUIREMENTS.md'))
 }
 
-/**
- * Counts whitespace-delimited tokens, the unit the record's word cap is stated
- * in. A code span counts as the tokens it holds, so a line citing a long path
- * pays for it the way a reader does. A caller gating on the count hands in
- * prose with fenced lines already dropped.
- */
-export function wordCount(text: string): number {
-  return text.match(/\S+/g)?.length ?? 0
-}
-
 export interface RequirementsReport {
   readonly rel: string
   /** The whole record's word count, frontmatter left out. */

package/src/git/status.ts

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { $ } from 'bun'
+import { gitEnv } from '@/git/env'
+
+export interface StatusEntry {
+  readonly path: string
+  readonly status: string
+  /** The content digest, or null where no regular file stands at the path. */
+  readonly digest: string | null
+}
+
+function digestOf(path: string): string | null {
+  try {
+    if (!statSync(path).isFile()) return null
+    return createHash('sha1').update(readFileSync(path)).digest('hex')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Every entry `git status` reports, untracked files listed one by one so a
+ * file a drive adds inside a tracked folder names itself, each with a content
+ * digest so a file already dirty at the baseline still reads as changed when
+ * a drive writes it again. Undefined when git cannot read the tree.
+ */
+export async function readWorktreeStatus(
+  worktree: string,
+): Promise<readonly StatusEntry[] | undefined> {
+  const result =
+    await $`git -C ${worktree} status --porcelain=v1 -z --untracked-files=all`
+      .env(gitEnv())
+      .quiet()
+      .nothrow()
+  if (result.exitCode !== 0) return undefined
+
+  const tokens = result.stdout.toString().split('\0')
+  const entries: StatusEntry[] = []
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index] ?? ''
+    if (token.length < 4) continue
+    const status = token.slice(0, 2)
+    const path = token.slice(3)
+    // A rename or copy carries its source as the next token.
+    if (status.includes('R') || status.includes('C')) index++
+    entries.push({ path, status, digest: digestOf(join(worktree, path)) })
+  }
+  return entries
+}
+
+/**
+ * The paths whose status or content differs from the baseline, in the order
+ * git reports them. An entry gone since the baseline is not reported, since a
+ * worker committing its own edit mid-pass clears it the same way.
+ */
+export function changedSince(
+  baseline: readonly StatusEntry[],
+  current: readonly StatusEntry[],
+): readonly string[] {
+  const before = new Map(baseline.map((entry) => [entry.path, entry]))
+  return current
+    .filter((entry) => {
+      const prior = before.get(entry.path)
+      return (
+        prior === undefined ||
+        prior.status !== entry.status ||
+        prior.digest !== entry.digest
+      )
+    })
+    .map((entry) => entry.path)
+}