@erclx/canon 4.9.2 → 4.11.0

package/src/commands/migrate.ts

@@ -4,6 +4,13 @@ import type { Command } from 'commander'
 import { listRepositoryFiles } from '@/git-files'
 import { applyRecordsMove, applyRename, readSources } from '@/migrate/apply'
 import { isToolkitOwned, planRename, type RenamePlan } from '@/migrate/plan'
+import {
+  applyRecordTree,
+  planRecordTree,
+  readRecordTree,
+  type RecordTreePlan,
+  walkRecordTree,
+} from '@/migrate/record-tree'
 import {
   ignoresDestination,
   isRecordArtifact,
@@ -280,6 +287,125 @@ function toRecordsRecord(
   }
 }
 
+interface RecordTreeOptions {
+  readonly json?: boolean
+  readonly write?: boolean
+  readonly root?: string
+}
+
+/**
+ * Repoints the old-root citations left inside the record tree itself.
+ *
+ * The sibling verb sweeps a git listing, which reaches every tracked file and
+ * none of the records, since those are gitignored by construction. This one
+ * walks the new root directly and is scoped to the folders a session still
+ * follows a path into, so the closed trails and the scratch folder keep saying
+ * what they say.
+ *
+ * No ignore gate here. Nothing moves, so there is no destination whose ignore
+ * status could publish a record, and a run in a project the move has not
+ * reached finds no new root to walk and reports nothing.
+ */
+async function runRecordTree(opts: RecordTreeOptions): Promise<number> {
+  const root = opts.root ?? process.cwd()
+
+  const walk = await walkRecordTree(root)
+  const plan = planRecordTree(
+    await readRecordTree(root, walk.files),
+    walk.excluded,
+    walk.skipped,
+  )
+
+  // stdout, so the record pipes clean. `pipeOutput` frames to stderr, which is
+  // where this command's report belongs and where a JSON record does not.
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify(toRecordTreeRecord(plan, walk.files.length, opts.write))}\n`,
+    )
+  }
+
+  reportRecordTree(plan, walk.files.length)
+
+  if (plan.entries.length === 0) return 0
+
+  if (!opts.write) {
+    logWarn('Nothing was written. Pass --write to apply this plan.')
+    return 2
+  }
+
+  const applied = await applyRecordTree(root, plan)
+  logStep(`Rewrote ${plural(applied.written, 'file')}.`)
+
+  if (applied.failed.length > 0) {
+    logError(`Could not write ${plural(applied.failed.length, 'file')}.`)
+    for (const path of applied.failed) logError(`  ${path}`)
+    return 1
+  }
+
+  return 0
+}
+
+/** How much of a citation's line the report prints before it wraps. */
+const LINE_WIDTH = 160
+
+function excerpt(text: string): string {
+  return text.length <= LINE_WIDTH ? text : `${text.slice(0, LINE_WIDTH)}…`
+}
+
+/**
+ * Names every citation with the line it sits on.
+ *
+ * The record tree is untracked and unbacked, so a wrong rewrite has no git undo
+ * and a count would give a reader nothing to judge before passing `--write`.
+ * The excluded corpora take the opposite treatment for the same reason
+ * `reportRecords` counts the records it skips: they are thousands of files
+ * nobody is being asked to check.
+ */
+function reportRecordTree(plan: RecordTreePlan, swept: number): void {
+  logInfo(`${plural(swept, 'file')} in the live record surface.`)
+  logInfo(
+    `${plural(plan.entries.length, 'file')} to change, ${plural(plan.rewritten, 'citation')} to rewrite.`,
+  )
+
+  for (const entry of plan.entries) {
+    for (const line of entry.lines) {
+      logInfo(`  ${entry.path}:${line.line}  ${excerpt(line.text)}`)
+    }
+  }
+
+  logInfo(`${plural(plan.kept, 'citation')} marked to keep the old root.`)
+
+  for (const corpus of plan.excluded) {
+    logInfo(`  ${corpus.path}: ${plural(corpus.files, 'file')}, left alone.`)
+  }
+
+  for (const path of plan.skipped) {
+    logInfo(`  ${path}: a git object store, skipped by name.`)
+  }
+}
+
+function toRecordTreeRecord(
+  plan: RecordTreePlan,
+  swept: number,
+  wrote: boolean | undefined,
+): unknown {
+  return {
+    ok: true,
+    wrote: wrote === true,
+    swept,
+    files: plan.entries.length,
+    rewritten: plan.rewritten,
+    kept: plan.kept,
+    excluded: plan.excluded,
+    skipped: plan.skipped,
+    paths: plan.entries.map((entry) => ({
+      path: entry.path,
+      rewritten: entry.rewritten,
+      lines: entry.lines,
+    })),
+  }
+}
+
 export function register(program: Command): void {
   const migrate = program
     .command('migrate')
@@ -328,6 +454,53 @@ export function register(program: Command): void {
       process.exitCode = await runRecords(opts)
     })
 
+  migrate
+    .command('record-tree')
+    .description('Repoint old-root citations inside the records themselves')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--write', 'Apply the plan rather than reporting it')
+    .option(
+      '--root <path>',
+      'Project root, defaulting to the working directory',
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Run this after canon migrate records. That verb sweeps a git listing,',
+        'so it reaches every tracked file and none of the records, which are',
+        'gitignored by construction. This one walks the new root itself.',
+        '',
+        'Scope: diagrams, memory, plans, proposals, review, tasks, and teach,',
+        'each minus its own archive subtree. The closed trails under groundwork',
+        'and intake, the scratch folder, and the backup history are reported as',
+        'counts and never rewritten, since a path inside a closed trail is part',
+        'of a sentence about work that already ended.',
+        '',
+        'Exit codes:',
+        '  0  nothing to rewrite, or --write applied the whole plan',
+        '  1  a write failed',
+        '  2  a plan exists and --write was not passed',
+        '',
+        'Every citation is reported with its file, its line, and the line text.',
+        'The records are untracked and unbacked, so a wrong rewrite has no undo',
+        'and the report is what a reader judges before passing --write.',
+        '',
+        'A line carrying canon-keep-record-root, or the line below it, keeps the',
+        'old root. Prose that dates a decision needs it; a live path does not.',
+        '',
+        'Examples:',
+        '  canon migrate record-tree',
+        '  canon migrate record-tree --write',
+        '  canon migrate record-tree --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RecordTreeOptions) => {
+      process.exitCode = await runRecordTree(opts)
+    })
+
   migrate
     .command('rename')
     .description('Rewrite every unprotected aitk token to canon')

package/src/design/base.css

@@ -6,12 +6,14 @@
 :root {
   --color-background: #191512;
   --color-surface: #211c19;
+  --color-chrome: #241e1a;
   --color-border: #2f2823;
   --color-text: #f4efe9;
   --color-text-body: #c9c0b7;
   --color-text-secondary: #a79d94;
   --color-muted: #948a81;
   --color-accent: #e0724b;
+  --color-success: #61c454;
   --color-light-background: #faf7f2;
   --color-light-surface: #f4efe6;
   --color-light-text: #1a1815;
@@ -43,7 +45,7 @@
   --radius-marker: 999px;
 }
 
-/* The record declares no light counterpart for text-body, text-secondary, so
+/* The record declares no light counterpart for chrome, text-body, text-secondary, success, so
    a light-ground surface using one is reading a dark value. Declare the
    counterpart in src/design/tokens.ts rather than overriding it here. */
 [data-theme='light'] {

package/src/design/tokens.ts

@@ -80,7 +80,9 @@ export const TOKENS: DesignTokens = {
     '',
     'The values below are the system rather than a reading of one. Until 2026-09-01 this record transcribed two surfaces and agreed with nothing else, which is what made a change to it reach nobody. The slide theme, the token preview, and a teach workspace stylesheet now read the module this file is rendered from, so a value changed there changes what all three render.',
     '',
-    'Two surfaces still carry their own copies. The rendered hero at `assets/hero.html` is written by `scripts/core/regen-hero.sh` against a committed capture, and the terminal framing in `scripts/lib/ui.sh` and `src/ui.ts` writes ANSI rather than hex. The dark half below is the palette the hero carries, so the two agree today by value and not yet by construction.',
+    'The two rendered captures read it as well. `scripts/core/regen-hero.sh` fills `assets/hero.html.tmpl` and `assets/install.html.tmpl` with what `canon design css --no-components` emits, so both frames now carry the custom properties rather than their own copies of the hex, and a value moved here moves what the next capture renders.',
+    '',
+    'The terminal framing is the one surface left holding its own values, and that is a decision rather than a gap. `scripts/lib/ui.sh` and `src/ui.ts` each spell six escape constants, and `.claude/ARCHITECTURE.md` records one color source per language with a check behind each, so generating a third spelling from here would break the rule those two checks enforce. What the record is still incomplete about is the other half of those six: `WHITE` and `GREY` name no role below, so the terminal palette is described here in part rather than in whole.',
   ].join('\n'),
 
   personality: [
@@ -90,7 +92,9 @@ export const TOKENS: DesignTokens = {
   colorNote: [
     'Every role clears WCAG AA at 4.5:1 against each ground it declares, asserted in `src/design/contrast.test.ts`. Two corrections landed with this record becoming the source. The light `muted` step moved from `#7A736A`, which read 4.38 and 4.09 against the two light grounds, and the dark `accent` moved off the `#C8602E` the slide theme carried, which read 4.36 and 3.99 against the two dark ones. Both now sit on the values below.',
     '',
