@erclx/canon 5.76.0 → 5.78.0

package/src/targets/registry.ts

@@ -2,11 +2,12 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  realpathSync,
   renameSync,
   writeFileSync,
 } from 'node:fs'
-import { homedir } from 'node:os'
-import { dirname, join, resolve } from 'node:path'
+import { homedir, tmpdir } from 'node:os'
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 
 /**
  * One project the toolkit has installed into, as the install recorded it.
@@ -116,15 +117,90 @@ function isRecord(value: Partial<TargetRecord>): value is TargetRecord {
 }
 
 /**
- * Reads every recorded target, sorted by path.
+ * The folders whose contents are never a project, resolved at call time so a
+ * test's `CANON_STATE_DIR` override moves the state root with it.
+ *
+ * Sandbox runs and replays live under the state folder, background jobs keep
+ * their scratch under `~/.claude/jobs/`, and unit tests stamp into the OS temp
+ * folder. Each one passes through a stamping sync, so without this list every
+ * run leaves a row behind for a folder that is gone a minute later.
+ */
+export function scratchRoots(): readonly string[] {
+  return [tmpdir(), stateDir(), join(homedir(), '.claude', 'jobs')]
+}
+
+/**
+ * Whether a path sits under a scratch root or inside any `.canon/tmp/` folder.
+ *
+ * Both sides are compared in their given and their real form, since macOS
+ * hands out its temp folder as `/var/folders/...` while a path that went
+ * through a symlink resolution reads `/private/var/folders/...`. A
+ * `.claude/worktrees/` checkout is not scratch: it is a real checkout of a real
+ * project, and only a root on the list or a `.canon/tmp/` segment refuses it.
+ */
+export function isScratchPath(
+  target: string,
+  roots: readonly string[] = scratchRoots(),
+): boolean {
+  const forms = bothForms(resolve(target))
+  const rootForms = roots.flatMap((root) => bothForms(resolve(root)))
+
+  return forms.some(
+    (form) =>
+      hasCanonTmpSegment(form) ||
+      rootForms.some((root) => isWithin(form, root)),
+  )
+}
+
+function bothForms(path: string): readonly string[] {
+  try {
+    const real = realpathSync(path)
+    return real === path ? [path] : [path, real]
+  } catch {
+    return [path]
+  }
+}
+
+function hasCanonTmpSegment(path: string): boolean {
+  const segments = path.split(sep)
+  return segments.some(
+    (segment, index) => segment === '.canon' && segments[index + 1] === 'tmp',
+  )
+}
+
+function isWithin(path: string, root: string): boolean {
+  const rel = relative(root, path)
+  return (
+    rel === '' ||
+    (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+  )
+}
+
+/**
+ * Whether a row still names a project worth listing: a folder that exists and
+ * sits under no scratch root. The read filter and the write prune both call
+ * this, so the two can never disagree on a row.
+ */
+function isLive(row: TargetRecord, roots: readonly string[]): boolean {
+  return existsSync(row.path) && !isScratchPath(row.path, roots)
+}
+
+/**
+ * Reads every recorded target that is still live, sorted by path.
  *
  * A row missing either field is dropped rather than reported. This module is
  * the file's only writer, so a malformed row is a hand edit or a truncated
  * write and neither is a finding the caller can act on. What a caller can act
  * on is the file being absent, which is its own kind above.
+ *
+ * A row whose folder is gone or under a scratch root is left out too, so the
+ * list is right on a machine whose file predates the prune, before any sync
+ * rewrites it. A target on a drive that is unmounted reads as gone here, and
+ * its next sync records it again.
  */
 export function readTargetRegistry(
   path: string = registryPath(),
+  roots: readonly string[] = scratchRoots(),
 ): TargetRegistry {
   let text: string
   try {
@@ -150,38 +226,46 @@ export function readTargetRegistry(
     .filter((row): row is TargetRecord =>
       isRecord(row as Partial<TargetRecord>),
     )
+    .filter((row) => isLive(row, roots))
     .sort((a, b) => a.path.localeCompare(b.path))
 
   return { kind: 'read', path, targets }
 }
 
-/** Why a record attempt did not land, so a caller can say so rather than assume it did. */
-export type RecordOutcome = 'recorded' | 'unwritten'
+/**
+ * Why a record attempt did not land, so a caller can say so rather than assume
+ * it did. `scratch` is a deliberate refusal of a path under a scratch root,
+ * not a failure.
+ */
+export type RecordOutcome = 'recorded' | 'unwritten' | 'scratch'
 
 /**
  * Records one target, keyed by its resolved path and replacing any row already
- * held for it.
+ * held for it, and refuses a path under a scratch root.
  *
  * The write is a temp file plus a rename, so a reader never meets a half
  * written file. Two syncs finishing together still resolve last-writer-wins on
  * the merged set, which can drop the row the loser added. That is left rather
  * than locked: the authoritative record of an install is the stamp inside the
  * target, this index is a cache over those, and the next sync of the dropped
- * target restores its row.
+ * target restores its row. The prune reads the same merged set the write
+ * already reads, so it adds no second read and does not widen that window.
  *
- * Nothing removes a row either, so a target that was deleted or that dropped
- * the toolkit stays here and the count drifts upward. `canon targets pulls`
- * meets that on use, since it refuses a path it cannot open rather than
- * reading it as a target with no work, but `canon targets list` does not: it
- * never opens a recorded path, and the count is its whole output.
+ * Every write also drops the rows `readTargetRegistry` leaves out, being a
+ * folder that is gone or one under a scratch root, so the file shrinks back to
+ * the live projects rather than growing with every sandbox run. A target on a
+ * drive that is unmounted drops with them, and its next sync restores it.
  */
 export function recordTarget(
   target: string,
   now: Date,
   path: string = registryPath(),
+  roots: readonly string[] = scratchRoots(),
 ): RecordOutcome {
   const resolved = resolve(target)
-  const current = readTargetRegistry(path)
+  if (isScratchPath(resolved, roots)) return 'scratch'
+
+  const current = readTargetRegistry(path, roots)
   const existing = current.kind === 'read' ? current.targets : []
 
   const targets = [
@@ -220,7 +304,8 @@ export type BackfillOutcome = RecordOutcome | 'no-stamp'
 export function backfillTarget(
   target: BackfillTarget,
   path: string = registryPath(),
+  roots: readonly string[] = scratchRoots(),
 ): BackfillOutcome {
   if (target.stampedAt === null) return 'no-stamp'
-  return recordTarget(target.path, new Date(target.stampedAt), path)
+  return recordTarget(target.path, new Date(target.stampedAt), path, roots)
 }

package/src/targets/resolve.ts

@@ -45,6 +45,8 @@ export interface ResolveTargetsOptions extends SweepOptions {
   /** Roots to walk, supplementing the record rather than replacing it. */
   readonly sweep?: readonly string[]
   readonly registryFile?: string
+  /** Folders whose recorded rows are left out, defaulting to `scratchRoots()`. */
+  readonly scratchRoots?: readonly string[]
 }
 
 /**
@@ -71,7 +73,7 @@ export async function resolveTargets(
   }
 
   const file = opts.registryFile ?? registryPath()
-  const registry = readTargetRegistry(file)
+  const registry = readTargetRegistry(file, opts.scratchRoots)
 
   const recorded: KnownTarget[] =
     registry.kind === 'read'

package/tooling/astro/configs/card.config.mjs

@@ -14,7 +14,11 @@ const portOffset = Number(process.env.WORKTREE_PORT_OFFSET) || 0
 // The base port sits outside the band `astro.config.mjs` serves from, so a card
 // server and a dev server of one worktree never contend, and two worktrees
 // separate here the way they separate there.
+//
+// The dev toolbar is off because this server exists to be captured, and the
+// toolbar paints over the viewport the capture cuts the card from.
 export default defineConfig({
+  devToolbar: { enabled: false },
   srcDir: './card-src',
   outDir: './card-dist',
   publicDir: './public',

package/tooling/astro/configs/scripts/check-card-exclusion.sh

@@ -50,8 +50,13 @@ if grep -rl "$MARKER" "$DIST" >/dev/null 2>&1; then
   exit 1
 fi
 
-if find "$DIST" -iname '*og-card*' | grep -q .; then
-  echo "A file named for the card route reached $DIST. See card.config.mjs's srcDir." >&2
+# Built pages only, since an image or font may carry the route's name without
+# being the route. The path test covers both formats Astro emits, being
+# og-card/index.html under build.format 'directory' and og-card.html under
+# 'file'. The search runs from inside dist so a project checked out under a
+# directory like blog-card-site cannot match on its own prefix.
+if (cd "$DIST" && find . -ipath '*og-card*' -name '*.html' | grep -q .); then
+  echo "A page named for the card route reached $DIST. See card.config.mjs's srcDir." >&2
   exit 1
 fi
 

package/tooling/astro/reference.md

@@ -64,7 +64,7 @@ The astro stack covers Astro + TypeScript projects, being content sites, marketi
 ## Social card route
 
 - Keep the social card as a route the project owns, so a re-render after a rename is one string edit and a re-capture rather than another `design-identity` pick loop
-- Expect `canon:design-identity` to write the picked composition into the route and capture it through the card server
+- Expect `canon:design-identity` to write the picked composition into the route and capture it through the card server, which runs with Astro's dev toolbar off so it never paints over the card
 - `card.config.mjs` is a second Astro config whose `srcDir` points at `./card-src`, which the main page router never reads, so the published build excludes the card structurally
 - It serves on base port `4421` plus `WORKTREE_PORT_OFFSET`, outside the band `astro.config.mjs` serves from, so a worktree's card and dev servers never contend
 - `bun run card:dev` serves the route and `bun run card:check` runs the exclusion check, which base's `scripts/verify.ts` also runs after its build stage
@@ -72,6 +72,7 @@ The astro stack covers Astro + TypeScript projects, being content sites, marketi
 ## Card exclusion and size
 
 - `scripts/check-card-exclusion.sh` fails when the route's `<meta name="og-card-marker">` tag reaches `dist/`, and when the route dropped the tag the leak test reads
+- The filename test reads built HTML pages only, under an `og-card` path in either build format, so an image or font may carry the route's name
 - Keep the exclusion a check rather than a convention, since the card server and the capture read the route and the published build must not carry it
 - Declare `.card` at 600x315, half the 1200x630 target, since `canon capture` shoots at a fixed 2x device scale and 1200x630 would capture at 2400x1260
 

package/tooling/web/configs/.github/workflows/readme-screenshot.yml

@@ -74,10 +74,12 @@ jobs:
         # Unconditional: the cache holds browser binaries and nothing apt
         # wrote, so gating this on a cache hit leaves a warm run launching
         # chromium without the libraries it needs.
-        run: bunx playwright install-deps chromium
+        timeout-minutes: 10
+        run: bash scripts/install-playwright-deps.sh chromium
 
       - name: Install Playwright Browser
         if: steps.playwright-cache.outputs.cache-hit != 'true'
+        timeout-minutes: 5
         run: bunx playwright install chromium
 
       - name: Capture README Screenshot

package/tooling/web/configs/.github/workflows/verify.yml

@@ -72,7 +72,7 @@ jobs:
       - name: Install Playwright System Dependencies
         if: steps.browser.outputs.enabled == 'true'
         timeout-minutes: 10
-        run: bunx playwright install-deps chromium
+        run: bash scripts/install-playwright-deps.sh chromium
 
       - name: Cache Playwright Browsers
         id: playwright-cache
@@ -84,6 +84,7 @@ jobs:
 
       - name: Install Playwright Chromium
         if: steps.browser.outputs.enabled == 'true' && steps.playwright-cache.outputs.cache-hit != 'true'
+        timeout-minutes: 5
         run: bunx playwright install chromium
 
       - name: Run Tests
@@ -151,7 +152,8 @@ jobs:
           path: dist/
 
       - name: Install Playwright System Dependencies
-        run: bunx playwright install-deps chromium
+        timeout-minutes: 10
+        run: bash scripts/install-playwright-deps.sh chromium
 
       - name: Cache Playwright Browsers
         id: playwright-cache
@@ -162,6 +164,7 @@ jobs:
 
       - name: Install Playwright Chromium
         if: steps.playwright-cache.outputs.cache-hit != 'true'
+        timeout-minutes: 5
         run: bunx playwright install chromium
 
       - name: Run E2E Tests

package/tooling/web/configs/scripts/install-playwright-deps.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Installs the Playwright system packages for the named browsers, killing an
+# attempt that outlives its bound and retrying it. A degraded apt mirror hangs
+# one connection rather than failing it, so a step timeout alone turns the
+# hang into a red check and never recovers it, while a fresh attempt usually
+# lands on a healthy backend.
+#
+# Usage: install-playwright-deps.sh [--package <spec>] <browser>...
+# Exits 0 on the first success, 2 when no browser is named, and the last
+# attempt's code when every attempt fails.
+set -e
+
+package=playwright
+if [ "$1" = "--package" ]; then
+  package=$2
+  shift 2
+fi
+
+if [ $# -eq 0 ]; then
+  echo "Usage: install-playwright-deps.sh [--package <spec>] <browser>..." >&2
+  exit 2
+fi
+
+attempts=3
+bound=${INSTALL_ATTEMPT_SECONDS:-150}
+
+# The runner image sets these, yet a stalled log shows gaps of minutes, so
+# print what apt actually reads to settle whether they took effect
+apt-config dump | grep -E '^Acquire::(Retries|http::Timeout) ' || true
+
+status=0
+for attempt in $(seq 1 "$attempts"); do
+  if [ "$attempt" -gt 1 ]; then
+    # timeout runs as the runner user, and Linux drops its signal to the root
+    # apt-get playwright spawns through sudo. sudo relays it only to its own
+    # child shell, so a root apt-get or dpkg can outlive the kill and hold the
+    # lock the next attempt needs.
+    sudo pkill -KILL -x 'apt-get|dpkg' || true
+    # A kill during unpack leaves dpkg interrupted, which refuses the next
+    # install. Its own failure must not end the loop.
+    sudo dpkg --configure -a || echo "dpkg --configure -a failed before attempt ${attempt}" >&2
+  fi
+
+  status=0
+  timeout --kill-after=10 "$bound" bunx "$package" install-deps "$@" || status=$?
+  if [ "$status" -eq 0 ]; then
+    exit 0
+  fi
+  echo "attempt ${attempt}/${attempts} failed with exit ${status}" >&2
+done
+
+exit "$status"

package/tooling/web/reference.md

@@ -88,6 +88,11 @@ The starter `e2e/home.spec.ts` is seeded once. Sync copies it into a project tha
 - `.github/workflows/verify.yml` runs `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests`. `unit-tests` installs Chromium and runs `test:browser` only when the project defines that script.
 - Read `governance/rules/tooling/ci-workflow.md` for when a workflow's commit-back is right and when a report is
 
+## Playwright installs in CI
+
+- Both workflows install Playwright's system packages through `scripts/install-playwright-deps.sh`, which sits beside `worktree-port.sh` and retries an attempt a stalled apt mirror hangs
+- Expect each system install bounded at 10 minutes and each browser download at 5, while the jobs carry no bound, since test and build time differs per project
+
 ## Design references
 
 - Expect a seeded `canon/design/index.md` stub carrying `auto: false`, copied only when missing, so a project's own index is never replaced

package/src/commands/fixtures/gh.sh

@@ -1,64 +0,0 @@
-#!/usr/bin/env bash
-# Fake gh for src/commands/pr.test.ts. Reads FAKE_GH_FX, FAKE_GH_COMMENTS, and FAKE_GH_API_LOG.
-set -o pipefail
-fx="$FAKE_GH_FX"
-f=.
-p=
-for a in "$@"; do
-  [ "$p" = --jq ] && f=$a
-  p=$a
-done
-case "$*" in
-*graphql* | "pr "* | "repo view"*) exit 1 ;;
-api*pulls/7/files*)
-  echo "$*" >>"$fx/files-calls.log"
-  [ -f "$fx/files-fail" ] && exit 1
-  {
-    if [ -f "$fx/files.tsv" ]; then
-      cat "$fx/files.tsv"
-    else
-      git diff --name-status --no-renames main...HEAD | sed -e 's/^A/added/' -e 's/^M/modified/' -e 's/^D/removed/'
-    fi
-  } | jq -Rn '[inputs | select(length > 0) | split("\t") | {status: .[0], filename: .[1]}]' | jq -r "$f"
-  ;;
-api*git/trees/*)
-  [ -f "$fx/base-tree.json" ] || exit 1
-  jq -r "$f" "$fx/base-tree.json"
-  ;;
-api*contents/*)
-  a="$*"
-  p=${a##*contents/}
-  p=${p%%\?*}
-  r=${a##*ref=}
-  [ -f "$fx/img/$r-$(basename "$p")" ] && cat "$fx/img/$r-$(basename "$p")" || exit 1
-  ;;
-api*compare/*)
-  if [ -f "$fx/merge-base" ]; then cat "$fx/merge-base"; else git merge-base main HEAD; fi
-  ;;
-"api -X PUT repos/{owner}/{repo}/pulls/7/reviews/"*)
-  id=${4##*/}
-  echo "$id" >>"$fx/review-puts.log"
-  [ -f "$fx/review-put-fail-$id" ] && exit 1
-  printf '%s\n' "${@: -1}" >>"$fx/review-bodies.log"
-  echo "{}"
-  ;;
-api*pulls/7/reviews*) [ -f "$fx/ui-reviews.json" ] && jq -r "$f" "$fx/ui-reviews.json" ;;
-api*issues/7/comments*) jq '[.comments[] | {html_url: .url, body}]' "$FAKE_GH_COMMENTS" | jq -r "$f" ;;
-"api -X PATCH repos/{owner}/{repo}/pulls/7 "*)
-  [ -f "$fx/body-fail" ] && exit 1
-  printf '%s' "${@: -1}" >"$fx/body-write.log"
-  echo "{}"
-  ;;
-"api repos/{owner}/{repo}/pulls/7")
-  if [ -f "$fx/head" ]; then h=$(cat "$fx/head"); else h=$(git rev-parse HEAD); fi
-  b=
-  [ -f "$fx/pr-body" ] && b=$(cat "$fx/pr-body")
-  jq -n --arg h "$h" --arg b "$b" '{number:7,head:{ref:"feat/x",sha:$h},base:{ref:"main"},mergeable_state:"clean",body:$b}'
-  ;;
-"api repos/{owner}/{repo}") echo "{\"full_name\":\"o/r\"}" ;;
-api*)
-  printf '%s' "${@: -1}" >"$FAKE_GH_API_LOG"
-  echo "{}"
-  ;;
-*) exit 1 ;;
-esac

