@erclx/canon 4.0.0

package/src/gov/consumed.ts

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import {
+  installRules,
+  installedRulesDir,
+  lookupRules,
+  type RuleSource,
+  ruleSubdir,
+} from '@/gov/install'
+import { mergeExtraRules, resolveRules } from '@/gov/stacks'
+
+export const RECORD_REL = join('internal', 'governance.toml')
+
+const INTERNAL_RULES_REL = join('internal', 'rules')
+
+/** The stack a repository installs into its own `.claude/rules/`. */
+export interface ConsumedRecord {
+  readonly stack: string
+  readonly add: readonly string[]
+}
+
+export type ConsumedResult =
+  | { readonly ok: true; readonly installed: readonly string[] }
+  | { readonly ok: false; readonly reason: string }
+
+export function consumedRecordPath(root: string): string {
+  return join(root, RECORD_REL)
+}
+
+export function internalRulesDir(root: string): string {
+  return join(root, INTERNAL_RULES_REL)
+}
+
+/**
+ * Reads the record naming the consumed stack. A file with no `stack` reads the
+ * same as no file at all, since neither tells the producer what to install and
+ * the caller's message covers both.
+ */
+export function readConsumedRecord(root: string): ConsumedRecord | undefined {
+  const path = consumedRecordPath(root)
+  if (!existsSync(path)) return undefined
+
+  const parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+    string,
+    unknown
+  >
+  const stack = typeof parsed.stack === 'string' ? parsed.stack : ''
+  if (stack === '') return undefined
+
+  return {
+    stack,
+    add: Array.isArray(parsed.add)
+      ? parsed.add.filter(
+          (rule): rule is string => typeof rule === 'string' && rule !== '',
+        )
+      : [],
+  }
+}
+
+/**
+ * Lists rules authored under `internal/rules/`. These govern toolkit authoring
+ * against paths only this repository has, so they install into the consumed
+ * copy without ever entering `governance/rules/`, which ships to targets.
+ */
+export function listInternalRules(root: string): RuleSource[] {
+  const dir = internalRulesDir(root)
+  if (!existsSync(dir)) return []
+
+  return [...new Bun.Glob('**/*.md').scanSync({ cwd: dir, onlyFiles: true })]
+    .sort()
+    .map((rel) => {
+      const src = join(dir, rel)
+      return { rule: basename(rel, '.md'), src, subdir: ruleSubdir(src, dir) }
+    })
+}
+
+/**
+ * Rebuilds a repository's own `.claude/rules/` from its record. Unlike
+ * `gov install` and `gov sync`, this runs against the toolkit root on purpose:
+ * those two refuse it because a target's rules are the operator's to edit,
+ * while this destination is produced output that happens to live beside its
+ * source.
+ */
+export async function regenConsumedRules(
+  root: string,
+): Promise<ConsumedResult> {
+  const record = readConsumedRecord(root)
+  if (record === undefined) {
+    return { ok: false, reason: `No stack recorded at ${RECORD_REL}` }
+  }
+
+  const resolution = resolveRules(root, record.stack)
+  if (!resolution.ok) {
+    return { ok: false, reason: `Stack not found: ${resolution.missingStack}` }
+  }
+
+  const { found, missing } = lookupRules(
+    root,
+    mergeExtraRules(resolution.rules, record.add.join(',')),
+  )
+  if (missing.length > 0) {
+    return { ok: false, reason: `No source for: ${missing.join(', ')}` }
+  }
+
+  const internal = listInternalRules(root)
+  const stackRules = new Set(found.map((entry) => entry.rule))
+  const shadowed = internal
+    .filter((entry) => stackRules.has(entry.rule))
+    .map((entry) => entry.rule)
+  if (shadowed.length > 0) {
+    return {
+      ok: false,
+      reason: `Internal rules shadow stack rules: ${shadowed.join(', ')}`,
+    }
+  }
+
+  // Clearing first is what makes a rule the record stopped naming disappear.
+  // Copying over the destination would leave it behind as an unsourced file,
+  // which is the state this producer exists to end.
+  await rm(installedRulesDir(root), { recursive: true, force: true })
+
+  const installed = [
+    ...(await installRules(found, root)),
+    ...(await installRules(internal, root)),
+  ]
+
+  return { ok: true, installed: installed.sort() }
+}

package/src/gov/install.ts

