@erclx/canon 5.35.0 → 5.36.0

package/tooling/shell/reference.md

@@ -0,0 +1,46 @@
+# Tooling shell reference
+
+## Overview
+
+The shell stack is an add-on that formats and lints the shell scripts a project writes. It extends nothing and syncs beside any other stack at the same root with `canon tooling sync shell . --write`, so a project that writes no shell never installs shfmt or shellcheck.
+
+## Install
+
+- Install `shfmt` and `shellcheck` by hand, through `sudo apt-get install shfmt shellcheck` or `brew install shfmt shellcheck`. Injection runs only `bun add -D`, and neither tool ships through the registry.
+- `scripts/verify.ts` probes both before the `Shell` phase and names the install command when one is missing, rather than letting `find` report a missing executable.
+
+## shfmt
+
+- Indent with 2 spaces, set through `--indent 2` on every call.
+- `.editorconfig` carries an `[*.sh]` block with `indent_style = space` and `indent_size = 2`, so the editor and shfmt agree. Dropping the block because shfmt already sets indentation produces spurious diffs.
+
+## shellcheck
+
+- Run at warning severity.
+- `.shellcheckrc` sets `external-sources=true`, which shellcheck needs to follow `source` directives.
+
+## Coverage
+
+- Both tools take their files from `find scripts -name '*.sh'`, since `scripts/` can mix shell with TypeScript and shellcheck has no directory mode.
+- A shell script with a shebang and no `.sh` extension is covered by neither, so give it the extension.
+- Keep shell scripts in `scripts/`. A `.sh` file elsewhere, such as a seeded `.claude/hooks/` script, is left out on purpose.
+
+## Verify
+
+- `scripts/verify.ts` runs `check:shell` in its `Shell` phase wherever `package.json` declares it, between the format check and the unit tests. No stack's `scripts/verify.json` requires it, so a folder that never synced this stack skips the phase.
+
+## lint-staged
+
+- `.lintstagedrc` is a base seed this stack cannot reach once written. Add a `**/*.sh` entry by hand, running `shfmt --write --indent 2` then `shellcheck --severity=warning`, to run the checks on commit.
+- Do NOT copy that glob into a `package.json` script. lint-staged expands its own globs and passes matched files as arguments, which a bare shell script does not.
+
+## CI
+
+- `.github/workflows/shell.yml` runs on pull requests targeting `main` and on `workflow_dispatch`: checkout, setup Bun, `bun install --frozen-lockfile`, install both tools through apt, then `check:shell`.
+
+## CLI
+
+| Script                 | What it does                                                    |
+| ---------------------- | --------------------------------------------------------------- |
+| `bun run check:shell`  | Asserts shfmt formatting, then runs shellcheck at warning level |
+| `bun run format:shell` | Writes shfmt formatting in place                                |

package/tooling/vite-react/manifest.toml

