@erclx/canon 4.112.0 → 4.114.0

package/src/tooling/inject.ts

@@ -10,19 +10,30 @@ import { ancestorsFirst, listFiles, type Manifest } from '@/tooling/manifest'
 import {
   applyScripts,
   collectDeps,
+  collectScripts,
   readPackage,
   serializePackage,
 } from '@/tooling/package'
-import { logAdd, logRemove, logStep } from '@/ui'
+import {
+  hasSpellConfig,
+  isSubfolderTarget,
+  isWithheldInSubfolder,
+  SUBFOLDER_SPELL_CONFIG,
+  subfolderSpellConfig,
+} from '@/tooling/subfolder'
+import { logAdd, logRemove, logStep, logWarn } from '@/ui'
 
 export async function injectConfigs(
   chain: readonly Manifest[],
   target: string,
 ): Promise<string[]> {
   const applied: string[] = []
+  const isSubfolder = isSubfolderTarget(target)
 
   for (const manifest of ancestorsFirst(chain)) {
-    const files = listFiles(manifest.configsDir)
+    const files = listFiles(manifest.configsDir).filter(
+      (rel) => !(isSubfolder && isWithheldInSubfolder(rel)),
+    )
     if (files.length === 0) continue
 
     logStep(`Applying ${manifest.name} configs`)
@@ -100,6 +111,16 @@ export async function injectSeeds(
     }
   }
 
+  const spellConfig = isSubfolderTarget(target)
+    ? subfolderSpellConfig(chain)
+    : undefined
+  if (spellConfig !== undefined && !hasSpellConfig(target)) {
+    logStep('Applying subfolder spell config')
+    await writeFile(join(target, SUBFOLDER_SPELL_CONFIG), spellConfig)
+    logAdd(SUBFOLDER_SPELL_CONFIG)
+    applied.push(SUBFOLDER_SPELL_CONFIG)
+  }
+
   return applied
 }
 
