@erclx/canon 5.26.0 → 5.28.0

package/src/claude/skills-audit.ts

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs'
 import { dirname, join } from 'node:path'
+import { isFamilyKey } from '@/claude/skills-families'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { bodyLines, maskDisplayed } from '@/markdown/scan'
 
@@ -128,6 +129,7 @@ export interface SkillsAudit {
   readonly datedProvenance: readonly SkillFinding[]
   readonly practiceShape: readonly SkillFinding[]
   readonly referenceContents: readonly SkillFinding[]
+  readonly family: readonly SkillFinding[]
 }
 
 interface SkillSource {
@@ -136,6 +138,8 @@ interface SkillSource {
   readonly hasReadme: boolean
   readonly name: string | undefined
   readonly description: string | undefined
+  /** `metadata.family`, undefined when absent, blank, or not a string. */
+  readonly family: string | undefined
   /** Undefined when the folder carries no `REQUIREMENT.md` at all. */
   readonly requirementHeadings: readonly string[] | undefined
   /** Every H2 in `SKILL.md` outside a fence, for the practice shape. */
@@ -207,6 +211,7 @@ export async function auditSkills(root: string): Promise<SkillsAudit> {
     referenceContents: sources.flatMap((source) =>
       source.bodies.flatMap(contentsFindings),
     ),
+    family: sources.flatMap(familyFindings),
   }
 }
 
@@ -261,6 +266,7 @@ async function readSkill(
     hasReadme: existsSync(join(skillDir, 'README.md')),
     name: declared(readField(fields, 'name')),
     description: declared(readField(fields, 'description')),
+    family: declaredFamily(fields?.fields.metadata),
     requirementHeadings:
       requirement === undefined ? undefined : headings(requirement),
     sections: sectionsOf(body),
@@ -285,6 +291,13 @@ function declared(value: string | undefined): string | undefined {
   return trimmed === undefined || trimmed === '' ? undefined : trimmed
 }
 
+function declaredFamily(metadata: unknown): string | undefined {
+  if (typeof metadata !== 'object' || metadata === null) return undefined
+  if (Array.isArray(metadata)) return undefined
+  const { family } = metadata as Record<string, unknown>
+  return typeof family === 'string' ? declared(family) : undefined
+}
+
 /** Every H2 outside a fence, the one level both exact-section checks read. */
 function sectionsOf(source: string): string[] {
   return bodyLines(source)
@@ -375,6 +388,21 @@ function practiceFindings(source: SkillSource): SkillFinding[] {
   return [...sections, ...ledger]
 }
 
+/**
+ * Asks only the shipped corpus for a family, since the family names the skill
+ * map group a skill's row sits under and an internal skill takes no row.
+ */
+function familyFindings(source: SkillSource): SkillFinding[] {
+  if (dirname(source.rel) !== SHIPPED_CORPUS) return []
+  if (source.family === undefined) {
+    return [
+      { rel: source.rel, detail: 'frontmatter declares no metadata.family' },
+    ]
+  }
+  if (isFamilyKey(source.family)) return []
+  return [{ rel: source.rel, detail: `unknown family: ${source.family}` }]
+}
+
 /**
  * Reads references alone, since `SKILL.md` carries its own length checkpoint
  * and no contents rule. Frontmatter counts toward the length, so the count a

package/src/claude/skills-drift.ts

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { execaSync } from 'execa'
-import { gitEnv } from '@/git-env'
+import { gitEnv } from '@/git/env'
 
 /**
  * The shipped corpus alone. A session loads a body from the plugin root, which

package/src/claude/skills-families.ts

@@ -0,0 +1,36 @@
+export interface SkillFamily {
+  /** The value a shipped `SKILL.md` declares as `metadata.family`. */
+  readonly key: string
+  /** The skill map heading the family's rows sit under, verbatim. */
+  readonly group: string
+}
+
+/**
+ * The one vocabulary a shipped skill's family is drawn from, in the order the
+ * skill map reads across its two pages. A heading is the map's prose and a key
+ * is what frontmatter carries, so renaming a heading touches this constant and
+ * no skill.
+ *
+ * Import-free on purpose: `skills-list.ts` and `skills-audit.ts` both read it,
+ * and the first already imports the second.
+ */
+export const SKILL_FAMILIES: readonly SkillFamily[] = [
+  { key: 'setup', group: 'Set up a project' },
+  { key: 'decide', group: 'Decide what to build' },
+  { key: 'build', group: 'Build the feature' },
+  { key: 'check', group: 'Check the work before it leaves the branch' },
+  { key: 'ship', group: 'Ship it' },
+  { key: 'after-pr', group: 'After the pull request opens' },
+  { key: 'parallel', group: 'Run several tracks at once' },
+  { key: 'upkeep', group: 'Keep the project current with the toolkit' },
+  { key: 'generate', group: 'Generate an artifact on demand' },
+  { key: 'answer', group: 'Answer a question at any point' },
+]
+
+export function familyKeys(): string[] {
+  return SKILL_FAMILIES.map((family) => family.key)
+}
+
+export function isFamilyKey(value: string): boolean {
+  return SKILL_FAMILIES.some((family) => family.key === value)
+}

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/claude/skills-reach.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { resolveSkillsCorpus } from '@/claude/skills-list'
-import { SURFACE_ROOTS } from '@/surface-root'
+import { SURFACE_ROOTS } from '@/roots/surface'
 
 /**
  * The authoring roots this repository owns and no install channel delivers.

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 { PROJECT_ROOT } from '@/roots/project'
 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 { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
+import { recordDir } from '@/roots/record'
+import { SURFACE_ENTRIES, surfaceDir } from '@/roots/surface'
+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