package/src/take/fixtures/busy.html

@@ -1,107 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>Busy</title>
-    <!--
-      A hero canvas that redraws every frame and spends busy=<ms> of main
-      thread work on each, so a frame takes about that long to render. A card
-      sits about 2900px down, below the window, and the rail link scrolls to it.
-      With timed=1 each frame spins on performance.now() instead, as the
-      groundwork page did, which never ends once the stepper pauses virtual
-      time.
-    -->
-    <style>
-      html {
-        scroll-behavior: smooth;
-      }
-
-      body {
-        margin: 0;
-        font-family: sans-serif;
-      }
-
-      nav {
-        position: fixed;
-        top: 10px;
-        right: 10px;
-        z-index: 2;
-      }
-
-      nav a {
-        display: block;
-        padding: 12px 20px;
-        background: #fff;
-      }
-
-      canvas {
-        display: block;
-        width: 100vw;
-        height: 100vh;
-      }
-
-      section {
-        height: 900px;
-        border-top: 1px solid #ccc;
-        padding: 40px;
-      }
-
-      .card {
-        width: 400px;
-        height: 240px;
-        background: #ddd;
-      }
-
-      .card:hover {
-        background: #f60;
-      }
-    </style>
-  </head>
-  <body>
-    <nav><a id="rail" href="#cards">Cards</a></nav>
-    <canvas id="hero"></canvas>
-    <section>one</section>
-    <section>two</section>
-    <section id="cards"><div class="card" id="card">card</div></section>
-    <section>four</section>
-    <script>
-      const params = new URLSearchParams(location.search)
-      const busy = Number(params.get('busy') || 0)
-      const timed = params.get('timed') === '1'
-      const hero = document.getElementById('hero')
-      hero.width = innerWidth
-      hero.height = innerHeight
-      const context = hero.getContext('2d')
-      // The work is a count calibrated in real time on load, since a loop
-      // timed by performance.now() never ends under a paused virtual clock.
-      let sink = 0
-      const spin = (count) => {
-        for (let i = 0; i < count; i += 1) sink += Math.sqrt(i)
-      }
-      const measure = (ms) => {
-        let count = 0
-        const start = performance.now()
-        while (performance.now() - start < ms) {
-          spin(10000)
-          count += 10000
-        }
-        return count / ms
-      }
-      // Warmed first, so the count matches the optimized loop a frame runs.
-      measure(100)
-      const work = Math.round(busy * measure(200))
-      const draw = (time) => {
-        if (timed) {
-          const start = performance.now()
-          while (performance.now() - start < busy) {}
-        } else {
-          spin(work)
-        }
-        context.fillStyle = `hsl(${(time / 10) % 360}, 60%, 50%)`
-        context.fillRect(0, 0, hero.width, hero.height)
-        requestAnimationFrame(draw)
-      }
-      requestAnimationFrame(draw)
-    </script>
-  </body>
-</html>

