@erclx/canon 5.12.0 → 5.13.0

package/src/tooling/verify-stack.ts

@@ -0,0 +1,249 @@
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { execa, type Options } from 'execa'
+import { isStackExcluded, loadManifest } from '@/tooling/manifest'
+import { intro, logError, logInfo, logStep, logWarn, outro } from '@/ui'
+
+const SCREENSHOT_TIMEOUT_MS = 60_000
+const TAIL_LINES = 20
+
+export interface VerifyOptions {
+  readonly root: string
+  readonly stack: string
+  readonly keep?: boolean
+}
+
+export interface PhaseResult {
+  readonly name: string
+  readonly passed: boolean
+}
+
+export interface VerifyOutcome {
+  readonly results: readonly PhaseResult[]
+  readonly exitCode: number
+}
+
+interface Run {
+  readonly dir: string
+  readonly results: PhaseResult[]
+  isFailed: boolean
+}
+
+/**
+ * Scaffolds a stack into `.canon/tmp/runs/verify-<stack>/`, syncs its chain
+ * from the checkout at `root`, and runs the scaffold's own `lint:fix`,
+ * `check`, `test:e2e`, and `screenshot` scripts. Every line goes to stderr.
+ *
+ * A failed phase is recorded and the run carries on, so the Results block
+ * reports every phase rather than the first failure. The tmp dir is removed
+ * only on a clean run without `keep`.
+ */
+export async function verifyStack(opts: VerifyOptions): Promise<VerifyOutcome> {
+  intro(`canon tooling verify ${opts.stack}`)
+  // A signal skips the `finally` below, so the handler closes the frame on
+  // that path and leaves the tmp dir in place for inspection.
+  let isOpen = true
+  const close = (): void => {
+    if (isOpen) outro()
+    isOpen = false
+  }
+  const handleSignal = (): void => {
+    close()
+    process.exit(130)
+  }
+  process.once('SIGINT', handleSignal)
+  process.once('SIGTERM', handleSignal)
+
+  try {
+    return await run(opts)
+  } finally {
+    process.off('SIGINT', handleSignal)
+    process.off('SIGTERM', handleSignal)
+    close()
+  }
+}
+
+async function run({
+  root,
+  stack,
+  keep = false,
+}: VerifyOptions): Promise<VerifyOutcome> {
+  const refuse = (message: string): VerifyOutcome => {
+    logError(message)
+    return { results: [], exitCode: 1 }
+  }
+
+  if (isStackExcluded(stack)) {
+    return refuse(`Stack '${stack}' is excluded from tooling.`)
+  }
+  const manifest = loadManifest(root, stack)
+  if (manifest === undefined) {
+    return refuse(`No manifest at tooling/${stack}/manifest.toml`)
+  }
+  if (manifest.scaffold === undefined) {
+    return refuse(`Stack '${stack}' has no scaffold command in manifest.`)
+  }
+
+  const runsDir = join(root, '.canon/tmp/runs')
+  const name = `verify-${stack}`
+  const state: Run = { dir: join(runsDir, name), results: [], isFailed: false }
+
+  mkdirSync(runsDir, { recursive: true })
+  rmSync(state.dir, { recursive: true, force: true })
+
+  logStep(`Scaffolding ${stack}`)
+  // Manifests carry shell syntax (`&&`, `cd`, quoted globs), so the command
+  // runs under a shell rather than as a split argv.
+  const scaffold = await shell(
+    manifest.scaffold.replaceAll('{{name}}', name),
+    runsDir,
+  )
+  if (scaffold.failed) {
+    logWarn('Scaffold failed')
+    writeTail(scaffold.all)
+    state.isFailed = true
+  }
+
+  if (!existsSync(state.dir)) {
+    return refuse(`Scaffold did not produce ${state.dir}`)
+  }
+
+  await shell(
+    'git init -q && git add . && git commit -m "chore: verify scaffold" -q --no-verify --allow-empty',
+    state.dir,
+  )
+
+  const { prepare } = manifest
+  if (prepare !== undefined) {
+    await phase(state, 'Prepare', () => shell(prepare, state.dir))
+  }
+
+  const cli = join(root, 'src/cli.ts')
+  logInfo(`Sync resolves via bun ${cli}, not PATH canon`)
+  await phase(state, 'Sync', () =>
+    execa('bun', [cli, 'tooling', 'sync', stack, '.', '--write'], {
+      ...captured(state.dir),
+      env: { CI: '1', CANON_NON_INTERACTIVE: '1' },
+    }),
+  )
+
+  const packagePath = join(state.dir, 'package.json')
+  if (existsSync(packagePath)) {
+    await runScripts(state, readScriptKeys(packagePath))
+  } else {
+    logError(
+      `No package.json after Sync for ${stack}, so no phase past Sync can run.`,
+    )
+    state.isFailed = true
+  }
+
+  logStep('Results')
+  for (const result of state.results) {
+    if (result.passed) logInfo(result.name)
+    else logWarn(result.name)
+  }
+
+  if (!keep && !state.isFailed) {
+    rmSync(state.dir, { recursive: true, force: true })
+  } else {
+    logInfo(`Kept ${state.dir}`)
+  }
+
+  return { results: state.results, exitCode: state.isFailed ? 1 : 0 }
+}
+
+/**
+ * `lint:fix` runs first and reformats the scaffold, so `check` reads the
+ * reformatted tree.
+ */
+async function runScripts(state: Run, scripts: Set<string>): Promise<void> {
+  await phase(state, 'lint:fix', () => bunRun('lint:fix', state.dir))
+  await phase(state, 'check', () => bunRun('check', state.dir))
+
+  if (scripts.has('test:e2e')) {
+    await phase(state, 'test:e2e', () => bunRun('test:e2e', state.dir))
+  }
+
+  if (!scripts.has('screenshot')) return
+  const isShot = await phase(state, 'screenshot', () =>
+    bunRun('screenshot', state.dir, SCREENSHOT_TIMEOUT_MS),
+  )
+  // A killed or failed screenshot run is already a failure, and its partial
+  // output says nothing about the artifacts.
+  if (!isShot) return
+
+  const shots = countScreenshots(join(state.dir, 'screenshots'))
+  if (shots === 0) logWarn('screenshot produced no png files')
+  record(state, 'screenshot-artifacts', shots > 0)
+}
+
+type Spawned = Awaited<ReturnType<typeof execa>>
+
+async function phase(
+  state: Run,
+  name: string,
+  spawn: () => Promise<Spawned>,
+): Promise<boolean> {
+  logStep(name)
+  const result = await spawn()
+  if (!result.failed) {
+    logInfo(`${name} passed`)
+    record(state, name, true)
+    return true
+  }
+  logWarn(result.timedOut ? `${name} timed out` : `${name} failed`)
+  writeTail(result.all)
+  record(state, name, false)
+  return false
+}
+
+function record(state: Run, name: string, passed: boolean): void {
+  state.results.push({ name, passed })
+  if (!passed) state.isFailed = true
+}
+
+function captured(cwd: string): Options {
+  return { cwd, all: true, reject: false, stdin: 'ignore' }
+}
+
+function shell(command: string, cwd: string): Promise<Spawned> {
+  return execa(command, {
+    ...captured(cwd),
+    shell: 'bash',
+    env: { CI: '1' },
+  })
+}
+
+function bunRun(
+  script: string,
+  cwd: string,
+  timeout?: number,
+): Promise<Spawned> {
+  return execa('bun', ['run', script], {
+    ...captured(cwd),
+    env: { CI: '1' },
+    ...(timeout !== undefined ? { timeout } : {}),
+  })
+}
+
+function writeTail(output: unknown): void {
+  if (typeof output !== 'string' || output === '') return
+  const lines = output.replace(/\n$/, '').split('\n').slice(-TAIL_LINES)
+  process.stderr.write(`${lines.join('\n')}\n`)
+}
+
+function readScriptKeys(packagePath: string): Set<string> {
+  try {
+    const parsed = JSON.parse(readFileSync(packagePath, 'utf8')) as {
+      scripts?: Record<string, unknown>
+    }
+    return new Set(Object.keys(parsed.scripts ?? {}))
+  } catch {
+    return new Set()
+  }
+}
+
+function countScreenshots(dir: string): number {
+  if (!existsSync(dir)) return 0
+  return [...new Bun.Glob('**/*.png').scanSync({ cwd: dir, dot: true })].length
+}

