@meith/web 0.17.1 → 0.18.0

package/bin/forum-web.mjs

@@ -28,7 +28,32 @@
  * (`<root>/.meith/app`) on purpose: `next.config.mjs` (copied verbatim, see
  * below) computes its own workspace root as two directories up from itself,
  * so materializing at that exact depth keeps that computation correct
- * without touching the file.
+ * without touching the file. This bin now also passes that root explicitly,
+ * as `FORUM_WORKSPACE_ROOT`, so the depth is what keeps the *copied file's*
+ * own default honest rather than what the build depends on.
+ *
+ * `--at-root` materializes into the workspace root itself instead
+ * (`<root>`, depth zero), which is the one thing Vercel's Next.js preset
+ * needs and `.meith/app` cannot give it: the build artefact at
+ * `<root>/.next`, where that builder looks and where, for a Next.js project,
+ * it cannot be told to look elsewhere. Nothing about the seam changes — the
+ * generated tsconfig's `paths` name `./community.config.ts` instead of
+ * `../../community.config.ts`, and every other path in here is computed from
+ * `appDir` rather than assumed. Because that mode writes framework-owned
+ * names (`app/`, `src/`, `next.config.mjs`, ...) into a directory the board
+ * also keeps its own files in, ownership there is decided per *file* — the
+ * files it wrote last time, recorded in `.meith/materialized.json`, plus any
+ * whose contents are already byte for byte what it would write. Everything
+ * else is the board's: never removed, never overwritten, and a collision
+ * stops the build naming every file involved. A board can therefore keep
+ * `public/ads.txt` beside the shipped `public/sw.js`.
+ *
+ * `GENERATED_ENTRIES` are the exception, and have to be: `tsconfig.json` and
+ * `next-env.d.ts` are written from scratch rather than copied, so there is no
+ * shipped file to compare a board's own against and nothing to tell one apart
+ * from a stale one this bin wrote. Both are replaced without asking, so a
+ * board cannot keep its own compiler options at the root of an `--at-root`
+ * workspace. See docs/development.md, "Consuming the board from a workspace".
  *
  * This assumes a *hoisted* `node_modules` (npm, yarn classic, or pnpm with
  * `node-linker=hoisted`) — see docs/development.md for why.
@@ -39,21 +64,29 @@
  * (non-hoisted) pnpm install, nested two directories deeper again. Two
  * environment variables, set only by that workspace's own `build`/`dev`
  * scripts, cover the difference without changing anything for a real
- * external board, which never sets either: `FORUM_WORKSPACE_ROOT`
+ * external board, which sets neither itself: `FORUM_WORKSPACE_ROOT`
  * (apps/community/next.config.mjs) points tracing at this repository's real
  * root, and `FORUM_ALIASES_FROM` (`monorepoAliases()` below) carries this
  * repository's own `@meith/*` tsconfig aliases into the generated tsconfig,
  * since packages here resolve each other through those aliases rather than
  * through real `dependencies` entries a hoisted `node_modules` would need.