package/src/take/fixtures/fade.html

@@ -1,49 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>Fade</title>
-    <!--
-      A band that fades from black to white over exactly one second of page
-      time once the button is pressed, so its brightness frame by frame reads
-      how much page time each frame of a take advanced.
-    -->
-    <style>
-      body {
-        margin: 0;
-        background: #808080;
-      }
-
-      #go {
-        position: absolute;
-        left: 100px;
-        top: 100px;
-        width: 200px;
-        height: 60px;
-      }
-
-      #band {
-        position: absolute;
-        left: 0;
-        top: 300px;
-        width: 1920px;
-        height: 780px;
-        background-color: #000;
-        transition: background-color 1000ms linear;
-      }
-
-      #band.lit {
-        background-color: #fff;
-      }
-    </style>
-  </head>
-  <body>
-    <button id="go">Go</button>
-    <div id="band"></div>
-    <script>
-      document.getElementById('go').addEventListener('click', () => {
-        document.getElementById('band').classList.add('lit')
-      })
-    </script>
-  </body>
-</html>

package/src/take/fixtures/fetch.html

@@ -1,38 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>Fetch</title>
-    <!--
-      A button whose press starts a fetch the server answers slowly, the way
-      a page switch in an app loads what the next view shows. A take must keep
-      stepping frames while the fetch is in flight.
-    -->
-    <style>
-      body {
-        margin: 0;
-        background: #808080;
-      }
-
-      #go {
-        position: absolute;
-        left: 100px;
-        top: 100px;
-        width: 200px;
-        height: 60px;
-      }
-    </style>
-  </head>
-  <body>
-    <button id="go">Load</button>
-    <p id="status">idle</p>
-    <script>
-      document.getElementById('go').addEventListener('click', () => {
-        document.getElementById('status').textContent = 'loading'
-        fetch('/slow').then(() => {
-          document.getElementById('status').textContent = 'loaded'
-        })
-      })
-    </script>
-  </body>
-</html>