@erclx/canon 4.0.0

package/src/claude/seeds.ts

@@ -0,0 +1,150 @@
+import { existsSync } from 'node:fs'
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { copyPreservingMode } from '@/copy'
+import { rewritesOnInstall, stripSeedMarker } from '@/seed-marker'
+
+const SEEDS_DIR = join('tooling', 'claude', 'seeds')
+const CLAUDE_DIR = '.claude'
+const CLAUDE_MD = 'CLAUDE.md'
+const HOOKS = 'hooks'
+/**
+ * Seed subdirectories under `.claude/`. Exported because each one replaced a
+ * single file of the same stem in an older layout, which is what
+ * `@/sync/layout` pairs a target against to find a superseded artifact.
+ */
+export const SUBDIRS: readonly string[] = [
+  HOOKS,
+  'context',
+  'diagrams',
+  'memory',
+  'tasks',
+  'wireframes',
+]
+
+export type SeedScope = 'claude' | 'root'
+
+export interface Seed {
+  readonly src: string
+  readonly dest: string
+  readonly scanLabel: string
+  readonly applyLabel: string
+  readonly scope: SeedScope
+  readonly executable: boolean
+}
+
+export interface SeedEntry {
+  readonly seed: Seed
+  readonly present: boolean
+}
+
+export interface SeedCounts {
+  readonly claude: number
+  readonly root: number
+}
+
+function seedsRoot(root: string): string {
+  return join(root, SEEDS_DIR)
+}
+
+/**
+ * Lists a single directory level, sorted the way `find -maxdepth 1 -type f |
+ * sort` was. Bun.Glob skips dotfiles without `dot`, and every path here sits
+ * under `.claude`, so omitting it would match nothing.
+ */
+function listLevel(dir: string): string[] {
+  if (!existsSync(dir)) return []
+  return [
+    ...new Bun.Glob('*').scanSync({ cwd: dir, onlyFiles: true, dot: true }),
+  ].sort()
+}
+
+/**
+ * Builds the seed list in the order the bash scanned it: the `.claude` root
+ * level, then each subdirectory, then the project-level `CLAUDE.md`. Order is
+ * load-bearing because it is also the order the timeline prints.
+ */
+export function planSeeds(root: string, target: string): SeedEntry[] {
+  const source = join(seedsRoot(root), CLAUDE_DIR)
+  const destDir = join(target, CLAUDE_DIR)
+  const seeds: Seed[] = []
+
+  for (const name of listLevel(source)) {
+    seeds.push({
+      src: join(source, name),
+      dest: join(destDir, name),
+      scanLabel: name,
+      applyLabel: join(CLAUDE_DIR, name),
+      scope: 'claude',
+      executable: false,
+    })
+  }
+
+  for (const subdir of SUBDIRS) {
+    for (const name of listLevel(join(source, subdir))) {
+      const rel = `${subdir}/${name}`
+      seeds.push({
+        src: join(source, subdir, name),
+        dest: join(destDir, subdir, name),
+        scanLabel: rel,
+        applyLabel: join(CLAUDE_DIR, subdir, name),
+        scope: 'claude',
+        executable: subdir === HOOKS,
+      })
+    }
+  }
+
+  const claudeMd = join(seedsRoot(root), CLAUDE_MD)
+  if (existsSync(claudeMd)) {
+    seeds.push({
+      src: claudeMd,
+      dest: join(target, CLAUDE_MD),
+      scanLabel: CLAUDE_MD,
+      applyLabel: CLAUDE_MD,
+      scope: 'root',
+      executable: false,
+    })
+  }
+
+  return seeds.map((seed) => ({ seed, present: existsSync(seed.dest) }))
+}
+
+export function pendingSeeds(entries: readonly SeedEntry[]): Seed[] {
+  return entries.filter((entry) => !entry.present).map((entry) => entry.seed)
+}
+
+export function countByScope(seeds: readonly Seed[]): SeedCounts {
+  return {
+    claude: seeds.filter((seed) => seed.scope === 'claude').length,
+    root: seeds.filter((seed) => seed.scope === 'root').length,
+  }
+}
+
+/**
+ * Copies each pending seed. Hooks get the executable bit the way `chmod +x`
+ * granted it, added on top of whatever mode the destination already carried.
+ *
+ * A markdown seed is rewritten rather than copied, so the stub marker the seed
+ * gate reads does not reach the target. Every other seed copies byte for byte,
+ * which is what keeps the hook scripts and `settings.json` untouched.
+ */
+export async function applySeeds(seeds: readonly Seed[]): Promise<string[]> {
+  const applied: string[] = []
+
+  for (const seed of seeds) {
+    if (rewritesOnInstall(seed.src)) {
+      await mkdir(dirname(seed.dest), { recursive: true })
+      await writeFile(
+        seed.dest,
+        stripSeedMarker(await readFile(seed.src, 'utf8')),
+      )
+    } else {
+      await copyPreservingMode(seed.src, seed.dest)
+    }
+
+    if (seed.executable) await chmod(seed.dest, 0o755)
+    applied.push(seed.applyLabel)
+  }
+
+  return applied
+}

