@erclx/canon 5.14.1 → 5.15.0

package/src/commands/canvas.ts

@@ -0,0 +1,325 @@
+import { statSync } from 'node:fs'
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import {
+  addFrame,
+  addPage,
+  type ContentRefused,
+  canvasDir,
+  DEFAULT_FRAME,
+  listPages,
+  renamePage,
+} from '@/canvas/content'
+import { CANVAS_PORT, startCanvas } from '@/canvas/server'
+import { resolveFrameTokens } from '@/canvas/tokens'
+import { displayPath, parsePort, waitForInterrupt } from '@/serve/report'
+import {
+  intro,
+  logAdd,
+  logError,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  plural,
+} from '@/ui'
+import { mainWorktreeRoot } from '@/worktree'
+
+const BANNER = 'canon canvas'
+
+interface RootOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
+interface Refused {
+  readonly ok: false
+  readonly reason: ContentRefused['reason'] | 'no-root'
+  readonly detail: string
+}
+
+type RootOutcome = { readonly ok: true; readonly root: string } | Refused
+
+/**
+ * Refuses a root that is not a directory rather than letting the first write
+ * scaffold `.canon/canvas/` under a mistyped path, the way `canon serve`
+ * refuses a directory it cannot find.
+ */
+async function resolveRoot(opts: RootOptions): Promise<RootOutcome> {
+  const root = opts.root
+    ? resolve(process.cwd(), opts.root)
+    : await mainWorktreeRoot()
+  if (!statSync(root, { throwIfNoEntry: false })?.isDirectory()) {
+    return {
+      ok: false,
+      reason: 'no-root',
+      detail: `${root} is not a directory`,
+    }
+  }
+  return { ok: true, root }
+}
+
+function writeJson(record: unknown): void {
+  process.stdout.write(`${JSON.stringify(record)}\n`)
+}
+
+/** Every verb's refusal, framed on stderr and mirrored on stdout under --json. */
+function refuse(refusal: Refused, emitJson: boolean): number {
+  if (emitJson) writeJson(refusal)
+  intro(BANNER)
+  logError(refusal.detail)
+  outro()
+  return 1
+}
+
+/**
+ * Parses a size flag. NaN for a value that is not a positive integer, which
+ * the content module then refuses as an invalid size.
+ */
+function parseSize(raw: string | undefined, fallback: number): number {
+  if (raw === undefined) return fallback
+  const value = Number(raw)
+  return Number.isInteger(value) && value > 0 ? value : Number.NaN
+}
+
+function withRoot(command: Command): Command {
+  return command
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .option('--json', 'Emit a machine-readable record on stdout')
+}
+
+export function register(program: Command): void {
+  const canvas = program
+    .command('canvas')
+    .helpOption('-h, --help', 'Show this help message')
+    .description(
+      'Local canvas of pages and HTML frames (serve, list, page, frame)',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'A page is a folder under .canon/canvas/, a frame is one HTML file in',
+        'it, and layout.json beside them holds each frame box. Edit a frame by',
+        'editing its file, and an open canvas reloads that frame.',
+        '',
+        'Examples:',
+        '  canon canvas serve',
+        '  canon canvas page add drafts',
+        '  canon canvas frame add drafts hero --width 1440 --height 900',
+        '  canon canvas list --json',
+        '',
+      ].join('\n'),
+    )
+
+  withRoot(
+    canvas
+      .command('serve')
+      .description('Serve the canvas on localhost and print the link')
+      .option('--port <number>', `Port to try first, default ${CANVAS_PORT}`),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  the server stopped after running',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'The server binds 127.0.0.1 and nothing else. It runs until',
+        'interrupted, so a session wanting the link starts it in the',
+        'background and reads the record off stdout.',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RootOptions & { port?: string }) => {
+      process.exitCode = await runServe(opts)
+    })
+
+  withRoot(
+    canvas.command('list').description('List pages and the frames on each'),
+  ).action(async (opts: RootOptions) => {
+    const resolved = await resolveRoot(opts)
+    if (!resolved.ok) {
+      process.exitCode = refuse(resolved, opts.json ?? false)
+      return
+    }
+    const { root } = resolved
+    const pages = listPages(root)
+    if (opts.json) {
+      writeJson({ ok: true, root, content: canvasDir(root), pages })
+    }
+    intro(BANNER)
+    if (pages.length === 0) {
+      logStep('No pages')
+      logInfo('canon canvas page add <name> adds one')
+    }
+    for (const page of pages) {
+      logStep(`${page.name} (${plural(page.frames.length, 'frame')})`)
+      for (const frame of page.frames) {
+        logInfo(`${frame.name}  ${frame.width} × ${frame.height}`)
+      }
+      if (page.layoutIssue === 'malformed') {
+        logWarn('layout.json does not parse, so frames sit in a default row')
+      }
+    }
+    outro()
+  })
+
+  const page = canvas
+    .command('page')
+    .helpOption('-h, --help', 'Show this help message')
+    .description('Add or rename a page')
+
+  withRoot(
+    page
+      .command('add')
+      .description('Add a page')
+      .argument('<name>', 'Page name, one path segment'),
+  ).action(async (name: string, opts: RootOptions) => {
+    const resolved = await resolveRoot(opts)
+    const outcome = resolved.ok ? addPage(resolved.root, name) : resolved
+    if (!outcome.ok) {
+      process.exitCode = refuse(outcome, opts.json ?? false)
+      return
+    }
+    if (opts.json) writeJson(outcome)
+    intro(BANNER)
+    logAdd(`page ${outcome.page}`)
+    outro()
+  })
+
+  withRoot(
+    page
+      .command('rename')
+      .description('Rename a page, keeping its frames and layout')
+      .argument('<from>', 'Current page name')
+      .argument('<to>', 'New page name'),
+  ).action(async (from: string, to: string, opts: RootOptions) => {
+    const resolved = await resolveRoot(opts)
+    const outcome = resolved.ok ? renamePage(resolved.root, from, to) : resolved
+    if (!outcome.ok) {
+      process.exitCode = refuse(outcome, opts.json ?? false)
+      return
+    }
+    if (opts.json) writeJson({ ...outcome, from })
+    intro(BANNER)
+    logAdd(`page ${from} → ${outcome.page}`)
+    outro()
+  })
+
+  const frame = canvas
+    .command('frame')
+    .helpOption('-h, --help', 'Show this help message')
+    .description('Add a frame to a page')
+
+  withRoot(
+    frame
+      .command('add')
+      .description('Add a frame as a new HTML file, placed after the others')
+      .argument('<page>', 'Page to add the frame to')
+      .argument('<name>', 'Frame name, which becomes <name>.html')
+      .option('--width <px>', `Frame width, default ${DEFAULT_FRAME.width}`)
+      .option('--height <px>', `Frame height, default ${DEFAULT_FRAME.height}`),
+  ).action(
+    async (
+      pageName: string,
+      name: string,
+      opts: RootOptions & { width?: string; height?: string },
+    ) => {
+      const resolved = await resolveRoot(opts)
+      if (!resolved.ok) {
+        process.exitCode = refuse(resolved, opts.json ?? false)
+        return
+      }
+      const { root } = resolved
+      const outcome = addFrame(root, pageName, name, {
+        width: parseSize(opts.width, DEFAULT_FRAME.width),
+        height: parseSize(opts.height, DEFAULT_FRAME.height),
+      })
+      if (!outcome.ok) {
+        process.exitCode = refuse(outcome, opts.json ?? false)
+        return
+      }
+      if (opts.json) {
+        writeJson({
+          ...outcome,
+          path: resolve(canvasDir(root), outcome.page, outcome.file),
+        })
+      }
+      intro(BANNER)
+      logAdd(`${outcome.page}/${outcome.file}`)
+      logInfo(
+        `${outcome.box.width} × ${outcome.box.height} at ${outcome.box.x}, ${outcome.box.y}`,
+      )
+      outro()
+    },
+  )
+}
+
+async function runServe(
+  opts: RootOptions & { port?: string },
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const port = opts.port === undefined ? CANVAS_PORT : parsePort(opts.port)
+  if (port === undefined) {
+    return refuseServe('no-port', `${opts.port} is not a port`, emitJson)
+  }
+
+  const resolved = await resolveRoot(opts)
+  if (!resolved.ok) {
+    return refuseServe(resolved.reason, resolved.detail, emitJson)
+  }
+  const { root } = resolved
+  /*
+   * Imported here rather than at the top, so a command module the test runner
+   * loads never asks it for an HTML module it cannot parse.
+   */
+  const { default: shell } = await import('@/canvas/index.html')
+  const outcome = startCanvas(root, { port, shell })
+  if (!outcome.ok) {
+    return refuseServe(outcome.reason, outcome.detail, emitJson)
+  }
+
+  const tokens = resolveFrameTokens(root)
+  const { css: _css, ...tokenSource } = tokens
+  if (emitJson) {
+    writeJson({
+      ok: true,
+      root: outcome.root,
+      content: outcome.content,
+      host: outcome.host,
+      port: outcome.port,
+      url: outcome.url,
+      tokens: tokenSource,
+    })
+  }
+  intro(BANNER)
+  logStep('Serving')
+  logInfo(displayPath(outcome.content))
+  logStep('Open')
+  logInfo(outcome.url)
+  logStep('Tokens')
+  if (tokens.source === 'none') logWarn(tokens.notice)
+  else if (tokens.source === 'installed') {
+    for (const file of tokens.files) logInfo(file)
+  } else logInfo('this toolkit’s own token module')
+  logStep('Stop')
+  logInfo('Ctrl-C')
+
+  await waitForInterrupt(outcome.stop)
+  return 0
+}
+
+function refuseServe(
+  reason: string,
+  detail: string,
+  emitJson: boolean,
+): number {
+  if (emitJson) writeJson({ ok: false, reason, detail })
+  intro(BANNER)
+  logError(detail)
+  outro()
+  return 1
+}

