@erclx/canon 5.26.0 → 5.27.0

package/src/claude/skills-list.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { CORPORA } from '@/claude/skills-audit'
+import { isFamilyKey, SKILL_FAMILIES } from '@/claude/skills-families'
 
 const FRONTMATTER = /^---\n([\s\S]*?)\n---/
 
@@ -8,6 +9,11 @@ export interface SkillListing {
   readonly name: string
   readonly description: string
   readonly requirement: boolean
+  /**
+   * The `metadata.family` the frontmatter declares, read as written. Whether it
+   * names a vocabulary key is the audit's finding, not the listing's.
+   */
+  readonly family: string | null
 }
 
 export interface SkillsCorpus {
@@ -72,28 +78,83 @@ export function listSkillsAt(skillsRoot: string): SkillListing[] {
     }),
   ].sort()
 
-  return paths.map((path) => ({
-    name: dirname(path),
-    description: readDescription(join(skillsRoot, path)),
-    requirement: existsSync(join(skillsRoot, dirname(path), 'REQUIREMENT.md')),
-  }))
+  return paths.map((path) => {
+    const { description, family } = readListedFields(join(skillsRoot, path))
+    return {
+      name: dirname(path),
+      description,
+      requirement: existsSync(
+        join(skillsRoot, dirname(path), 'REQUIREMENT.md'),
+      ),
+      family,
+    }
+  })
+}
+
+export interface FamilyGroup {
+  readonly key: string
+  readonly group: string
+  readonly skills: readonly string[]
+}
+
+export interface FamilyGrouping {
+  /** Vocabulary order, holding only the families some listing declares. */
+  readonly groups: readonly FamilyGroup[]
+  /** Listings whose family is missing or names no vocabulary key. */
+  readonly unassigned: readonly string[]
+}
+
+export function groupByFamily(
+  listings: readonly SkillListing[],
+): FamilyGrouping {
+  const groups = SKILL_FAMILIES.map((family) => ({
+    ...family,
+    skills: listings
+      .filter((listing) => listing.family === family.key)
+      .map((listing) => listing.name),
+  })).filter((group) => group.skills.length > 0)
+
+  return {
+    groups,
+    unassigned: listings
+      .filter(
+        (listing) => listing.family === null || !isFamilyKey(listing.family),
+      )
+      .map((listing) => listing.name),
+  }
+}
+
+interface ListedFields {
+  readonly description: string
+  readonly family: string | null
 }
 
 /**
- * Returns an empty description rather than throwing on a skill whose
- * frontmatter is missing or unparseable, so one malformed file does not hide
- * the rest of the catalog from a caller counting it.
+ * Returns an empty description and a null family rather than throwing on a
+ * skill whose frontmatter is missing or unparseable, so one malformed file
+ * does not hide the rest of the catalog from a caller counting it.
  */