+ * `FORUM_WORKSPACE_ROOT` is always exported onward from here, defaulting to
+ * the invoking workspace's own root when that workspace did not set it, so
+ * that everything downstream — the copied `next.config.mjs`, and the
+ * `@source` rebase below — reads one answer rather than each re-deriving it
+ * from where it happens to sit.
  */
 import { spawn } from 'node:child_process'
 import {
   cpSync,
   existsSync,
   mkdirSync,
+  readdirSync,
   readFileSync,
   realpathSync,
+  rmdirSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from 'node:fs'
 import { createRequire } from 'node:module'
@@ -63,26 +96,25 @@ import { fileURLToPath } from 'node:url'
 const here = dirname(fileURLToPath(import.meta.url))
 const packageRoot = join(here, '..')
 const workspaceRoot = process.cwd()
-const appDir = join(workspaceRoot, '.meith', 'app')
-
-// `next dev|build` runs with `.meith/app` as its own cwd (see `run()` below),
-// so a relative FORUM_WORKSPACE_ROOT / FORUM_ALIASES_FROM — the shape
-// boards/stock/package.json's scripts write, relative to *this* process's
-// own cwd (the board's own directory) — would resolve against the wrong
-// directory if left for next.config.mjs to resolve itself. Rewriting them to
-// absolute paths here, before spawning, means both env vars mean the same
-// thing regardless of which process reads them.
+const AT_ROOT_FLAG = '--at-root'
+const atRoot = process.argv.includes(AT_ROOT_FLAG)
+const appDir = atRoot ? workspaceRoot : join(workspaceRoot, '.meith', 'app')
+
 for (const name of ['FORUM_WORKSPACE_ROOT', 'FORUM_ALIASES_FROM']) {
   if (process.env[name]) process.env[name] = resolve(workspaceRoot, process.env[name])
 }
+if (!process.env.FORUM_WORKSPACE_ROOT) process.env.FORUM_WORKSPACE_ROOT = workspaceRoot
 
-// Files this package ships (see its `files` allowlist) that belong inside
-// the materialized app. Board files (community.config.ts, board.plugins.json,
-// community.plugins.ts) are never copied — they are read in place, from the
-// workspace, through the generated tsconfig instead.
+/**
+ * Files this package ships (see its `files` allowlist) that belong inside the
+ * materialized app. Board files (community.config.ts, board.plugins.json,
+ * community.plugins.ts) are never copied — they are read in place, from the
+ * workspace, through the generated tsconfig instead.
+ */
 const APP_ENTRIES = [
   'app',
   'src',
+  'public',
   'next.config.mjs',
   'postcss.config.mjs',
   'components.json',
@@ -95,6 +127,180 @@ function fail(message) {
   process.exit(1)
 }
 
+const GENERATED_ENTRIES = ['tsconfig.json', 'next-env.d.ts']
+const SHARED_ENTRIES = ['public']
+const GLOBALS_CSS = 'src/styles/globals.css'
+const MATERIALIZED_RECORD = join(workspaceRoot, '.meith', 'materialized.json')
+
+function walkFiles(dir, prefix, into) {
+  for (const item of readdirSync(dir, { withFileTypes: true })) {
+    const rel = prefix === '' ? item.name : `${prefix}/${item.name}`
+    if (item.isDirectory()) walkFiles(join(dir, item.name), rel, into)
+    else into.push(rel)
+  }
+  return into
+}
+
+/**
+ * Every file `--at-root` is about to write into the workspace root, as posix
+ * relative paths: the shipped entries expanded file by file, plus the two
+ * this bin generates. Ownership is decided per file rather than per
+ * top-level name so that a board can keep its own files inside a directory
+ * the framework also writes into — `public/ads.txt` beside the shipped
+ * `public/sw.js`. See docs/development.md, "Consuming the board from a
+ * workspace".
+ */
+function intendedRootFiles() {
+  const files = []
+  for (const entry of APP_ENTRIES) {
+    const source = join(packageRoot, entry)
+    if (!existsSync(source)) continue
+    if (statSync(source).isDirectory()) walkFiles(source, entry, files)
+    else files.push(entry)
+  }
+  return [...files, ...GENERATED_ENTRIES]
+}
+
+function readMaterializedRecord() {
+  if (!existsSync(MATERIALIZED_RECORD)) return []
+  try {
+    return JSON.parse(readFileSync(MATERIALIZED_RECORD, 'utf8')).files ?? []
+  } catch {
+    return []
+  }
+}
+
+function absoluteRootPath(rel) {
+  return join(workspaceRoot, ...rel.split('/'))
+}
+
+/**
+ * What this bin would leave at `rel`, which is the shipped file's own bytes
+ * for everything except `globals.css` — that one is rewritten in place after
+ * the copy (`rewriteGlobalsCssSourcePaths`), so comparing a materialized
+ * tree against the package source would report the one file this bin always
+ * edits as though the board had edited it.
+ */
+function materializedContent(rel) {
+  const source = readFileSync(join(packageRoot, ...rel.split('/')))
+  if (rel !== GLOBALS_CSS) return source
+  return Buffer.from(
+    rebaseGlobalsCssSources(
+      source.toString('utf8'),
+      dirname(absoluteRootPath(rel)),
+      process.env.FORUM_WORKSPACE_ROOT,
+    ),
+  )
+}
+
+function alreadyMaterialized(rel) {
+  try {
+    return readFileSync(absoluteRootPath(rel)).equals(materializedContent(rel))
+  } catch {
+    return false
+  }
+}
+
+function pruneEmptyDirectories(rel) {
+  let current = dirname(absoluteRootPath(rel))
+  while (current !== workspaceRoot && current.startsWith(workspaceRoot)) {
+    try {
+      rmdirSync(current)
+    } catch {
+      return
+    }
+    current = dirname(current)
+  }
+}
+
+/**
+ * `--at-root` only; every other mode owns `.meith/app` outright and replaces
+ * it wholesale. A file this bin is about to write is its own to replace when
+ * the record says it wrote that file before, or when what is on disk is byte
+ * for byte what it would write anyway — the second case being a checkout
+ * that committed a materialized file, where no record exists and refusing
+ * would fail the deploy over a file identical to the one being written.
+ * Anything else is the board's, and the board's is never overwritten —
+ * except `GENERATED_ENTRIES`, which are written rather than copied and so
+ * can satisfy neither test; those are replaced unconditionally.
+ */
+function claimRootFiles(intended) {
+  const owned = new Set(readMaterializedRecord())
+
+  const collisions = intended.filter((rel) => {
+    if (!existsSync(absoluteRootPath(rel))) return false
+    if (owned.has(rel)) return false
+    if (GENERATED_ENTRIES.includes(rel)) return false
+    return !alreadyMaterialized(rel)
+  })
+
+  if (collisions.length > 0) {
+    fail(
+      `refusing to overwrite ${collisions.length} file(s) in ${workspaceRoot} that ` +
+        `"${AT_ROOT_FLAG}" did not write:\n` +
+        collisions.map((rel) => `  ${rel}`).join('\n') +
+        `\nThis mode materializes @meith/web's own app into this directory, and each of ` +
+        "these is either the board's own file under a name the framework ships, or a " +
+        'materialized file that has been edited since. Move it aside, or drop the flag ' +
+        'to materialize into .meith/app instead.',
+    )
+  }
+}
+
+/**
+ * Files the previous run wrote and this one will not: the framework stopped
+ * shipping them. They were this bin's own, so they go — nothing the board
+ * added is in the record, which is why removal is driven from it rather than
+ * from the directory.
+ */
+function removeStaleRootFiles(intended) {
+  const keeping = new Set(intended)
+  for (const rel of readMaterializedRecord()) {
+    if (keeping.has(rel)) continue
+    rmSync(absoluteRootPath(rel), { recursive: true, force: true })
+    pruneEmptyDirectories(rel)
+  }
+}
+
+function recordRootFiles(intended) {
+  mkdirSync(dirname(MATERIALIZED_RECORD), { recursive: true })
+  writeFileSync(MATERIALIZED_RECORD, `${JSON.stringify({ files: intended }, null, 2)}\n`)
+}
+
+/**
+ * Files the board itself put under a directory the framework owns outright.
+ * Nothing here removes them — ownership is per file, so they simply survive —
+ * but a scaffolded board gitignores those directories as a unit, so a route
+ * added under `app/` works locally, is never committed, and is absent from a
+ * deploy built out of the checkout. Warned about rather than refused: the
+ * file is the author's to keep, and this is the only moment anything looks at
+ * it. `public/` is excluded because that one is shared on purpose.
+ */
+function warnAboutStrayBoardFiles(intended) {
+  const written = new Set(intended)
+  const owned = APP_ENTRIES.filter((entry) => !SHARED_ENTRIES.includes(entry))
+  const strays = []
+
+  for (const entry of owned) {
+    const dir = join(workspaceRoot, entry)
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) continue
+    for (const rel of walkFiles(dir, entry, [])) {
+      if (!written.has(rel)) strays.push(rel)
+    }
+  }
+
+  if (strays.length === 0) return
+
+  console.warn(
+    `forum-web: ${strays.length} file(s) here are not @meith/web's, under a directory that is:\n` +
+      `${strays.map((rel) => `  ${rel}`).join('\n')}\n` +
+      'They are left exactly as they are. A scaffolded board gitignores these directories as ' +
+      'a unit, though, so nothing above is committed, and a deploy that builds from the ' +
+      'checkout will not see it. A board extends the forum through plugins and themes ' +
+      '(docs/plugin-api.md, docs/theme-api.md), not by adding files here.',
+  )
+}
+
 function toPosixRelative(from, to) {
   const rel = relative(from, to).split(sep).join('/')
   return rel.startsWith('.') ? rel : `./${rel}`
@@ -108,14 +314,14 @@ export function rebaseGlobalsCssSources(css, cssDir, workspaceRootOverride) {
 }
 
 function rewriteGlobalsCssSourcePaths() {
-  const workspaceRootOverride = process.env.FORUM_WORKSPACE_ROOT
-  if (!workspaceRootOverride) return
-
-  const cssPath = join(appDir, 'src', 'styles', 'globals.css')
+  const cssPath = join(appDir, ...GLOBALS_CSS.split('/'))
   if (!existsSync(cssPath)) return
 
   const css = readFileSync(cssPath, 'utf8')
-  writeFileSync(cssPath, rebaseGlobalsCssSources(css, dirname(cssPath), workspaceRootOverride))
+  writeFileSync(
+    cssPath,
+    rebaseGlobalsCssSources(css, dirname(cssPath), process.env.FORUM_WORKSPACE_ROOT),
+  )
 }
 
 /**
@@ -136,7 +342,10 @@ function rewriteGlobalsCssSourcePaths() {
  * materialized app's own generated tsconfig, rebased to be relative to
  * `.meith/app` — the same aliases apps/community's own tsconfig.json
  * hand-maintains for exactly this reason. Unset (the default, and the only
- * path a real external board ever takes), this is a no-op.
+ * path a real external board ever takes), this is a no-op. `@board/config`
+ * and `@board/plugins` are excluded from the copy — they are this
+ * workspace's own seam, wired below to *this* board's files, never to
+ * whatever apps/community's own tsconfig happens to alias them to.
  */
 function monorepoAliases() {
   const configFile = process.env.FORUM_ALIASES_FROM
@@ -148,15 +357,20 @@ function monorepoAliases() {
 
   const aliases = {}
   for (const [alias, targets] of Object.entries(paths)) {
-    // `@board/config`/`@board/plugins` are this workspace's own seam, wired
-    // below to *this* board's files — never to whatever apps/community's own
-    // tsconfig happens to alias them to.
     if (alias === '@board/config' || alias === '@board/plugins') continue
     aliases[alias] = targets.map((target) => toPosixRelative(appDir, join(sourceDir, target)))
   }
   return aliases
 }
 
+/**
+ * Replaces each shipped entry (`APP_ENTRIES`) but never `rm -rf`s the whole
+ * `.meith/app` directory: `.next` lives there too once a build has run, and
+ * `forum-web start` needs that build still on disk after this same function
+ * re-materializes the sources ahead of launching the standalone server. The
+ * `next-env.d.ts` it writes only needs to exist, not be complete — next
+ * regenerates it with the right content on first run.
+ */
 function materialize() {
   const boardConfig = join(workspaceRoot, 'community.config.ts')
   const boardPlugins = join(workspaceRoot, 'community.plugins.ts')
@@ -168,16 +382,18 @@ function materialize() {
     )
   }
 
-  // Replace each shipped entry, but never `rm -rf` the whole directory:
-  // `.next` lives here too once a build has run, and `forum-web start` needs
-  // that build still on disk after this same function re-materializes the
-  // sources ahead of launching the standalone server.
+  const rootFiles = atRoot ? intendedRootFiles() : null
+  if (rootFiles) {
+    claimRootFiles(rootFiles)
+    removeStaleRootFiles(rootFiles)
+  }
+
   mkdirSync(appDir, { recursive: true })
 
   for (const entry of APP_ENTRIES) {
     const source = join(packageRoot, entry)
     const target = join(appDir, entry)
-    rmSync(target, { recursive: true, force: true })
+    if (!atRoot) rmSync(target, { recursive: true, force: true })
     if (!existsSync(source)) continue
     cpSync(source, target, { recursive: true })
   }
@@ -213,20 +429,25 @@ function materialize() {
 
   writeFileSync(join(appDir, 'tsconfig.json'), `${JSON.stringify(tsconfig, null, 2)}\n`)
 
-  // next dev/build reads its own next-env.d.ts if present; an empty one is
-  // enough, and next regenerates it with the right content on first run.
   writeFileSync(
     join(appDir, 'next-env.d.ts'),
     '/// <reference types="next" />\n/// <reference types="next/image-types/global" />\n',
   )
+
+  if (rootFiles) {
+    recordRootFiles(rootFiles)
+    warnAboutStrayBoardFiles(rootFiles)
+  }
 }
 
+/**
+ * Resolved from this package's own directory rather than the workspace root:
+ * `next` is `@meith/web`'s dependency, not necessarily the workspace
+ * manifest's, and resolving from here finds it either way — hoisted to the
+ * workspace root (npm, yarn classic) or nested under this package's own
+ * `node_modules` (pnpm's default, non-hoisted layout).
+ */
 function resolveNextBin() {
-  // Resolved from this package's own directory rather than the workspace
-  // root: `next` is @meith/web's dependency, not necessarily the workspace
-  // manifest's, and resolving from here finds it either way — hoisted to
-  // the workspace root (npm, yarn classic) or nested under this package's
-  // own node_modules (pnpm's default, non-hoisted layout).
   const require = createRequire(join(packageRoot, 'package.json'))
   try {
     return require.resolve('next/dist/bin/next')
@@ -235,37 +456,60 @@ function resolveNextBin() {
   }
 }
 
-function run(executable, args, cwd) {
+function standaloneAppDir() {
+  return join(appDir, '.next', 'standalone', relative(workspaceRoot, appDir))
+}
+
+function stageStandaloneAssets() {
+  const targetAppDir = standaloneAppDir()
+
+  const staticTarget = join(targetAppDir, '.next', 'static')
+  rmSync(staticTarget, { recursive: true, force: true })
+  cpSync(join(appDir, '.next', 'static'), staticTarget, { recursive: true })
+
+  const publicSource = join(appDir, 'public')
+  const publicTarget = join(targetAppDir, 'public')
+  rmSync(publicTarget, { recursive: true, force: true })
+  if (existsSync(publicSource)) {
+    cpSync(publicSource, publicTarget, { recursive: true })
+  }
+}
+
+function run(executable, args, cwd, onSuccess) {
   const child = spawn(executable, args, { cwd, stdio: 'inherit' })
-  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+  child.on('exit', (code, signal) => {
+    const exitCode = code ?? (signal ? 1 : 0)
+    if (exitCode === 0 && onSuccess) onSuccess()
+    process.exit(exitCode)
+  })
   child.on('error', (error) => fail(error.message))
 }
 
 if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
-  const [, , command, ...rest] = process.argv
+  const [command, ...rest] = process.argv.slice(2).filter((argument) => argument !== AT_ROOT_FLAG)
 
   if (!['dev', 'build', 'start'].includes(command ?? '')) {
-    console.error('Usage: forum-web <dev|build|start> [next arguments]')
+    console.error(`Usage: forum-web <dev|build|start> [${AT_ROOT_FLAG}] [next arguments]`)
     process.exit(1)
   }
 
   materialize()
 
   if (command === 'start') {
-    // `next.config.mjs` sets `output: 'standalone'`, and a standalone build is
-    // run from its own traced server.js, not `next start` (see docker/Dockerfile
-    // and docker/entrypoint.sh, which run the image's board the same way). The
-    // tracing root is the workspace root (see the module comment on why
-    // `.meith/app` sits exactly two levels below it), so the standalone bundle
-    // preserves that same relative path down to the app directory.
+    const targetAppDir = standaloneAppDir()
     const standaloneRoot = join(appDir, '.next', 'standalone')
-    const serverScript = join(standaloneRoot, relative(workspaceRoot, appDir), 'server.js')
+    const serverScript = join(targetAppDir, 'server.js')
     if (!existsSync(serverScript)) {
       fail(`no standalone build at ${serverScript} — run "forum-web build" first.`)
     }
     run(process.execPath, [serverScript, ...rest], standaloneRoot)
   } else {
     const nextBin = resolveNextBin()
-    run(process.execPath, [nextBin, command, ...rest], appDir)
+    run(
+      process.execPath,
+      [nextBin, command, ...rest],
+      appDir,
+      command === 'build' ? stageStandaloneAssets : undefined,
+    )
   }
 }

package/bin/forum-web.test.ts

@@ -1,4 +1,10 @@
-import { describe, expect, it } from 'vitest'
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { afterAll, describe, expect, it } from 'vitest'
 
 // @ts-expect-error forum-web.mjs ships untyped, imported directly for its pure export
 import { rebaseGlobalsCssSources } from './forum-web.mjs'
@@ -28,6 +34,35 @@ describe('rebaseGlobalsCssSources', () => {
     expect(rewritten).toContain('.foo { color: red; }')
   })
 
+  /**
+   * Against the real shipped file, not a fixture: this rebase now runs on
+   * every materialization including the default one, where it must be a
+   * no-op. Every `@source` in that file is written relative to the workspace
+   * root, and this only stays a no-op while that holds — a `@source` meaning
+   * anything else (`../fonts`, for `src/fonts`) would be silently retargeted
+   * at the workspace root, and fails here instead.
+   */
+  const shippedGlobalsCss = readFileSync(
+    new URL('../src/styles/globals.css', import.meta.url),
+    'utf8',
+  )
+
+  it('leaves the shipped globals.css byte for byte alone at the default depth', () => {
+    expect(
+      rebaseGlobalsCssSources(shippedGlobalsCss, '/board/.meith/app/src/styles', '/board'),
+    ).toBe(shippedGlobalsCss)
+  })
+
+  it('rebases every shipped @source against the board root at depth zero', () => {
+    const rewritten = rebaseGlobalsCssSources(shippedGlobalsCss, '/board/src/styles', '/board')
+    const sources = [...rewritten.matchAll(/@source "([^"]+)";/g)].map((match) => match[1])
+
+    expect(sources.length).toBeGreaterThan(0)
+    expect(sources).toContain('../../themes')
+    expect(sources).toContain('../../packages/ui/src')
+    for (const source of sources) expect(source.startsWith('../../')).toBe(true)
+  })
+
   it('is a no-op for a file with no @source lines', () => {
     const css = '@import "tailwindcss";\n.foo { color: red; }\n'
     expect(rebaseGlobalsCssSources(css, '/repo/boards/stock/.meith/app/src/styles', '/repo')).toBe(
@@ -35,3 +70,131 @@ describe('rebaseGlobalsCssSources', () => {
     )
   })
 })
+
+/**
+ * `forum-web start --at-root` materializes and then stops, because there is
+ * no standalone build for it to exec — which makes it the whole
+ * materialization path in under a tenth of a second, with no `next build`
+ * anywhere near it. Materialization is the part that has been wrong; the
+ * build is not.
+ */
+const BIN = fileURLToPath(new URL('./forum-web.mjs', import.meta.url))
+
+function materializeAtRoot(dir: string) {
+  const result = spawnSync(process.execPath, [BIN, 'start', '--at-root'], {
+    cwd: dir,
+    encoding: 'utf8',
+  })
+  const output = `${result.stdout ?? ''}${result.stderr ?? ''}`
+  return {
+    output,
+    refused: output.includes('refusing to overwrite'),
+    materialized: output.includes('no standalone build'),
+  }
+}
+
+describe('materializing at the workspace root', () => {
+  const boards: string[] = []
+
+  afterAll(() => {
+    for (const dir of boards) rmSync(dir, { recursive: true, force: true })
+  })
+
+  function board(): string {
+    const dir = mkdtempSync(join(tmpdir(), 'forum-web-at-root-'))
+    writeFileSync(join(dir, 'community.config.ts'), 'export default {}\n')
+    writeFileSync(join(dir, 'community.plugins.ts'), 'export const INSTALLED_PLUGINS = []\n')
+    boards.push(dir)
+    return dir
+  }
+
+  it('writes the app into the workspace root and records every file it wrote', () => {
+    const dir = board()
+
+    expect(materializeAtRoot(dir).materialized).toBe(true)
+
+    for (const rel of ['next.config.mjs', 'app', 'src/styles/globals.css', 'public/sw.js']) {
+      expect(existsSync(join(dir, rel))).toBe(true)
+    }
+
+    const record = JSON.parse(readFileSync(join(dir, '.meith/materialized.json'), 'utf8'))
+    expect(record.files).toContain('public/sw.js')
+    expect(record.files).toContain('next.config.mjs')
+    expect(record.files).toContain('tsconfig.json')
+  })
+
+  it('leaves a board file under a shared directory alone on a second run', () => {
+    const dir = board()
+    expect(materializeAtRoot(dir).materialized).toBe(true)
+
+    writeFileSync(join(dir, 'public/ads.txt'), 'board-owned\n')
+    mkdirSync(join(dir, 'public/.well-known'), { recursive: true })
+    writeFileSync(join(dir, 'public/.well-known/thing'), 'verify\n')
+
+    const second = materializeAtRoot(dir)
+
+    expect(second.refused).toBe(false)
+    expect(second.materialized).toBe(true)
+    expect(readFileSync(join(dir, 'public/ads.txt'), 'utf8')).toBe('board-owned\n')
+    expect(readFileSync(join(dir, 'public/.well-known/thing'), 'utf8')).toBe('verify\n')
+    expect(existsSync(join(dir, 'public/sw.js'))).toBe(true)
+  })
+
+  it('refuses a board file under a name the framework ships, before writing anything', () => {
+    const dir = board()
+    writeFileSync(join(dir, 'instrumentation.ts'), 'export function register() {}\n')
+
+    const result = materializeAtRoot(dir)
+
+    expect(result.refused).toBe(true)
+    expect(result.output).toContain('instrumentation.ts')
+    expect(readFileSync(join(dir, 'instrumentation.ts'), 'utf8')).toBe(
+      'export function register() {}\n',
+    )
+    expect(existsSync(join(dir, 'app'))).toBe(false)
+    expect(existsSync(join(dir, 'next.config.mjs'))).toBe(false)
+  })
+
+  it('proceeds on a fresh checkout whose materialized files are committed', () => {
+    const dir = board()
+    expect(materializeAtRoot(dir).materialized).toBe(true)
+
+    rmSync(join(dir, '.meith'), { recursive: true, force: true })
+    const second = materializeAtRoot(dir)
+
+    expect(second.refused).toBe(false)
+    expect(second.materialized).toBe(true)
+  })
+
+  it('removes a file it recorded and no longer ships, and nothing else', () => {
+    const dir = board()
+    expect(materializeAtRoot(dir).materialized).toBe(true)
+
+    const recordPath = join(dir, '.meith/materialized.json')
+    const record = JSON.parse(readFileSync(recordPath, 'utf8'))
+    writeFileSync(join(dir, 'src/dropped-by-a-release.ts'), 'stale\n')
+    writeFileSync(join(dir, 'src/mine.ts'), 'board\n')
+    record.files.push('src/dropped-by-a-release.ts')
+    writeFileSync(recordPath, JSON.stringify(record))
+
+    expect(materializeAtRoot(dir).materialized).toBe(true)
+
+    expect(existsSync(join(dir, 'src/dropped-by-a-release.ts'))).toBe(false)
+    expect(readFileSync(join(dir, 'src/mine.ts'), 'utf8')).toBe('board\n')
+  })
+
+  it('warns about a board file under a directory the framework owns outright', () => {
+    const dir = board()
+    expect(materializeAtRoot(dir).materialized).toBe(true)
+
+    mkdirSync(join(dir, 'app/custom'), { recursive: true })
+    writeFileSync(join(dir, 'app/custom/page.tsx'), 'export default () => null\n')
+
+    const second = materializeAtRoot(dir)
+
+    expect(second.refused).toBe(false)
+    expect(second.output).toContain('app/custom/page.tsx')
+    expect(second.output).toContain("not @meith/web's")
+    expect(existsSync(join(dir, 'app/custom/page.tsx'))).toBe(true)
+  })
+})