@erclx/canon 5.55.0 → 5.57.0

package/src/process/harness.ts

@@ -9,6 +9,13 @@ const CLI = join(PROJECT_ROOT, 'src/cli.ts')
 /** No case has ever needed longer, and a blocked verb should fail fast. */
 const DEFAULT_TIMEOUT_MS = 10_000
 
+/**
+ * A spawn that reaches `bun add` fails at once against this unreachable
+ * address, so an unseeded install is a loud defect rather than a test that
+ * passes or fails with the network. `options.env` still wins.
+ */
+const DEAD_REGISTRY = 'http://127.0.0.1:9'
+
 export interface ProcessRun {
   readonly status: number | null
   readonly stdout: string
@@ -127,6 +134,7 @@ export function runCli(
       ...inherited,
       CANON_STATE_DIR: join(options.cwd, '.canon-state'),
       CANON_SANDBOX_DIR: join(options.cwd, '.canon-state', 'sandbox'),
+      BUN_CONFIG_REGISTRY: DEAD_REGISTRY,
       ...options.env,
     },
   })

package/src/process/seeded-package.ts

@@ -0,0 +1,21 @@
+import { existsSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { PROJECT_ROOT } from '@/roots/project'
+import { resolveChain } from '@/tooling/manifest'
+import { collectDeps, parseSpec } from '@/tooling/package'
+
+// A write run into a folder with no package.json would run `bun add -D` against
+// the registry. A package.json already naming the stack's packages leaves
+// nothing to install, so a test not about the manifest stays offline.
+export const seedPackage = (dir: string, stack: string): void => {
+  const path = join(dir, 'package.json')
+  if (existsSync(path)) return
+
+  const devDependencies = Object.fromEntries(
+    collectDeps(resolveChain(PROJECT_ROOT, stack), {}).map((dep) => [
+      dep.name,
+      parseSpec(dep.spec).pin || '*',
+    ]),
+  )
+  writeFileSync(path, JSON.stringify({ devDependencies }))
+}

package/src/records/validate.ts

@@ -219,6 +219,7 @@ const QUESTION_ITEM = /^\d+[a-z]?\.[ \t]+\S/
 
 const PLAN_SECTIONS = [
   'Summary',
+  'Current behavior',
   'Constraints',
   'Files to touch',
   'Design references',

package/src/serve/static.ts

@@ -1,6 +1,5 @@
 import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs'
 import { join, resolve, sep } from 'node:path'
-import type { LiveStream } from '@/serve/live'
 
 /**
  * The loopback interface, never a wildcard bind. A preview serves whatever
@@ -79,25 +78,11 @@ export interface ServeStarted {
 
 export type ServeOutcome = ServeStarted | ServeRefused
 
-/** The route a live page's script opens its event stream on. */
-export const LIVE_EVENTS_PATH = '/__live'
-
-export interface LiveServe {
-  readonly stream: Pick<LiveStream<unknown>, 'answer'>
-  /**
-   * The `<script>` element spliced into every page served, built by the caller
-   * so this module stays free of what a reload means to any one surface.
-   */
-  readonly script: string
-}
-
 export interface ServeOptions {
   readonly port?: number
   readonly entry?: string
   /** Answers a directory request with no index page by listing it. Off by default. */
   readonly index?: boolean
-  /** Answers the events route and splices a script into each page. Off by default. */
-  readonly live?: LiveServe
 }
 
 function escapeHtml(text: string): string {
@@ -267,59 +252,16 @@ export function bindFirstFree(
   return undefined
 }
 
-/**
- * Splices the script in before the last closing body tag of a page. A page
- * carrying none goes out as the bytes on disk, since guessing a place for it
- * risks breaking markup the author wrote. The splice happens per response and
- * never on disk, so a page the reader saves or commits carries no hook.
- */
-export async function injectLive(
-  response: Response,
-  script: string,
-): Promise<Response> {
-  const type = response.headers.get('content-type') ?? ''
-  if (response.status !== 200 || !type.startsWith('text/html')) return response
-
-  const bytes = new Uint8Array(await response.arrayBuffer())
-  const html = new TextDecoder().decode(bytes)
-  /*
-   * Searched in the original rather than a lowercased copy, since lowercasing
-   * changes the length of some characters, such as İ, and an index read off
-   * the copy would cut the original inside the tag.
-   */
-  const at = [...html.matchAll(/<\/body>/gi)].at(-1)?.index
-  const init = { status: response.status, headers: response.headers }
-  if (at === undefined) return new Response(bytes, init)
-  return new Response(`${html.slice(0, at)}${script}${html.slice(at)}`, init)
-}
-
 function listen(
   root: string,
   first: number,
   index: boolean,
-  live: LiveServe | undefined,
 ): { server: BoundServer; port: number } | undefined {
-  if (!live) {
-    return bindFirstFree(first, (port) =>
-      Bun.serve({
-        hostname: SERVE_HOST,
-        port,
-        fetch: (request) => respond(root, request, index),
-      }),
-    )
-  }
   return bindFirstFree(first, (port) =>
     Bun.serve({
       hostname: SERVE_HOST,
       port,
-      /* The event stream stays open for as long as the page does. */
-      idleTimeout: 0,
-      fetch: async (request, server) => {
-        if (new URL(request.url).pathname === LIVE_EVENTS_PATH) {
-          return live.stream.answer(request, server.port ?? 0)
-        }
-        return injectLive(await respond(root, request, index), live.script)
-      },
+      fetch: (request) => respond(root, request, index),
     }),
   )
 }
@@ -435,7 +377,7 @@ export function startServer(
    */
   let bound: ReturnType<typeof listen>
   try {
-    bound = listen(root, first, options.index ?? false, options.live)
+    bound = listen(root, first, options.index ?? false)
   } catch (error) {
     const code = (error as NodeJS.ErrnoException).code ?? 'unknown'
     return refuse(

package/src/tasks/branch.ts

@@ -43,6 +43,11 @@ function slugOf(path: string): string {
   return stem.startsWith(PLAN_PREFIX) ? stem.slice(PLAN_PREFIX.length) : stem
 }
 
+/** The branch a plan file derives, from its filename alone. */
+export function branchOfPlan(path: string): string {
+  return `${PLAN_BRANCH_TYPE}/${slugOf(path)}`
+}
+
 /**
  * Derives the branch a dispatch checks and a worker takes, from the plan both
  * of them name. It is the one derivation, so the collision check and the
@@ -60,7 +65,7 @@ export function planBranch(root: string, reference: string): BranchOutcome {
   if (!resolved.ok) return resolved
 
   const slug = slugOf(resolved.path)
-  const branch = `${PLAN_BRANCH_TYPE}/${slug}`
+  const branch = branchOfPlan(resolved.path)
   const words = slug.split('-').filter((word) => word.length > 0).length
 
   return {

package/src/tasks/record.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import { readFile, writeFile } from 'node:fs/promises'
 import { basename, join, relative } from 'node:path'
 import { planCandidates } from '@/tasks/answers'
+import { branchOfPlan } from '@/tasks/branch'
 import {
   appendPlanLink,
   describeUnmatchedStem,
@@ -57,6 +58,7 @@ export interface RecordRefused {
 export type RecordSelector =
   | { readonly kind: 'stem'; readonly stem: string }
   | { readonly kind: 'plan'; readonly plan: string }
+  | { readonly kind: 'branch'; readonly branches: readonly string[] }
 
 export type LineAction = 'added' | 'appended' | 'corrected' | 'unchanged'
 
@@ -383,6 +385,25 @@ async function resolveStem(
     return selector.stem
   }
 
+  if (selector.kind === 'branch') {
+    const matched = await matchByBranch(dir, stems, selector.branches)
+    const label = selector.branches[0] ?? 'no branch'
+
+    if (matched.length === 0) {
+      return refuse('no-match', `No task's plan derives branch ${label}.`)
+    }
+
+    if (matched.length > 1) {
+      return refuse(
+        'ambiguous',
+        `${matched.length} tasks derive branch ${label}. One task, one plan.`,
+        matched,
+      )
+    }
+
+    return matched[0]
+  }
+
   const matched = await matchByPlan(dir, stems, selector.plan)
 
   if (matched.length === 0) {
@@ -400,6 +421,29 @@ async function resolveStem(
   return matched[0]
 }
 
+/**
+ * Matches a branch to the tasks whose plan derives it. A task with no `Plan:`
+ * line carries no target and so never matches.
+ */
+async function matchByBranch(
+  dir: string,
+  stems: readonly string[],
+  branches: readonly string[],
+): Promise<string[]> {
+  const read = await Promise.all(
+    stems.map(async (stem) => ({
+      stem,
+      targets: readPlanTargets(await readFile(join(dir, `${stem}.md`), 'utf8')),
+    })),
+  )
+
+  return read
+    .filter((entry) =>
+      entry.targets.some((target) => branches.includes(branchOfPlan(target))),
+    )
+    .map(({ stem }) => stem)
+}
+
 export async function openTask(
   root: string,
   selector: RecordSelector,

package/tooling/base/reference.md

@@ -91,18 +91,19 @@ Negative knowledge that costs a failed run to relearn.
 
 ## CLI
 
-| Script                 | What it does                                                                                                                  |
-| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `bun run check`        | Gates a checkout through `scripts/verify.ts`, writing nothing. `VERIFY_NESTED=true` suppresses timeline boundaries in a call. |
-| `bun run check:format` | Asserts oxfmt formatting without writing                                                                                      |
-| `bun run format`       | Writes oxfmt formatting in place                                                                                              |
-| `bun run prepare`      | Initializes husky hooks, run automatically on `bun install`                                                                   |
+| Script                 | What it does                                                  |
+| ---------------------- | ------------------------------------------------------------- |
+| `bun run check`        | Gates a checkout through `scripts/verify.ts`, writing nothing |
+| `bun run check:format` | Asserts oxfmt formatting without writing                      |
+| `bun run format`       | Writes oxfmt formatting in place                              |
+| `bun run prepare`      | Initializes husky hooks, run automatically on `bun install`   |
 
 ### The check script
 
 Base writes `check` as a `[scripts.override]`, so a sync replaces whatever `check` a target declared, including one that chained further checks after the runner. Re-add a chained check as its own script after a sync.
 
 - `bun run check` writes nothing. Formatting drift fails it at `check:format`, and the failure line names `bun run format`, the one command that writes.
+- `VERIFY_NESTED=true` suppresses timeline boundaries when `check` runs inside another call
 - Auto-fixing drift inside `check` rewrote files in a shared checkout on every push and left a gate that could not fail, so the writing pass stays in `bun run format`.
 - The pull request workflow calls `check:format` directly as well.
 

package/tooling/claude/reference.md

@@ -47,11 +47,13 @@ A project installed before the board became a folder still holds `.claude/TASKS.
 
 ## CLI
 
-| Command              | What it does                                                                                                                                                                     |
-| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `canon claude init`  | Seeds `.claude/` workflow docs, updates `.gitignore`                                                                                                                             |
-| `canon claude sync`  | Reconciles `.gitignore` against the manifest. Reports seeded file status.                                                                                                        |
-| `canon claude setup` | Installs user-level config to `~/.claude/` once per machine: statusline and the permissions allow and deny lists, and removes the empty attribution pair an earlier setup wrote. |
+| Command              | What it does                                                              |
+| -------------------- | ------------------------------------------------------------------------- |
+| `canon claude init`  | Seeds `.claude/` workflow docs, updates `.gitignore`                      |
+| `canon claude sync`  | Reconciles `.gitignore` against the manifest. Reports seeded file status. |
+| `canon claude setup` | Installs user-level config to `~/.claude/` once per machine               |
+
+`canon claude setup` writes the statusline and the permissions allow and deny lists, and removes the empty attribution pair an earlier setup wrote.
 
 ## CLAUDE.md
 

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -79,12 +79,13 @@ colons=$(printf '%s' "$record" |
 # returns them for a path in its scope and a finding the push does not fail on
 # yet is the one a rewrite has to clear before its folder is gated.
 density=$(printf '%s' "$record" |
-  jq -r '.entries[]?.density[]? | ":\(.line)  \(.kind)  " + (if .limit == null then "opens with neither a paragraph nor a table" else "\(.value) past \(.limit)" end) + (if .gating then "  gating" else "" end)' 2>/dev/null)
+  jq -r '.entries[]?.density[]? | ":\(.line)  \(.kind)  " + (if .kind == "table-then-list" then "a list follows the table with no lead sentence" elif .limit == null then "opens with neither a paragraph nor a table" else "\(.value) past \(.limit)" end) + (if .gating then "  gating" else "" end)' 2>/dev/null)
 
-# Table findings report and never gate, so each kind is handed back with the
-# fix its shape takes rather than the seam a density finding splits at.
+# The row count and the wide token report and never gate, so each kind is handed
+# back with the fix its shape takes rather than the seam a density finding
+# splits at. The cell and the trailing list arrive as density findings.
 tables=$(printf '%s' "$record" |
-  jq -r '.entries[]?.tables[]? | ":\(.line)  \(.kind)  " + (if .limit == null then "a list follows the table with no lead sentence" else "\(.value) past \(.limit)" end)' 2>/dev/null)
+  jq -r '.entries[]?.tables[]? | ":\(.line)  \(.kind)  " + "\(.value) past \(.limit)"' 2>/dev/null)
 
 # A page marked `kind: reference` carries reference shape findings, handed back
 # whole the same way, since a gated one fails the push like a density finding.
@@ -126,12 +127,12 @@ if [ -n "$colons" ]; then
 fi
 
 if [ -n "$density" ]; then
-  found=$(printf 'Standards-audit: %s breaks the markdown density limits, being a 350-character paragraph, 2 paragraphs in a row, a 200-character bullet, 5 plain bullets in a row, no H4, and a paragraph or table opening every H3. Split each block at its seam rather than trimming words to pass. A finding marked gating fails the push.\n%s' "$file" "$density")
+  found=$(printf 'Standards-audit: %s breaks the markdown density limits, being a 350-character paragraph, 2 paragraphs in a row, a 200-character bullet, 5 plain bullets in a row, no H4, and a paragraph or table opening every H3, a 120-character table cell, and no list directly after a table. Split each block at its seam rather than trimming words to pass. A finding marked gating fails the push.\n%s' "$file" "$density")
   msg="${msg:+$msg$nl}$found"
 fi
 
 if [ -n "$tables" ]; then
-  found=$(printf 'Standards-audit: %s breaks the markdown table limits, being a 120-character cell, 8 body rows, a list directly after a table, and a code span holding a run past 30 characters. These report and never fail a push. Move a long cell into a bullet under the table'"'"'s lead, split a long table into groups each under a lead sentence, give a trailing list its own lead sentence, and move a wide token out of the table.\n%s' "$file" "$tables")
+  found=$(printf 'Standards-audit: %s breaks the markdown table limits that report, being 8 body rows and a code span holding a run past 30 characters. These never fail a push. Split a long table into groups each under a lead sentence, and move a wide token out of the table.\n%s' "$file" "$tables")
   msg="${msg:+$msg$nl}$found"
 fi
 

package/src/serve/live.ts

@@ -1,113 +0,0 @@
-import { type FSWatcher, watch } from 'node:fs'
-import { SERVE_HOST } from '@/serve/static'
-
-/**
- * How long a burst of watch events for one path waits before it is sent. One
- * editor save raises several, and each would otherwise reach a reader again.
- */
-const SETTLE_MS = 40
-
-export interface LiveOptions<T> {
-  /**
-   * Turns a changed path, relative to the watched directory, into what a change
-   * carries, or into undefined to drop it, such as a write's staging file.
-   */
-  readonly map: (path: string) => T | undefined
-  /**
-   * Takes each settled change in place of the clients. A caller that has work
-   * to do before a reader may look, such as regenerating pages, sends its own
-   * payload through `send` once that work lands.
-   */
-  readonly onChange?: (payload: T) => void
-}
-
-/**
- * Whether a request names this server by a loopback name and its own port.
- * The bind keeps other machines out, and this keeps out a page the operator
- * visits whose domain was rebound to 127.0.0.1, which reaches the socket with
- * its own name in the Host header.
- */
-export function isLoopbackHost(host: string | null, port: number): boolean {
-  return host === `${SERVE_HOST}:${port}` || host === `localhost:${port}`
-}
-
-/**
- * Watches a directory and fans each settled change out as a server-sent event
- * to every open client, or to `onChange` when the caller takes changes itself.
- */
-export class LiveStream<T> {
-  private readonly clients = new Set<ReadableStreamDefaultController<string>>()
-  private readonly pending = new Map<string, ReturnType<typeof setTimeout>>()
-  private readonly watcher: FSWatcher
-
-  constructor(
-    dir: string,
-    private readonly options: LiveOptions<T>,
-  ) {
-    this.watcher = watch(dir, { recursive: true }, (_event, filename) => {
-      if (filename) this.queue(filename.toString())
-    })
-  }
-
-  private queue(path: string): void {
-    const payload = this.options.map(path)
-    if (payload === undefined) return
-    clearTimeout(this.pending.get(path))
-    this.pending.set(
-      path,
-      setTimeout(() => {
-        this.pending.delete(path)
-        if (this.options.onChange) this.options.onChange(payload)
-        else this.send(payload)
-      }, SETTLE_MS),
-    )
-  }
-
-  send(payload: unknown): void {
-    const frame = `data: ${JSON.stringify(payload)}\n\n`
-    for (const client of this.clients) client.enqueue(frame)
-  }
-
-  open(): Response {
-    let self: ReadableStreamDefaultController<string> | undefined
-    const stream = new ReadableStream<string>({
-      start: (controller) => {
-        self = controller
-        this.clients.add(controller)
-        controller.enqueue(': open\n\n')
-      },
-      cancel: () => {
-        if (self) this.clients.delete(self)
-      },
-    })
-    return new Response(stream, {
-      headers: {
-        'content-type': 'text/event-stream',
-        'cache-control': 'no-store',
-      },
-    })
-  }
-
-  /** Opens a stream for a request naming this server, and refuses any other. */
-  answer(request: Request, port: number): Response {
-    if (isLoopbackHost(request.headers.get('host'), port)) return this.open()
-    return new Response('Forbidden\n', {
-      status: 403,
-      headers: { 'content-type': 'text/plain; charset=utf-8' },
-    })
-  }
-
-  close(): void {
-    this.watcher.close()
-    for (const timer of this.pending.values()) clearTimeout(timer)
-    this.pending.clear()
-    for (const client of this.clients) {
-      try {
-        client.close()
-      } catch {
-        /* Already closed by the browser going away. */
-      }
-    }
-    this.clients.clear()
-  }
-}