-function readDescription(path: string): string {
+function readListedFields(path: string): ListedFields {
+  const empty = { description: '', family: null }
   const match = FRONTMATTER.exec(readFileSync(path, 'utf8'))
-  if (!match) return ''
+  if (!match) return empty
 
+  let parsed: unknown
   try {
-    const parsed = Bun.YAML.parse(match[1])
-    if (typeof parsed !== 'object' || parsed === null) return ''
-    const { description } = parsed as Record<string, unknown>
-    return typeof description === 'string' ? description : ''
+    parsed = Bun.YAML.parse(match[1])
   } catch {
-    return ''
+    return empty
   }
+  if (!isRecord(parsed)) return empty
+
+  const { description, metadata } = parsed
+  const family = isRecord(metadata) ? metadata.family : undefined
+  return {
+    description: typeof description === 'string' ? description : '',
+    family: typeof family === 'string' ? family : null,
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
 }

package/src/commands/audits.ts

@@ -19,9 +19,9 @@ import {
   type Summary,
   summarize,
 } from '@/audits/run'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
-import { currentWorktreeRoot } from '@/worktree'
+import { currentWorktreeRoot } from '@/git/worktree'
 
 interface RunCommandOptions {
   readonly json?: boolean

package/src/commands/canvas.ts

@@ -12,6 +12,7 @@ import {
   readPage,
   readSelection,
   renamePage,
+  resizeFrame,
 } from '@/canvas/content'
 import { captureCanvas, captureComposite } from '@/canvas/capture'
 import {
@@ -19,10 +20,22 @@ import {
   editFrameAtIndex,
   STYLE_PROPERTIES,
 } from '@/canvas/edit'
+import {
+  clearEditing,
+  EDITING_TTL_MS,
+  markEditing,
+  readEditing,
+} from '@/canvas/editing'
 import { CANVAS_PORT, startCanvas } from '@/canvas/server'
 import { PROJECT_ROOT } from '@/project-root'
 import { resolveFrameTokens } from '@/canvas/tokens'
 import { displayPath, parsePort, waitForInterrupt } from '@/serve/report'
+import {
+  callerIdentity,
+  type Located,
+  resolveSessions,
+  selfOf,
+} from '@/sessions/resolve'
 import {
   intro,
   logAdd,
@@ -33,7 +46,7 @@ import {
   outro,
   plural,
 } from '@/ui'
-import { mainWorktreeRoot } from '@/worktree'
+import { mainWorktreeRoot } from '@/git/worktree'
 
 const BANNER = 'canon canvas'
 
@@ -135,7 +148,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, capture)',
+      'Local canvas of pages and HTML frames (serve, list, page, frame, selection, edit, editing, capture)',
     )
     .addHelpText(
       'after',
@@ -152,6 +165,7 @@ export function register(program: Command): void {
         '  canon canvas frame move drafts hero --x 200 --y 120',
         '  canon canvas selection --json',
         "  canon canvas edit drafts/hero --element 4 --set 'color=var(--color-accent)'",
+        '  canon canvas editing drafts/hero',
         '  canon canvas capture drafts/hero',
         '  canon canvas list --json',
         '',
@@ -341,6 +355,56 @@ export function register(program: Command): void {
     },
   )
 
+  withRoot(
+    frame
+      .command('resize')
+      .description('Resize a frame, and move it when given a position')
+      .argument('<page>', 'Page the frame is on')
+      .argument('<name>', 'Frame name')
+      .option('--width <px>', 'New width, defaulting to the frame width')
+      .option('--height <px>', 'New height, defaulting to the frame height')
+      .option('--x <px>', 'New x, defaulting to where the frame is')
+      .option('--y <px>', 'New y, defaulting to where the frame is'),
+  ).action(
+    async (
+      pageName: string,
+      name: string,
+      opts: RootOptions & {
+        width?: string
+        height?: string
+        x?: string
+        y?: string
+      },
+    ) => {
+      const resolved = await resolveRoot(opts)
+      if (!resolved.ok) {
+        process.exitCode = refuse(resolved, opts.json ?? false)
+        return
+      }
+      const { root } = resolved
+      const current = readPage(root, pageName)?.frames.find(
+        (candidate) => candidate.name === name,
+      )
+      const outcome = resizeFrame(root, pageName, name, {
+        x: parsePosition(opts.x, current?.x ?? 0),
+        y: parsePosition(opts.y, current?.y ?? 0),
+        width: parseSize(opts.width, current?.width ?? DEFAULT_FRAME.width),
+        height: parseSize(opts.height, current?.height ?? DEFAULT_FRAME.height),
+      })
+      if (!outcome.ok) {
+        process.exitCode = refuse(outcome, opts.json ?? false)
+        return
+      }
+      if (opts.json) writeJson(outcome)
+      intro(BANNER)
+      logAdd(`${outcome.page}/${outcome.file}`)
+      logInfo(
+        `${outcome.box.width} × ${outcome.box.height} at ${outcome.box.x}, ${outcome.box.y}`,
+      )
+      outro()
+    },
+  )
+
   withRoot(
     canvas
       .command('selection')
@@ -487,6 +551,91 @@ export function register(program: Command): void {
       },
     )
 
+  withRoot(
+    canvas
+      .command('editing')
+      .description('Mark a frame as being edited, clear it, or list the marks')
+      .argument('[target]', '<page>/<frame>, or none to list the marks')
+      .option('--done', 'Clear the mark once the edits are written')
+      .option('--by <name>', 'The label the mark shows, over the session name'),
+  )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Mark a frame before writing it and clear it with --done after, so an',
+        `open canvas shows who is editing it. A mark lapses after ${EDITING_TTL_MS / 60_000} minutes`,
+        'unless marked again, so re-mark during a long edit. A mark gates no',
+        'write, and --done on a frame holding no mark succeeds.',
+        '',
+      ].join('\n'),
+    )
+    .action(
+      async (
+        target: string | undefined,
+        opts: RootOptions & { done?: boolean; by?: string },
+      ) => {
+        const emitJson = opts.json ?? false
+        const resolved = await resolveRoot(opts)
+        if (!resolved.ok) {
+          process.exitCode = refuse(resolved, emitJson)
+          return
+        }
+        const { root } = resolved
+        const now = new Date()
+
+        if (target !== undefined) {
+          const [pageName, frameName, ...rest] = target.split('/')
+          if (!pageName || !frameName || rest.length > 0) {
+            process.exitCode = refuse(
+              {
+                ok: false,
+                reason: 'invalid-name',
+                detail: `${target} is not <page>/<frame>`,
+              },
+              emitJson,
+            )
+            return
+          }
+          const outcome = opts.done
+            ? clearEditing(root, pageName, frameName)
+            : markEditing(
+                root,
+                pageName,
+                frameName,
+                opts.by ?? (await sessionLabel()),
+                now,
+              )
+          if (!outcome.ok) {
+            process.exitCode = refuse(outcome, emitJson)
+            return
+          }
+        } else if (opts.done) {
+          process.exitCode = refuse(
+            {
+              ok: false,
+              reason: 'invalid-name',
+              detail: '--done needs the <page>/<frame> to clear',
+            },
+            emitJson,
+          )
+          return
+        }
+
+        const marks = readEditing(root, now)
+        if (emitJson) writeJson({ ok: true, editing: marks })
+        intro(BANNER)
+        if (target !== undefined) {
+          logStep(`${target} ${opts.done ? 'cleared' : 'marked'}`)
+        }
+        if (marks.length === 0) logInfo('No frame is marked as being edited')
+        for (const mark of marks) {
+          logInfo(`${mark.page}/${mark.frame}  ${mark.by} until ${mark.until}`)
+        }
+        outro()
+      },
+    )
+
   withRoot(
     canvas
       .command('capture')
@@ -644,6 +793,29 @@ async function runComposite(
   return 0
 }
 
+async function unlocated(): Promise<Located> {
+  return {
+    repository: null,
+    worktree: null,
+    branch: null,
+    unresolved: 'git-unavailable',
+  }
+}
+
+/**
+ * The caller's roster name, or a generic label when the environment names no
+ * session or the roster holds no row for it, as in a sandbox or a CI run.
+ */
+async function sessionLabel(): Promise<string> {
+  const identity = callerIdentity()
+  if (identity.sessionId === null && identity.pid === null) return 'a session'
+  /* The label needs the name alone, so skip the git probe each row's branch costs. */
+  const report = await resolveSessions({ locate: unlocated })
+  if (report.kind === 'absent') return 'a session'
+  const self = selfOf(report.sessions, identity)
+  return self.kind === 'self' ? self.session.name : 'a session'
+}
+
 /** NaN for a value that is not a number, which the content module refuses. */
 function parsePosition(raw: string | undefined, fallback: number): number {
   if (raw === undefined) return fallback
@@ -698,6 +870,11 @@ async function runServe(
   if (tokens.source === 'none') logWarn(tokens.notice)
   else if (tokens.source === 'installed') {
     for (const file of tokens.files) logInfo(file)
+    for (const face of tokens.dropped ?? []) {
+      logWarn(
+        `${face.sheet}: dropped the face at ${face.file} (${face.reason})`,
+      )
+    }
   } else logInfo('this toolkit’s own token module')
   logStep('Stop')
   logInfo('Ctrl-C')

package/src/commands/claude.ts

@@ -5,7 +5,7 @@ import { join, resolve } from 'node:path'
 import type { Command } from 'commander'
 import { execa } from 'execa'
 import { singleLine } from '@/commands/upgrade'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 import { claudeChain, pendingEntries, planGitignore } from '@/claude/gitignore'
 import {
   matchInstall,
@@ -44,7 +44,12 @@ import {
   scanRouting,
 } from '@/claude/routing'
 import { type DriftReport, readDrift } from '@/claude/skills-drift'
-import { listSkills } from '@/claude/skills-list'
+import { familyKeys, SKILL_FAMILIES } from '@/claude/skills-families'
+import {
+  type FamilyGrouping,
+  groupByFamily,
+  listSkills,
+} from '@/claude/skills-list'
 import {
   type ReachRefusal,
   type ReachReport,
@@ -64,12 +69,12 @@ import {
   serializeSettings,
   writeSettings,
 } from '@/claude/settings'
-import { copyPreservingMode } from '@/copy'
+import { copyPreservingMode } from '@/sync/copy'
 import { execScript } from '@/exec'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/project-root'
 import { recordDir } from '@/record-root'
 import { SURFACE_ENTRIES, surfaceDir } from '@/surface-root'
-import { isDirectory, resolveTarget } from '@/target'
+import { isDirectory, resolveTarget } from '@/targets/validate'
 import { injectGitignore, pruneGitignore } from '@/tooling/inject'
 import {
   frameError,
@@ -96,6 +101,7 @@ interface SeedsListOptions {
 interface SkillsListOptions {
   readonly json?: boolean
   readonly names?: boolean
+  readonly byFamily?: boolean
 }
 
 interface SkillsAuditOptions {
@@ -359,8 +365,12 @@ export function register(program: Command): void {
     .command('list')
     .description('List the plugin skills shipped under claude/skills/')
     .helpOption('-h, --help', 'Show this help message')
-    .option('--json', 'Emit JSON with name and description')
+    .option(
+      '--json',
+      'Emit JSON with each skill and the ordered family vocabulary',
+    )
     .option('--names', 'Only list skill names, one per line')
+    .option('--by-family', 'Group the listing under each family')
     .addHelpText(
       'after',
       [
@@ -368,6 +378,8 @@ export function register(program: Command): void {
         'Notes:',
         '  Internal skills under .claude/skills/ are excluded, since they',
         '  never install into a target project.',
+        '  Each skill carries the family its frontmatter declares under',
+        '  metadata.family, and --json lists the vocabulary as families.',
         '',
       ].join('\n'),
     )
@@ -770,7 +782,9 @@ function runSkillsList(opts: SkillsListOptions): number {
 
   if (opts.json) {
     if (mismatch !== undefined) logWarn(mismatch)
-    process.stdout.write(`${JSON.stringify({ skills: listings })}\n`)
+    process.stdout.write(
+      `${JSON.stringify({ skills: listings, families: SKILL_FAMILIES })}\n`,
+    )
     return 0
   }
 
@@ -784,14 +798,34 @@ function runSkillsList(opts: SkillsListOptions): number {
 
   intro('canon claude')
   if (mismatch !== undefined) logWarn(mismatch)
-  logStep('Plugin skills')
-  for (const listing of listings) {
-    logInfo(listing.name)
+  if (opts.byFamily) {
+    reportByFamily(groupByFamily(listings))
+  } else {
+    logStep('Plugin skills')
+    for (const listing of listings) {
+      logInfo(listing.name)
+    }
   }
   outro()
   return 0
 }
 
+/**
+ * One step per family in vocabulary order. A skill with a missing or unknown
+ * family takes a trailing step rather than vanishing, so the view still
+ * accounts for every listed skill.
+ */
+function reportByFamily(grouping: FamilyGrouping): void {
+  for (const group of grouping.groups) {
+    logStep(`${group.group} (${group.key})`)
+    for (const name of group.skills) logInfo(name)
+  }
+
+  if (grouping.unassigned.length === 0) return
+  logStep('No known family')
+  for (const name of grouping.unassigned) logWarn(name)
+}
+
 /**
  * Measures the cwd for the same reason the audit does, and takes the ref as a
  * required argument with no default. `HEAD` would be the only defensible one and
@@ -1402,6 +1436,7 @@ async function runSkillsAudit(
     reportProvenance(report)
     reportPracticeShape(report)
     reportReferenceContents(report)
+    reportFamily(report)
     reportUnmeasured()
     outro()
   }
@@ -1426,6 +1461,7 @@ async function runSkillsAudit(
           datedProvenance: report.datedProvenance,
           practiceShape: report.practiceShape,
           referenceContents: report.referenceContents,
+          family: report.family,
         },
         checkpoints: {
           descriptionLimit: DESCRIPTION_LIMIT,
@@ -1435,6 +1471,7 @@ async function runSkillsAudit(
           ledgerSkills: LEDGER_SKILLS,
           practiceSections: PRACTICE_SECTIONS,
           contentsThreshold: CONTENTS_THRESHOLD,
+          families: familyKeys(),
         },
       })}\n`,
     )
@@ -1668,6 +1705,27 @@ function reportReferenceContents(report: SkillsAudit): void {
   reportFindings(report.referenceContents)
 }
 
+/**
+ * Reports without failing the verb, the split the practice shape takes. The
+ * Skill family stage of `canon gate run` is what fails a push on it.
+ */
+function reportFamily(report: SkillsAudit): void {
+  logStep('Family')
+  logInfo(
+    `A skill under ${SHIPPED_CORPUS} declares metadata.family, one of ${familyKeys().join(', ')}.`,
+  )
+
+  if (report.family.length === 0) {
+    logInfo('Every shipped skill declares a known family.')
+    return
+  }
+
+  logWarn(
+    `${plural(report.family.length, 'skill')} with a missing or unknown family`,
+  )
+  reportFindings(report.family)
+}
+
 /**
  * Stated on every run, including the run where everything above passed. A
  * report that lists only what it measured reads as a verdict on the standard