@erclx/canon 5.13.0 → 5.14.1

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/sandbox/census.ts

@@ -134,7 +134,7 @@ export function parseExemptions(source: string): Map<string, string> {
 }
 
 function readExemptions(root: string): Map<string, string> {
-  const path = join(root, 'scripts', 'sandbox', EXEMPT_FILE)
+  const path = join(root, 'sandbox', EXEMPT_FILE)
   if (!existsSync(path)) return new Map()
 
   return parseExemptions(readFileSync(path, 'utf8'))

package/src/sandbox/coverage.ts

@@ -88,7 +88,7 @@ function armsFor(
  * a suite that proves something from one that runs.
  */
 export function collectCoverage(root: string): CoverageReport {
-  const sandboxDir = join(root, 'scripts', 'sandbox')
+  const sandboxDir = join(root, 'sandbox')
   const fixturesDir = join(sandboxDir, FIXTURES_DIR)
 
   const scenarios = listScenarios(sandboxDir).map((scenario) => ({

package/src/sandbox/expect.ts

@@ -138,7 +138,6 @@ export function expectFilePath(
 ): string {
   return join(
     root,
-    'scripts',
     'sandbox',
     'fixtures',
     category,

package/src/shipped/references.ts

@@ -36,13 +36,10 @@ export const SHIPPED_CORPORA = [
 
 /**
  * Trees inside a corpus above that no target receives, matching the negations
- * the `files` field already makes. A number under either names something its
- * only reader can already resolve.
+ * the `files` field already makes. A number under one names something its only
+ * reader can already resolve.
  */
-export const SHIPPED_EXCLUSIONS = [
-  /^scripts\/sandbox\//,
-  /^scripts\/eval\//,
-] as const
+export const SHIPPED_EXCLUSIONS = [/^scripts\/eval\//] as const
 
 /** Whether a repository-relative path sits in the gated corpus. */
 export function isShippedCorpus(path: string): boolean {
@@ -97,10 +94,11 @@ const PULL_REQUEST = /(?<![0-9A-Za-z_])#([0-9]+)(?![0-9A-Za-z_])/g
  * The third is the one a later author meets. Admitting an all-digit sha admits
  * every run of seven or more decimal digits with it, so a date written without
  * separators, a large count, or a float artifact reads as a commit reference.
- * The corpus carries no instance and that is the exclusions rather than luck:
- * twelve such runs sit under the seven roots, eleven of them under
- * `scripts/sandbox/`, `scripts/eval/`, or a test file, and the twelfth is the
- * genuine sha in `orchestrator-poll.md`. Write a seven-digit measurement into a
+ * The corpus carries no instance and that is the corpus bounds rather than luck:
+ * twelve such runs were counted when the scenario tree still sat under
+ * `scripts/`, eleven of them under that tree, `scripts/eval/`, or a test file,
+ * all now outside the corpus, and the twelfth is the genuine sha in
+ * `orchestrator-poll.md`. Write a seven-digit measurement into a
  * shipped page and the push fails on it, which the marker answers and no
  * narrowing can, since requiring a letter loses the all-digit sha above.
  */

package/src/targets/pulls.ts

@@ -8,7 +8,7 @@ const GH_TIMEOUT_MS = 30_000
  * The two headings a review pass posts under.
  *
  * Owned by `review-pr`, which states the full set once, and pinned here
- * the way `role-orchestrator/scripts/poll.sh` pins them. All three surfaces
+ * the way `role-orchestrator/scripts/poll.ts` pins them. All three surfaces
  * ship separately, so a heading added in that skill goes stale here with
  * nothing comparing the copies.
  */
@@ -139,7 +139,7 @@ export function rollup(checks: readonly RawCheck[]): ChecksState | null {
 
 /**
  * Reads the heading of the newest pass carrying one, matching on the first line
- * alone the way `poll.sh` does.
+ * alone the way `poll.ts` does.
  *
  * The reviews arrive oldest first, so the last match is the current state of
  * the thread. A pass carrying neither heading is somebody reviewing by hand and

package/src/tooling/manifest.ts

@@ -111,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)

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
+  }
+}

package/tooling/claude/manifest.toml

@@ -1,5 +1,5 @@
 # Consumed only by `canon claude init`. Claude is not a discoverable tooling stack
-# and is excluded from `canon tooling` discovery via scripts/lib/tooling.sh.
+# and is excluded from `canon tooling` discovery via `EXCLUDED_STACKS` in src/tooling/manifest.ts.
 
 [stack]
 name = "claude"
@@ -8,8 +8,8 @@ runtime = ""
 scaffold = ""
 
 # Checked against this repository's own `.gitignore` by
-# scripts/core/check-ignore-parity.sh, which carries no sanctioned divergence
-# now that both sides ship the same two entries.
+# the Ignore parity stage of `bun run check`, which carries no sanctioned
+# divergence now that both sides ship the same two entries.
 #
 # One root entry rather than a folder apiece, so a target that gains a record
 # folder later receives no manifest edit and no sync. `.claude/worktrees/` is

package/tsconfig.json

@@ -11,5 +11,5 @@
       "@/*": ["./src/*"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "claude/skills/*/scripts/**/*.ts"]
 }