package/tooling/base/seeds/.cspell/tech-stack.txt

@@ -3,11 +3,13 @@ bradlc
 bunx
 commitlint
 dbaeumer
+dotenv
 dotfolders
 erclx
 errexit
 esac
 esbenp
+eslintcache
 frontmatter
 lintstagedrc
 mkhl

package/tooling/go/manifest.toml

@@ -11,3 +11,6 @@ scaffold = "mkdir {{name}} && cd {{name}} && go mod init example.com/{{name}} &&
 "test" = "go test ./..."
 "test:run" = "go test -v ./..."
 "build" = "go build ./..."
+
+[verify]
+prepare = "bun init -y && (command -v golangci-lint >/dev/null || go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest)"

package/tooling/go/reference.md

@@ -32,6 +32,7 @@ The go stack also ships `smoke_test.go` at the module root as a copy-once seed.
 - Probe `go` and `golangci-lint` first, and name the `go install` command when `golangci-lint` is missing.
 - Keep `build` out of `verify.json`, even though the stack declares the script. `go build ./...` exits 1 with `no packages to build` on a module holding only a test file, and a seeded `main.go` would assume every module is a binary rather than a library.
 - Keep `-race` out of `test:run`. The race detector needs cgo and a C toolchain, so it belongs in CI rather than in a local `bun run check`.
