@erclx/canon 4.86.0 → 4.88.0

package/src/cli.ts

@@ -72,7 +72,7 @@ function showHelp(): void {
     `${GREY}│${NC}    demo [cmd]         ${GREY}# Record a running app (compile, run)${NC}`,
     `${GREY}│${NC}    inventory [subj]   ${GREY}# Report one computed property across every route${NC}`,
     `${GREY}│${NC}    drive <url> <run>  ${GREY}# Walk a page through named interactions and measure each state${NC}`,
-    `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .canon/review/feedback/${NC}`,
+    `${GREY}│${NC}    feedback           ${GREY}# Write toolkit feedback from stdin to .canon/feedback/${NC}`,
     `${GREY}│${NC}    transcripts <url>  ${GREY}# Fetch a YouTube transcript with metadata frontmatter${NC}`,
     `${GREY}│${NC}    tasks [cmd]        ${GREY}# Task board commands (archive)${NC}`,
     `${GREY}│${NC}    intake [cmd]       ${GREY}# Intake folders under .canon/intake/ (list, answer)${NC}`,

package/src/commands/design.ts

@@ -16,7 +16,7 @@ import {
   isOwnCheckout,
   PROJECT_ROOT,
 } from '@/project-root'
-import { creationRel } from '@/record-root'
+import { creationRel, SCRATCH } from '@/record-root'
 import { surfaceDir } from '@/surface-root'
 import { recordStamp, runDomainSync } from '@/sync/engine'
 import { resolveTarget } from '@/target'
@@ -113,7 +113,7 @@ export function register(program: Command): void {
     .option(
       '-o, --out <path>',
       'Output directory',
-      creationRel(process.cwd(), 'review', 'design'),
+      creationRel(process.cwd(), SCRATCH, 'render', 'design'),
     )
     .action((opts: { source: string; out: string }) => {
       const sourcePath = resolve(process.cwd(), opts.source)
@@ -143,7 +143,7 @@ export function register(program: Command): void {
     .option(
       '-o, --out <path>',
       'Output directory',
-      creationRel(process.cwd(), 'review', 'board'),
+      creationRel(process.cwd(), SCRATCH, 'render', 'board'),
     )
     .option('--root <path>', 'Project root, defaulting to the main worktree')
     .addHelpText(

package/src/commands/feedback.ts

@@ -40,20 +40,20 @@ function isToolkitSource(): boolean {
 }
 
 /**
- * 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.
+ * One producer, one record folder. Feedback is not a review, so it writes
+ * under a root folder of its own rather than inside `review/`, and `canon
+ * records push` backs it with no list edit, since it carries every `.canon/`
+ * entry it does not exclude.
  */
 function writeLocal(body: string, mismatch: string | undefined): string {
-  // Resolved against the same root the write joins onto, so a checkout that has
-  // not migrated its records writes this beside the ones already there rather
-  // than opening a second root nothing reads.
-  const relativeDir = creationRel(PROJECT_ROOT, 'review', 'feedback')
-  const reviewDir = join(PROJECT_ROOT, relativeDir)
-  mkdirSync(reviewDir, { recursive: true })
+  // Resolved against the same root the write joins onto. `creationRel` reads
+  // whichever root already carries a `feedback/` folder and falls back to the
+  // creation root when neither does.
+  const relativeDir = creationRel(PROJECT_ROOT, 'feedback')
+  const feedbackDir = join(PROJECT_ROOT, relativeDir)
+  mkdirSync(feedbackDir, { recursive: true })
   const filename = `feedback-${deriveSlug(body)}-${timestamp()}.md`
-  const filePath = join(reviewDir, filename)
+  const filePath = join(feedbackDir, filename)
   writeFileSync(filePath, `${body}\n`, 'utf8')
 
   // Manual frame rather than `frameSuccess`, since the mismatch warning is a
@@ -72,7 +72,7 @@ export function register(program: Command): void {
   program
     .command('feedback')
     .description(
-      'Write toolkit feedback from stdin to .canon/review/feedback/, or open a GitHub issue with --github',
+      'Write toolkit feedback from stdin to .canon/feedback/, or open a GitHub issue with --github',
     )
     .option(
       '--github',

package/src/commands/migrate.ts

@@ -671,7 +671,7 @@ interface ScratchEvidenceOptions {
 
 /**
  * Moves the nine cited-and-unwritten folders under `.canon/tmp/` to
- * `.canon/review/evidence/`, and repoints the citations that name them,
+ * `.canon/evidence/`, and repoints the citations that name them,
  * archives included.
  */
 async function runScratchEvidence(
@@ -760,9 +760,10 @@ interface RecordLayoutOptions {
 }
 
 /**
- * Moves review receipts from `.canon/review/memory/` to `.canon/memory/review/`
- * and retired entries from `.canon/tmp/memory-archive/` to
- * `.canon/memory/archive/`, and repoints the citations that name either.
+ * Moves every row of `RECORD_LAYOUT_MOVES`: the memory pen's receipts and
+ * retired entries under `.canon/memory/`, and everything under
+ * `.canon/review/` that is not a review out to its own folder, then repoints
+ * the citations that name any of them.
  */
 async function runRecordLayout(opts: RecordLayoutOptions): Promise<number> {
   const root = opts.root ?? process.cwd()
@@ -797,7 +798,7 @@ async function runRecordLayout(opts: RecordLayoutOptions): Promise<number> {
 
   const applied = await applyRecordLayout(plan)
   logStep(
-    `Moved ${plural(applied.moved, 'folder')} and rewrote ${plural(applied.written, 'file')}.`,
+    `Moved ${plural(applied.moved, 'path')} and rewrote ${plural(applied.written, 'file')}.`,
   )
 
   if (applied.failed.length > 0) {
@@ -810,9 +811,10 @@ async function runRecordLayout(opts: RecordLayoutOptions): Promise<number> {
 }
 
 function reportRecordLayout(plan: RecordLayoutPlan): void {
-  logInfo(`${plural(plan.moves.length, 'folder')} to move.`)
+  logInfo(`${plural(plan.moves.length, 'path')} to move.`)
   for (const move of plan.moves) {
-    logInfo(`  ${move.from} -> ${move.to}`)
+    const label = move.classified === undefined ? '' : ` (${move.classified})`
+    logInfo(`  ${move.from} -> ${move.to}${label}`)
   }
 
   logInfo(
@@ -837,7 +839,11 @@ function toRecordLayoutRecord(
   return {
     ok: true,
     wrote: wrote === true,
-    moves: plan.moves.map((move) => ({ from: move.from, to: move.to })),
+    moves: plan.moves.map((move) => ({
+      from: move.from,
+      to: move.to,
+      ...(move.classified === undefined ? {} : { classified: move.classified }),
+    })),
     collisions: plan.collisions,
     files: plan.entries.length,
     rewritten: plan.rewritten,
@@ -1097,7 +1103,7 @@ export function register(program: Command): void {
 
   migrate
     .command('scratch-evidence')
-    .description('Promote cited measurement folders out of tmp into review')
+    .description('Promote cited measurement folders out of tmp into evidence')
     .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')
@@ -1110,7 +1116,7 @@ export function register(program: Command): void {
       [
         '',
         'Moves nine folders cited as measurement evidence from .canon/tmp/ to',
-        '.canon/review/evidence/, which canon records push already backs, and',
+        '.canon/evidence/<nn>-<folder>/, numbered by first appearance, and',
         'repoints every citation that names one, live or archived.',
         '',
         'A promoted folder is one a durable record cites and no source file',
@@ -1136,7 +1142,7 @@ export function register(program: Command): void {
 
   migrate
     .command('record-layout')
-    .description('Fold memory review receipts and archive under memory/')
+    .description('Move record folders to their batch layout')
     .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')
@@ -1151,8 +1157,25 @@ export function register(program: Command): void {
         'Moves review receipts from .canon/review/memory/ to',
         '.canon/memory/review/, and retired entries from',
         '.canon/tmp/memory-archive/ to .canon/memory/archive/, backed for',
-        'the first time, and repoints every citation that names either,',
-        'live or archived.',
+        'the first time.',
+        '',
+        'Leaves .canon/review/ holding only reviews:',
+        '  review/feedback/                -> feedback/',
+        '  review/{design,board,slides,diagrams}/ -> tmp/render/<kind>/',
+        '  review/references/              -> picks/references/',
+        '  review/branch/review-<slug>.md  -> review/branch-<slug>.md',
+        '  review/ui-checklist-<slug>.md   -> tmp/handoff/ui-checklist/<slug>.md',
+        '  review/evidence/<slug>/         -> picks/<slug>/ or evidence/<nn>-<slug>/',
+        '',
+        'An evidence folder is a pick when it directly holds an arm-<id>',
+        'capture or a design-handoff.md, and evidence otherwise. Evidence',
+        'folders are numbered by the oldest file each holds, continuing past',
+        'any ordinal evidence/ already carries. The dry run labels every',
+        'derived destination, so check the split before passing --write.',
+        '',
+        'A citation reaching into a moved folder or naming a moved file is',
+        'repointed, live or archived. A bare mention of an emptied folder, such',
+        'as review/evidence/ with no slug, matches no row and stays as written.',
         '',
         'A receipt sitting at the flat review/ root, the shape memory-review',
         'wrote before review/memory/ existed, is reported rather than moved.',

package/src/commands/records.ts

@@ -10,6 +10,12 @@ import {
   isOrdinalKind,
   ORDINAL_KINDS,
 } from '@/records/ordinal'
+import {
+  DEFAULT_OLDER_THAN_DAYS,
+  type PruneReport,
+  type PruneUnit,
+  pruneScratch,
+} from '@/records/prune'
 import {
   type FolderSize,
   formatBytes,
@@ -50,6 +56,9 @@ const EXIT_MIGRATABLE = 2
 /** Returned when `--claim` loses every retry to a collision. */
 const EXIT_CONTENDED = 2
 
+/** Returned when candidates exist and `--write` was not passed. */
+const EXIT_PRUNABLE = 2
+
 interface ValidateCommandOptions {
   readonly json?: boolean
   readonly root?: string
@@ -61,6 +70,11 @@ interface MigrateCommandOptions extends ValidateCommandOptions {
   readonly write?: boolean
 }
 
+interface PruneCommandOptions extends ValidateCommandOptions {
+  readonly write?: boolean
+  readonly olderThan?: string
+}
+
 interface OrdinalCommandOptions extends ValidateCommandOptions {
   readonly claim?: boolean
 }
@@ -233,6 +247,55 @@ export function register(program: Command): void {
       process.exitCode = await runSize(opts)
     })
 
+  records
+    .command('prune-tmp')
+    .description('Report scratch nobody has touched in a while, and delete it')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .option('--write', 'Delete every candidate the report lists')
+    .option(
+      '--older-than <days>',
+      `Age in days a unit's newest file must clear to be offered (default ${DEFAULT_OLDER_THAN_DAYS})`,
+    )
+    .option('--root <path>', 'Project root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'A candidate is a unit whose newest file is older than --older-than:',
+        '  a tmp/<slug>/ folder, a folder one level inside runs/, render/, or',
+        '  pr/, or a single marker file inside hooks/<hook>/. A unit with no',
+        '  files is offered whatever its age.',
+        '',
+        'tmp/handoff/ and tmp/pr/poll/ are never offered, since a reader deletes',
+        'a handoff itself and a poll baseline is live state. The pre-split names',
+        'the same two folders replaced (memory-routing/, teach-promotion/,',
+        'ui-checklist/, pr-poll/) are skipped the same way rather than offered',
+        'as ordinary slugs.',
+        '',
+        'Exit codes:',
+        '  0  nothing to prune, or --write deleted every candidate',
+        '  1  refused, with the reason on stderr or in the JSON record, or a',
+        '     delete failed',
+        '  2  candidates exist and --write was not passed',
+        '',
+        'It writes nothing until --write is passed, matching canon records',
+        'migrate: a session record has no history to undo a wrong delete from.',
+        'It reads mtime like canon records size, so a machine restored by canon',
+        'records pull reads everything as new, which fails safe by offering',
+        'nothing.',
+        '',
+        'Examples:',
+        '  canon records prune-tmp',
+        '  canon records prune-tmp --write',
+        '  canon records prune-tmp --older-than 30 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: PruneCommandOptions) => {
+      process.exitCode = await runPruneTmp(opts)
+    })
+
   records
     .command('push')
     .description(
@@ -390,6 +453,102 @@ function reportSize(outcome: Extract<SizeOutcome, { ok: true }>): void {
   outro()
 }
 
+async function runPruneTmp(opts: PruneCommandOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+  const olderThan = Number(opts.olderThan ?? DEFAULT_OLDER_THAN_DAYS)
+
+  if (!Number.isFinite(olderThan) || olderThan <= 0) {
+    return reportRefusal(
+      'canon records prune-tmp',
+      {
+        reason: 'bad-older-than',
+        message: `--older-than must be a positive number of days, got ${opts.olderThan}.`,
+      },
+      emitJson,
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const write = opts.write ?? false
+  const outcome = await pruneScratch(root, olderThan, write)
+
+  if (!outcome.ok)
+    return reportRefusal('canon records prune-tmp', outcome, emitJson)
+
+  return reportPrune(outcome, emitJson)
+}
+
+function pruneRow(entry: PruneUnit): string[] {
+  return [
+    entry.path,
+    String(entry.files),
+    formatBytes(entry.bytes),
+    entry.newest ?? '',
+  ]
+}
+
+function pruneExitCode(outcome: PruneReport): number {
+  if (outcome.failed.length > 0) return 1
+  if (outcome.candidates.length > 0 && outcome.deleted.length === 0)
+    return EXIT_PRUNABLE
+  return 0
+}
+
+function reportPrune(outcome: PruneReport, emitJson: boolean): number {
+  const exit = pruneExitCode(outcome)
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify(outcome)}\n`)
+    return exit
+  }
+
+  intro('canon records prune-tmp')
+
+  if (outcome.candidates.length === 0) {
+    logStep('Prunable')
+    logInfo(`none, older than ${plural(outcome.olderThan, 'day')}`)
+  } else {
+    logStep(outcome.deleted.length > 0 ? 'Deleted' : 'Prunable')
+
+    const headers = ['path', 'files', 'size', 'newest']
+    const rows = outcome.candidates.map(pruneRow)
+    const widths = headers.map((header, column) =>
+      columnWidth(
+        header,
+        rows.map((row) => row[column]),
+      ),
+    )
+    const render = (cells: readonly string[]): string =>
+      cells
+        .map((cell, column) =>
+          column === 0
+            ? cell.padEnd(widths[column])
+            : cell.padStart(widths[column]),
+        )
+        .join('  ')
+        .trimEnd()
+
+    pipeOutput([render(headers), ...rows.map(render)].join('\n'))
+
+    if (outcome.deleted.length === 0) logInfo('Re-run with --write to delete.')
+  }
+
+  if (outcome.skipped.length > 0) {
+    logStep('Skipped')
+    for (const entry of outcome.skipped)
+      logInfo(`${entry.path}: ${entry.reason}`)
+  }
+
+  if (outcome.failed.length > 0) {
+    logStep('Failed')
+    for (const entry of outcome.failed)
+      logWarn(`${entry.path}: ${entry.message}`)
+  }
+
+  outro()
+  return exit
+}
+
 async function runPush(opts: BackupCommandOptions): Promise<number> {
   const root = opts.root ?? (await mainWorktreeRoot())
   const outcome = await pushRecords(root)

package/src/commands/slides.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
-import { creationRel } from '@/record-root'
+import { creationRel, SCRATCH } from '@/record-root'
 import { LAYOUTS } from '@/slides/layouts'
 import { openDeck } from '@/slides/open'
 import { renderSlidesDoc } from '@/slides/render'
@@ -20,7 +20,7 @@ export function register(program: Command): void {
     .option(
       '-o, --out <path>',
       'Output directory',
-      creationRel(process.cwd(), 'review', 'slides'),
+      creationRel(process.cwd(), SCRATCH, 'render', 'slides'),
     )
     .option('-v, --variant <variant>', 'Override variant (light or dark)')
     .option(

package/src/design/board.ts

@@ -399,7 +399,7 @@ function isImage(name: string): boolean {
   return IMAGE_EXTENSIONS.some((ext) => name.toLowerCase().endsWith(ext))
 }
 
-/** Every image file directly inside an evidence arm folder, one level deep. */
+/** Every image file directly inside a pick folder, one level deep. */
 function imagesIn(dir: string): string[] {
   return readdirSync(dir, { withFileTypes: true })
     .filter((entry) => entry.isFile() && isImage(entry.name))
@@ -407,32 +407,39 @@ function imagesIn(dir: string): string[] {
     .sort()
 }
 
+/**
+ * The folder under `picks/` holding operator-supplied reference images, which
+ * the References panel reads. It sits beside the captures of the choices it
+ * fed, so the candidates panel steps over it rather than listing it as a pick.
+ */
+const REFERENCES_FOLDER = 'references'
+
 function writeCandidatesPanel(root: string, outDir: string): void {
   const dir = join(outDir, 'candidates')
   mkdirSync(dir, { recursive: true })
 
-  const evidenceDir = recordDir(root, 'review', 'evidence')
-  if (!existsSync(evidenceDir)) {
+  const picksDir = recordDir(root, 'picks')
+  if (!existsSync(picksDir)) {
     writeFileSync(
       join(dir, 'index.html'),
       panelPage(
         'Past candidates',
-        `<p class="empty">No ${relative(root, evidenceDir)} folder yet.</p>`,
+        `<p class="empty">No ${relative(root, picksDir)} folder yet.</p>`,
       ),
     )
     return
   }
 
-  const folders = readdirSync(evidenceDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
+  const folders = readdirSync(picksDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name !== REFERENCES_FOLDER)
     .map((entry) => entry.name)
     .sort()
 
   const found: Array<{ folder: string; images: string[] }> = []
   for (const folder of folders) {
-    const images = imagesIn(join(evidenceDir, folder))
+    const images = imagesIn(join(picksDir, folder))
     if (images.length > 0) {
-      cpSync(join(evidenceDir, folder), join(dir, folder), { recursive: true })
+      cpSync(join(picksDir, folder), join(dir, folder), { recursive: true })
       found.push({ folder, images })
     }
   }
@@ -442,7 +449,7 @@ function writeCandidatesPanel(root: string, outDir: string): void {
       join(dir, 'index.html'),
       panelPage(
         'Past candidates',
-        `<p class="empty">${folders.length} folders under ${relative(root, evidenceDir)}/ and none carries a draft-and-pick arm capture. The archival capture step has not run since it shipped.</p>`,
+        `<p class="empty">${folders.length} folders under ${relative(root, picksDir)}/ and none carries a draft-and-pick arm capture. The archival capture step has not run since it shipped.</p>`,
       ),
     )
     return
@@ -462,7 +469,7 @@ function writeReferencesPanel(root: string, outDir: string): void {
   const dir = join(outDir, 'references')
   mkdirSync(dir, { recursive: true })
 
-  const referencesDir = recordDir(root, 'review', 'references')
+  const referencesDir = recordDir(root, 'picks', REFERENCES_FOLDER)
   if (!existsSync(referencesDir)) {
     writeFileSync(
       join(dir, 'index.html'),

package/src/migrate/evidence-ordinal.ts

@@ -0,0 +1,79 @@
+/**
+ * How a folder under `.canon/evidence/` is numbered, shared by the two
+ * migrations that land folders there.
+ *
+ * A folder takes `<nn>-<slug>` in the order folders first appeared, and a new
+ * one continues past the highest ordinal already present. No record folder is
+ * tracked in git, so file modification times are the only history a target
+ * holds to order by.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { extractOrdinal } from '@/intake/folder'
+
+const ORDINAL_WIDTH = 2
+
+/**
+ * When a folder first appeared, read as the oldest modification time of any
+ * file under it. A folder holding no file falls back to its own.
+ */
+export function firstAppearance(dir: string): number {
+  let oldest = Number.POSITIVE_INFINITY
+
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name)
+    const time = entry.isDirectory()
+      ? firstAppearance(path)
+      : statSync(path).mtimeMs
+    oldest = Math.min(oldest, time)
+  }
+
+  return Number.isFinite(oldest) ? oldest : statSync(dir).mtimeMs
+}
+
+/** The folder names directly inside `dir`, sorted, or none when it is absent. */
+export function folderNames(dir: string): string[] {
+  if (!existsSync(dir)) return []
+
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+}
+
+/** A folder name with any leading ordinal removed. */
+export function slugOf(name: string): string {
+  const ordinal = extractOrdinal(name)
+  return ordinal === '' ? name : name.slice(ordinal.length + 1)
+}
+
+/** The ordinal a new folder takes after every name already present. */
+export function nextOrdinal(existing: readonly string[]): number {
+  return (
+    existing
+      .map((name) => Number(extractOrdinal(name) || 0))
+      .reduce((carry, ordinal) => Math.max(carry, ordinal), 0) + 1
+  )
+}
+
+/** The folder name an ordinal and a slug make together. */
+export function numberedName(ordinal: number, slug: string): string {
+  return `${String(ordinal).padStart(ORDINAL_WIDTH, '0')}-${slug}`
+}
+
+/**
+ * Orders candidate folders by first appearance, breaking an exact tie on the
+ * name so two runs over one tree number it the same way.
+ */
+export function byFirstAppearance<T extends { name: string; dir: string }>(
+  folders: readonly T[],
+): T[] {
+  return folders
+    .map((folder) => ({ folder, appeared: firstAppearance(folder.dir) }))
+    .sort(
+      (a, b) =>
+        a.appeared - b.appeared || a.folder.name.localeCompare(b.folder.name),
+    )
+    .map(({ folder }) => folder)
+}