@@ -15,7 +15,6 @@ packages = [
 "build" = "tsc --noEmit && vite build"
 "preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && vite preview"
 "typecheck" = "tsc --noEmit"
-"setup" = "./scripts/setup.sh"
 
 [scripts.override]
 "build" = "tsc --noEmit && vite build"

package/tooling/vite-react/reference.md

@@ -33,14 +33,6 @@ When scaffolding a Chrome extension, override the installed golden configs:
 - `screenshot` script: `bun run build && bun e2e/screenshot.ts` (no preview server).
 - Additional gitignore entries: `*.crx`, `*.pem`, `release/`.
 
-## Setup script
-
-- File: `scripts/setup.sh`. Destructive: deletes `.git` and self-removes after running. Run once immediately after scaffolding.
-- Prompt for project name, normalize to kebab-case, derive title-cased display name.
-- Update `package.json` name and version, inject verify/clean/update scripts, remove setup.
-- Update `<title>` tags in HTML files.
-- Wipe `.git`, re-init, make scripts executable, commit as `chore(root): initialize <name>`.
-
 ## Development docs (extend)
 
 Append to the `## Scripts` table:

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

@@ -95,11 +95,9 @@ jobs:
         # and stops here without pushing a second time.
         if: steps.diff.outputs.changed == 'true'
         # The hooks are off because this commit carries nothing they can read.
-        # `pre-push` runs the full verify, whose format step shells out to
-        # `shfmt`, which the runner does not install, so a push through them
-        # exits 127. The jobs in verify.yml already run those checks against
-        # the source, and what this step pushes is PNG bytes a capture
-        # produced.
+        # `pre-push` runs the full verify, which reruns every check the jobs
+        # in verify.yml already ran against the source, and what this step
+        # pushes is PNG bytes a capture produced.
         env:
           HUSKY: 0
         run: |

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

@@ -30,9 +30,6 @@ jobs:
       - name: Install Dependencies
         run: bun install --frozen-lockfile
 
-      - name: Install Shell Tools
-        run: sudo apt-get install -y shfmt shellcheck
-
       - name: Typecheck
         run: bun run typecheck
 
@@ -42,9 +39,6 @@ jobs:
       - name: Check Formatting
         run: bun run check:format
 
-      - name: Check Shell
-        run: bun run check:shell
-
   unit-tests:
     name: 🧪 Unit Tests
     runs-on: ubuntu-latest

package/tooling/web/manifest.toml

@@ -46,7 +46,7 @@ packages = [
 "test:e2e:changed" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && playwright test --only-changed"
 "test:e2e:ui" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && playwright test --ui"
 "test:e2e:report" = "playwright show-report"
-"check:full" = "./scripts/verify.sh && bun run test:e2e"
+"check:full" = "bun scripts/verify.ts && bun run test:e2e"
 "smoke:prod" = "bun e2e/screenshot.ts --check-console-clean --require-base-url"
 
 [scripts.override]

package/tooling/web/reference.md

@@ -16,7 +16,7 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 - `scripts/screenshot.sh`: sources `scripts/lib/preview-server.sh`, then runs the capture against the served preview.
 - `scripts/lib/preview-server.sh`: sourced, never executed. Builds, serves on `PREVIEW_PORT`, blocks until the port answers, and traps the whole process group on exit, including the detached grandchild `lsof` finds. Both capture scripts source it so the startup lives once.
 - `scripts/readme-screenshot.sh`: captures one case under `SCREENSHOT_FILTER` and copies its light and dark frames to `assets/evidence/readme/`. `README_FILTER` ships empty with `header/1280` as its example, and the script exits 1 until a project fills it, since a shipped default would capture the wrong part of the page in every project but one. Its copy reads from `screenshots/<hostname>/`, which is where the harness writes.
-- `.github/workflows/readme-screenshot.yml`: refreshes that frame on a pull request and commits it back to the branch. The path list ships as `REPLACE_WITH_PROJECT_PATHS`, and the job's first step after checkout exits 1 while it stays, since a job that never fires leaves no run and no diff to notice. The workflow's own path is in the list so the installing pull request reaches that step. When a commit-back is right and when a report is, `governance/rules/tooling/700-ci-workflow.md` states the test.
+- `.github/workflows/readme-screenshot.yml`: refreshes that frame on a pull request and commits it back to the branch. The path list ships as `REPLACE_WITH_PROJECT_PATHS`, and the job's first step after checkout exits 1 while it stays, since a job that never fires leaves no run and no diff to notice. The workflow's own path is in the list so the installing pull request reaches that step. When a commit-back is right and when a report is, `governance/rules/tooling/ci-workflow.md` states the test.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.json`: the phases base's verify runner requires here, being typecheck, lint, unit tests, and build. `## Verify script` covers the order and the card exclusion stage.
 - `scripts/worktree-port.sh`: prints a base port plus this working directory's offset. Called with no argument it prints the offset alone. It refuses a folder left under the worktrees directory after its worktree was removed, rather than printing a port for it.
@@ -113,7 +113,7 @@ Append rows:
 
 `canon tooling verify <stack>` is the only automated caller of `bun run screenshot`, running it for any stack whose `package.json` declares the script and asserting that PNG files land under `screenshots/`. It counts them with a recursive find carrying no depth limit, so the section folders the seed writes satisfy the assertion without a change to it. Do not flatten the layout to protect that check. No ship chain captures a screenshot, so the output path the seed writes is a contract that one verifier reads rather than a default a ship step depends on.
 
-`governance/rules/ui/440-surface-capture.md` is what asks a session to run the capture after a surface changes. It now fires on every component file too, reversing the route-and-page-only scope this reference once described, after a shipped batch of components carried no capture and a defect went unseen. The rule body states its own exemption for a component the production build strips out, so a reader chasing that case reads it there rather than here.
+`governance/rules/ui/surface-capture.md` is what asks a session to run the capture after a surface changes. It now fires on every component file too, reversing the route-and-page-only scope this reference once described, after a shipped batch of components carried no capture and a defect went unseen. The rule body states its own exemption for a component the production build strips out, so a reader chasing that case reads it there rather than here.
 
 The sweep under `screenshots/` is ignored again, and only a flagged case's `evidence/` output tracks in git, so the first capture a scaffolded target runs after this change is the baseline it commits there. A case naming sections commits a folder per section under that baseline rather than one file per theme, which is what lets a pull request comparison land on the part of the page that moved instead of on one image of the whole of it. The count is the section list times the themes, so a list is worth sizing against how many frames each later change has to regenerate and a reviewer has to read.
 
@@ -126,6 +126,6 @@ The sweep under `screenshots/` is ignored again, and only a flagged case's `evid
 
 ## Verify script
 
-The web layer's `scripts/verify.json` requires `typecheck`, `lint`, `test:run`, and `build`, and base's `scripts/verify.ts` runs them in its fixed order: typecheck, lint, format, shell, unit tests, build, markdown bans, then the card exclusion check where one is installed. astro, vite-react, and nextjs inherit the list, since the nearest stack's copy wins. An adapter whose phases differ ships its own `verify.json` rather than a script.
+The web layer's `scripts/verify.json` requires `typecheck`, `lint`, `test:run`, and `build`, and base's `scripts/verify.ts` runs them in its fixed order: typecheck, lint, format, shell where the `shell` stack declares it, unit tests, build, markdown bans, then the card exclusion check where one is installed. astro, vite-react, and nextjs inherit the list, since the nearest stack's copy wins. An adapter whose phases differ ships its own `verify.json` rather than a script.
 
 The card stage runs `scripts/check-card-exclusion.sh` whenever that file is installed, which keeps the social card route's build exclusion on the default path rather than behind a flag. It tests for the script rather than the stack, so a project with no card route runs one less stage with no override, and the stack shipping a card route owns what the check reads, being the build the stage before it produced. The astro reference carries the route itself.

package/tooling/base/configs/scripts/verify.sh

@@ -1,2 +0,0 @@
-#!/bin/bash
-exec bun "$(dirname "$0")/verify.ts" "$@"