@erclx/canon 4.65.0 → 4.67.0

package/src/commands/migrate.ts

@@ -5,6 +5,7 @@ import { listRepositoryFiles } from '@/git-files'
 import { indexSourceRules } from '@/gov/adapter'
 import { applyRecordsMove, applyRename, readSources } from '@/migrate/apply'
 import { isToolkitOwned, planRename, type RenamePlan } from '@/migrate/plan'
+import { AITK_RULES, type RenameRules } from '@/migrate/rename'
 import {
   applyRecordTree,
   planRecordTree,
@@ -24,6 +25,7 @@ import {
   type RuleLayoutPlan,
   walkFlatRules,
 } from '@/migrate/rule-layout'
+import { SKILL_NAME_MAP, SKILL_NAME_RULES } from '@/migrate/skill-names'
 import {
   applyScratchEvidence,
   planScratchEvidence,
@@ -31,14 +33,17 @@ import {
   type ScratchEvidencePlan,
   walkScratchEvidenceCorpus,
 } from '@/migrate/scratch-evidence'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { readStamp, stampedHashes } from '@/sync/stamp'
-import { logError, logInfo, logStep, logWarn, pipeOutput, plural } from '@/ui'
+import { logError, logInfo, logStep, logWarn, plural } from '@/ui'
 
-interface RenameOptions {
+interface SweepOptions {
   readonly json?: boolean
   readonly write?: boolean
   readonly root?: string
+}
+
+interface RenameOptions extends SweepOptions {
   readonly scope?: string
 }
 
@@ -51,12 +56,11 @@ function isScope(value: string): value is Scope {
 }
 
 /**
- * Reports rather than writes without `--write`, matching `canon records
- * migrate`. A rename touching this many files has no undo short of the branch
- * it ran on, so the safe outcome sits on the default path.
+ * The `aitk` sweep, which is the one rename with a second population to name.
+ * A target holds toolkit-owned folders whose content came from here beside
+ * prose that project wrote, and the scope is what separates them.
  */
 async function runRename(opts: RenameOptions): Promise<number> {
-  const root = opts.root ?? process.cwd()
   const scope = opts.scope ?? 'self'
 
   if (!isScope(scope)) {
@@ -64,6 +68,33 @@ async function runRename(opts: RenameOptions): Promise<number> {
     return 1
   }
 
+  return runSweep(opts, AITK_RULES, scope)
+}
+
+/**
+ * The skill rename owns no scope. Every folder it moves is authored here, and
+ * no target holds a copy of this repository's skill catalog, so there is no
+ * second population for a caller to name.
+ */
+async function runSkillNames(opts: SweepOptions): Promise<number> {
+  return runSweep(opts, SKILL_NAME_RULES, undefined)
+}
+
+/**
+ * One sweep over a repository's tracked files under whichever rules it was
+ * handed.
+ *
+ * Reports rather than writes without `--write`, matching `canon records
+ * migrate`. A rename touching this many files has no undo short of the branch
+ * it ran on, so the safe outcome sits on the default path.
+ */
+async function runSweep(
+  opts: SweepOptions,
+  rules: RenameRules,
+  scope: Scope | undefined,
+): Promise<number> {
+  const root = opts.root ?? process.cwd()
+
   const files = await listRepositoryFiles(root)
   if (files === undefined) {
     logError(`Could not list files under ${root}. Is it a git repository?`)
@@ -72,7 +103,7 @@ async function runRename(opts: RenameOptions): Promise<number> {
 
   const scoped = scope === 'target' ? files.filter(isToolkitOwned) : files
   const sources = await readSources(root, scoped)
-  const plan = planRename(sources)
+  const plan = planRename(sources, rules)
 
   // A target scope reports the citations it did not rewrite, since prose the
   // project wrote is theirs to change and a sweep editing it underneath them
@@ -84,12 +115,15 @@ async function runRename(opts: RenameOptions): Promise<number> {
             root,
             files.filter((f) => !isToolkitOwned(f)),
           ),
+          rules,
         ).entries.length
       : 0
 
+  // 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) {
-    pipeOutput(
-      JSON.stringify(toRecord(plan, scope, citations, opts.write), null, 2),
+    process.stdout.write(
+      `${JSON.stringify(toRecord(plan, scope, citations, opts.write), null, 2)}\n`,
     )
   }
 
@@ -115,8 +149,12 @@ async function runRename(opts: RenameOptions): Promise<number> {
   return 0
 }
 
-function report(plan: RenamePlan, scope: Scope, citations: number): void {
-  logInfo(`Scope ${scope}.`)
+function report(
+  plan: RenamePlan,
+  scope: Scope | undefined,
+  citations: number,
+): void {
+  if (scope !== undefined) logInfo(`Scope ${scope}.`)
   logInfo(
     `${plural(plan.entries.length, 'file')} to change, ${plural(plan.renamed, 'occurrence')} to rewrite.`,
   )
@@ -138,12 +176,12 @@ function report(plan: RenamePlan, scope: Scope, citations: number): void {
 
 function toRecord(
   plan: RenamePlan,
-  scope: Scope,
+  scope: Scope | undefined,
   citations: number,
   wrote: boolean | undefined,
 ): unknown {
   return {
-    scope,
+    ...(scope === undefined ? {} : { scope }),
     wrote: wrote === true,
     files: plan.entries.length,
     renamed: plan.renamed,
@@ -584,6 +622,9 @@ interface RuleLayoutOptions {
 async function runRuleLayout(opts: RuleLayoutOptions): Promise<number> {
   const root = opts.root ?? process.cwd()
 
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
   const files = await walkFlatRules(root)
   const hashes = stampedHashes(readStamp(root), 'governance')
   const catalog = new Set(indexSourceRules(PROJECT_ROOT).keys())
@@ -848,6 +889,45 @@ export function register(program: Command): void {
       process.exitCode = await runRename(opts)
     })
 
+  migrate
+    .command('skill-names')
+    .description('Move the prefixed skill folders onto their two-word names')
+    .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',
+      [
+        '',
+        `Rewrites ${Object.keys(SKILL_NAME_MAP).length} skill names and moves the folders that carry them.`,
+        'It takes no scope. The skill folders it moves are authored in the',
+        'toolkit and no target holds a copy of that catalog, so in a target it',
+        'rewrites citations of a renamed skill and moves nothing.',
+        '',
+        'Exit codes:',
+        '  0  nothing to rewrite, or --write applied the whole plan',
+        '  1  refused, or a move failed',
+        '  2  a plan exists and --write was not passed',
+        '',
+        'The changelog is never rewritten, and neither is an eval transcript.',
+        'Each records what shipped or what a session ran under the name that',
+        'was current then.',
+        '',
+        'Examples:',
+        '  canon migrate skill-names',
+        '  canon migrate skill-names --write',
+        '  canon migrate skill-names --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: SweepOptions) => {
+      process.exitCode = await runSkillNames(opts)
+    })
+
   migrate
     .command('rule-layout')
     .description('Move installed rules from the flat layout onto canon/')

package/src/commands/sandbox.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Command } from 'commander'
 import { execScript } from '@/exec'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import {
   assertedPercent,
   collectCensus,
@@ -286,6 +286,9 @@ function runCoverage(options: CoverageOptions): void {
 
   intro('canon sandbox coverage')
 
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
   const report = collectCoverage(PROJECT_ROOT)
 
   // A broken `exempt.toml` reads as a caller error, not as a crash. The parser
@@ -341,6 +344,9 @@ function runCheck(
 ): void {
   intro('canon sandbox check')
 
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
   const parsed = parseTarget(target)
   if (parsed === undefined) {
     logError('Invalid target. Use <category>:<command>, e.g. claude:docs.')

package/src/commands/snippets.ts

@@ -1,9 +1,9 @@
 import type { Command } from 'commander'
 import { registerPassThroughVerbs } from '@/commands/pass-through'
-import { PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { BASE_CATEGORY } from '@/snippets/categories'
 import { buildSnippetsCatalog } from '@/snippets/list'
-import { intro, logInfo, logStep, outro } from '@/ui'
+import { intro, logInfo, logStep, logWarn, outro } from '@/ui'
 
 const PASS_THROUGH_VERBS = ['create'] as const
 
@@ -42,14 +42,20 @@ export function register(program: Command): void {
  * emitted section headers and the pass-through above it owned the `┌`.
  */
 function runList(opts: ListOptions): number {
+  // The warning is a frame-interior line, so it goes out after `intro` on the
+  // path that opens one and bare on the `--json` path, which returns first and
+  // opens none. One position cannot serve both.
+  const mismatch = checkoutMismatchWarning(process.cwd())
   const catalog = buildSnippetsCatalog(PROJECT_ROOT)
 
   if (opts.json) {
+    if (mismatch !== undefined) logWarn(mismatch)
     process.stdout.write(`${JSON.stringify(catalog)}\n`)
     return 0
   }
 
   intro('canon snippets list')
+  if (mismatch !== undefined) logWarn(mismatch)
 
   const showCategories = opts.entries !== true
   const showEntries = opts.categories !== true

package/src/commands/tooling.ts

@@ -1,7 +1,7 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { execScript } from '@/exec'
-import { findCheckoutMismatch, PROJECT_ROOT } from '@/project-root'
+import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import {
   injectConfigs,
   injectGitignore,
@@ -180,14 +180,20 @@ export function register(program: Command): void {
  * pass-through loop below skips the `intro` the shared helper carries.
  */
 function runList(opts: ListOptions): number {
+  // The warning is a frame-interior line, so it goes out after `intro` on the
+  // path that opens one and bare on the `--json` path, which returns first and
+  // opens none. One position cannot serve both.
+  const mismatch = checkoutMismatchWarning(process.cwd())
   const stacks = buildStackSummaries(PROJECT_ROOT)
 
   if (opts.json) {
+    if (mismatch !== undefined) logWarn(mismatch)
     process.stdout.write(`${JSON.stringify({ stacks })}\n`)
     return 0
   }
 
   intro('canon tooling list')
+  if (mismatch !== undefined) logWarn(mismatch)
   logStep('Stacks')
   for (const summary of stacks) logInfo(describeStack(summary))
   outro()
@@ -229,6 +235,9 @@ function printReference(stack: string): number {
  * stack the way it drove `merge_gitignore` before.
  */
 function prepare(stack: string, target: string, skip?: string): Prepared {
+  const mismatch = checkoutMismatchWarning(process.cwd())
+  if (mismatch !== undefined) logWarn(mismatch)
+
   if (!stackExists(PROJECT_ROOT, stack)) {
     return { ok: false, error: `Stack not found: ${stack}` }
   }
@@ -268,13 +277,6 @@ async function runSync(
 ): Promise<number> {
   intro('canon tooling sync')
 
-  const mismatch = findCheckoutMismatch(process.cwd())
-  if (mismatch !== undefined) {
-    logWarn(
-      `Resolved via ${PROJECT_ROOT}, not the checkout at ${mismatch}. Run \`bun ${mismatch}/src/cli.ts tooling sync ...\` to sync against that checkout instead.`,
-    )
-  }
-
   if (opts.check === true && opts.write === true) {
     logWarn('Pass --check or --write, not both.')
     outro()

package/src/demo/container.ts

@@ -1,3 +1,4 @@
+import { existsSync, mkdirSync, rmSync } from 'node:fs'
 import { join, parse } from 'node:path'
 import { execa } from 'execa'
 
@@ -20,6 +21,15 @@ export type GifResult =
   | { status: 'skipped'; reason: 'converter-missing' }
   | { status: 'failed'; reason: string }
 
+export type FramesResult =
+  | { status: 'extracted'; framePaths: string[] }
+  | { status: 'skipped'; reason: 'converter-missing' }
+  | { status: 'failed'; reason: string }
+
+export interface ExtractFramesOptions {
+  readonly fps?: number
+}
+
 /**
  * Writes mp4 beside the webm rather than instead of it, since both stated use
  * cases are a `<video>` tag on a page the operator controls, where webm
@@ -122,3 +132,88 @@ export async function convertToGif(
   }
   return { status: 'converted', gifPath }
 }
+
+/**
+ * Written beside the video by default, so frames fall under the same
+ * `demos/*.png` 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.
+ *
+ * The missing-binary and failure handling matches `convertToMp4` exactly: the
+ * recording already succeeded by the time this runs, so an optional step
+ * never fails the run.
+ *
+ * A prior extraction's frames are cleared before ffmpeg runs, not left for
+ * `-y` to overwrite. ffmpeg's `-y` only overwrites the indices this run
+ * produces, so a shorter re-extraction against the same video's stable
+ * output path (the plan's declared `output.video`, unchanged across
+ * re-records) would otherwise leave the previous run's tail in place,
+ * sorted into the returned list as if it were still current.
+ */
+export async function extractFrames(
+  videoPath: string,
+  outDir?: string,
+  opts: ExtractFramesOptions = {},
+  bin: string = CONVERTER_BIN,
+): Promise<FramesResult> {
+  const { dir, name } = parse(videoPath)
+  const targetDir = outDir ?? dir
+  const fps = opts.fps ?? 1
+  if (outDir) mkdirSync(outDir, { recursive: true })
+
+  if (existsSync(targetDir)) {
+    for (const stale of new Bun.Glob(`${name}-frame-*.png`).scanSync({
+      cwd: targetDir,
+      onlyFiles: true,
+    })) {
+      rmSync(join(targetDir, stale))
+    }
+  }
+
+  const pattern = join(targetDir, `${name}-frame-%03d.png`)
+  const result = await execa(
+    bin,
+    ['-y', '-i', videoPath, '-vf', `fps=${fps}`, pattern],
+    { reject: false },
+  )
+
+  if (result.failed && result.code === 'ENOENT') {
+    return { status: 'skipped', reason: 'converter-missing' }
+  }
+  if (result.exitCode !== 0) {
+    return {
+      status: 'failed',
+      reason: result.stderr?.trim() || `ffmpeg exited ${result.exitCode}`,
+    }
+  }
+
+  return { status: 'extracted', framePaths: collectFrames(targetDir, name) }
+}
+
+/**
+ * The glob-and-sort step `extractFrames` reads its result from, pulled out so
+ * a test can drive it against a directory it wrote by hand rather than
+ * through a real extraction, which is the only way to reach the four-digit
+ * boundary below without an ffmpeg run long enough to produce one.
+ *
+ * ffmpeg's `%03d` pads to three characters and then widens rather than
+ * truncating, so a run producing 1000 or more frames writes `-1000.png`
+ * beside `-999.png`, and a lexicographic sort reads the wider name first.
+ * `frameIndex` sorts on the parsed number instead.
+ */
+export function collectFrames(targetDir: string, name: string): string[] {
+  return [
+    ...new Bun.Glob(`${name}-frame-*.png`).scanSync({
+      cwd: targetDir,
+      onlyFiles: true,
+    }),
+  ]
+    .sort((a, b) => frameIndex(a) - frameIndex(b))
+    .map((frame) => join(targetDir, frame))
+}
+
+function frameIndex(filename: string): number {
+  const match = filename.match(/-frame-(\d+)\.png$/)
+  return match ? Number(match[1]) : 0
+}