@erclx/canon 5.12.0 → 5.14.0

package/src/gate/stages.ts

@@ -1,3 +1,10 @@
+import {
+  capabilitySeeding,
+  ignoreParity,
+  pluginBoundary,
+  seedIndependence,
+  skillPaths,
+} from '@/gate/boundaries'
 import {
   architectureRecord,
   auditSet,
@@ -99,7 +106,6 @@ export const TEST_CORPORA_PATTERNS = [
   '^standards/markdown\\.md$',
   '^tooling/base/reference\\.md$',
   '^tooling/web/configs/scripts/worktree-port\\.sh$',
-  '^scripts/core/check-ignore-parity\\.sh$',
 ]
 
 const TESTS_SCOPE = new RegExp(
@@ -277,34 +283,19 @@ export const STAGES: readonly Stage[] = [
     // produces either list, so there is nothing to regenerate and diff.
     id: 'ignore-parity',
     label: 'Ignore parity',
-    checks: [
-      script(
-        'check-ignore-parity.sh',
-        "The ignore set a target receives disagrees with this repository's own.",
-      ),
-    ],
+    checks: [{ kind: 'measure', measure: ignoreParity }],
     success: 'Ignore parity clean',
   },
   {
     id: 'skill-paths',
     label: 'Skill paths',
-    checks: [
-      script(
-        'check-skill-paths.sh',
-        'Shipped skills reference a repo-local path.',
-      ),
-    ],
+    checks: [{ kind: 'measure', measure: skillPaths }],
     success: 'Skill paths clean',
   },
   {
     id: 'plugin-boundary',
     label: 'Plugin boundary',
-    checks: [
-      script(
-        'check-plugin-boundary.sh',
-        'Plugin ships toolkit-internal content.',
-      ),
-    ],
+    checks: [{ kind: 'measure', measure: pluginBoundary }],
     success: 'Plugin boundary clean',
   },
   {
@@ -315,9 +306,7 @@ export const STAGES: readonly Stage[] = [
     // propagates into every project scaffolded after it.
     id: 'seed-independence',
     label: 'Seed independence',
-    checks: [
-      script('check-seed-independence.sh', 'Seed prose cites the toolkit CLI.'),
-    ],
+    checks: [{ kind: 'measure', measure: seedIndependence }],
     success: 'Seed prose cites no toolkit CLI',
   },
   {
@@ -326,12 +315,7 @@ export const STAGES: readonly Stage[] = [
     // recorded reason, per the criterion in canon/context/tooling/seeds.md.
     id: 'capability-seeding',
     label: 'Capability seeding',
-    checks: [
-      script(
-        'check-capability-seeding.sh',
-        'A capability reaches one side of the seed or config boundary and not the other.',
-      ),
-    ],
+    checks: [{ kind: 'measure', measure: capabilitySeeding }],
     success: 'Capability seeding clean',
   },
   {

package/src/pr/frames.ts

@@ -0,0 +1,323 @@
+import { readFile } from 'node:fs/promises'
+
+/** The branch holding review frames. It never merges into a branch anyone checks out. */
+export const FRAMES_BRANCH = 'canon-frames'
+
+/** The eight bytes every PNG opens with. A frame that lacks them embeds as a broken image. */
+const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+
+const SHORT_HEAD_LENGTH = 7
+
+const HEAD_PATTERN = /^[0-9a-f]{7,40}$/
+
+/** A compact UTC instant such as `20261002T154450Z`, the form `date -u +%Y%m%dT%H%M%SZ` prints. */
+const PASS_PATTERN = /^\d{8}T\d{6}Z$/
+
+/** How many times an add rebuilds on a tip another writer moved. */
+const ADD_ATTEMPTS = 3
+
+const FOLDER_PATTERN = /^pr-(\d+)$/
+
+const DAY_MS = 86_400_000
+
+export interface TreeEntry {
+  readonly path: string
+  readonly mode: string
+  readonly type: 'blob' | 'tree'
+  readonly sha: string
+}
+
+export type Tip =
+  | { readonly kind: 'found'; readonly commit: string; readonly tree: string }
+  | { readonly kind: 'missing' }
+  | { readonly kind: 'unreadable' }
+
+/** How a ref write landed. `conflict` means another writer holds the ref the call expected to own. */
+export type RefWrite = 'ok' | 'conflict' | 'failed'
+
+export interface PullClosure {
+  readonly state: 'open' | 'closed'
+  readonly closedAt?: string
+}
+
+/**
+ * The git data API calls a frame write needs, injected so the logic runs
+ * without a network. Every read that fails returns undefined rather than
+ * throwing, and each caller decides what an absent answer means.
+ */
+export interface FramesApi {
+  readTip(): Promise<Tip>
+  listTree(tree: string): Promise<readonly TreeEntry[] | undefined>
+  createBlob(base64: string): Promise<string | undefined>
+  createTree(
+    entries: readonly TreeEntry[],
+    base?: string,
+  ): Promise<string | undefined>
+  createCommit(
+    message: string,
+    tree: string,
+    parents: readonly string[],
+  ): Promise<string | undefined>
+  createRef(commit: string): Promise<RefWrite>
+  moveRef(commit: string, force: boolean): Promise<RefWrite>
+  deleteRef(): Promise<boolean>
+  readPull(number: number): Promise<PullClosure | undefined>
+}
+
+export type FramesRefusal = 'unreadable-tip' | 'push-failed' | 'ref-conflict'
+
+export interface FrameInput {
+  readonly number: number
+  readonly head: string
+  readonly pass: string
+  readonly box: number
+  readonly bytes: Uint8Array
+}
+
+export type PushResult =
+  | {
+      readonly kind: 'pushed'
+      readonly commit: string
+      readonly path: string
+      readonly created: boolean
+    }
+  | { readonly kind: 'refused'; readonly reason: FramesRefusal }
+
+export type DropResult =
+  | {
+      readonly kind: 'dropped'
+      readonly removed: readonly number[]
+      readonly commit?: string
+      readonly deleted?: boolean
+    }
+  | { readonly kind: 'refused'; readonly reason: FramesRefusal }
+
+export type PruneResult =
+  | {
+      readonly kind: 'dropped'
+      readonly removed: readonly number[]
+      readonly kept: readonly number[]
+      readonly unread: readonly number[]
+      readonly commit?: string
+      readonly deleted?: boolean
+    }
+  | { readonly kind: 'refused'; readonly reason: FramesRefusal }
+
+/** Whether a value names a commit, so a branch name or a path never becomes a folder. */
+export function isFrameHead(head: string): boolean {
+  return HEAD_PATTERN.test(head)
+}
+
+/** Whether a value is a compact UTC stamp, the only pass segment the path takes. */
+export function isFramePass(pass: string): boolean {
+  return PASS_PATTERN.test(pass)
+}
+
+/**
+ * Where a frame lands. The pass segment keeps a second pass at the same head
+ * and box from replacing the image an earlier review comment shows, since a
+ * branch-path link reads whatever the path holds now.
+ */
+export function framePath(
+  number: number,
+  head: string,
+  pass: string,
+  box: number,
+): string {
+  return `pr-${number}/${head.slice(0, SHORT_HEAD_LENGTH)}/${pass}/box-${box}.png`
+}
+
+/**
+ * The embed link, by branch path rather than by commit. Every drop rewrites
+ * the branch, so a commit-pinned link to another pull request's frame would
+ * stop resolving once GitHub collects the commit, while a path link lives
+ * exactly as long as its file. The blob form is the one `canon pr evidence`
+ * embeds, which a private repository's browser can open where the raw host
+ * serves nothing.
+ */
+export function frameLink(repo: string, path: string): string {
+  return `https://github.com/${repo}/blob/${FRAMES_BRANCH}/${path}?raw=true`
+}
+
+/** The frame's bytes, or undefined when the file is absent, empty, or not a PNG. */
+export async function readFrame(path: string): Promise<Uint8Array | undefined> {
+  const bytes = await readFile(path).catch(() => undefined)
+  if (bytes === undefined || bytes.length <= PNG_SIGNATURE.length) {
+    return undefined
+  }
+  return PNG_SIGNATURE.every((byte, index) => bytes[index] === byte)
+    ? new Uint8Array(bytes)
+    : undefined
+}
+
+/**
+ * Commits one frame onto the branch, creating the branch with a root
+ * commit when it is missing. The ref only fast-forwards here, so a drop or a
+ * second add landing between the read and the move fails the move, and the
+ * add rebuilds on the tip that writer left.
+ */
+export async function pushFrame(
+  api: FramesApi,
+  input: FrameInput,
+): Promise<PushResult> {
+  const path = framePath(input.number, input.head, input.pass, input.box)
+  const blob = await api.createBlob(Buffer.from(input.bytes).toString('base64'))
+  if (blob === undefined) return { kind: 'refused', reason: 'push-failed' }
+  const entry: TreeEntry = { path, mode: '100644', type: 'blob', sha: blob }
+  const message = `chore(frames): add box ${input.box} of #${input.number}`
+
+  for (let attempt = 0; attempt < ADD_ATTEMPTS; attempt += 1) {
+    const tip = await api.readTip()
+    if (tip.kind === 'unreadable') {
+      return { kind: 'refused', reason: 'unreadable-tip' }
+    }
+
+    const base = tip.kind === 'found' ? tip.tree : undefined
+    const tree = await api.createTree([entry], base)
+    if (tree === undefined) return { kind: 'refused', reason: 'push-failed' }
+    const parents = tip.kind === 'found' ? [tip.commit] : []
+    const commit = await api.createCommit(message, tree, parents)
+    if (commit === undefined) return { kind: 'refused', reason: 'push-failed' }
+
+    const write =
+      tip.kind === 'found'
+        ? await api.moveRef(commit, false)
+        : await api.createRef(commit)
+    if (write === 'failed') return { kind: 'refused', reason: 'push-failed' }
+    if (write === 'ok') {
+      return { kind: 'pushed', commit, path, created: tip.kind === 'missing' }
+    }
+  }
+  return { kind: 'refused', reason: 'ref-conflict' }
+}
+
+function folderNumber(entry: TreeEntry): number | undefined {
+  if (entry.type !== 'tree') return undefined
+  const match = FOLDER_PATTERN.exec(entry.path)
+  return match?.[1] === undefined ? undefined : Number(match[1])
+}
+
+async function readFolders(
+  api: FramesApi,
+): Promise<
+  | { readonly kind: 'read'; readonly entries: readonly TreeEntry[] }
+  | { readonly kind: 'missing' }
+  | { readonly kind: 'refused'; readonly reason: FramesRefusal }
+> {
+  const tip = await api.readTip()
+  if (tip.kind === 'missing') return { kind: 'missing' }
+  if (tip.kind === 'unreadable') {
+    return { kind: 'refused', reason: 'unreadable-tip' }
+  }
+  const entries = await api.listTree(tip.tree)
+  if (entries === undefined) {
+    return { kind: 'refused', reason: 'unreadable-tip' }
+  }
+  return { kind: 'read', entries }
+}
+
+/**
+ * Rewrites the branch without the named pull requests' folders, as one
+ * root commit the ref is force-moved to. A plain delete commit would
+ * keep every dropped image reachable through history. The rewrite builds from
+ * the tip it reads, and a branch left empty is deleted rather than holding an
+ * empty tree.
+ */
+async function rewriteWithout(
+  api: FramesApi,
+  entries: readonly TreeEntry[],
+  drop: ReadonlySet<number>,
+): Promise<DropResult> {
+  const removed = entries
+    .map(folderNumber)
+    .filter((n): n is number => n !== undefined && drop.has(n))
+    .sort((a, b) => a - b)
+  if (removed.length === 0) return { kind: 'dropped', removed: [] }
+
+  const kept = entries.filter((entry) => {
+    const n = folderNumber(entry)
+    return n === undefined || !drop.has(n)
+  })
+  if (kept.length === 0) {
+    return (await api.deleteRef())
+      ? { kind: 'dropped', removed, deleted: true }
+      : { kind: 'refused', reason: 'push-failed' }
+  }
+
+  const tree = await api.createTree(kept)
+  if (tree === undefined) return { kind: 'refused', reason: 'push-failed' }
+  const message = `chore(frames): drop ${removed.map((n) => `#${n}`).join(', ')}`
+  const commit = await api.createCommit(message, tree, [])
+  if (commit === undefined) return { kind: 'refused', reason: 'push-failed' }
+  const write = await api.moveRef(commit, true)
+  return write === 'ok'
+    ? { kind: 'dropped', removed, commit }
+    : { kind: 'refused', reason: 'push-failed' }
+}
+
+export async function dropFrames(
+  api: FramesApi,
+  numbers: readonly number[],
+): Promise<DropResult> {
+  const folders = await readFolders(api)
+  if (folders.kind === 'missing') return { kind: 'dropped', removed: [] }
+  if (folders.kind === 'refused') return folders
+  return rewriteWithout(api, folders.entries, new Set(numbers))
+}
+
+/**
+ * Whether a pull request's frames are past keeping. Only a pull request
+ * reading closed, with a close date strictly older than the window, expires,
+ * so a reopened one, an unread one, and one at the boundary all stay.
+ */
+export function isExpired(
+  closure: PullClosure | undefined,
+  days: number,
+  now: Date,
+): boolean {
+  if (closure?.state !== 'closed' || closure.closedAt === undefined) {
+    return false
+  }
+  const closed = Date.parse(closure.closedAt)
+  if (Number.isNaN(closed)) return false
+  return now.getTime() - closed > days * DAY_MS
+}
+
+/**
+ * Drops every pull request on the branch that closed more than `days` ago, in
+ * one rewrite. A pull request whose state could not be read is kept and
+ * listed under `unread`, so a failed read never deletes frames.
+ */
+export async function pruneFrames(
+  api: FramesApi,
+  days: number,
+  now: Date,
+): Promise<PruneResult> {
+  const folders = await readFolders(api)
+  if (folders.kind === 'missing') {
+    return { kind: 'dropped', removed: [], kept: [], unread: [] }
+  }
+  if (folders.kind === 'refused') return folders
+
+  const numbers = folders.entries
+    .map(folderNumber)
+    .filter((n): n is number => n !== undefined)
+  const closures = await Promise.all(numbers.map((n) => api.readPull(n)))
+  const expired = new Set<number>()
+  const kept: number[] = []
+  const unread: number[] = []
+  numbers.forEach((n, index) => {
+    const closure = closures[index]
+    if (closure === undefined) unread.push(n)
+    if (isExpired(closure, days, now)) expired.add(n)
+    else kept.push(n)
+  })
+
+  const result = await rewriteWithout(api, folders.entries, expired)
+  if (result.kind === 'refused') return result
+  return {
+    ...result,
+    kept: kept.sort((a, b) => a - b),
+    unread: unread.sort((a, b) => a - b),
+  }
+}

package/src/pr/preview.ts

@@ -95,6 +95,8 @@ export interface RunRow {
   readonly databaseId: number
   readonly status: string
   readonly conclusion: string
+  readonly headSha: string
+  readonly createdAt: string
 }
 
 /** The `gh` calls a preview makes, injected so the wait can be driven without a network. */
@@ -176,3 +178,67 @@ export async function mintPreview(
 
   return { kind: 'minted', runId, url }
 }
+
+export type PreviewHeadReason = 'fresh' | 'stale' | 'building' | 'no-build'
+
+export type PreviewHeadReading =
+  | {
+      readonly reason: PreviewHeadReason
+      readonly tip: string
+      readonly built?: string
+      readonly runId?: number
+    }
+  | { readonly reason: 'gh-failed' }
+
+/**
+ * Compares the head the newest successful dispatch built with the branch tip.
+ *
+ * The run listing is the only record of the built head, since the alias serves
+ * the newest successful deployment per branch and names no sha. Runs are
+ * ordered by creation rather than list position, so the verdict follows the
+ * most recent deploy. A run still going at the tip reads `building` rather
+ * than `stale`, so a mint already under way is not reported as a failure.
+ */
+export async function readPreviewHead(
+  runner: PreviewRunner,
+  target: {
+    readonly workflow: string
+    readonly branch: string
+    readonly tip: string
+  },
+): Promise<PreviewHeadReading> {
+  const rows = await runner.listRuns(target.workflow, target.branch)
+  if (rows === undefined) return { reason: 'gh-failed' }
+
+  const { tip } = target
+  const newest = [...rows].sort((a, b) =>
+    b.createdAt.localeCompare(a.createdAt),
+  )
+  const built = newest.find(
+    (row) => row.status === 'completed' && row.conclusion === 'success',
+  )
+
+  if (built?.headSha === tip) {
+    return {
+      reason: 'fresh',
+      built: built.headSha,
+      tip,
+      runId: built.databaseId,
+    }
+  }
+
+  const pending = newest.find(
+    (row) => row.status !== 'completed' && row.headSha === tip,
+  )
+  if (pending !== undefined) {
+    return {
+      reason: 'building',
+      tip,
+      runId: pending.databaseId,
+      ...(built !== undefined && { built: built.headSha }),
+    }
+  }
+
+  if (built === undefined) return { reason: 'no-build', tip }
+  return { reason: 'stale', built: built.headSha, tip, runId: built.databaseId }
+}

package/src/tooling/manifest.ts

@@ -30,6 +30,14 @@ export interface Manifest {
    * gitignore entries.
    */
   readonly onlyConfigs?: readonly string[]
+  /**
+   * The command that creates a fresh project for this stack, from `[stack]
+   * scaffold`, with `{{name}}` standing for the project folder. Unset on a
+   * layer stack, which scaffolds nothing of its own.
+   */
+  readonly scaffold?: string
+  /** Post-scaffold setup `canon tooling verify` runs ahead of Sync. */
+  readonly prepare?: string
 }
 
 export interface ChainOptions {
@@ -103,9 +111,8 @@ export function isStackExcluded(stack: string): boolean {
 }
 
 /**
- * Lists installable stack names, filtering the `claude` stack the way
- * `is_tooling_stack_excluded` in `scripts/lib/tooling.sh` did. Claude is
- * managed by `canon claude`, not `canon tooling`.
+ * Lists installable stack names, filtering the stacks in `EXCLUDED_STACKS`.
+ * Claude is managed by `canon claude`, not `canon tooling`.
  */
 export function listStacks(root: string): string[] {
   const dir = toolingDir(root)
@@ -134,6 +141,8 @@ export function loadManifest(
     typeof stackTable.extends === 'string' ? stackTable.extends : ''
   const scriptsTable = asTable(parsed.scripts)
   const perRoot = readStrings(asTable(parsed.sync).per_root)
+  const scaffold = readString(stackTable.scaffold)
+  const prepare = readString(asTable(parsed.verify).prepare)
   const dir = join(toolingDir(root), stack)
 
   return {
@@ -147,6 +156,8 @@ export function loadManifest(
     gitignore: readGitignoreSections(asTable(parsed.gitignore)),
     devPackages: readDevPackages(parsed.dependencies),
     ...(perRoot.length > 0 ? { perRoot } : {}),
+    ...(scaffold !== undefined ? { scaffold } : {}),
+    ...(prepare !== undefined ? { prepare } : {}),
   }
 }
 
@@ -231,6 +242,10 @@ function readDevPackages(dependencies: unknown): string[] {
   return readStrings(asTable(asTable(dependencies).dev).packages)
 }
 
+function readString(value: unknown): string | undefined {
+  return typeof value === 'string' && value !== '' ? value : undefined
+}
+
 function readStrings(value: unknown): string[] {
   if (!Array.isArray(value)) return []
   return value.filter(

package/src/tooling/seeds.ts

@@ -0,0 +1,37 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+const TOOLING = 'tooling'
+const SURFACE_ROOTS = ['.claude', 'canon']
+
+/**
+ * Every `tooling/<stack>/seeds` holding a `.claude/` or a `canon/`, sorted and
+ * relative to the root.
+ *
+ * Both seed stages discover through this rather than naming a stack, so a stack
+ * seeding either root later reaches both and the two cannot disagree about which
+ * roots exist. A stack seeding only tracked surfaces carries `canon/` alone,
+ * which a `.claude/` test would drop from both stages. An absent `tooling/` is
+ * an empty answer, and each caller decides what an empty answer means.
+ */
+export function seedRoots(root: string): string[] {
+  const tooling = join(root, TOOLING)
+  if (!existsSync(tooling)) return []
+
+  return readdirSync(tooling)
+    .filter((name) => !name.startsWith('.'))
+    .sort()
+    .map((name) => `${TOOLING}/${name}/seeds`)
+    .filter((seeds) => isDirectory(join(root, seeds)))
+    .filter((seeds) =>
+      SURFACE_ROOTS.some((surface) => isDirectory(join(root, seeds, surface))),
+    )
+}
+
+function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}