@erclx/canon 4.113.0 → 4.114.0

package/src/teach/nav.ts

@@ -18,6 +18,7 @@ import {
   TEACH_MISSION,
   TEACH_REFERENCE,
   TEACH_STYLESHEET,
+  TEACH_STYLESHEET_BASE,
   teachDir,
   type TeachRefused,
   type WorkspaceDetail,
@@ -35,12 +36,23 @@ const BRAND_MARK = 'assets/brand/mark.svg'
  */
 const HAND_WRITTEN_ICON = `<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='10 10 80 80'%3E%3Cpath d='M34,20 L15,28 L15,72 L34,80 Z M66,20 L85,28 L85,72 L66,80 Z' fill='rgb(224,114,75)' /%3E%3Crect x='44' y='15' width='12' height='70' rx='2' fill='rgb(224,114,75)' /%3E%3C/svg%3E" />`
 
-function dropHandWrittenIcon(html: string): string {
-  return html
-    .split('\n')
-    .filter((line) => line.trim() !== HAND_WRITTEN_ICON)
-    .join('\n')
-    .replaceAll(HAND_WRITTEN_ICON, '')
+/**
+ * The stylesheet link lessons used to carry by hand outside every region. The
+ * `style` region now links the base sheet itself, so keeping this one would
+ * load the base twice.
+ */
+const HAND_WRITTEN_STYLESHEET = `<link rel="stylesheet" href="../${TEACH_ASSETS}/${TEACH_STYLESHEET}" />`
+
+const HAND_WRITTEN_HEAD = [HAND_WRITTEN_ICON, HAND_WRITTEN_STYLESHEET]
+
+function dropHandWrittenHead(html: string): string {
+  return HAND_WRITTEN_HEAD.reduce(
+    (text, link) => text.replaceAll(link, ''),
+    html
+      .split('\n')
+      .filter((line) => !HAND_WRITTEN_HEAD.includes(line.trim()))
+      .join('\n'),
+  )
 }
 
 /**
@@ -504,6 +516,11 @@ function titleCase(slug: string): string {
   ].join(' ')
 }
 
+/** The mission's own title, falling back to the slug where it names none. */
+function workspaceLabel(workspace: WorkspaceSummary): string {
+  return workspace.title ?? titleCase(workspace.topic)
+}
+
 interface JumpEntry {
   readonly ordinal: string
   readonly label: string
@@ -629,7 +646,7 @@ function renderSidebar(sidebar: Sidebar): string {
 
   return `<aside class="sb">
   <div class="sb-top">
-    <details class="sb-ws" name="mast"><summary><span class="ws-name">${escapeHtml(sidebar.heading)}</span><span class="car">${CARET}</span></summary><div class="sb-wl"><ul class="jump-list">${renderJumpList(sidebar.switcher)}</ul></div></details>
+    <details class="sb-ws" name="mast"><summary><span class="ws-name" title="${escapeHtml(sidebar.heading)}">${escapeHtml(sidebar.heading)}</span><span class="car">${CARET}</span></summary><div class="sb-wl"><ul class="jump-list">${renderJumpList(sidebar.switcher)}</ul></div></details>
   </div>
   <div class="sb-scroll">
     <div class="sb-meta">${escapeHtml(sidebar.meta)}</div>
@@ -724,7 +741,7 @@ function workspaceJumpEntries(
 ): JumpEntry[] {
   return workspaces.map((workspace) => ({
     ordinal: ordinalOf(workspace),
-    label: titleCase(workspace.topic),
+    label: workspaceLabel(workspace),
     href: hrefForWorkspace(workspace, prefix),
     at: workspace.slug === currentSlug,
     trailing: String(workspace.lessons),
@@ -935,7 +952,7 @@ function renderRootPage(workspaces: readonly WorkspaceSummary[]): string {
     meta: `${workspaces.length} workspace${workspaces.length === 1 ? '' : 's'}`,
     items: workspaces.map((workspace) => ({
       ordinal: ordinalOf(workspace),
-      label: titleCase(workspace.topic),
+      label: workspaceLabel(workspace),
       href: hrefForWorkspace(workspace, '') ?? '#',
       at: false,
     })),
@@ -951,7 +968,7 @@ function renderRootPage(workspaces: readonly WorkspaceSummary[]): string {
           ? 'Live'
           : 'Open'
       const blurb = `${workspace.lessons} lesson(s) &middot; ${workspace.reference} reference page(s) &middot; ${workspace.terms} term(s)`
-      const inner = `<span class="num">${ordinalOf(workspace)}</span><b>${escapeHtml(titleCase(workspace.topic))}</b><span class="state">${state}</span><span class="blurb">${blurb}</span>`
+      const inner = `<span class="num">${ordinalOf(workspace)}</span><b>${escapeHtml(workspaceLabel(workspace))}</b><span class="state">${state}</span><span class="blurb">${blurb}</span>`
 
       return href === undefined
         ? `<li class="soon"><a href="#" aria-disabled="true" tabindex="-1">${inner}</a></li>`
@@ -1014,7 +1031,7 @@ async function renderContentsPage(
       )
     : undefined
 
-  const title = detail.title ?? titleCase(detail.topic)
+  const title = workspaceLabel(detail)
 
   const segments: CrumbSegment[] = [
     {
@@ -1026,7 +1043,7 @@ async function renderContentsPage(
       },
     },
     {
-      label: titleCase(detail.topic),
+      label: workspaceLabel(detail),
       jump: {
         ariaLabel: 'Jump to a lesson',
         entries: lessonJumpEntries(metas, '', undefined),
@@ -1035,7 +1052,7 @@ async function renderContentsPage(
   ]
 
   const sidebar: Sidebar = {
-    heading: titleCase(detail.topic),
+    heading: workspaceLabel(detail),
     switcher: workspaceJumpEntries(workspaces, '../', detail.slug),
     meta: `${metas.length} lesson${metas.length === 1 ? '' : 's'}`,
     items: metas.map((meta, index) => ({
@@ -1139,21 +1156,44 @@ interface LessonRefused {
   readonly missing: Region
 }
 
-/**
- * Splices the four chrome regions into one lesson file, in a fixed order so a
- * missing marker is always reported against the same region a session can
- * check first. Nothing is written when any region is missing, which is what
- * keeps a partially-spliced file off disk.
- */
 /**
  * A lesson embeds the workspace stylesheet, and an `@import` resolves against
  * the lesson's own folder there rather than the assets folder, so it never
- * loaded anything. The base sheet reaches the page through the `<link>`.
+ * loaded anything. The base sheet reaches the page through the `<link>` the
+ * `style` region carries ahead of the embedded rules.
  */
 function stripImports(css: string): string {
   return css.replace(/^@import[^;]*;[ \t]*\n?/gm, '')
 }
 
+const HEADER_CLOSE = '<!-- /canon:teach:header -->'
+const FOOTNAV_OPEN = '<!-- canon:teach:footnav -->'
+
+/**
+ * The authored body between the header and footnav regions, wrapped in
+ * `<main>` when it holds none. The skill has a session write the body bare,
+ * and the column width hangs off `main`. A body already holding one is left
+ * alone, which keeps a second run byte-identical.
+ */
+function wrapMain(html: string): string {
+  const start = html.indexOf(HEADER_CLOSE)
+  const end = html.indexOf(FOOTNAV_OPEN, start)
+  if (start === -1 || end === -1) return html
+
+  const bodyStart = start + HEADER_CLOSE.length
+  const body = html.slice(bodyStart, end)
+  if (/<main[\s>]/.test(body)) return html
+
+  return `${html.slice(0, bodyStart)}\n<main>\n${body.trim()}\n</main>\n${html.slice(end)}`
+}
+
+/**
+ * Splices the four chrome regions into one lesson file, in a fixed order so a
+ * missing marker is always reported against the same region a session can
+ * check first, then wraps the authored body in `<main>` where it holds none.
+ * Nothing is written when any region is missing, which is what keeps a
+ * partially-spliced file off disk.
+ */
 async function rewriteLesson(
   root: string,
   detail: WorkspaceDetail,
@@ -1164,7 +1204,7 @@ async function rewriteLesson(
 ): Promise<LessonRewritten | LessonRefused> {
   const file = metas[index].file
   const path = join(root, detail.path, TEACH_LESSONS, file)
-  let html = dropHandWrittenIcon(await readFile(path, 'utf8'))
+  let html = dropHandWrittenHead(await readFile(path, 'utf8'))
 
   const teachPrefix = '../../'
   const workspacePrefix = '../'
@@ -1180,7 +1220,7 @@ async function rewriteLesson(
         },
       },
       {
-        label: titleCase(detail.topic),
+        label: workspaceLabel(detail),
         href: `${workspacePrefix}index.html`,
         jump: {
           ariaLabel: 'Jump to a lesson',
@@ -1190,7 +1230,7 @@ async function rewriteLesson(
       { label: `Lesson ${index + 1} of ${metas.length}` },
     ],
     {
-      heading: titleCase(detail.topic),
+      heading: workspaceLabel(detail),
       switcher: workspaceJumpEntries(workspaces, teachPrefix, detail.slug),
       meta: `${metas.length} lesson${metas.length === 1 ? '' : 's'}`,
       items: metas.map((meta, i) => ({
@@ -1210,6 +1250,16 @@ async function rewriteLesson(
   // the class the script reveals feedback with.
   const legacy = html.includes(LEGACY_OPTION)
 
+  // Linked ahead of the embedded rules so those still win the cascade.
+  // Embedding it instead repeats a sheet carrying its fonts inline in every
+  // lesson. A workspace seeded before the pair has no base sheet to link.
+  const hasBase = existsSync(
+    join(root, detail.path, TEACH_ASSETS, TEACH_STYLESHEET_BASE),
+  )
+  const baseLink = hasBase
+    ? `<link rel="stylesheet" href="../${TEACH_ASSETS}/${TEACH_STYLESHEET_BASE}">\n`
+    : ''
+
   const regions: ReadonlyArray<readonly [Region, string]> = [
     // The stepper follows the workspace stylesheet so it wins the cascade at
     // equal specificity, which is what reaches a workspace seeded before it.
@@ -1218,7 +1268,7 @@ async function rewriteLesson(
     // lesson would lack.
     [
       'style',
-      `${teachFavicon()}\n<style>\n${legacy ? css : `${css}\n${QUIZ_CSS}`}\n</style>\n${headScript('lesson')}`,
+      `${teachFavicon()}\n${baseLink}<style>\n${legacy ? css : `${css}\n${QUIZ_CSS}`}\n</style>\n${headScript('lesson')}`,
     ],
     ['header', header],
     ['footnav', `${renderFootNav(metas, index)}\n${PANE_CLOSE}`],
@@ -1231,7 +1281,7 @@ async function rewriteLesson(
     html = spliced
   }
 
-  await writeFile(path, html)
+  await writeFile(path, wrapMain(html))
   return { ok: true, file }
 }
 

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/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/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"