package/src/claude/settings.ts

@@ -0,0 +1,151 @@
+import { existsSync } from 'node:fs'
+import { chmod, mkdir, readFile, stat, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+const DEFAULT_INDENT = '  '
+const INDENT = /^([ \t]+)\S/m
+
+export type SettingsRecord = Record<string, unknown>
+
+export interface SettingsKey {
+  readonly label: string
+  readonly changed: boolean
+}
+
+export interface SettingsPlan {
+  readonly keys: readonly SettingsKey[]
+  readonly next: SettingsRecord
+  readonly changed: boolean
+}
+
+/**
+ * Reads the indentation of the first indented line. Rewriting an operator's
+ * settings file at a different width is a diff they did not ask for, and this
+ * verb is the only one in the toolkit that writes outside a target.
+ */
+export function detectIndent(source: string): string {
+  return INDENT.exec(source)?.[1] ?? DEFAULT_INDENT
+}
+
+export function serializeSettings(
+  value: SettingsRecord,
+  indent: string,
+): string {
+  return `${JSON.stringify(value, null, indent)}\n`
+}
+
+/**
+ * Parses a settings file, treating an absent one as empty. A malformed one
+ * throws rather than resolving to empty, because the alternative silently
+ * replaces a file the operator owns with a generated one.
+ */
+export async function readSettings(
+  path: string,
+): Promise<{ value: SettingsRecord; indent: string }> {
+  if (!existsSync(path)) return { value: {}, indent: DEFAULT_INDENT }
+
+  const source = await readFile(path, 'utf8')
+  const indent = detectIndent(source)
+  if (source.trim() === '') return { value: {}, indent }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(source)
+  } catch (cause) {
+    throw new Error(`${path} is not valid JSON`, { cause })
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${path} is not a JSON object`)
+  }
+
+  return { value: parsed as SettingsRecord, indent }
+}
+
+function asRecord(value: unknown): SettingsRecord {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return {}
+  }
+  return value as SettingsRecord
+}
+
+function asStrings(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((entry): entry is string => typeof entry === 'string')
+}
+
+function equals(left: unknown, right: unknown): boolean {
+  return Bun.deepEquals(left, right)
+}
+
+/**
+ * Unions two permission lists into the sorted, deduplicated shape `jq unique`
+ * produced. The sort is load-bearing, since the comparison that decides
+ * whether to write runs against the sorted result.
+ */
+function mergeList(current: unknown, incoming: unknown): string[] {
+  return [...new Set([...asStrings(current), ...asStrings(incoming)])].sort()
+}
+
+/**
+ * Applies the four settings the toolkit owns, leaving every other key in
+ * place. Each key reports whether it changed so the caller prints `+` or `✓`
+ * per key, matching the four separate `jq` passes this replaced.
+ */
+export function planSettings(
+  current: SettingsRecord,
+  template: SettingsRecord,
+  statusLineCommand: string,
+): SettingsPlan {
+  const next: SettingsRecord = { ...current }
+  const keys: SettingsKey[] = []
+
+  const statusLine = asRecord(next.statusLine)
+  const statusLineChanged = statusLine.command !== statusLineCommand
+  if (statusLineChanged) {
+    next.statusLine = { type: 'command', command: statusLineCommand }
+  }
+  keys.push({ label: 'statusLine', changed: statusLineChanged })
+
+  const attribution = template.attribution
+  const attributionChanged = !equals(next.attribution, attribution)
+  if (attributionChanged) next.attribution = attribution
+  keys.push({ label: 'attribution', changed: attributionChanged })
+
+  const permissions = asRecord(next.permissions)
+  const merged: SettingsRecord = { ...permissions }
+  const templatePermissions = asRecord(template.permissions)
+
+  for (const field of ['allow', 'deny'] as const) {
+    const union = mergeList(permissions[field], templatePermissions[field])
+    const changed = !equals(asStrings(permissions[field]), union)
+    if (changed) merged[field] = union
+    keys.push({ label: `permissions.${field}`, changed })
+  }
+
+  if (keys.some((key) => key.label.startsWith('permissions.') && key.changed)) {
+    next.permissions = merged
+  }
+
+  return { keys, next, changed: keys.some((key) => key.changed) }
+}
+
+/**
+ * Writes in place, restoring the file's existing mode. The bash wrote through
+ * `mktemp` and `mv`, which handed the destination the temp file's 600 and
+ * silently tightened a settings file the operator had left at 644.
+ */
+export async function writeSettings(
+  path: string,
+  content: string,
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+
+  const mode = await stat(path)
+    .then((info) => info.mode)
+    .catch(() => undefined)
+
+  await writeFile(path, content)
+
+  if (mode !== undefined) await chmod(path, mode)
+}

package/src/claude/skills-audit.ts

@@ -0,0 +1,228 @@
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import {
+  type Frontmatter,
+  parseFrontmatter,
+  readField,
+} from '@/indexes/frontmatter'
+
+/** Returned when a skill folder carries no `REQUIREMENT.md`, the gating check. */
+export const EXIT_MISSING_REQUIREMENT = 2
+
+/** The description ceiling stated in the frontmatter rules of `standards/skill.md`. */
+export const DESCRIPTION_LIMIT = 1024
+
+/** The two headings the requirement template declares, matched at any level. */
+export const REQUIREMENT_SECTIONS: readonly string[] = ['Gap', 'Must']
+
+/**
+ * Both trees the standard governs. `claude/skills/` ships to a target and
+ * `.claude/skills/` stays here, and every rule measured below applies to each,
+ * so a corpus reading one of them reports a pass over half the subject.
+ */
+export const CORPORA: readonly string[] = [
+  join('claude', 'skills'),
+  join('.claude', 'skills'),
+]
+
+/**
+ * The one reason this audit refuses. A project carrying neither corpus is the
+ * ordinary state of a target that has not adopted either skills convention,
+ * the same absence `no-skills` reads for the shipped citation reach check.
+ */
+export type SkillsAuditRefusal = 'no-corpus'
+
+/** Kebab-case, which the standard states as no spaces, capitals, or underscores. */
+const KEBAB_CASE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+const HEADING = /^#{1,6}\s+(.+?)\s*$/
+
+export interface SkillFinding {
+  readonly rel: string
+  readonly detail: string
+}
+
+export interface CorpusReport {
+  /**
+   * Left as `join` produced it, where `SkillsCorpus.rel` in `skills-list.ts`
+   * normalizes the same spelling to POSIX. This one is an existing JSON field
+   * a caller already reads, so the split holds until a branch reading this verb
+   * is the one to close it.
+   */
+  readonly rel: string
+  readonly skills: number
+}
+
+export interface SkillsAudit {
+  readonly corpora: readonly CorpusReport[]
+  readonly skills: number
+  readonly missingRequirement: readonly string[]
+  readonly readme: readonly string[]
+  readonly folderName: readonly string[]
+  readonly missingDescription: readonly string[]
+  readonly nameMismatch: readonly SkillFinding[]
+  readonly longDescription: readonly SkillFinding[]
+  readonly requirementSections: readonly SkillFinding[]
+}
+
+interface SkillSource {
+  readonly rel: string
+  readonly folder: string
+  readonly hasReadme: boolean
+  readonly name: string | undefined
+  readonly description: string | undefined
+  /** Undefined when the folder carries no `REQUIREMENT.md` at all. */
+  readonly requirementHeadings: readonly string[] | undefined
+}
+
+/**
+ * Measures both skill corpora against the rules `standards/skill.md` states
+ * mechanically. A corpus the project does not carry is skipped rather than
+ * reported, so a target holding only `.claude/skills/` reads as in scope.
+ *
+ * Reads raw frontmatter rather than `listSkills`, which prefers the folder name
+ * over the declared one and so can never surface a disagreement between them.
+ */
+export async function auditSkills(root: string): Promise<SkillsAudit> {
+  const present = CORPORA.map((rel) => ({ rel, dir: join(root, rel) })).filter(
+    (corpus) => existsSync(corpus.dir),
+  )
+
+  const perCorpus = await Promise.all(
+    present.map((corpus) => readCorpus(corpus.rel, corpus.dir)),
+  )
+  const sources = perCorpus.flat()
+
+  return {
+    corpora: present.map((corpus, index) => ({
+      rel: corpus.rel,
+      skills: perCorpus[index]?.length ?? 0,
+    })),
+    skills: sources.length,
+    missingRequirement: sources
+      .filter((source) => source.requirementHeadings === undefined)
+      .map((source) => source.rel),
+    readme: sources
+      .filter((source) => source.hasReadme)
+      .map((source) => source.rel),
+    folderName: sources
+      .filter((source) => !KEBAB_CASE.test(source.folder))
+      .map((source) => source.rel),
+    missingDescription: sources
+      .filter((source) => source.description === undefined)
+      .map((source) => source.rel),
+    nameMismatch: sources.flatMap(nameFindings),
+    longDescription: sources.flatMap(lengthFindings),
+    requirementSections: sources.flatMap(sectionFindings),
+  }
+}
+
+/**
+ * Only a required file that is absent sets a failing code, which is a fact.
+ * Every other measure is a judgment a reader settles, and failing a push on one
+ * teaches contributors to route around the stage.
+ */
+export function auditExitCode(report: SkillsAudit): number {
+  return report.missingRequirement.length > 0 ? EXIT_MISSING_REQUIREMENT : 0
+}
+
+async function readCorpus(rel: string, dir: string): Promise<SkillSource[]> {
+  const paths = [
+    ...new Bun.Glob('*/SKILL.md').scanSync({ cwd: dir, onlyFiles: true }),
+  ].sort()
+
+  return Promise.all(paths.map((path) => readSkill(rel, dir, dirname(path))))
+}
+
+async function readSkill(
+  rel: string,
+  dir: string,
+  folder: string,
+): Promise<SkillSource> {
+  const skillDir = join(dir, folder)
+  const requirementPath = join(skillDir, 'REQUIREMENT.md')
+
+  const [body, requirement] = await Promise.all([
+    Bun.file(join(skillDir, 'SKILL.md')).text(),
+    existsSync(requirementPath)
+      ? Bun.file(requirementPath).text()
+      : Promise.resolve(undefined),
+  ])
+
+  const fields = readFields(body)
+
+  return {
+    rel: join(rel, folder),
+    folder,
+    hasReadme: existsSync(join(skillDir, 'README.md')),
+    name: declared(readField(fields, 'name')),
+    description: declared(readField(fields, 'description')),
+    requirementHeadings:
+      requirement === undefined ? undefined : headings(requirement),
+  }
+}
+
+/**
+ * Returns undefined rather than throwing on unparseable YAML, so one malformed
+ * body reports as missing its required fields instead of ending the audit
+ * before it reaches the rest of the corpus.
+ */
+function readFields(body: string): Frontmatter | undefined {
+  try {
+    return parseFrontmatter(body)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * A key carrying an empty value declares nothing, so blank reads as absent
+ * rather than as a name that disagrees with every folder.
+ */
+function declared(value: string | undefined): string | undefined {
+  const trimmed = value?.trim()
+  return trimmed === undefined || trimmed === '' ? undefined : trimmed
+}
+
+function headings(source: string): string[] {
+  return source
+    .split('\n')
+    .map((line) => HEADING.exec(line)?.[1])
+    .filter((text): text is string => text !== undefined)
+}
+
+function nameFindings(source: SkillSource): SkillFinding[] {
+  if (source.name === undefined) {
+    return [{ rel: source.rel, detail: 'frontmatter declares no name' }]
+  }
+  if (source.name === source.folder) return []
+  return [{ rel: source.rel, detail: `frontmatter name: ${source.name}` }]
+}
+
+function lengthFindings(source: SkillSource): SkillFinding[] {
+  const { description } = source
+  if (description === undefined) return []
+  if (description.length <= DESCRIPTION_LIMIT) return []
+  return [{ rel: source.rel, detail: `${description.length} characters` }]
+}
+
+/**
+ * Stays silent on a folder carrying no requirement at all, which the presence
+ * check already reports. Counting the same skill twice reads as two defects.
+ */
+function sectionFindings(source: SkillSource): SkillFinding[] {
+  const { requirementHeadings } = source
+  if (requirementHeadings === undefined) return []
+
+  const missing = REQUIREMENT_SECTIONS.filter(
+    (section) => !requirementHeadings.includes(section),
+  )
+  if (missing.length === 0) return []
+
+  return [
+    {
+      rel: join(source.rel, 'REQUIREMENT.md'),
+      detail: `missing: ${missing.join(', ')}`,
+    },
+  ]
+}

package/src/claude/skills-drift.ts

@@ -0,0 +1,156 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { execaSync } from 'execa'
+import { gitEnv } from '@/git-env'
+
+/**
+ * The shipped corpus alone. A session loads a body from the plugin root, which
+ * resolves to `claude/skills/`, so the internal tree carries no held copy that
+ * could go stale in one.
+ *
+ * Held with posix separators because it is passed to git as a pathspec. Git
+ * emits and accepts posix separators on every platform, so a `join()` form would
+ * reach a Windows checkout as `claude\skills`, match no path, and return an
+ * empty log that reads as a tree where nothing moved.
+ */
+const SHIPPED_SKILLS = 'claude/skills'
+
+/** A `%H` line, which is 40 hex characters under sha1 and 64 under sha256. */
+const COMMIT = /^[0-9a-f]{40,64}$/
+
+/**
+ * A skill body, which is the only file in the folder a session loads. A
+ * reference or a requirement beside it is read by whoever opens it, so it holds
+ * no copy that outlives the read.
+ */
+const BODY = /^claude\/skills\/([^/]+)\/SKILL\.md$/
+
+export interface MovedBody {
+  readonly name: string
+  /** The newest commit that rewrote this body, not the first. */
+  readonly commit: string
+}
+
+export type DriftReport =
+  | {
+      readonly kind: 'measured'
+      readonly base: string
+      readonly head: string
+      readonly moved: readonly MovedBody[]
+    }
+  | { readonly kind: 'unreadable'; readonly reason: string }
+
+/**
+ * Reads `--name-only` log output into one entry per skill whose body moved.
+ *
+ * Reverse-chronological input means the first commit naming a body is the
+ * newest that rewrote it, so an existing name is never overwritten. A body
+ * rewritten twice therefore reports the recent commit, which is the one a
+ * session can read to see what it is missing.
+ */
+export function parseMovedBodies(output: string): MovedBody[] {
+  const moved = new Map<string, string>()
+  let commit = ''
+
+  for (const line of output.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+
+    if (COMMIT.test(trimmed)) {
+      commit = trimmed
+      continue
+    }
+
+    const match = BODY.exec(trimmed)
+    if (match === null || commit === '') continue
+    if (!moved.has(match[1])) moved.set(match[1], commit)
+  }
+
+  return [...moved]
+    .map(([name, sha]) => ({ name, commit: sha }))
+    .sort((left, right) => left.name.localeCompare(right.name))
+}
+
+/**
+ * Which shipped skill bodies were rewritten between `ref` and the current
+ * `HEAD` of the tree at `root`.
+ *
+ * This measures a file moving rather than a held copy differing. A session
+ * cannot read its own loaded body as bytes, so the comparison runs against
+ * history and a session passing a ref older than its oldest load over-reports.
+ * That is the safe direction, since confirming a name costs one read of the
+ * body while the failure this answers is silence.
+ *
+ * Every path that cannot answer returns `unreadable` with its own reason. A
+ * target project loads the plugin from a marketplace cache with no history
+ * behind it, where reporting an empty result would read as a clean tree.
+ */
+export function readDrift(root: string, ref: string): DriftReport {
+  if (!existsSync(join(root, SHIPPED_SKILLS))) {
+    return {
+      kind: 'unreadable',
+      reason: `No shipped skill corpus under ${root}. Looked for ${SHIPPED_SKILLS}.`,
+    }
+  }
+
+  const head = revParse(root, 'HEAD')
+  if (head === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `No git history under ${root}. A plugin loaded from a marketplace cache carries none, so a ref cannot be resolved there.`,
+    }
+  }
+
+  const base = revParse(root, ref)
+  if (base === undefined) {
+    return {
+      kind: 'unreadable',
+      reason: `Ref ${ref} resolves to no commit in ${root}. Pass a commit this tree carries.`,
+    }
+  }
+
+  const result = execaSync(
+    'git',
+    [
+      '-C',
+      root,
+      'log',
+      '--name-only',
+      '--no-renames',
+      '--format=%H',
+      `${base}..${head}`,
+      '--',
+      SHIPPED_SKILLS,
+    ],
+    { reject: false, env: gitEnv(), extendEnv: false },
+  )
+
+  if (result.exitCode !== 0) {
+    return {
+      kind: 'unreadable',
+      reason: `Reading history between ${ref} and HEAD failed: ${result.stderr || result.stdout}`,
+    }
+  }
+
+  return {
+    kind: 'measured',
+    base,
+    head,
+    moved: parseMovedBodies(result.stdout),
+  }
+}
+
+/**
+ * The commit a ref names, or `undefined` when the tree carries no repository or
+ * no such ref. `^{commit}` is what turns a tag or a tree into the commit behind
+ * it, so a caller never compares a ref against an object of another type.
+ */
+function revParse(root: string, ref: string): string | undefined {
+  const result = execaSync(
+    'git',
+    ['-C', root, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`],
+    { reject: false, env: gitEnv(), extendEnv: false },
+  )
+
+  return result.exitCode === 0 ? result.stdout.trim() : undefined
+}