package/src/commands/claude.ts

@@ -153,21 +153,16 @@ const SEEDED_FILES: readonly string[] = [
   'REQUIREMENTS.md',
   'DESIGN.md',
 ]
-const SEEDED_DIRS: readonly string[] = [
-  'decisions',
-  'memory',
-  'tasks',
-  'wireframes',
-]
+const SEEDED_DIRS: readonly string[] = ['memory', 'tasks', 'wireframes']
 
 /**
  * Where a `SEEDED_DIRS` entry resolves for the sync presence check.
  *
- * `wireframes` and `decisions` are tracked surface entries, resolved under
- * `canon/` ahead of `.claude/`, while `memory` and `tasks` are session records
- * resolved under `.canon/` ahead of `.claude/`. Routing every name through
- * `recordDir` reported a migrated target's `canon/wireframes/` or
- * `canon/decisions/` as missing, since that resolver never checks `canon/`.
+ * `wireframes` is a tracked surface entry, resolved under `canon/` ahead of
+ * `.claude/`, while `memory` and `tasks` are session records resolved under
+ * `.canon/` ahead of `.claude/`. Routing every name through `recordDir`
+ * reported a migrated target's `canon/wireframes/` as missing, since that
+ * resolver never checks `canon/`.
  */
 export function seededDirPath(resolved: string, name: string): string {
   return SURFACE_ENTRIES.includes(name)
@@ -605,9 +600,9 @@ async function runSync(target: string): Promise<number> {
 
   // A record folder resolves at either root, so a migrated target is reported as
   // seeded rather than sent to `canon claude init` to re-create records it
-  // already holds. `wireframes` and `decisions` are tracked surface entries
-  // instead, resolved through `surfaceDir`, since a migrated target holds them
-  // at `canon/` rather than under either record root.
+  // already holds. `wireframes` is a tracked surface entry instead, resolved
+  // through `surfaceDir`, since a migrated target holds it at `canon/` rather
+  // than under either record root.
   logStep('Seeded')
   for (const name of SEEDED_FILES) {
     if (existsSync(join(resolved, '.claude', name))) logInfo(name)

package/src/commands/demo.ts

@@ -73,7 +73,7 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '',
         'Examples:',
-        '  canon demo compile .canon/tmp/screencast/inline-edit.md',
+        '  canon demo compile demos/inline-edit/beats.md --slug inline-edit',
         '  canon demo compile draft.md --out demos --force',
         '',
       ].join('\n'),
@@ -114,8 +114,8 @@ export function register(program: Command): void {
         '  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',
+        '  canon demo run demos/inline-edit/plan.json',
+        '  canon demo run demos/inline-edit/plan.json --cursor ~/cursors/theme',
         '',
       ].join('\n'),
     )
@@ -146,8 +146,8 @@ export function register(program: Command): void {
         '  1  refused, with the reason on stderr',
         '',
         'Examples:',
-        '  canon demo frames demos/inline-edit.webm',
-        '  canon demo frames demos/inline-edit.webm --fps 2 --out frames',
+        '  canon demo frames demos/inline-edit/take/inline-edit.webm',
+        '  canon demo frames demos/inline-edit/take/inline-edit.webm --fps 2 --out frames',
         '',
       ].join('\n'),
     )
