@erclx/canon 5.54.0 → 5.56.0

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/sync/engine.ts

@@ -26,7 +26,7 @@ import {
   logStep,
   logWarn,
   outro,
-  palette,
+  outroSuccess,
   select,
 } from '@/cli/ui'
 import { compareVersions, parseVersion } from '@/version/compare'
@@ -436,7 +436,6 @@ export async function runDomainSync(
   }
 
   const plan = planSync(adapter, resolved)
-  const { GREEN, GREY, NC } = palette(process.stderr)
 
   if (
     !existsSync(adapter.installedRoot(resolved)) &&
@@ -453,8 +452,7 @@ export async function runDomainSync(
   if (count === 0) {
     await adapter.onComplete?.(resolved)
     await recordStamp(adapter, resolved, new Date())
-    outro()
-    process.stderr.write(`${GREEN}✓ Everything up to date${NC}\n`)
+    outroSuccess('Everything up to date')
     return 0
   }
 
@@ -489,10 +487,7 @@ export async function runDomainSync(
   await adapter.onComplete?.(resolved)
   await recordStamp(adapter, resolved, new Date())
 
-  outro()
-  process.stderr.write(
-    `${GREEN}✓ Sync complete${NC} ${GREY}(${count} ${adapter.unit})${NC}\n`,
-  )
+  outroSuccess('Sync complete', `(${count} ${adapter.unit})`)
   return 0
 }
 

package/src/sync/workflow.ts

@@ -19,7 +19,7 @@ import {
   logStep,
   logWarn,
   outro,
-  palette,
+  outroSuccess,
   pipeOutput,
   select,
 } from '@/cli/ui'
@@ -75,7 +75,7 @@ export async function collectChanges(git: GitRunner): Promise<DomainChange[]> {
  *
  * This is the only toolkit code that writes to a git remote, which is why a
  * headless run refuses it outright. `select_option` resolved to its first
- * option under `CANON_NON_INTERACTIVE=1`, and the first option here was
+ * option with no terminal to answer it, and the first option here was
  * `Commit and open PR` whenever `gh` was installed, so an agent following the
  * documented non-interactive path pushed a branch and opened a pull request on
  * someone's repository without being asked.
@@ -193,8 +193,6 @@ function promptChoice(canOpenPullRequest: boolean): Promise<WorkflowChoice> {
 }
 
 function succeed(message: string): number {
-  const { GREEN, NC } = palette(process.stderr)
-  outro()
-  process.stderr.write(`\n${GREEN}✓ ${message}${NC}\n`)
+  outroSuccess(message)
   return 0
 }

package/src/tooling/verify-stack.ts

@@ -124,7 +124,7 @@ async function run({
   await phase(state, 'Sync', () =>
     execa('bun', [cli, 'tooling', 'sync', stack, '.', '--write'], {
       ...captured(state.dir),
-      env: { CI: '1', CANON_NON_INTERACTIVE: '1' },
+      env: { CI: '1' },
     }),
   )
 

package/tooling/base/configs/.husky/post-merge

@@ -27,20 +27,16 @@ if ! command -v canon >/dev/null 2>&1; then
   exit 0
 fi
 
-# A global binary older than the verb cannot run it, and the verb carries the
-# only step that would update it, so reinstall here and probe again. The probe
-# reads the verb's own usage line rather than the exit, since an older binary
-# answers an unknown command's `--help` with its root help and exits zero.
+# A global binary older than the verb cannot run it, and its owner upgrades it
+# by hand. The probe reads the verb's own usage line rather than the exit,
+# since an older binary answers an unknown command's `--help` with its root
+# help and exits zero.
 has_verb() {
   canon hooks post-merge --help 2>/dev/null | grep -q '^Usage: canon hooks post-merge'
 }
 
-if ! has_verb; then
-  if [ -z "$CANON_SKIP_UPGRADE" ]; then
-    CANON_NON_INTERACTIVE=1 canon upgrade >/dev/null 2>&1 || true
-  fi
-fi
-
 if has_verb; then
   canon hooks post-merge --root "$root" || true
+else
+  echo 'canon is too old to run the post-merge hook. Run `canon upgrade`.' >&2
 fi

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/scripts/core/check-color-source.sh

@@ -1,51 +0,0 @@
-#!/usr/bin/env bash
-set -e
-set -o pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
-
-SCRIPTS_ROOT="$PROJECT_ROOT/scripts"
-SANDBOX_ROOT="$PROJECT_ROOT/sandbox"
-PALETTE_SOURCE="$SCRIPTS_ROOT/lib/ui.sh"
-
-# `find` writes to stderr and returns non-zero for a missing root, inside a
-# process substitution whose status nothing reads. Without this the walk covers
-# nothing and the check reports the tree clean having never measured it.
-if [ ! -f "$PALETTE_SOURCE" ]; then
-  echo "No palette source at ${PALETTE_SOURCE#"$PROJECT_ROOT/"}, color sourcing unverifiable." >&2
-  exit 1
-fi
-
-# The same silence follows a root that moved, so a walked root that is gone
-# fails here rather than shrinking the corpus with no message.
-for root in "$SCRIPTS_ROOT" "$SANDBOX_ROOT"; do
-  if [ ! -d "$root" ]; then
-    echo "No shell root at ${root#"$PROJECT_ROOT/"}, color sourcing unverifiable." >&2
-    exit 1
-  fi
-done
-
-# Any SGR sequence in either spelling. The cursor and erase sequences an
-# interactive prompt writes end in a letter instead, and they run only where a
-# terminal already exists, so they are not what this measures.
-SGR='\\(033|e|x1b)\[[0-9;]*m'
-
-# Sixteen copies of one decision is what made color impossible to turn off on
-# the TypeScript side. A rule nothing enforces rebuilds them the next time a
-# script wants grey, so the escape lives in the shared library and every other
-# script reads the palette that library derives for its stream.
-offenders=""
-while IFS= read -r file; do
-  [ "$file" = "$PALETTE_SOURCE" ] && continue
-  if grep -qE "$SGR" "$file"; then
-    offenders="$offenders  ${file#"$PROJECT_ROOT/"}"$'\n'
-  fi
-done < <(find "$SCRIPTS_ROOT" "$SANDBOX_ROOT" -type f -name '*.sh')
-
-if [ -n "$offenders" ]; then
-  echo "A color escape is defined outside the shared library:" >&2
-  printf '%s' "$offenders" >&2
-  echo "Source scripts/lib/ui.sh and read its palette, so one answer covers every writer." >&2
-  exit 1
-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()
-  }
-}