-    'Success, warning, and error hold ANSI codes because that is what `scripts/lib/ui.sh` writes, and no rendered surface implements an equivalent. Giving them a hex value would invent a mapping no file has, so they carry no contrast reading either.',
+    'Warning and error hold ANSI codes because that is what `scripts/lib/ui.sh` writes and no rendered surface implements an equivalent. Giving either a hex value would invent a mapping no file has, so they carry no contrast reading either.',
+    '',
+    'Success is the one of the three that does have a rendered equivalent, which is why it carries a hex. `assets/install.html` marks every confirmed step with it, and the shell writes `ANSI 32` for the same role, so the two are one role in two registers rather than one value in two spellings. The hex is what the rendered surface picked and no reading claims the terminal renders that value. It declares `background` alone as its ground, since that is the only role it is drawn on, where every other dark text role is drawn on both.',
   ].join('\n'),
 
   color: [
@@ -104,6 +108,11 @@ export const TOKENS: DesignTokens = {
       intent: 'cards, panels, raised blocks',
       value: '#211c19',
     },
+    {
+      role: 'chrome',
+      intent: 'the window titlebar, one step above the canvas',
+      value: '#241e1a',
+    },
     {
       role: 'border',
       intent: 'every rule and panel edge',
@@ -139,7 +148,12 @@ export const TOKENS: DesignTokens = {
       value: '#e0724b',
       grounds: DARK_GROUNDS,
     },
-    { role: 'success', intent: 'terminal confirmations', value: 'ANSI 32' },
+    {
+      role: 'success',
+      intent: 'confirmations, rendered and in the terminal',
+      value: '#61c454',
+      grounds: ['background'],
+    },
     { role: 'warning', intent: 'terminal cautions', value: 'ANSI 33' },
     { role: 'error', intent: 'terminal failures', value: 'ANSI 31' },
     {

package/src/gate/measures.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto'
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 export interface CommandResult {
@@ -99,8 +99,8 @@ export const SANDBOX_UNDECLARED_CEILING = 47
  */
 export const AUDITS_BASELINE = '.claude/canon/baseline.json'
 
-export const HERO_STAMP_FAILURE =
-  'The hero set disagrees with the stamp written when the image was captured. Run canon capture assets/hero.html --selector .window and commit all three files together.'
+export const CAPTURE_STAMP_FAILURE =
+  'A capture set disagrees with the stamp written when its image was captured. Run canon capture assets --selector .window and commit each frame with its image and its stamp.'
 
 function parseJson(payload: string): unknown {
   try {
@@ -585,6 +585,27 @@ async function collectPluginManifests(ctx: MeasureContext): Promise<string[]> {
   return [...seen].sort()
 }
 
+const CAPTURE_DIR = 'assets'
+
+/**
+ * Every capture under `assets/`, named by the base its three files share.
+ *
+ * Read off the folder rather than listed, and off the markup specifically,
+ * because that is how `resolveCaptureSources` decides what `canon capture
+ * assets` renders. A list would fail open on the frame somebody adds next,
+ * which is the one nobody thinks to add here, and driving off the PNGs instead
+ * would report a missing set for any image in the folder that is not a capture.
+ */
+function captureBases(root: string): string[] {
+  const dir = join(root, CAPTURE_DIR)
+  if (!existsSync(dir)) return []
+
+  return readdirSync(dir)
+    .filter((name) => name.endsWith('.html'))
+    .map((name) => name.slice(0, -'.html'.length))
+    .sort()
+}
+
 /**
  * The drift assert on the Hero stage covers the markup because the image beside
  * it is a chromium render whose bytes move with the browser. That leaves the
@@ -600,36 +621,37 @@ async function collectPluginManifests(ctx: MeasureContext): Promise<string[]> {
  *
  * Both digests are checked because either file can move alone. The markup side
  * catches an edit committed with no capture, and the image side catches an
- * image replaced under markup that never changed. All three absent passes,
- * which is correct for a tree that carries none of them.
+ * image replaced under markup that never changed. A tree carrying no markup
+ * under `assets/` has no set to read and passes, which is correct.
  */
-export const heroStamp: Measure = async (ctx) => {
-  const set = [
-    ['assets/hero.html', join(ctx.root, 'assets/hero.html')],
-    ['assets/hero.png', join(ctx.root, 'assets/hero.png')],
-    ['assets/hero.stamp', join(ctx.root, 'assets/hero.stamp')],
-  ] as const
-
-  if (set.every(([, path]) => !existsSync(path))) return { emissions: [] }
-
-  const missing = set
-    .filter(([, path]) => !existsSync(path))
-    .map(([label]) => label)
+export const captureStamps: Measure = async (ctx) => {
+  const lines = captureBases(ctx.root).flatMap((base) =>
+    readCaptureSet(ctx.root, base),
+  )
+  if (lines.length === 0) return { emissions: [] }
+
+  return {
+    emissions: [output(lines.join('\n'))],
+    failure: CAPTURE_STAMP_FAILURE,
+  }
+}
+
+/** One capture set, as the lines it has to report and none where it agrees. */
+function readCaptureSet(root: string, base: string): string[] {
+  const set = (['html', 'png', 'stamp'] as const).map(
+    (extension) => `${CAPTURE_DIR}/${base}.${extension}`,
+  )
+
+  const missing = set.filter((rel) => !existsSync(join(root, rel)))
   if (missing.length > 0) {
-    return {
-      emissions: [output(`Missing from the hero set: ${missing.join(' ')}`)],
-      failure: HERO_STAMP_FAILURE,
-    }
+    return [`Missing from the ${base} set: ${missing.join(' ')}`]
   }
 
-  const [[, html], [, png], [, stamp]] = set
-  const lines = [
-    ...assertStampField(ctx.root, stamp, 'source-sha256', html),
-    ...assertStampField(ctx.root, stamp, 'image-sha256', png),
+  const [html, png, stamp] = set.map((rel) => join(root, rel))
+  return [
+    ...assertStampField(root, stamp, 'source-sha256', html),
+    ...assertStampField(root, stamp, 'image-sha256', png),
   ]
-  if (lines.length === 0) return { emissions: [] }
-
-  return { emissions: [output(lines.join('\n'))], failure: HERO_STAMP_FAILURE }
 }
 
 /**

package/src/gate/stages.ts

@@ -1,6 +1,6 @@
 import {
   auditSet,
-  heroStamp,
+  captureStamps,
   markdownBans,
   type Measure,
   pluginManifests,
@@ -181,17 +181,21 @@ export const STAGES: readonly Stage[] = [
     // render whose bytes move with the browser version, so a drift check over it
     // would fail on a machine whose chromium differs rather than on a stale
     // count. The stamp measure below is what covers the image instead.
+    //
+    // The stage covers both frames under `assets/` and keeps the narrower name,
+    // because the label is spelled across the context entries and the CI table
+    // and renaming it buys nothing the pathspec below does not already say.
     id: 'hero',
     label: 'Hero',
     checks: [
       script('regen-hero.sh', 'Hero regen failed'),
       {
         kind: 'drift',
-        pathspec: 'assets/hero.html',
+        pathspec: 'assets/*.html',
         failure:
-          'Hero counts drifted. Run bun run check, then canon capture assets/hero.html --selector .window, and commit assets/hero.html with assets/hero.png and assets/hero.stamp.',
+          'A generated frame drifted from the catalogs or the design source. Run bun run check, then canon capture assets --selector .window, and commit each assets/*.html with its .png and .stamp.',
       },
-      { kind: 'measure', measure: heroStamp },
+      { kind: 'measure', measure: captureStamps },
     ],
     success: 'Hero clean',
   },

package/src/github-format.ts

@@ -4,6 +4,29 @@ export interface CreateIssueOptions {
   labels?: string[]
 }
 
+/**
+ * Why a `gh issue create` call produced no URL. The two reasons reach the
+ * operator as different repairs, which is the whole reason the helper returns a
+ * discriminated result rather than a nullable string: an absent binary is
+ * something to install, and a failed call is something the stderr explains.
+ */
+export type IssueFailureReason = 'missing-binary' | 'command-failed'
+
+export interface IssueFailure {
+  readonly ok: false
+  readonly reason: IssueFailureReason
+  readonly detail?: string
+}
+
+export interface IssueSuccess {
+  readonly ok: true
+  readonly url: string
+}
+
+export type CreateIssueResult = IssueSuccess | IssueFailure
+
+const ISSUE_URL = 'https://github.com/erclx/canon/issues/new'
+
 export function buildIssueArgs(opts: CreateIssueOptions): string[] {
   const args = ['issue', 'create', '--title', opts.title, '--body', opts.body]
   for (const label of opts.labels ?? []) {
@@ -11,3 +34,42 @@ export function buildIssueArgs(opts: CreateIssueOptions): string[] {
   }
   return args
 }
+
+/**
+ * Collapses to one line. Both callers write the detail inside a framed error or
+ * a colored warning, and a newline in the middle of either breaks the frame and
+ * leaves the color reset stranded after the last line. `gh` writes multi-line
+ * diagnostics routinely, so this is the ordinary case rather than the edge.
+ */
+function oneLine(text: string): string {
+  return text.trim().replace(/\s+/g, ' ')
+}
+
+/**
+ * Pulls the operator-readable half out of whatever the spawn threw. `gh` writes
+ * its own diagnosis to stderr, so that is preferred over the wrapper's message,
+ * which names the exit status and nothing about the cause.
+ */
+export function failureDetail(error: unknown): string {
+  if (typeof error === 'object' && error !== null) {
+    const stderr = (error as { stderr?: unknown }).stderr
+    if (typeof stderr === 'string' && stderr.trim()) return oneLine(stderr)
+    const short = (error as { shortMessage?: unknown }).shortMessage
+    if (typeof short === 'string' && short.trim()) return oneLine(short)
+    const message = (error as { message?: unknown }).message
+    if (typeof message === 'string' && message.trim()) return oneLine(message)
+  }
+  return 'gh failed with no diagnostic on stderr'
+}
+
+/**
+ * The sentence the operator reads. It sits beside the argument builder so both
+ * reasons are asserted without spawning `gh`, which is the distinction the
+ * nullable return left untestable.
+ */
+export function issueFailureMessage(failure: IssueFailure): string {
+  if (failure.reason === 'missing-binary') {
+    return `gh is not installed, so no issue was filed. Install gh, or file it at ${ISSUE_URL}`
+  }
+  return `gh could not file the issue: ${failure.detail ?? 'no diagnostic on stderr'}`
+}

package/src/github.ts

@@ -1,14 +1,19 @@
 import { execa } from 'execa'
 import { gitEnv } from '@/git-env'
 import { PROJECT_ROOT } from '@/project-root'
-import { buildIssueArgs, type CreateIssueOptions } from '@/github-format'
+import {
+  buildIssueArgs,
+  failureDetail,
+  type CreateIssueOptions,
+  type CreateIssueResult,
+} from '@/github-format'
 
 const GH_TIMEOUT_MS = 30_000
 
 export async function createGithubIssue(
   opts: CreateIssueOptions,
-): Promise<string | null> {
-  if (Bun.which('gh') === null) return null
+): Promise<CreateIssueResult> {
+  if (Bun.which('gh') === null) return { ok: false, reason: 'missing-binary' }
   try {
     // See src/worktrees/reclaim.ts for why gh needs the stripped environment.
     const result = await execa('gh', buildIssueArgs(opts), {
@@ -17,8 +22,14 @@ export async function createGithubIssue(
       env: gitEnv(),
       extendEnv: false,
     })
-    return result.stdout.trim() || null
-  } catch {
-    return null
+    const url = result.stdout.trim()
+    if (url) return { ok: true, url }
+    return {
+      ok: false,
+      reason: 'command-failed',
+      detail: 'gh exited zero and printed no issue URL',
+    }
+  } catch (error) {
+    return { ok: false, reason: 'command-failed', detail: failureDetail(error) }
   }
 }