@erclx/canon 4.113.0 → 4.115.0

package/src/teach/nav.ts

@@ -1,12 +1,13 @@
 import { existsSync, readFileSync } from 'node:fs'
-import { readFile, writeFile } from 'node:fs/promises'
-import { join, relative } from 'node:path'
+import { readdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { join, posix, relative } from 'node:path'
 import {
   TEACH_SIDEBAR_BREAKPOINT,
   TEACH_STYLESHEET_COMPONENTS,
 } from '@/design/components'
 import { buildDesignCss } from '@/design/css'
 import { FAVICON_COLORS, faviconLink, renderFavicon } from '@/design/favicon'
+import { stripFrontmatter } from '@/frontmatter'
 import { parseFrontmatter, readField } from '@/indexes/frontmatter'
 import { PROJECT_ROOT } from '@/project-root'
 import { TEACH_FONT_FACES } from '@/teach/fonts'
@@ -14,10 +15,12 @@ import {
   listWorkspaces,
   readWorkspace,
   TEACH_ASSETS,
+  TEACH_GLOSSARY,
   TEACH_LESSONS,
   TEACH_MISSION,
   TEACH_REFERENCE,
   TEACH_STYLESHEET,
+  TEACH_STYLESHEET_BASE,
   teachDir,
   type TeachRefused,
   type WorkspaceDetail,
@@ -35,12 +38,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 +518,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 +648,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>
@@ -678,6 +697,8 @@ function pageHead(
   title: string,
   cssHref: string | undefined,
   embeddedCss: string | undefined,
+  page: 'index' | 'lesson' = 'index',
+  extraHead = '',
 ): string {
   const style =
     embeddedCss === undefined
@@ -689,10 +710,10 @@ function pageHead(
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${escapeHtml(title)}</title>
+${extraHead}<title>${escapeHtml(title)}</title>
 ${teachFavicon()}
 ${style}
-${headScript('index')}
+${headScript(page)}
 </head>
 `
 }
@@ -724,7 +745,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 +956,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 +972,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>`
@@ -998,13 +1019,15 @@ async function readLessonMetas(
  * on disk: the mission, the lessons already written, the reference pages, and
  * the glossary. A workspace with no `index.html` yet gets one the same way a
  * workspace that already had one gets its rewrite, since both read the same
- * sources.
+ * sources. A reference row links the rendered sibling, or the markdown itself
+ * on a Bun that cannot render one, so no row points at a file never written.
  */
 async function renderContentsPage(
   root: string,
   workspaces: readonly WorkspaceSummary[],
   detail: WorkspaceDetail,
   metas: readonly LessonMeta[],
+  canRenderMarkdown: boolean,
 ): Promise<string> {
   const missionPath = join(root, detail.path, TEACH_MISSION)
   const description = existsSync(missionPath)
@@ -1014,7 +1037,7 @@ async function renderContentsPage(
       )
     : undefined
 
-  const title = detail.title ?? titleCase(detail.topic)
+  const title = workspaceLabel(detail)
 
   const segments: CrumbSegment[] = [
     {
@@ -1026,7 +1049,7 @@ async function renderContentsPage(
       },
     },
     {
-      label: titleCase(detail.topic),
+      label: workspaceLabel(detail),
       jump: {
         ariaLabel: 'Jump to a lesson',
         entries: lessonJumpEntries(metas, '', undefined),
@@ -1035,7 +1058,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) => ({
@@ -1059,9 +1082,10 @@ async function renderContentsPage(
       detail.referenceFiles.map(async (file, index) => {
         const title = await readTitle(
           join(root, detail.path, TEACH_REFERENCE, file),
-          basenameTitle(file),
+          referenceFallbackTitle(file),
         )
-        return `<li><a href="${TEACH_REFERENCE}/${file}"><span class="num">R${index + 1}</span><b>${escapeHtml(title)}</b></a></li>`
+        const target = canRenderMarkdown ? renderedReferenceName(file) : file
+        return `<li><a href="${TEACH_REFERENCE}/${target}"><span class="num">R${index + 1}</span><b>${escapeHtml(title)}</b></a></li>`
       }),
     )
   ).join('')
@@ -1100,6 +1124,157 @@ ${renderScripts(false, true)}
 `
 }
 
+/**
+ * Marks a reference page as nav's own output, which is the one test nav applies
+ * before deleting a page whose markdown source is gone. A hand-written HTML
+ * file beside the reference pages carries none and is never touched.
+ */
+const REFERENCE_GENERATOR = '<meta name="generator" content="canon teach nav">'
+
+/** A formatter closes the tag as `/>`, which still marks the page as generated. */
+const REFERENCE_GENERATOR_PATTERN =
+  /<meta name="generator" content="canon teach nav"\s*\/?>/
+
+function renderedReferenceName(file: string): string {
+  return file.replace(/\.md$/, '.html')
+}
+
+function referenceFallbackTitle(file: string): string {
+  return titleCase(file.replace(/\.md$/, ''))
+}
+
+/**
+ * A relative href landing on another reference page's markdown is retargeted
+ * to its rendered sibling, and one landing on the workspace glossary goes to
+ * the glossary the contents page renders under `#gloss`, dropping any fragment
+ * since the entries there carry no per-term anchor. The resources page has no
+ * rendered form, so a blanket suffix swap would break a link to it.
+ */
+function retargetReferenceLinks(
+  html: string,
+  referenceFiles: ReadonlySet<string>,
+): string {
+  return html.replace(
+    /href="([^"#?:]+)\.md([#?][^"]*)?"/g,
+    (match, stem: string, suffix: string | undefined) => {
+      const target = posix.normalize(posix.join(TEACH_REFERENCE, `${stem}.md`))
+      if (target === TEACH_GLOSSARY) return 'href="../index.html#gloss"'
+
+      const [folder, file, ...rest] = target.split('/')
+      if (folder !== TEACH_REFERENCE || rest.length > 0) return match
+      if (!referenceFiles.has(file)) return match
+      return `href="${stem}.html${suffix ?? ''}"`
+    },
+  )
+}
+
+/**
+ * One reference page as a styled page carrying the workspace chrome. The
+ * markdown beside it stays the durable, promotable half, and this file is
+ * regenerated from it on every run. Raw HTML in the markdown is escaped rather
+ * than passed through, since a reference page is plain markdown by contract.
+ */
+async function renderReferencePage(
+  root: string,
+  workspaces: readonly WorkspaceSummary[],
+  detail: WorkspaceDetail,
+  metas: readonly LessonMeta[],
+  file: string,
+): Promise<string> {
+  const source = await readFile(
+    join(root, detail.path, TEACH_REFERENCE, file),
+    'utf8',
+  )
+  const title =
+    readField(parseFrontmatter(source), 'title') ?? referenceFallbackTitle(file)
+
+  const rendered = retargetReferenceLinks(
+    Bun.markdown.html(stripFrontmatter(source), {
+      noHtmlBlocks: true,
+      noHtmlSpans: true,
+    }),
+    new Set(detail.referenceFiles),
+  )
+  const body = /<h1[\s>]/.test(rendered)
+    ? rendered
+    : `<h1>${escapeHtml(title)}</h1>\n${rendered}`
+
+  const teachPrefix = '../../'
+  const workspacePrefix = '../'
+
+  const header = renderHeader(
+    [
+      {
+        label: 'Workspaces',
+        href: `${teachPrefix}index.html`,
+        jump: {
+          ariaLabel: 'Switch workspace',
+          entries: workspaceJumpEntries(workspaces, teachPrefix, detail.slug),
+        },
+      },
+      {
+        label: workspaceLabel(detail),
+        href: `${workspacePrefix}index.html`,
+        jump: {
+          ariaLabel: 'Jump to a lesson',
+          entries: lessonJumpEntries(metas, workspacePrefix, undefined),
+        },
+      },
+      { label: title },
+    ],
+    {
+      heading: workspaceLabel(detail),
+      switcher: workspaceJumpEntries(workspaces, teachPrefix, detail.slug),
+      meta: `${metas.length} lesson${metas.length === 1 ? '' : 's'}`,
+      items: metas.map((meta, index) => ({
+        ordinal: String(index + 1).padStart(2, '0'),
+        label: meta.title,
+        href: `${workspacePrefix}${TEACH_LESSONS}/${meta.file}`,
+        at: false,
+      })),
+      foot: workspaceFoot(detail),
+    },
+  )
+
+  // The sidebar opens as on a lesson, since this page lists no lessons itself.
+  return `${pageHead(title, `${workspacePrefix}${TEACH_ASSETS}/${TEACH_STYLESHEET}`, undefined, 'lesson', `${REFERENCE_GENERATOR}\n`)}<body>
+${header}
+<main class="ref">
+${body.trim()}
+</main>
+${PANE_CLOSE}
+${renderScripts(false, false)}
+</body>
+</html>
+`
+}
+
+/**
+ * Deletes a generated reference page whose markdown source is gone, so a
+ * renamed or removed page leaves nothing no contents row reaches.
+ */
+async function removeOrphanReferencePages(
+  root: string,
+  detail: WorkspaceDetail,
+): Promise<void> {
+  const dir = join(root, detail.path, TEACH_REFERENCE)
+  if (!existsSync(dir)) return
+
+  const sources = new Set(detail.referenceFiles.map(renderedReferenceName))
+  const orphans = (await readdir(dir)).filter(
+    (file) => file.endsWith('.html') && !sources.has(file),
+  )
+
+  await Promise.all(
+    orphans.map(async (file) => {
+      const path = join(dir, file)
+      if (REFERENCE_GENERATOR_PATTERN.test(await readFile(path, 'utf8'))) {
+        await rm(path)
+      }
+    }),
+  )
+}
+
 const REGIONS = ['style', 'header', 'footnav', 'scripts'] as const
 type Region = (typeof REGIONS)[number]
 
@@ -1139,21 +1314,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 +1362,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 +1378,7 @@ async function rewriteLesson(
         },
       },
       {
-        label: titleCase(detail.topic),
+        label: workspaceLabel(detail),
         href: `${workspacePrefix}index.html`,
         jump: {
           ariaLabel: 'Jump to a lesson',
@@ -1190,7 +1388,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 +1408,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 +1426,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 +1439,7 @@ async function rewriteLesson(
     html = spliced
   }
 
-  await writeFile(path, html)
+  await writeFile(path, wrapMain(html))
   return { ok: true, file }
 }
 
@@ -1246,10 +1454,22 @@ export interface NavGenerated {
   readonly root: string
   readonly contents: readonly string[]
   readonly lessons: number
-  /** A lesson file missing a chrome marker, refused rather than rewritten. */
+  /** Reference pages rendered to their `.html` sibling. */
+  readonly reference: number
+  /**
+   * A lesson file missing a chrome marker, refused rather than rewritten, or a
+   * reference page left unrendered on a Bun carrying no markdown renderer.
+   */
   readonly skipped: readonly LessonSkipped[]
 }
 
+const MARKDOWN_RENDERER = 'Bun.markdown'
+
+/** An older Bun carries no `Bun.markdown`, and calling it there throws. */
+function hasMarkdownRenderer(): boolean {
+  return typeof Bun.markdown?.html === 'function'
+}
+
 export type NavOutcome = NavGenerated | TeachRefused
 
 /**
@@ -1293,6 +1513,8 @@ export async function generateNav(
   const contents: string[] = []
   const skipped: LessonSkipped[] = []
   let lessons = 0
+  let reference = 0
+  const canRenderMarkdown = hasMarkdownRenderer()
 
   for (const slug of targetSlugs) {
     const found = await readWorkspace(root, slug)
@@ -1307,10 +1529,31 @@ export async function generateNav(
     const contentsPath = join(root, detail.path, 'index.html')
     await writeFile(
       contentsPath,
-      await renderContentsPage(root, listed.workspaces, detail, metas),
+      await renderContentsPage(
+        root,
+        listed.workspaces,
+        detail,
+        metas,
+        canRenderMarkdown,
+      ),
     )
     contents.push(relative(root, contentsPath))
 
+    for (const file of detail.referenceFiles) {
+      const source = join(detail.path, TEACH_REFERENCE, file)
+      if (!canRenderMarkdown) {
+        skipped.push({ file: source, missing: MARKDOWN_RENDERER })
+        continue
+      }
+
+      await writeFile(
+        join(root, detail.path, TEACH_REFERENCE, renderedReferenceName(file)),
+        await renderReferencePage(root, listed.workspaces, detail, metas, file),
+      )
+      reference += 1
+    }
+    await removeOrphanReferencePages(root, detail)
+
     const css = stripImports(await readFile(cssPath, 'utf8'))
 
     for (let index = 0; index < metas.length; index += 1) {
@@ -1339,6 +1582,7 @@ export async function generateNav(
     root: relative(root, rootPath),
     contents,
     lessons,
+    reference,
     skipped,
   }
 }

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,