+- The manifest's `[verify] prepare` runs checklist steps 3 and 6 for `canon tooling verify go`: `bun init -y`, then the `golangci-lint` `go install` when the binary is not already on PATH. The scaffold writes no `package.json`, and a verify that reaches its end with none fails.
 
 ## CI
 

package/tooling/php/manifest.toml

@@ -13,3 +13,6 @@ scaffold = "mkdir {{name}} && cd {{name}} && composer init -n --name example/{{n
 
 [gitignore]
 "# PHP" = ["vendor/", ".php-cs-fixer.cache", ".phpunit.cache/", ".phpunit.result.cache"]
+
+[verify]
+prepare = "bun init -y && composer require --dev friendsofphp/php-cs-fixer phpstan/phpstan phpunit/phpunit"

package/tooling/php/reference.md

@@ -44,6 +44,7 @@ The php stack also ships `tests/SmokeTest.php` as a copy-once seed, so `bun run
 - Probe `php` and `composer` first.
 - Hold a precondition on `vendor/bin/phpunit`, so the run stops and names `composer install` when it is missing.
 - Require Typecheck (`phpstan analyse`), Lint (`php-cs-fixer check`), and Unit tests (`phpunit --testdox`). Base's runner adds the four base phases wherever the folder declares their scripts, then the markdown bans stage.
+- The manifest's `[verify] prepare` runs checklist steps 2 and 5 for `canon tooling verify php`: `bun init -y`, then the `composer require --dev` line. The scaffold writes no `package.json`, and a verify that reaches its end with none fails.
 
 ## Gitignore
 

package/tooling/python/manifest.toml

@@ -14,3 +14,6 @@ scaffold = "uv init --package {{name}}"
 
 [gitignore]
 "# Python" = [".pytest_cache/", ".mypy_cache/", ".ruff_cache/", ".coverage_cache/"]
+
+[verify]
+prepare = "bun init -y && uv add --dev ruff mypy pytest pytest-cov && uv sync"

package/tooling/python/reference.md

@@ -39,7 +39,7 @@ The manifest declares no `[dependencies.dev]`. Manifest injection currently call
 
 ## Verify command
 
-`canon tooling verify <stack>` currently runs `bun run lint:fix` and `bun run check` against any stack with a `package.json`. Since base ships a `package.json`, those run for python too. Python's `verify.json` requires the package.json `lint`/`typecheck`/`test:run` scripts that delegate to `uv run`, so the verify path works end-to-end as long as `uv` is installed in the verify environment. The end-to-end test and screenshot phases are gated on `package.json` script keys that python does not declare, so they cleanly skip.
+`canon tooling verify python` runs the manifest's `[verify] prepare` before Sync, which is checklist steps 2, 5, and 6: `bun init -y`, `uv add --dev ruff mypy pytest pytest-cov`, and `uv sync`. `uv init` writes no `package.json`, and a verify that reaches its end with none fails, so the prepare is what lets `bun run lint:fix` and `bun run check` run at all. Python's `verify.json` requires the `lint`, `typecheck`, and `test:run` scripts that delegate to `uv run`, so the run needs `uv` on the machine and a network for the installs. The end-to-end test and screenshot phases are gated on `package.json` script keys that python does not declare, so they skip.
 
 ## Anti-patterns
 

package/tooling/python/seeds/.cspell/tech-stack.txt

@@ -2,7 +2,6 @@ addopts
 appuser
 asyncio
 coveragerc
-dotenv
 fastapi
 flake8
 htmlcov

package/scripts/tooling/verify.sh

@@ -1,184 +0,0 @@
-#!/usr/bin/env bash
-set -e
-set -o pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
-
-source "$PROJECT_ROOT/scripts/lib/ui.sh"
-source "$PROJECT_ROOT/scripts/lib/tooling.sh"
-
-show_help() {
-  echo -e "${GREY}┌${NC}"
-  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} canon tooling verify <stack> [options]"
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
-  echo -e "${GREY}│${NC}    --keep       ${GREY}# Keep tmp dir after run for inspection${NC}"
-  echo -e "${GREY}│${NC}    -h, --help   ${GREY}# Show this help message${NC}"
-  echo -e "${GREY}│${NC}"
-  echo -e "${GREY}│${NC}  Scaffolds <stack> into .canon/tmp/runs/verify-<stack>/, syncs the full"
-  echo -e "${GREY}│${NC}  layer chain, and runs check + test:e2e + screenshot."
-  echo -e "${GREY}└${NC}"
-  exit 0
-}
-
-read_manifest_field() {
-  local toml="$1"
-  local section="$2"
-  local field="$3"
-  awk -v s="$section" -v f="$field" '
-    $0 == "[" s "]" { in_section = 1; next }
-    in_section && /^\[/ { exit }
-    in_section && match($0, "^" f "[[:space:]]*=") {
-      val = substr($0, RLENGTH + 1)
-      sub(/^[[:space:]]+/, "", val)
-      sub(/^"/, "", val)
-      sub(/"$/, "", val)
-      print val
-      exit
-    }
-  ' "$toml"
-}
-
-run_phase() {
-  local name="$1"
-  shift
-  log_step "$name"
-  if "$@" >/tmp/verify-phase.log 2>&1; then
-    log_info "$name passed"
-    RESULTS+=("$name:pass")
-    return 0
-  fi
-  log_warn "$name failed"
-  tail -20 /tmp/verify-phase.log >&2
-  RESULTS+=("$name:fail")
-  FAILED=1
-  return 1
-}
-
-main() {
-  local stack=""
-  local keep=0
-
-  while [[ $# -gt 0 ]]; do
-    case "$1" in
-    -h | --help) show_help ;;
-    --keep)
-      keep=1
-      shift
-      ;;
-    -*)
-      log_error "Unknown option: $1"
-      ;;
-    *)
-      if [ -z "$stack" ]; then
-        stack="$1"
-        shift
-      else
-        log_error "Unexpected argument: $1"
-      fi
-      ;;
-    esac
-  done
-
-  [ -z "$stack" ] && log_error "Stack required. See --help."
-
-  export CI=1
-
-  if is_tooling_stack_excluded "$stack"; then
-    log_error "Stack '$stack' is excluded from tooling."
-  fi
-
-  local manifest="$PROJECT_ROOT/tooling/$stack/manifest.toml"
-  [ ! -f "$manifest" ] && log_error "No manifest at $manifest"
-
-  local scaffold
-  scaffold=$(read_manifest_field "$manifest" "stack" "scaffold")
-  [ -z "$scaffold" ] && log_error "Stack '$stack' has no scaffold command in manifest."
-
-  local prepare
-  prepare=$(read_manifest_field "$manifest" "verify" "prepare")
-
-  open_timeline "canon tooling verify $stack"
-  trap close_timeline EXIT
-
-  local tmp_root="$PROJECT_ROOT/.canon/tmp/runs"
-  local tmp_dir="$tmp_root/verify-$stack"
-
-  mkdir -p "$tmp_root"
-  rm -rf "$tmp_dir"
-
-  local project_name="verify-$stack"
-  local scaffold_cmd="${scaffold//\{\{name\}\}/$project_name}"
-
-  RESULTS=()
-  FAILED=0
-
-  log_step "Scaffolding $stack"
-  (cd "$tmp_root" && eval "$scaffold_cmd") >/tmp/verify-scaffold.log 2>&1 || {
-    log_warn "Scaffold failed"
-    tail -20 /tmp/verify-scaffold.log >&2
-    FAILED=1
-  }
-
-  if [ ! -d "$tmp_dir" ]; then
-    log_error "Scaffold did not produce $tmp_dir"
-  fi
-
-  (cd "$tmp_dir" && git init -q && git add . && git commit -m "chore: verify scaffold" -q --no-verify)
-
-  if [ -n "$prepare" ]; then
-    run_phase "Prepare" bash -c "cd '$tmp_dir' && $prepare"
-  fi
-
-  log_info "Sync resolves via bun $PROJECT_ROOT/src/cli.ts, not PATH canon"
-  run_phase "Sync" bash -c "cd '$tmp_dir' && CANON_NON_INTERACTIVE=1 bun '$PROJECT_ROOT/src/cli.ts' tooling sync $stack . --write"
-
-  if [ -f "$tmp_dir/package.json" ]; then
-    run_phase "lint:fix" bash -c "cd '$tmp_dir' && bun run lint:fix"
-    run_phase "check" bash -c "cd '$tmp_dir' && bun run check"
-
-    if grep -q '"test:e2e"' "$tmp_dir/package.json"; then
-      run_phase "test:e2e" bash -c "cd '$tmp_dir' && bun run test:e2e"
-    fi
-
-    if grep -q '"screenshot"' "$tmp_dir/package.json"; then
-      if run_phase "screenshot" bash -c "cd '$tmp_dir' && timeout 60 bun run screenshot"; then
-        local shots
-        shots=$(find "$tmp_dir/screenshots" -type f -name '*.png' 2>/dev/null | wc -l)
-        if [ "$shots" -eq 0 ]; then
-          log_warn "screenshot produced no png files"
-          RESULTS+=("screenshot-artifacts:fail")
-          FAILED=1
-        else
-          RESULTS+=("screenshot-artifacts:pass")
-        fi
-      fi
-    fi
-  fi
-
-  log_step "Results"
-  for r in "${RESULTS[@]}"; do
-    local name="${r%:*}"
-    local status="${r##*:}"
-    if [ "$status" = "pass" ]; then
-      log_info "$name"
-    else
-      log_warn "$name"
-    fi
-  done
-
-  if [ "$keep" -eq 0 ] && [ "$FAILED" -eq 0 ]; then
-    rm -rf "$tmp_dir"
-  else
-    log_info "Kept $tmp_dir"
-  fi
-
-  if [ "$FAILED" -ne 0 ]; then
-    exit 1
-  fi
-}
-
-if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
-  main "$@"
-fi