@erclx/canon 4.87.0 → 4.88.0

package/src/commands/migrate.ts

@@ -1164,7 +1164,7 @@ export function register(program: Command): void {
         '  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/ui-checklist/<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>',

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/migrate/record-layout.ts

@@ -6,7 +6,7 @@
  * feedback moves to `.canon/feedback/`, option captures to `.canon/picks/`,
  * claim-backing folders to a numbered `.canon/evidence/`, renders rebuilt from
  * committed sources to `.canon/tmp/render/`, a branch report flattens to
- * `review/branch-<slug>.md`, and a flat checklist joins the `tmp/ui-checklist/`
+ * `review/branch-<slug>.md`, and a flat checklist joins the `tmp/handoff/ui-checklist/`
  * handoff folder. `canon records push` carries every top-level `.canon/`
  * entry except `EXCLUDED_ENTRIES`, so the new root folders are backed with no
  * list edit, and `tmp/render/` is deliberately not.
@@ -120,7 +120,7 @@ export const RECORD_LAYOUT_MOVES: readonly RecordLayoutMove[] = [
     kind: 'files',
     from: ['review'],
     prefix: 'ui-checklist-',
-    to: [SCRATCH, 'ui-checklist'],
+    to: [SCRATCH, 'handoff', 'ui-checklist'],
     renamed: '',
     prune: false,
   },

package/src/migrate/scratch-evidence.ts

@@ -48,11 +48,9 @@ import { recordDir, SCRATCH } from '@/record-root'
  * `verify-astro` and `verify-vite-react` pass the same test and are excluded
  * by name: both are scaffolds a command generates rather than records a
  * session wrote, and each is 100+ MB, which the review remote is not sized
- * for. `ablation`, `eval-runs`, `sandbox-runs`, `memory-archive`,
- * `groundwork-fixtures`, `precompact-handoff`, `pr-poll`, `pr`,
- * `address-review`, and `memory-routing` fail the second clause: a script or
- * a skill body names each of those paths, so moving one needs a code change
- * first rather than a promotion.
+ * for. `ablation`, `runs`, `memory-archive`, `hooks`, `pr`, and `handoff`
+ * fail the second clause: a script or a skill body names each of those
+ * paths, so moving one needs a code change first rather than a promotion.
  */
 export const PROMOTED_FOLDERS: readonly string[] = [
   'hero-probe',