@meith/web 0.17.2 → 0.19.0

package/LICENSE.md

@@ -1,165 +1,21 @@
-                   GNU LESSER GENERAL PUBLIC LICENSE
-                       Version 3, 29 June 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-
-  This version of the GNU Lesser General Public License incorporates
-the terms and conditions of version 3 of the GNU General Public
-License, supplemented by the additional permissions listed below.
-
-  0. Additional Definitions.
-
-  As used herein, "this License" refers to version 3 of the GNU Lesser
-General Public License, and the "GNU GPL" refers to version 3 of the GNU
-General Public License.
-
-  "The Library" refers to a covered work governed by this License,
-other than an Application or a Combined Work as defined below.
-
-  An "Application" is any work that makes use of an interface provided
-by the Library, but which is not otherwise based on the Library.
-Defining a subclass of a class defined by the Library is deemed a mode
-of using an interface provided by the Library.
-
-  A "Combined Work" is a work produced by combining or linking an
-Application with the Library.  The particular version of the Library
-with which the Combined Work was made is also called the "Linked
-Version".
-
-  The "Minimal Corresponding Source" for a Combined Work means the
-Corresponding Source for the Combined Work, excluding any source code
-for portions of the Combined Work that, considered in isolation, are
-based on the Application, and not on the Linked Version.
-
-  The "Corresponding Application Code" for a Combined Work means the
-object code and/or source code for the Application, including any data
-and utility programs needed for reproducing the Combined Work from the
-Application, but excluding the System Libraries of the Combined Work.
-
-  1. Exception to Section 3 of the GNU GPL.
-
-  You may convey a covered work under sections 3 and 4 of this License
-without being bound by section 3 of the GNU GPL.
-
-  2. Conveying Modified Versions.
-
-  If you modify a copy of the Library, and, in your modifications, a
-facility refers to a function or data to be supplied by an Application
-that uses the facility (other than as an argument passed when the
-facility is invoked), then you may convey a copy of the modified
-version:
-
-   a) under this License, provided that you make a good faith effort to
-   ensure that, in the event an Application does not supply the
-   function or data, the facility still operates, and performs
-   whatever part of its purpose remains meaningful, or
-
-   b) under the GNU GPL, with none of the additional permissions of
-   this License applicable to that copy.
-
-  3. Object Code Incorporating Material from Library Header Files.
-
-  The object code form of an Application may incorporate material from
-a header file that is part of the Library.  You may convey such object
-code under terms of your choice, provided that, if the incorporated
-material is not limited to numerical parameters, data structure
-layouts and accessors, or small macros, inline functions and templates
-(ten or fewer lines in length), you do both of the following:
-
-   a) Give prominent notice with each copy of the object code that the
-   Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the object code with a copy of the GNU GPL and this license
-   document.
-
-  4. Combined Works.
-
-  You may convey a Combined Work under terms of your choice that,
-taken together, effectively do not restrict modification of the
-portions of the Library contained in the Combined Work and reverse
-engineering for debugging such modifications, if you also do each of
-the following:
-
-   a) Give prominent notice with each copy of the Combined Work that
-   the Library is used in it and that the Library and its use are
-   covered by this License.
-
-   b) Accompany the Combined Work with a copy of the GNU GPL and this license
-   document.
-
-   c) For a Combined Work that displays copyright notices during
-   execution, include the copyright notice for the Library among
-   these notices, as well as a reference directing the user to the
-   copies of the GNU GPL and this license document.
-
-   d) Do one of the following:
-
-       0) Convey the Minimal Corresponding Source under the terms of this
-       License, and the Corresponding Application Code in a form
-       suitable for, and under terms that permit, the user to
-       recombine or relink the Application with a modified version of
-       the Linked Version to produce a modified Combined Work, in the
-       manner specified by section 6 of the GNU GPL for conveying
-       Corresponding Source.
-
-       1) Use a suitable shared library mechanism for linking with the
-       Library.  A suitable mechanism is one that (a) uses at run time
-       a copy of the Library already present on the user's computer
-       system, and (b) will operate properly with a modified version
-       of the Library that is interface-compatible with the Linked
-       Version.
-
-   e) Provide Installation Information, but only if you would otherwise
-   be required to provide such information under section 6 of the
-   GNU GPL, and only to the extent that such information is
-   necessary to install and execute a modified version of the
-   Combined Work produced by recombining or relinking the
-   Application with a modified version of the Linked Version. (If
-   you use option 4d0, the Installation Information must accompany
-   the Minimal Corresponding Source and Corresponding Application
-   Code. If you use option 4d1, you must provide the Installation
-   Information in the manner specified by section 6 of the GNU GPL
-   for conveying Corresponding Source.)
-
-  5. Combined Libraries.
-
-  You may place library facilities that are a work based on the
-Library side by side in a single library together with other library
-facilities that are not Applications and are not covered by this
-License, and convey such a combined library under terms of your
-choice, if you do both of the following:
-
-   a) Accompany the combined library with a copy of the same work based
-   on the Library, uncombined with any other library facilities,
-   conveyed under the terms of this License.
-
-   b) Give prominent notice with the combined library that part of it
-   is a work based on the Library, and explaining where to find the
-   accompanying uncombined form of the same work.
-
-  6. Revised Versions of the GNU Lesser General Public License.
-
-  The Free Software Foundation may publish revised and/or new versions
-of the GNU Lesser General Public License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns.
-
-  Each version is given a distinguishing version number. If the
-Library as you received it specifies that a certain numbered version
-of the GNU Lesser General Public License "or any later version"
-applies to it, you have the option of following the terms and
-conditions either of that published version or of any later version
-published by the Free Software Foundation. If the Library as you
-received it does not specify a version number of the GNU Lesser
-General Public License, you may choose any version of the GNU Lesser
-General Public License ever published by the Free Software Foundation.
-
-  If the Library as you received it specifies that a proxy can decide
-whether future versions of the GNU Lesser General Public License shall
-apply, that proxy's public statement of acceptance of any version is
-permanent authorization for you to choose that version for the
-Library.
+MIT License
+
+Copyright (c) 2026 Jordan Harrison and the Meith contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/app/admin/groups/promotions/page.tsx

