@erclx/canon 5.32.0 → 5.34.0

package/src/commands/canvas.ts

@@ -9,12 +9,15 @@ import {
   DEFAULT_FRAME,
   listPages,
   moveFrame,
+  pruneLayout,
   readPage,
   readSelection,
   renamePage,
   resizeFrame,
 } from '@/canvas/content'
+import { planArrange } from '@/canvas/arrange'
 import { captureCanvas, captureComposite } from '@/canvas/capture'
+import { fitCanvas, isOwed } from '@/canvas/fit'
 import {
   type EditRefused,
   editFrameAtIndex,
@@ -148,7 +151,7 @@ export function register(program: Command): void {
     .command('canvas')
     .helpOption('-h, --help', 'Show this help message')
     .description(
-      'Local canvas of pages and HTML frames (serve, list, page, frame, selection, edit, editing, capture)',
+      'Local canvas of pages and HTML frames (serve, list, page, frame, selection, edit, editing, capture, fit, arrange)',
     )
     .addHelpText(
       'after',
@@ -167,6 +170,8 @@ export function register(program: Command): void {
         "  canon canvas edit drafts/hero --element 4 --set 'color=var(--color-accent)'",
         '  canon canvas editing drafts/hero',
         '  canon canvas capture drafts/hero',
+        '  canon canvas fit drafts/hero --json',
+        '  canon canvas arrange drafts --check',
         '  canon canvas list --json',
         '',
       ].join('\n'),
@@ -728,6 +733,179 @@ export function register(program: Command): void {
       outro()
       if (failed) process.exitCode = 1
     })
+
+  withRoot(
+    canvas
+      .command('fit')
+      .description("Set each frame's height to its content")
+      .argument('<target>', '<page>/<frame> for one frame, <page> for all')
+      .option('--check', 'Report what is owed and write nothing'),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Measures each frame in the capture browser at its box width, through',
+        'the served address, so the faces the canvas serves are the ones read.',
+        'The height is the content height rounded up, with no margin. A',
+        'content wider than the box is reported and the box is never widened.',
+        'A frame whose body text names a family the canvas does not serve is',
+        'reported as font, since its height may not hold in another browser.',
+        '',
+        'Run canvas arrange after a fit that grew a frame, since rows below',
+        'do not move on their own.',
+        '',
+        'Exit codes:',
+        '  0  written, or nothing owed under --check',
+        '  1  refused or the browser failed',
+        '  2  --check found a height off, a wide frame, or a font',
+        '',
+      ].join('\n'),
+    )
+    .action(async (target: string, opts: FitOptions) => {
+      process.exitCode = await runFit(target, opts)
+    })
+
+  withRoot(
+    canvas
+      .command('arrange')
+      .description('Re-lay a page in rows on the frame gap')
+      .argument('<page>', 'Page to arrange')
+      .option('--check', 'Report what is owed and write nothing'),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Keeps the rows the frames already sit in, orders each left to right on',
+        'the frame gap, stacks the rows on their tallest frame, and drops',
+        'layout entries whose frame file is gone.',
+        '',
+        'Exit codes:',
+        '  0  written, or nothing owed under --check',
+        '  1  refused',
+        '  2  --check found frames to move or entries to drop',
+        '',
+      ].join('\n'),
+    )
+    .action(async (pageName: string, opts: FitOptions) => {
+      process.exitCode = await runArrange(pageName, opts)
+    })
+}
+
+interface FitOptions extends RootOptions {
+  readonly check?: boolean
+}
+
+async function runFit(target: string, opts: FitOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+  const resolved = await resolveRoot(opts)
+  if (!resolved.ok) return refuse(resolved, emitJson)
+
+  const check = opts.check ?? false
+  let outcome: Awaited<ReturnType<typeof fitCanvas>>
+  try {
+    outcome = await fitCanvas(resolved.root, target, !check)
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    return refuse({ ok: false, reason: 'capture-failed', detail }, emitJson)
+  }
+  if (!outcome.ok) return refuse(outcome, emitJson)
+
+  const frames = outcome.rows.map((row) => ({ ...row, owed: isOwed(row) }))
+  const owed = frames.some((row) => row.owed)
+  if (emitJson) writeJson({ ok: true, written: outcome.written, frames })
+  intro(BANNER)
+  for (const row of frames) {
+    const name = `${row.page}/${row.frame}`
+    if (row.fitted === row.height) logInfo(`${name} fits at ${row.height}`)
+    else if (outcome.written) logAdd(`${name} ${row.height} to ${row.fitted}`)
+    else logStep(`${name} owes ${row.height} to ${row.fitted}`)
+    if (row.wide) logWarn(`${name} is wider than its box, so widen the box`)
+    if (row.viewport) {
+      logWarn(
+        `${name} sets a height in viewport units, so its height was not written and a fixed height fits it`,
+      )
+    }
+    if (row.font) {
+      logWarn(
+        `${name} sets ${row.family}, which the canvas does not serve, so its height may not hold in another browser`,
+      )
+    }
+  }
+  outro()
+  return check && owed ? 2 : 0
+}
+
+async function runArrange(pageName: string, opts: FitOptions): Promise<number> {
+  const emitJson = opts.json ?? false
+  const resolved = await resolveRoot(opts)
+  if (!resolved.ok) return refuse(resolved, emitJson)
+  const { root } = resolved
+
+  const page = readPage(root, pageName)
+  if (!page) {
+    return refuse(
+      {
+        ok: false,
+        reason: 'no-page',
+        detail: `page ${pageName} does not exist`,
+      },
+      emitJson,
+    )
+  }
+  if (page.layoutIssue) {
+    return refuse(
+      {
+        ok: false,
+        reason: 'malformed-layout',
+        detail: `${pageName}/layout.json does not parse`,
+      },
+      emitJson,
+    )
+  }
+
+  const check = opts.check ?? false
+  const pruned = pruneLayout(root, pageName, !check)
+  if (!pruned.ok) return refuse(pruned, emitJson)
+
+  const moves = planArrange(page.frames)
+  if (!check) {
+    for (const move of moves) {
+      const outcome = resizeFrame(root, pageName, move.name, move.to)
+      if (!outcome.ok) return refuse(outcome, emitJson)
+    }
+  }
+
+  if (emitJson) {
+    writeJson({
+      ok: true,
+      page: pageName,
+      written: !check,
+      moved: moves.map((move) => ({
+        frame: move.name,
+        from: { x: move.from.x, y: move.from.y },
+        to: { x: move.to.x, y: move.to.y },
+      })),
+      dropped: pruned.dropped,
+    })
+  }
+  intro(BANNER)
+  for (const move of moves) {
+    const text = `${pageName}/${move.name} ${move.from.x}, ${move.from.y} to ${move.to.x}, ${move.to.y}`
+    if (check) logStep(`${text} is owed`)
+    else logAdd(text)
+  }
+  for (const name of pruned.dropped) {
+    logWarn(
+      `${pageName}/${name} has no frame file, so its entry is ${check ? 'owed a drop' : 'dropped'}`,
+    )
+  }
+  if (moves.length === 0 && pruned.dropped.length === 0) {
+    logInfo(`${pageName} is already laid out`)
+  }
+  outro()
+  return check && (moves.length > 0 || pruned.dropped.length > 0) ? 2 : 0
 }
 
 interface CaptureOptions extends RootOptions {

package/src/commands/claude.ts

@@ -386,7 +386,7 @@ export function register(program: Command): void {
   skills
     .command('audit')
     .description(
-      'Report both skill corpora against the mechanical rules in standards/skill.md',
+      'Report both skill corpora against the mechanical rules in claude/skills/create-skill/references/skill.md',
     )
     .argument('[path]', 'Project root, defaulting to the current directory')
     .helpOption('-h, --help', 'Show this help message')

package/src/commands/gov.ts

@@ -12,7 +12,6 @@ import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
 import { creationRel, SCRATCH } from '@/roots/record'
 import { createGovAdapter } from '@/gov/adapter'
 import { regenConsumedRules } from '@/gov/consumed'
-import { regenStandardRules } from '@/gov/standard-rules'
 import { installRules, lookupRules } from '@/gov/install'
 import { buildGovCatalog, describeRule, describeStack } from '@/gov/list'
 import { buildRulesPayload, listRuleFiles } from '@/gov/payload'
@@ -20,6 +19,7 @@ import {
   govStackExists,
   listGovStacks,
   mergeExtraRules,
+  resolveExtraRules,
   resolveRules,
 } from '@/gov/stacks'
 import {
@@ -52,6 +52,7 @@ import {
   type TestOrderReport,
 } from '@/gov/test-order'
 import { recordStamp, runDomainSync } from '@/sync/engine'
+import { detectRules } from '@/gov/detect'
 import { writeChainStamp } from '@/sync/stamp'
 import { resolveTarget } from '@/targets/validate'
 import {
@@ -154,6 +155,11 @@ export function register(program: Command): void {
         '  canon gov install react',
         '  canon gov install node ../my-app',
         '  canon gov install astro --add 200-react,260-shadcn ../my-app',
+        '  canon gov install --add tasks,plan ../my-app',
+        '',
+        'With --add and no stack, the named rules install alone. A first',
+        'positional naming a stack is read as the stack, so pass . or a path',
+        'carrying a slash to force a target that shares a stack name.',
         '',
       ].join('\n'),
     )
@@ -191,18 +197,14 @@ export function register(program: Command): void {
 
   gov
     .command('regen')
-    .description(
-      "Rebuild the standard-pointer rules and a repository's own .claude/rules/",
-    )
+    .description("Rebuild a repository's own .claude/rules/")
     .helpOption('-h, --help', 'Show this help message')
     .option('--root <path>', 'Repository root to regenerate', PROJECT_ROOT)
     .addHelpText(
       'after',
       [
         '',
-        'First writes governance/rules/standards/ from the paths: and rule:',
-        'fields in each standard under standards/. Then reads',
-        'internal/governance.toml and installs the stack it names, plus any',
+        'Reads internal/governance.toml and installs the stack it names, plus any',
         'rules under internal/rules/. Unlike install and sync, this runs',
         'against the toolkit root, whose .claude/rules/ is produced output.',
         '',
@@ -226,6 +228,31 @@ export function register(program: Command): void {
       process.exitCode = runList(opts)
     })
 
+  gov
+    .command('detect')
+    .description('Propose opt-in rules from the evidence a target holds')
+    .argument('[target]', 'Target directory', '.')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--stack <stack>', 'Leave out every rule this stack resolves')
+    .option('--json', 'Emit machine-readable JSON')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Reads governance/detect.toml and matches each rule against the',
+        "target's manifests and git-listed paths to depth two. Pass the",
+        'proposals to canon gov install --add once confirmed.',
+        '',
+        'Examples:',
+        '  canon gov detect --json',
+        '  canon gov detect ../my-app --stack node --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (target: string, opts: DetectOptions) => {
+      process.exitCode = await runDetect(target, opts)
+    })
+
   gov
     .command('test-order')
     .description(
@@ -1075,6 +1102,7 @@ function runList(opts: ListOptions): number {
         ...(sections.stacks ? { stacks: catalog.stacks } : {}),
         ...(sections.rules ? { rules: catalog.rules } : {}),
         unreferenced: catalog.unreferenced,
+        staleDetect: catalog.staleDetect,
       })}\n`,
     )
     return 0
@@ -1102,6 +1130,51 @@ function runList(opts: ListOptions): number {
   return 0
 }
 
+interface DetectOptions {
+  readonly stack?: string
+  readonly json?: boolean
+}
+
+async function runDetect(target: string, opts: DetectOptions): Promise<number> {
+  const resolved = resolve(target)
+  if (!existsSync(resolved)) {
+    logError(`Target not found: ${target}`)
+    return 1
+  }
+
+  const result = await detectRules(PROJECT_ROOT, resolved, opts.stack)
+  if (!result.ok) {
+    logError(`Stack not found: ${result.missingStack}`)
+    return 1
+  }
+
+  if (opts.json) {
+    process.stdout.write(
+      `${JSON.stringify({
+        target: resolved,
+        stack: opts.stack ?? null,
+        proposals: result.proposals,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon gov detect')
+  if (result.proposals.length === 0) {
+    logInfo('No opt-in rule matched this target')
+  } else {
+    logStep('Proposed rules')
+    for (const proposal of result.proposals) {
+      const reasons = proposal.evidence
+        .map((evidence) => `${evidence.match} in ${evidence.path}`)
+        .join(', ')
+      logInfo(`${proposal.rule}: ${reasons}`)
+    }
+  }
+  outro()
+  return 0
+}
+
 /**
  * Silent on success so the consumed-copy stage that calls it stays quiet. It is
  * the only work that stage does now. The installed set is readable on disk, so
@@ -1121,14 +1194,6 @@ async function runRegen(
 
   const root = resolve(opts.root ?? PROJECT_ROOT)
 
-  // The consumed copy installs from `governance/rules/`, so the band this
-  // writes has to be fresh before that copy is built from it.
-  const generated = await regenStandardRules(root)
-  if (!generated.ok) {
-    process.stderr.write(`Standard-rules regen failed: ${generated.reason}\n`)
-    return 1
-  }
-
   const result = await regenConsumedRules(root)
 
   if (!result.ok) {
@@ -1184,6 +1249,11 @@ async function runInstall(
 ): Promise<number> {
   intro('canon gov install')
 
+  const add = opts.add ?? ''
+  if (add !== '' && isAddWithoutStack(stack, target)) {
+    return installExtras(add, stack ?? target)
+  }
+
   const resolved = resolveTarget(target, PROJECT_ROOT)
   if (typeof resolved === 'number') return resolved
 
@@ -1207,7 +1277,6 @@ async function runInstall(
     return 1
   }
 
-  const add = opts.add ?? ''
   const rules =
     add === '' ? resolution.rules : mergeExtraRules(resolution.rules, add)
 
@@ -1260,6 +1329,67 @@ async function runInstall(
   return 0
 }
 
+/**
+ * Whether `--add` runs with no stack under it. Commander fills the first
+ * positional before the second, so `--add a,b ../my-app` arrives with the
+ * target in `stack` and the default `.` in `target`. A first positional that
+ * names a stack keeps today's meaning, so a folder named `node` reads as the
+ * stack, and `.` or a path carrying a slash is how a caller forces the target.
+ */
+function isAddWithoutStack(stack: string | undefined, target: string): boolean {
+  if (stack === undefined) return true
+  if (target !== '.') return false
+  if (stack === '.' || stack.includes('/')) return true
+  return !govStackExists(PROJECT_ROOT, stack)
+}
+
+/**
+ * Installs `--add` names alone. The chain stamp is left as it was, since the
+ * extras are not a stack, and overwriting the chain would cost a target the
+ * missing-rule report its stack install recorded.
+ */
+async function installExtras(add: string, target: string): Promise<number> {
+  const resolved = resolveTarget(target, PROJECT_ROOT)
+  if (typeof resolved === 'number') return resolved
+
+  logStep('Resolving extras with no stack')
+
+  const { found, missing } = lookupRules(PROJECT_ROOT, resolveExtraRules(add))
+  for (const rule of missing) logWarn(`${rule} (source not found, skipping)`)
+  for (const source of found) logInfo(source.rule)
+
+  if (found.length === 0) {
+    logError('No named rule resolved, so nothing was installed.')
+    outro()
+    return 1
+  }
+
+  const shouldInstall = await select({
+    message: `Install ${found.length} rules to ${displayPath(target, CANON_RULES_REL)}?`,
+    options: [
+      { value: true, label: 'Yes' },
+      { value: false, label: 'No' },
+    ],
+    nonInteractiveDefault: true,
+  })
+
+  if (!shouldInstall) {
+    logWarn('Cancelled')
+    outro()
+    return 0
+  }
+
+  logStep('Installing rules')
+  for (const rel of await installRules(found, resolved)) logAdd(rel)
+
+  await recordStamp(createGovAdapter(PROJECT_ROOT), resolved, new Date())
+
+  const { GREEN, NC } = palette(process.stderr)
+  outro()
+  process.stderr.write(`${GREEN}✓ Rules installed${NC}\n`)
+  return 0
+}
+
 /**
  * Emits the rules payload the `gov-*` skills read. The output lands in the
  * target's scratch directory rather than stdout because the file is the