@@ -158,8 +179,9 @@ export async function pruneGitignore(
 
 /**
  * Installs missing dev dependencies, fills package scripts, and merges
- * gitignore entries. This is the `inject_tooling_manifest` sequence, which
- * assumed a target that already has a package.json.
+ * gitignore entries. A target with no package.json gets the gitignore alone,
+ * plus a warning naming every install it skipped, since seeding a package.json
+ * would pick a package manager and a project name on the target's behalf.
  */
 export async function injectManifest(
   chain: readonly Manifest[],
@@ -192,4 +214,21 @@ export async function injectManifest(
   }
 
   await injectGitignore(chain, target)
+
+  if (!pkg) warnSkippedInstalls(chain, target)
+}
+
+function warnSkippedInstalls(chain: readonly Manifest[], target: string): void {
+  const deps = collectDeps(chain, {}).map((dep) => dep.spec)
+  const scripts = collectScripts(chain, {}).map((script) => script.key)
+  if (deps.length === 0 && scripts.length === 0) return
+
+  logStep('Skipped installs')
+  if (deps.length > 0) {
+    logWarn(`Dev dependencies not installed: ${deps.join(', ')}`)
+  }
+  if (scripts.length > 0) {
+    logWarn(`Scripts not added: ${scripts.join(', ')}`)
+  }
+  logWarn(`No package.json: run 'bun init' in ${target}, then sync again`)
 }

package/src/tooling/scan.ts

@@ -10,6 +10,13 @@ import {
   readPackage,
   type ScriptState,
 } from '@/tooling/package'
+import {
+  hasSpellConfig,
+  isSubfolderTarget,
+  isWithheldInSubfolder,
+  SUBFOLDER_SPELL_CONFIG,
+  subfolderSpellConfig,
+} from '@/tooling/subfolder'
 
 export interface ConfigState {
   readonly rel: string
@@ -27,8 +34,15 @@ export interface EntryState {
   readonly state: 'missing' | 'present'
 }
 
+export interface WithheldState {
+  readonly rel: string
+  readonly stack: string
+  readonly present: boolean
+}
+
 export interface ScanResult {
   readonly configs: readonly ConfigState[]
+  readonly withheld: readonly WithheldState[]
   readonly seeds: readonly SeedState[]
   readonly scripts: readonly ScriptState[]
   readonly deps: readonly DepState[]
@@ -48,9 +62,16 @@ function isIdentical(a: string, b: string): boolean {
  * category and mirrors the bash: configs, seeds, and scripts resolve nearest
  * stack first, while dependencies and gitignore entries resolve from the
  * furthest ancestor inward.
+ *
+ * A target below its git toplevel is scanned as a subfolder: a path GitHub
+ * reads only at the root moves to `withheld` and counts as no change, and the
+ * nested spell config joins the seeds. The scope is read here so every caller
+ * of `scan` agrees without passing a flag.
  */
 export function scan(chain: readonly Manifest[], target: string): ScanResult {
+  const isSubfolder = isSubfolderTarget(target)
   const configs: ConfigState[] = []
+  const withheld: WithheldState[] = []
   const seenConfigs = new Set<string>()
 
   for (const manifest of chain) {
@@ -60,6 +81,12 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
 
       const source = join(manifest.configsDir, rel)
       const dest = join(target, rel)
+
+      if (isSubfolder && isWithheldInSubfolder(rel)) {
+        withheld.push({ rel, stack: manifest.name, present: existsSync(dest) })
+        continue
+      }
+
       const state = !existsSync(dest)
         ? 'new'
         : isIdentical(source, dest)
@@ -87,6 +114,13 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
     }
   }
 
+  if (isSubfolder && subfolderSpellConfig(chain) !== undefined) {
+    seeds.push({
+      rel: SUBFOLDER_SPELL_CONFIG,
+      state: hasSpellConfig(target) ? 'present' : 'missing',
+    })
+  }
+
   const packagePath = join(target, 'package.json')
   const pkg = readPackage(packagePath)
   const scripts = pkg ? collectScripts(chain, pkg) : []
@@ -107,6 +141,7 @@ export function scan(chain: readonly Manifest[], target: string): ScanResult {
 
   return {
     configs,
+    withheld,
     seeds,
     scripts,
     deps,

package/src/tooling/subfolder.ts

@@ -0,0 +1,110 @@
+import { existsSync, readdirSync, realpathSync } from 'node:fs'
+import { basename, join, relative } from 'node:path'
+import { gitEnv } from '@/git-env'
+import { listFiles, type Manifest } from '@/tooling/manifest'
+
+/**
+ * The path the generated subfolder spell config is written to. Written
+ * copy-once, since a project that already configured cspell here owns it.
+ */
+export const SUBFOLDER_SPELL_CONFIG = 'cspell.json'
+
+const WITHHELD_PREFIX = '.github/'
+
+const SPELL_CONFIG_NAMES = ['cspell.json', '.cspell.json']
+
+/**
+ * Whether the target sits below the root of the git repository holding it. A
+ * target outside any repository, or one git cannot read, counts as a root, so
+ * a scratch folder with no repository keeps the behavior a root sync has.
+ *
+ * Synchronous because `scan` and `buildToolingReport` are, which is why this
+ * does not reuse the async worktree reader.
+ */
+export function isSubfolderTarget(target: string): boolean {
+  return subfolderPath(target) !== undefined
+}
+
+/**
+ * The target's path relative to its git toplevel, which is what a root CI
+ * job names as its `working-directory`. Undefined wherever
+ * `isSubfolderTarget` reads a root.
+ */
+export function subfolderPath(target: string): string | undefined {
+  const result = Bun.spawnSync(
+    ['git', '-C', target, 'rev-parse', '--show-toplevel'],
+    { env: gitEnv(), stdout: 'pipe', stderr: 'ignore' },
+  )
+  if (result.exitCode !== 0) return undefined
+
+  const toplevel = result.stdout.toString().trim()
+  if (toplevel === '') return undefined
+
+  try {
+    const path = relative(realpathSync(toplevel), realpathSync(target))
+    return path === '' ? undefined : path
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * GitHub reads workflows only at the repository root, so a `.github/` copied
+ * into a subfolder is a file nothing runs. `scan` and `injectConfigs` both
+ * read this, so the set the diff withholds and the set the sync skips cannot
+ * disagree.
+ */
+export function isWithheldInSubfolder(rel: string): boolean {
+  return rel.startsWith(WITHHELD_PREFIX)
+}
+
+/**
+ * Whether the target already carries a cspell config of its own, in any of
+ * the file names cspell searches for.
+ */
+export function hasSpellConfig(target: string): boolean {
+  if (SPELL_CONFIG_NAMES.some((name) => existsSync(join(target, name)))) {
+    return true
+  }
+  if (!existsSync(target)) return false
+  return readdirSync(target).some((name) => name.startsWith('cspell.config.'))
+}
+
+/**
+ * Builds the nested cspell config that registers a subfolder's seeded word
+ * lists. A root `cspell '**'` merges it with the root config for files under
+ * the subfolder. Each dictionary takes a `local-` name, since reusing a root
+ * dictionary's name shadows it inside the subfolder and a root word then fails
+ * there.
+ *
+ * Returns nothing when the chain carries `base`, whose own seed already writes
+ * a config, or when no stack seeds a word list.
+ */
+export function subfolderSpellConfig(
+  chain: readonly Manifest[],
+): string | undefined {
+  if (chain.some((manifest) => manifest.name === 'base')) return undefined
+
+  const lists = new Set<string>()
+  for (const manifest of chain) {
+    for (const rel of listFiles(manifest.seedsDir)) {
+      if (rel.startsWith('.cspell/') && rel.endsWith('.txt')) lists.add(rel)
+    }
+  }
+  if (lists.size === 0) return undefined
+
+  const definitions = [...lists].sort().map((path) => ({
+    name: `local-${basename(path, '.txt')}`,
+    path,
+    addWords: true,
+  }))
+
+  const config = {
+    version: '0.2',
+    dictionaryDefinitions: definitions,
+    dictionaries: definitions.map((definition) => definition.name),
+    ignorePaths: ['.cspell/**'],
+  }
+
+  return `${JSON.stringify(config, null, 2)}\n`
+}

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

@@ -82,7 +82,11 @@ if command -v canon >/dev/null 2>&1; then
     # ran the one-time setup. Nothing to report.
     if [ "$reason" != "no-repository" ]; then
       printf '\n🗄️  Records not backed up: %s\n' "${reason:-unknown}"
-      printf 'Run canon records push when the remote is reachable.\n\n'
+      if [ "$reason" = "unsafe-payload" ]; then
+        printf 'Run canon records push to see the blocked paths.\n\n'
+      else
+        printf 'Run canon records push when the remote is reachable.\n\n'
+      fi
     fi
   fi
 fi

package/tooling/base/seeds/cspell.json

@@ -16,5 +16,5 @@
     }
   ],
   "dictionaries": ["project-terms", "tech-stack"],
-  "ignorePaths": [".cspell/**", ".git/**"]
+  "ignorePaths": [".cspell/**", ".git/**", ".claude/rules/canon/**"]
 }

package/tooling/claude/seeds/.claude/hooks/silent-turn.sh

@@ -49,19 +49,18 @@ paths=$(tail -n +"$line_start" "$transcript_path" | jq -r '
 
 # Two written paths can share a basename, and a bare basename match would then
 # read one mention as covering both. Counting first is what lets a collision
-# fall back to the full path, which the ordinary case never needs.
-declare -A base_count
-while IFS= read -r path; do
+# fall back to the full path, which the ordinary case never needs. The count
+# avoids an associative array, since macOS ships bash 3.2.
+colliding=$(while IFS= read -r path; do
   [ -n "$path" ] || continue
-  base=$(basename "$path")
-  base_count["$base"]=$((${base_count["$base"]:-0} + 1))
-done <<<"$paths"
+  printf '%s\n' "${path##*/}"
+done <<<"$paths" | sort | uniq -d)
 
 unmentioned=()
 while IFS= read -r path; do
   [ -n "$path" ] || continue
-  base=$(basename "$path")
-  if [ "${base_count[$base]}" -gt 1 ]; then
+  base=${path##*/}
+  if [ -n "$colliding" ] && printf '%s\n' "$colliding" | grep -Fxq -- "$base"; then
     needle="$path"
   else
     needle="$base"

package/tooling/nextjs/configs/vitest.config.ts

@@ -5,7 +5,7 @@ import { defineConfig } from 'vitest/config'
 export default defineConfig({
   resolve: {
     alias: {
-      '@': path.resolve(__dirname, 'src'),
+      '@': path.resolve(import.meta.dirname, 'src'),
     },
   },
   test: {

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

@@ -16,6 +16,7 @@ log_error() {
   exit 1
 }
 log_step() { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}"; }
+log_skip() { echo -e "${GREY}│ - $1${NC}"; }
 
 pipe_output() { while IFS= read -r line; do echo -e "${GREY}│${NC}  $line"; done; }
 
@@ -24,6 +25,32 @@ check_dependencies() {
   command -v uv >/dev/null 2>&1 || log_error "uv is not installed"
 }
 
+check_package() {
+  [ -f package.json ] || log_error "No package.json here. Run 'bun init', then sync the stack again"
+}
+
+has_script() {
+  bun -e 'process.exit(require(process.cwd() + "/package.json").scripts?.[process.argv[1]] ? 0 : 1)' "$1"
+}
+
+# A subfolder synced with --skip base declares none of base's scripts, since
+# the repository root owns them. Each base phase runs only where its script is
+# declared, so this script passes on its own in that subfolder.
+run_base_phase() {
+  local title=$1
+  local script=$2
+  local err_msg=$3
+  local pass_msg=$4
+
+  log_step "$title"
+  if ! has_script "$script"; then
+    log_skip "Skipped: $script is not declared here, so the repository root runs it"
+    return
+  fi
+  run_check "bun run $script" "$err_msg"
+  log_info "$pass_msg"
+}
+
 run_check() {
   local cmd=$1
   local err_msg=$2
@@ -37,6 +64,7 @@ run_check() {
 
 main() {
   check_dependencies
+  check_package
 
   if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
 
@@ -48,21 +76,10 @@ main() {
   run_check "bun run lint" "Lint failed"
   log_info "Lint passed"
 
-  log_step "Formatting"
-  run_check "bun run format" "Format failed"
-  log_info "Format applied"
-
-  log_step "Format check"
-  run_check "bun run check:format" "Format check failed"
-  log_info "Format check passed"
-
-  log_step "Spelling"
-  run_check "bun run check:spell" "Spell check failed"
-  log_info "Spell check passed"
-
-  log_step "Shell"
-  run_check "bun run check:shell" "Shell check failed"
-  log_info "Shell check passed"
+  run_base_phase "Formatting" "format" "Format failed" "Format applied"
+  run_base_phase "Format check" "check:format" "Format check failed" "Format check passed"
+  run_base_phase "Spelling" "check:spell" "Spell check failed" "Spell check passed"
+  run_base_phase "Shell" "check:shell" "Shell check failed" "Shell check passed"
 
   log_step "Unit tests"
   run_check "bun run test:run" "Unit tests failed"

package/tooling/python/manifest.toml

@@ -2,7 +2,7 @@
 name = "python"
 extends = "base"
 runtime = "uv"
-scaffold = "uv init --app {{name}}"
+scaffold = "uv init --package {{name}}"
 
 [scripts]
 "lint" = "uv run ruff check . && uv run ruff format --check ."

package/tooling/python/reference.md

@@ -10,14 +10,13 @@ Configs ship as sidecar files (`ruff.toml`, `mypy.ini`, `pytest.ini`, `.coverage
 
 ## Scaffold checklist
 
-1. Scaffold with `uv init --app <name>`. This creates `pyproject.toml`, `.python-version` pinned to 3.14, `src/<name>/`, and a starter `main.py`. `uv init` defaults `requires-python` to `>=3.14`, which matches the `.python-version` pin this stack ships.
+1. Scaffold with `uv init --package <name>`. This creates `pyproject.toml` with a `uv_build` backend, `.python-version` pinned to 3.14, and `src/<name with underscores>/__init__.py` holding an annotated `def main() -> None:`, so source lands under `src/` where `mypy.ini`, `pytest.ini`, and `.coveragerc` look for it. `uv init` defaults `requires-python` to `>=3.14`, which matches the `.python-version` pin this stack ships.
 2. Seed `package.json` so the base layer's bun-side tools (husky, prettier, cspell, commitlint) have a target to install into: `bun init -y`. Without this the sync drops base configs but skips the dep install, since `resolve_missing_deps` short-circuits when `package.json` is absent.
 3. Install base tooling: `canon tooling sync base . --write`
 4. Install python tooling: `canon tooling sync python . --write`
 5. Install Python tooling deps: `uv add --dev ruff mypy pytest pytest-cov`. v1 of this stack does not declare these in `[dependencies.dev]` because manifest injection hardcodes `bun add -D`, which can not install Python packages. Until the injector branches on `runtime`, this step is manual.
 6. Sync the lockfile and create the venv: `uv sync`.
-7. Annotate `main()` in the scaffold-generated `main.py` with `-> None`. `uv init --app` ships an unannotated `main()` that fails strict mypy on the first run.
-8. Run `bun run lint:fix` then `bun run check`.
+7. Run `bun run lint:fix` then `bun run check`.
 
 The python stack also ships `tests/test_smoke.py` as a copy-once seed. `pytest` collects at least one test on first run, so `bun run test:run` exits 0 instead of the empty-collection exit code 5. Delete or replace the smoke test with real tests.
 
@@ -27,7 +26,7 @@ The python stack also ships `tests/test_smoke.py` as a copy-once seed. `pytest`
 - `mypy.ini`: strict mode, `python_version = 3.14`, `mypy_path = src`, excludes `tests/` and `docs/`.
 - `pytest.ini`: tests live under `tests/`, source under `src/`.
 - `.coveragerc`: branch coverage on `src/`, html report under `.coverage_cache/html`.
-- `.python-version`: pinned to `3.14` to match `uv init --app` defaults.
+- `.python-version`: pinned to `3.14` to match `uv init` defaults.
 - `scripts/verify.sh`: overrides base verify to add Typecheck (`mypy`), Lint (`ruff check && ruff format --check`), and Tests (`pytest -v`) phases.
 
 ## Hybrid project shape

package/tooling/vite-react/configs/vite.config.ts

@@ -9,7 +9,7 @@ export default defineConfig({
   plugins: [react(), tailwindcss()],
   resolve: {
     alias: {
-      '@': path.resolve(__dirname, './src'),
+      '@': path.resolve(import.meta.dirname, './src'),
     },
   },
   base: process.env.VITE_BASE_URL ?? '/',

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

@@ -16,6 +16,7 @@ log_error() {
   exit 1
 }
 log_step() { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}"; }
+log_skip() { echo -e "${GREY}│ - $1${NC}"; }
 
 pipe_output() { while IFS= read -r line; do echo -e "${GREY}│${NC}  $line"; done; }
 
@@ -23,6 +24,32 @@ check_dependencies() {
   command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
 }
 
+check_package() {
+  [ -f package.json ] || log_error "No package.json here. Run 'bun init', then sync the stack again"
+}
+
+has_script() {
+  bun -e 'process.exit(require(process.cwd() + "/package.json").scripts?.[process.argv[1]] ? 0 : 1)' "$1"
+}
+
+# A subfolder synced with --skip base declares none of base's scripts, since
+# the repository root owns them. Each base phase runs only where its script is
+# declared, so this script passes on its own in that subfolder.
+run_base_phase() {
+  local title=$1
+  local script=$2
+  local err_msg=$3
+  local pass_msg=$4
+
+  log_step "$title"
+  if ! has_script "$script"; then
+    log_skip "Skipped: $script is not declared here, so the repository root runs it"
+    return
+  fi
+  run_check "bun run $script" "$err_msg"
+  log_info "$pass_msg"
+}
+
 run_check() {
   local cmd=$1
   local err_msg=$2
@@ -36,6 +63,7 @@ run_check() {
 
 main() {
   check_dependencies
+  check_package
 
   if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
 
@@ -47,21 +75,10 @@ main() {
   run_check "bun run lint" "Lint failed"
   log_info "Lint passed"
 
-  log_step "Formatting"
-  run_check "bun run format" "Format failed"
-  log_info "Format applied"
-
-  log_step "Format check"
-  run_check "bun run check:format" "Format check failed"
-  log_info "Format check passed"
-
-  log_step "Spelling"
-  run_check "bun run check:spell" "Spell check failed"
-  log_info "Spell check passed"
-
-  log_step "Shell"
-  run_check "bun run check:shell" "Shell check failed"
-  log_info "Shell check passed"
+  run_base_phase "Formatting" "format" "Format failed" "Format applied"
+  run_base_phase "Format check" "check:format" "Format check failed" "Format check passed"
+  run_base_phase "Spelling" "check:spell" "Spell check failed" "Spell check passed"
+  run_base_phase "Shell" "check:shell" "Shell check failed" "Shell check passed"
 
   log_step "Unit tests"
   run_check "bun run test:run" "Unit tests failed"