@@ -101,6 +101,12 @@ export default async function AdminPromotionsPage() {
           {translator.t('adminGroups.examined', { count: result.examined })}
         </p>
 
+        {result.complete ? null : (
+          <p className={PANEL_NOTE}>
+            {translator.t('adminGroups.previewCapped', { count: result.examined })}
+          </p>
+        )}
+
         {result.outcomes.length === 0 ? (
           <p className={PANEL_NOTE}>
             {stored.length === 0

package/app/api/system/tick/route.ts

@@ -8,16 +8,23 @@ import { bearerSecret, secretMatches } from '@/server/secret-auth'
 
 export const dynamic = 'force-dynamic'
 export const revalidate = 0
+export const maxDuration = 300
 
 const SECRET_HEADER = 'x-tick-secret'
 
+function accepted(): string[] {
+  return [env.TICK_SECRET, env.CRON_SECRET].filter(
+    (candidate): candidate is string => typeof candidate === 'string' && candidate.length > 0,
+  )
+}
+
 function authorised(request: Request): boolean {
-  const expected = env.TICK_SECRET
+  const expected = accepted()
 
-  if (!expected) {
+  if (expected.length === 0) {
     logger().warn(
-      'TICK_SECRET is not set; the tick endpoint is unauthenticated. This is ' +
-        'permitted in development only.',
+      'Neither TICK_SECRET nor CRON_SECRET is set; the tick endpoint is unauthenticated. This is' +
+        ' permitted in development only.',
     )
     return true
   }
@@ -28,7 +35,14 @@ function authorised(request: Request): boolean {
     )
   }
 
-  return secretMatches(bearerSecret(request, SECRET_HEADER), expected)
+  const presented = bearerSecret(request, SECRET_HEADER)
+
+  let matched = false
+  for (const candidate of expected) {
+    if (secretMatches(presented, candidate)) matched = true
+  }
+
+  return matched
 }
 
 async function runTick(request: Request): Promise<NextResponse> {
@@ -60,11 +74,14 @@ async function runTick(request: Request): Promise<NextResponse> {
 
     const failed = outcomes.filter((o) => o.status === 'failed')
 
-    return NextResponse.json({
-      ok: failed.length === 0,
-      ran: outcomes,
-      registered: scheduler.tasks.length,
-    })
+    return NextResponse.json(
+      {
+        ok: failed.length === 0,
+        ran: outcomes,
+        registered: scheduler.tasks.length,
+      },
+      { status: 200 },
+    )
   })
 }
 

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,11 +96,14 @@ 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')
+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
@@ -91,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}`
@@ -104,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),
+  )
 }
 
 /**
@@ -172,12 +382,18 @@ function materialize() {
     )
   }
 
+  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 })
   }
@@ -217,6 +433,11 @@ function materialize() {
     join(appDir, 'next-env.d.ts'),
     '/// <reference types="next" />\n/// <reference types="next/image-types/global" />\n',
   )
+
+  if (rootFiles) {
+    recordRootFiles(rootFiles)
+    warnAboutStrayBoardFiles(rootFiles)
+  }
 }
 
 /**
@@ -265,10 +486,10 @@ function run(executable, args, cwd, onSuccess) {
 }
 
 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)
   }
 

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)
+  })
+})

package/next.config.mjs

@@ -5,10 +5,15 @@ import { fileURLToPath } from 'node:url'
 const here = path.dirname(fileURLToPath(import.meta.url))
 
 /**
- * Two directories up from this file's own location by default — correct at
- * the depth every consumer places it at except `boards/stock`, which
- * `FORUM_WORKSPACE_ROOT` overrides (see docs/architecture.md, "The stock
- * board"; docs/development.md, "Consuming the board from a workspace").
+ * Two directories up from this file's own location by default — correct
+ * where `forum-web` materializes at `.meith/app` and where this file sits in
+ * `apps/community` unmaterialized. `boards/stock` and `forum-web --at-root`
+ * are both at other depths, and neither relies on this default:
+ * `FORUM_WORKSPACE_ROOT` is set for the first by that board's own scripts
+ * and passed on by `forum-web` in every case, so this fallback only applies
+ * when the file is read outside that bin entirely (see
+ * docs/architecture.md, "The stock board"; docs/development.md, "Consuming
+ * the board from a workspace").
  */
 const workspaceRoot = process.env.FORUM_WORKSPACE_ROOT
   ? path.resolve(process.env.FORUM_WORKSPACE_ROOT)
@@ -18,9 +23,12 @@ const workspaceRoot = process.env.FORUM_WORKSPACE_ROOT
  * The relative equivalent of `workspaceRoot`, for `outputFileTracingIncludes`
  * below — see docs/development.md, "Consuming the board from a workspace",
  * for why that option needs a path relative to this file rather than an
- * absolute one.
+ * absolute one. It is `.` rather than the empty string when this file already
+ * sits at the workspace root, which is what `forum-web build --at-root`
+ * materializes (same section) — an empty prefix would make the glob below
+ * read as an absolute path and match nothing.
  */
-const upToWorkspaceRoot = path.relative(here, workspaceRoot).split(path.sep).join('/')
+const upToWorkspaceRoot = path.relative(here, workspaceRoot).split(path.sep).join('/') || '.'
 
 const loadedEnvFiles = []
 for (const name of ['.env.local', '.env']) {
@@ -39,13 +47,10 @@ const nextConfig = {
   poweredByHeader: false,
   distDir: process.env.FORUM_DIST_DIR ?? '.next',
 
-  experimental: {
-    turbopackFileSystemCacheForDev: false,
-  },
-
   serverExternalPackages: [
     '@aws-sdk/client-s3',
     '@aws-sdk/s3-request-presigner',
+    '@vercel/blob',
     'postgres',
     '@jsquash/jpeg',
     '@jsquash/png',
@@ -61,6 +66,7 @@ const nextConfig = {
   outputFileTracingIncludes: {
     '/**': [
       `${upToWorkspaceRoot}/node_modules/.pnpm/@swc+helpers@0.5.23/node_modules/@swc/helpers/**/*`,
+      `${upToWorkspaceRoot}/node_modules/@swc/helpers/**/*`,
     ],
   },
   images: {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@meith/web",
-  "version": "0.17.2",
+  "version": "0.19.0",
   "description": "The board itself: the Next.js app, and the forum-web bin that materializes it into an external board workspace.",
-  "license": "LGPL-3.0-or-later",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/meith-dev/meith.git",
@@ -43,52 +43,52 @@
     "typescript": "7.0.2",
     "@types/react": "^19",
     "@types/react-dom": "^19",
-    "@meith/admin": "0.17.2",
-    "@meith/antispam": "0.17.2",
-    "@meith/attachments": "0.17.2",
-    "@meith/api": "0.17.2",
-    "@meith/authorization": "0.17.2",
-    "@meith/accounts": "0.17.2",
-    "@meith/avatars": "0.17.2",
-    "@meith/core": "0.17.2",
-    "@meith/db": "0.17.2",
-    "@meith/events": "0.17.2",
-    "@meith/demo": "0.17.2",
-    "@meith/drivers": "0.17.2",
-    "@meith/forums": "0.17.2",
-    "@meith/groups": "0.17.2",
-    "@meith/i18n": "0.17.2",
-    "@meith/drafts": "0.17.2",
-    "@meith/mail": "0.17.2",
-    "@meith/install": "0.17.2",
-    "@meith/markdown": "0.17.2",
-    "@meith/import": "0.17.2",
-    "@meith/marketplace": "0.17.2",
-    "@meith/moderation": "0.17.2",
-    "@meith/notifications": "0.17.2",
-    "@meith/messages": "0.17.2",
-    "@meith/polls": "0.17.2",
-    "@meith/plugin-dues": "0.17.2",
-    "@meith/posts": "0.17.2",
-    "@meith/plugin-kit": "0.17.2",
-    "@meith/profile-fields": "0.17.2",
-    "@meith/runtime": "0.17.2",
-    "@meith/search": "0.17.2",
-    "@meith/relations": "0.17.2",
-    "@meith/reputation": "0.17.2",
-    "@meith/signatures": "0.17.2",
-    "@meith/settings": "0.17.2",
-    "@meith/subscriptions": "0.17.2",
-    "@meith/tasks": "0.17.2",
-    "@meith/theme-clubhouse": "0.17.2",
-    "@meith/theme-default": "0.17.2",
-    "@meith/theme-kit": "0.17.2",
-    "@meith/theme-midnight": "0.17.2",
-    "@meith/theme-phasebook": "0.17.2",
-    "@meith/theme-raidframe": "0.17.2",
-    "@meith/threads": "0.17.2",
-    "@meith/ui": "0.17.2",
-    "@meith/upgrade": "0.17.2"
+    "@meith/accounts": "0.19.0",
+    "@meith/admin": "0.19.0",
+    "@meith/antispam": "0.19.0",
+    "@meith/api": "0.19.0",
+    "@meith/attachments": "0.19.0",
+    "@meith/authorization": "0.19.0",
+    "@meith/core": "0.19.0",
+    "@meith/avatars": "0.19.0",
+    "@meith/db": "0.19.0",
+    "@meith/drafts": "0.19.0",
+    "@meith/demo": "0.19.0",
+    "@meith/drivers": "0.19.0",
+    "@meith/events": "0.19.0",
+    "@meith/groups": "0.19.0",
+    "@meith/forums": "0.19.0",
+    "@meith/i18n": "0.19.0",
+    "@meith/mail": "0.19.0",
+    "@meith/install": "0.19.0",
+    "@meith/markdown": "0.19.0",
+    "@meith/import": "0.19.0",
+    "@meith/marketplace": "0.19.0",
+    "@meith/messages": "0.19.0",
+    "@meith/moderation": "0.19.0",
+    "@meith/notifications": "0.19.0",
+    "@meith/plugin-dues": "0.19.0",
+    "@meith/polls": "0.19.0",
+    "@meith/relations": "0.19.0",
+    "@meith/posts": "0.19.0",
+    "@meith/plugin-kit": "0.19.0",
+    "@meith/profile-fields": "0.19.0",
+    "@meith/reputation": "0.19.0",
+    "@meith/runtime": "0.19.0",
+    "@meith/settings": "0.19.0",
+    "@meith/subscriptions": "0.19.0",
+    "@meith/search": "0.19.0",
+    "@meith/tasks": "0.19.0",
+    "@meith/theme-clubhouse": "0.19.0",
+    "@meith/theme-default": "0.19.0",
+    "@meith/signatures": "0.19.0",
+    "@meith/theme-kit": "0.19.0",
+    "@meith/theme-midnight": "0.19.0",
+    "@meith/theme-phasebook": "0.19.0",
+    "@meith/ui": "0.19.0",
+    "@meith/theme-raidframe": "0.19.0",
+    "@meith/upgrade": "0.19.0",
+    "@meith/threads": "0.19.0"
   },
   "scripts": {
     "dev": "next dev",

package/src/server/group-admin.ts

@@ -77,14 +77,10 @@ export function requirePromotionRules(): PostgresPromotionRepository {
   return repository
 }
 
-export async function previewPromotions(limit = 500): Promise<PromotionRunResult | null> {
+export async function previewPromotions(): Promise<PromotionRunResult | null> {
   if (getContainer().dataSource !== 'postgres') return null
 
-  const service = new PromotionService({
-    promotions: new PostgresPromotionRepository(getDb()),
-    guards: defaultPromotionGuards(),
-  })
-  return service.preview(limit)
+  return promotionService().preview()
 }
 
 export function promotionService(): PromotionService {

package/src/server/install.ts

@@ -15,6 +15,7 @@ import {
   getDb,
   isInstalled,
   markInstalled,
+  migrationUrl,
   PostgresAdminRepository,
   PostgresForumRepository,
   PostgresSettingsRepository,
@@ -126,7 +127,7 @@ async function forgetCachedBoard(): Promise<void> {
 export type InstallRun = { readonly sealed: true } | { readonly report: readonly StepOutcome[] }
 
 export async function runInstall(input: InstallInput): Promise<InstallRun> {
-  const url = env.DATABASE_URL ?? ''
+  const url = migrationUrl(env)
 
   try {
     const run = await withInstallLock(url, async (): Promise<InstallRun> => {

package/src/server/upgrade-notice.ts

@@ -6,7 +6,7 @@ import { planUpgrade, type UpgradeState, upgradeNotice } from '@meith/upgrade'
 
 import { activeDefinitions } from './plugin-host'
 
-export const CODE_VERSION = '0.17.2'
+export const CODE_VERSION = '0.19.0'
 
 export async function pendingUpgradeNotice(): Promise<string | null> {
   if (env.DATA_SOURCE !== 'postgres') return null