@@ -0,0 +1,132 @@
+import { existsSync } from 'node:fs'
+import { basename, dirname, join, relative } from 'node:path'
+import { copyPreservingMode } from '@/copy'
+
+export interface RuleSource {
+  readonly rule: string
+  readonly src: string
+  readonly subdir: string
+}
+
+export interface RuleLookup {
+  readonly found: readonly RuleSource[]
+  readonly missing: readonly string[]
+}
+
+export function rulesSourceDir(root: string): string {
+  return join(root, 'governance', 'rules')
+}
+
+export function installedRulesDir(target: string): string {
+  return join(target, '.claude', 'rules')
+}
+
+/**
+ * Rule names a target already holds, read off the installed tree by basename
+ * rather than off a recorded stack, since a target may hold rules `--add`
+ * layered on that no stack lists.
+ */
+export function installedRuleNames(target: string): Set<string> {
+  const dir = installedRulesDir(target)
+  const names = new Set<string>()
+  if (!existsSync(dir)) return names
+
+  for (const rel of new Bun.Glob('**/*.md').scanSync({
+    cwd: dir,
+    onlyFiles: true,
+    dot: true,
+  })) {
+    names.add(basename(rel, '.md'))
+  }
+
+  return names
+}
+
+/**
+ * Mirrors `rule_subdir` in `scripts/lib/gov.sh`, which stays in bash for the
+ * sandbox loops. A rule sitting directly under `governance/rules/` has no
+ * subdirectory and installs flat.
+ */
+export function ruleSubdir(src: string, rulesRoot: string): string {
+  const subdir = dirname(relative(rulesRoot, src))
+  return subdir === '.' ? '' : subdir
+}
+
+/**
+ * Lists every rule source path under `governance/rules/`, relative to it and
+ * sorted, so a caller walking the tree and a caller resolving one name read the
+ * same order.
+ */
+export function listRuleSourcePaths(root: string): string[] {
+  const rulesRoot = rulesSourceDir(root)
+  if (!existsSync(rulesRoot)) return []
+
+  return [
+    ...new Bun.Glob('**/*.md').scanSync({ cwd: rulesRoot, onlyFiles: true }),
+  ].sort()
+}
+
+/**
+ * Maps each rule name to its source file. First path wins, so a name appearing
+ * in two subdirectories resolves deterministically rather than by whichever
+ * entry the filesystem yielded first.
+ */
+function indexRuleSources(root: string): Map<string, string> {
+  const rulesRoot = rulesSourceDir(root)
+  const byName = new Map<string, string>()
+
+  for (const rel of listRuleSourcePaths(root)) {
+    const name = rel.slice(rel.lastIndexOf('/') + 1, -'.md'.length)
+    if (!byName.has(name)) byName.set(name, join(rulesRoot, rel))
+  }
+
+  return byName
+}
+
+/**
+ * Finds each rule's source file by name across the `governance/rules/`
+ * subfolders. A rule with no source is reported rather than dropped, matching
+ * the `(source not found, skipping)` warning the bash printed.
+ */
+export function lookupRules(
+  root: string,
+  rules: readonly string[],
+): RuleLookup {
+  const rulesRoot = rulesSourceDir(root)
+  const byName = indexRuleSources(root)
+
+  const found: RuleSource[] = []
+  const missing: string[] = []
+
+  for (const rule of rules) {
+    const src = byName.get(rule)
+    if (src === undefined) {
+      missing.push(rule)
+      continue
+    }
+    found.push({ rule, src, subdir: ruleSubdir(src, rulesRoot) })
+  }
+
+  return { found, missing }
+}
+
+/**
+ * Copies each rule into the subdirectory it was authored in, so the installed
+ * tree keeps the band structure `governance/rules/` carries. Returns the
+ * target-relative paths the timeline prints.
+ */
+export async function installRules(
+  sources: readonly RuleSource[],
+  target: string,
+): Promise<string[]> {
+  const rulesDir = installedRulesDir(target)
+  const installed: string[] = []
+
+  for (const source of sources) {
+    const dest = join(rulesDir, source.subdir, `${source.rule}.md`)
+    await copyPreservingMode(source.src, dest)
+    installed.push(relative(target, dest))
+  }
+
+  return installed
+}

package/src/gov/list.ts