@@ -182,7 +182,7 @@ function runCompile(draftPath: string, opts: CompileOptions): number {
   }
 
   const slug = opts.slug ?? basename(source, extname(source))
-  const target = resolve(process.cwd(), opts.out, `${slug}.json`)
+  const target = resolve(process.cwd(), opts.out, slug, 'plan.json')
 
   if (existsSync(target) && !opts.force) {
     logStep('Plan')

package/src/commands/sandbox.ts

@@ -13,6 +13,11 @@ import {
   coveragePercent,
   type CoverageReport,
 } from '@/sandbox/coverage'
+import {
+  equivalenceExitCode,
+  runEquivalence as collectEquivalence,
+  type EquivalenceRecord,
+} from '@/sandbox/equivalence'
 import {
   expectFilePath,
   parseTarget,
@@ -338,6 +343,71 @@ function runCoverage(options: CoverageOptions): void {
   process.exitCode = wrongExemption || rolloutIncomplete ? 1 : 0
 }
 
+interface EquivalenceOptions {
+  readonly base: string
+  readonly includeAnchor?: boolean
+  readonly out?: string
+  readonly masks: boolean
+  readonly json?: boolean
+}
+
+/**
+ * Provisions every arm on a base ref and on this checkout, then names what
+ * differs. The record is the only thing on stdout, and a red arm that is red the
+ * same way on both sides is reported without failing the run, since it proves
+ * nothing either way.
+ */
+async function runEquivalence(
+  targets: string[],
+  options: EquivalenceOptions,
+): Promise<void> {
+  if (reportAbsentScenarioTree()) return
+
+  intro('canon sandbox equivalence')
+
+  let record: EquivalenceRecord
+  try {
+    record = await collectEquivalence({
+      root: PROJECT_ROOT,
+      targets,
+      base: options.base,
+      includeAnchor: options.includeAnchor === true,
+      useMasks: options.masks,
+      out: options.out,
+    })
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    logError(`Cannot provision the baseline ${options.base}: ${reason}`)
+    outro()
+    process.exitCode = 1
+
+    return
+  }
+
+  logStep(`Base ${record.base} (${record.baseCommit.slice(0, 8)})`)
+  logInfo(`canon ${record.canonVersion}`)
+
+  for (const arm of record.arms) {
+    if (arm.state === 'identical' || arm.state === 'skipped-anchor') continue
+    const detail = arm.differs.length > 0 ? `: ${arm.differs.join(', ')}` : ''
+    if (arm.state === 'differs') logRemove(`${arm.arm} differs${detail}`)
+    else logWarn(`${arm.arm} is ${arm.state}`)
+  }
+  for (const line of record.masksApplied) logInfo(`masked ${line}`)
+  for (const error of record.errors) logError(error)
+
+  const { counts } = record
+  logStep('Equivalence')
+  const summary = `${counts.identical} identical, ${counts.differs} differs, ${counts['red-on-base']} red-on-base, ${counts['skipped-anchor']} skipped-anchor`
+  if (equivalenceExitCode(record) === 0) logInfo(summary)
+  else logWarn(summary)
+
+  if (options.json === true) process.stdout.write(`${JSON.stringify(record)}\n`)
+
+  outro()
+  process.exitCode = equivalenceExitCode(record)
+}
+
 function runCheck(
   target: string,
   arm: string | undefined,
@@ -482,4 +552,42 @@ export function register(program: Command): void {
     .action((options: CoverageOptions) => {
       runCoverage(options)
     })
+
+  sandbox
+    .command('equivalence')
+    .description(
+      'Provision every arm on a base ref and on this checkout, and diff the trees',
+    )
+    .argument(
+      '[target...]',
+      'Category or <category>:<command>, defaulting to every category',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--base <ref>', 'Ref the baseline is provisioned from', 'main')
+    .option(
+      '--include-anchor',
+      'Also run the arms that push to the shared GitHub anchor, one at a time (attended)',
+    )
+    .option('--out <dir>', 'Keep the provisioned trees and logs in this folder')
+    .option(
+      '--no-masks',
+      'Compare every path, listing what each mask would hide',
+    )
+    .option('--json', 'Emit the record as JSON on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Examples:',
+        '  canon sandbox equivalence claude --json',
+        '  canon sandbox equivalence claude:plan-feature --base origin/main',
+        '',
+        'Provisions offline only and never runs sandbox/run.sh or a claude binary.',
+        'Exit codes: 0 when every compared arm is identical or red the same way',
+        'on both sides, 1 on any difference, exit mismatch, or enumeration error.',
+      ].join('\n'),
+    )
+    .action((targets: string[], options: EquivalenceOptions) =>
+      runEquivalence(targets, options),
+    )
 }

package/src/context/classify/prompts.ts

@@ -20,7 +20,7 @@ File types and what they hold:
 Verdicts (pick exactly one):
 - KEEP: states current design, a rule, copy, a decision with its rejected alternative, or a live gotcha, on the right surface.
 - REPLACE: restates a fact or figure the existing section already carries ("moved again", "now", "the count moved", a newer number appended after an older one). The old statement should be rewritten in place, not appended to.
-- HISTORY: narrates how things got here: which branch/PR changed what, "closed on", "did not survive", review-pass stories, pick-by-pick rounds. The current state is what belongs; the trail goes to the PR or a decision log.
+- HISTORY: narrates how things got here: which branch/PR changed what, "closed on", "did not survive", review-pass stories, pick-by-pick rounds. The current state is what belongs; the trail goes to the PR.
 - MOVE: correct content on the wrong surface (domain mechanism in ARCHITECTURE.md, implementation detail in a wireframe).
 
 Return only JSON: {"verdict": "...", "quote": "<the shortest added phrase that decided it>", "reason": "<one sentence>"}

package/src/context/folders.ts

@@ -19,7 +19,6 @@ import { SURFACE_ROOTS } from '@/surface-root'
  */
 export const DEFAULT_FOLDERS: readonly string[] = [
   'context',
-  'decisions',
   'diagrams',
   'wireframes',
 ]

package/src/demo/compile.ts

@@ -134,8 +134,8 @@ export function compilePlan(draft: Draft, options: CompileOptions): DemoPlan {
     url: '',
     viewport: VIEWPORT,
     output: {
-      video: `${options.outDir}/${options.slug}.webm`,
-      still: `${options.outDir}/${options.slug}.png`,
+      video: `${options.outDir}/${options.slug}/take/${options.slug}.webm`,
+      still: `${options.outDir}/${options.slug}/take/${options.slug}.png`,
     },
     pointer: { travelMs: POINTER_TRAVEL_MS, typeDelayMs: TYPE_DELAY_MS },
     annotations: ANNOTATIONS,
@@ -252,8 +252,12 @@ export function parsePlan(text: string): PlanParse {
       },
       ...(colorScheme.value && { colorScheme: colorScheme.value }),
       output: {
-        video: asText(output.video) || `demos/${slug || 'demo'}.webm`,
-        still: asText(output.still) || `demos/${slug || 'demo'}.png`,
+        video:
+          asText(output.video) ||
+          `demos/${slug || 'demo'}/take/${slug || 'demo'}.webm`,
+        still:
+          asText(output.still) ||
+          `demos/${slug || 'demo'}/take/${slug || 'demo'}.png`,
       },
       pointer: {
         travelMs: asNumber(pointer.travelMs, POINTER_TRAVEL_MS),

package/src/demo/container.ts

@@ -135,7 +135,7 @@ export async function convertToGif(
 
 /**
  * Written beside the video by default, so frames fall under the same
- * `demos/*.png` gitignore entry the still already uses with no new rule
+ * `take` folder gitignore entry the still already uses with no new rule
  * needed. One frame a second by default, matched to the seconds-to-tens-of-
  * seconds length a tuned recording runs, without a smarter sampling strategy
  * nobody has asked for.

package/src/gov/renames.ts

@@ -34,8 +34,9 @@ export function loadRenames(root: string): Renames {
 
 /**
  * Follows a declared rename to the name the toolkit ships the rule under now,
- * through every later rename of that name. The ledger is never pruned, so a
- * target several releases behind still reaches the current name.
+ * through every later rename of that name. The ledger is pruned only once a
+ * rule is retired, so a target several releases behind still reaches the
+ * current name of every rule that still ships.
  *
  * Returns nothing when the chain ends on a name with no source, or loops,
  * since installing a guess is worse than the retire the caller falls back to.

package/src/help.ts

@@ -45,6 +45,7 @@ export const COMMAND_GROUPS: { title: string; rows: CommandRow[] }[] = [
       ['drive <url> <run>', 'Walk a page through interactions, measure each'],
       ['transcripts <url>', 'Fetch a YouTube transcript with frontmatter'],
       ['teach [cmd]', 'Learning workspaces (list, open, resource, glossary)'],
+      ['canvas [cmd]', 'Local canvas of pages and frames (serve, list)'],
     ],
   },
   {

package/src/record-root.ts

@@ -64,6 +64,7 @@ export const RECORD_ENTRIES: readonly string[] = [
   '.records.git',
   SCRATCH,
   'README.md',
+  'canvas',
   'diagrams',
   'evidence',
   'feedback',