@@ -0,0 +1,106 @@
+import { readFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+import { listRuleSourcePaths, rulesSourceDir } from '@/gov/install'
+import {
+  expandStackEntry,
+  listGovStacks,
+  loadGovStack,
+  unreferencedRules,
+} from '@/gov/stacks'
+import { parseFrontmatter, readField } from '@/indexes/frontmatter'
+
+export interface StackEntry {
+  readonly name: string
+  readonly extends: string | null
+  readonly rules: string[]
+}
+
+export interface RuleEntry {
+  readonly name: string
+  readonly domain: string
+  readonly description: string
+  readonly paths: string[] | null
+}
+
+export interface GovCatalog {
+  readonly stacks: StackEntry[]
+  readonly rules: RuleEntry[]
+  readonly unreferenced: string[]
+}
+
+/**
+ * Reports each stack's own entries expanded, so a folder entry reaches a
+ * consumer as the rules it stands for. `setup-gov` dedupes `--add` extras
+ * against this list, and a stack answering `core` there would re-add every
+ * rule that folder already carries.
+ *
+ * The `extends` chain is deliberately not resolved, which is what the bash
+ * did. The list shows what each stack contributes beside the parent it
+ * inherits from, rather than repeating the ancestors under every descendant.
+ */
+export function buildStackEntries(root: string): StackEntry[] {
+  const entries: StackEntry[] = []
+
+  for (const name of listGovStacks(root)) {
+    const stack = loadGovStack(root, name)
+    if (!stack) continue
+
+    const seen = new Set<string>()
+    const rules: string[] = []
+
+    for (const entry of stack.rules) {
+      for (const rule of expandStackEntry(root, entry)) {
+        if (seen.has(rule)) continue
+        seen.add(rule)
+        rules.push(rule)
+      }
+    }
+
+    entries.push({ name, extends: stack.parent ?? null, rules })
+  }
+
+  return entries
+}
+
+/**
+ * Reads the catalog straight off the source tree. A rule's domain is the
+ * subdirectory it sits in, which is the band grouping install preserves.
+ */
+export function buildRuleEntries(root: string): RuleEntry[] {
+  const rulesRoot = rulesSourceDir(root)
+
+  return listRuleSourcePaths(root).map((rel) => {
+    const frontmatter = parseFrontmatter(
+      readFileSync(join(rulesRoot, rel), 'utf8'),
+    )
+    const paths = frontmatter?.fields.paths
+
+    return {
+      name: basename(rel, '.md'),
+      domain: rel.includes('/') ? rel.slice(0, rel.indexOf('/')) : '',
+      description: readField(frontmatter, 'description') ?? '',
+      paths: Array.isArray(paths)
+        ? paths.filter((entry): entry is string => typeof entry === 'string')
+        : null,
+    }
+  })
+}
+
+export function buildGovCatalog(root: string): GovCatalog {
+  return {
+    stacks: buildStackEntries(root),
+    rules: buildRuleEntries(root),
+    unreferenced: unreferencedRules(root),
+  }
+}
+
+export function describeStack(entry: StackEntry): string {
+  const count = `${entry.rules.length} rules`
+  return entry.extends === null
+    ? `${entry.name} (${count})`
+    : `${entry.name} (extends: ${entry.extends}, ${count})`
+}
+
+export function describeRule(entry: RuleEntry): string {
+  return `${entry.name} [${entry.domain}] ${entry.description}`
+}

package/src/gov/payload.ts

@@ -0,0 +1,39 @@
+import { readFileSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+import { stripFrontmatter } from '@/frontmatter'
+
+/**
+ * Lists installed rules in the order the payload concatenates them. Sorting by
+ * path keeps the numeric filename prefixes ordered inside each subdirectory,
+ * which is how the rule bands are meant to read.
+ */
+export function listRuleFiles(rulesDir: string): string[] {
+  return [
+    ...new Bun.Glob('**/*.md').scanSync({
+      cwd: rulesDir,
+      onlyFiles: true,
+      dot: true,
+    }),
+  ]
+    .sort()
+    .map((path) => resolve(rulesDir, path))
+}
+
+/**
+ * Wraps each rule in a named tag so a model reading the payload can tell the
+ * rules apart without the file boundaries. Bodies are trimmed of blank lines
+ * at both ends and separated by exactly one blank line.
+ */
+export function buildRulesPayload(files: readonly string[]): string {
+  const blocks = files.map((file) => {
+    const name = basename(file, '.md')
+    const body = trimBlankLines(stripFrontmatter(readFileSync(file, 'utf8')))
+    return `<rule name="${name}">\n${body}\n</rule>`
+  })
+
+  return `${blocks.join('\n\n')}\n`
+}
+
+function trimBlankLines(source: string): string {
+  return source.replace(/^(?:[ \t]*\n)+/, '').replace(/(?:\n[ \t]*)+$/, '')
+}