@statorjs/stator 2.9.0 → 2.10.0-next.0

package/src/build/copy-set.ts

@@ -0,0 +1,349 @@
+import { type Dirent, realpathSync } from 'node:fs'
+import { readdir, readFile, stat } from 'node:fs/promises'
+import { builtinModules } from 'node:module'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { build } from 'esbuild'
+import { compile, regionResolverFor } from '../compiler/index.ts'
+
+/**
+ * What `stator build` copies into `dist/` — derived from the app's own module
+ * graph, not from a list of directory names.
+ *
+ * The build used to copy every top-level directory that wasn't on a denylist,
+ * which meant runtime data (an uploads dir, a JSON cache a deploy script
+ * maintains) landed in the artifact, while a root-level file a module actually
+ * reads — `new URL('../app.db', import.meta.url)` — did not. Both failures come
+ * from the same place: guessing at the app's shape instead of asking the code.
+ *
+ * So one esbuild pass walks the graph from the entry points the FRAMEWORK
+ * itself loads — the route and machine files, plus the root single-file hooks —
+ * and everything else is copied because it was reached. `templates/`, `lib/`,
+ * `components/` are not names this module knows; they are consequences. The
+ * pass parses nothing itself: resolution is esbuild's, so tsconfig `paths`,
+ * extensionless specifiers, index files and `exports` maps behave exactly as
+ * they do at runtime, and `.stator` files are compiled on load so frontmatter
+ * imports are in the graph like any other import.
+ *
+ * Copying is DIRECTORY-granular on purpose. A module's data files — a template
+ * read with `readFile`, a fixture JSON — are invisible to any import graph, so
+ * a reached module brings its whole top-level directory along. The cost is
+ * copying a few unreferenced siblings; the alternative is a dist that is
+ * missing files nothing declared.
+ *
+ * Nothing from `node_modules` is traced or copied. A bare specifier is recorded
+ * as a direct dependency and left external, so the walk stops there and never
+ * descends into a dependency's own imports — `dist/` holds no `node_modules`,
+ * and the recorded list is the app's own dependency set, which is exactly what
+ * a manifest should declare.
+ */
+
+/** Directories whose files are entry points, by framework convention. */
+const ENTRY_DIRS = ['routes', 'machines']
+/** Root-level single-file entry points. Each is optional. */
+const ENTRY_FILES = [
+  'middleware.ts',
+  'boot.ts',
+  'stator.config.ts',
+  'stator.config.mts',
+  'stator.config.js',
+  'stator.config.mjs',
+]
+/** Directories the framework serves by path rather than importing. */
+const SERVED_DIRS = ['static']
+/** Never app source, so never worth reporting as an uncopied candidate. */
+const NEVER_SOURCE = new Set(['node_modules', 'dist', 'tests', 'test', '__tests__'])
+
+const CODE = /\.(ts|tsx|mts|cts|js|mjs|cjs|jsx|stator)$/
+const BUILTIN = new Set([...builtinModules, ...builtinModules.map((m) => `node:${m}`)])
+/** `new URL('./x', import.meta.url)` — invisible to the bundler, so read the
+ *  literal directly. Same limit as the client seam: relative string literals.
+ *  (Injecting an import instead does NOT work: esbuild's TS loader elides an
+ *  import whose binding is unused, so the injected one disappears.) */
+const URL_ASSET_RE = /new\s+URL\(\s*(['"])(\.{1,2}\/[^'"\n]+)\1\s*,\s*import\.meta\.url\s*\)/g
+/** A `node_modules` path segment, either separator. Anything under one is a
+ *  dependency, never app source — and a real app's `node_modules` sits INSIDE
+ *  its root, so root containment alone cannot tell them apart. */
+const NODE_MODULES = /[\\/]node_modules[\\/]/
+/** `import(` not followed by a string or template literal. */
+const OPAQUE_IMPORT_RE = /(?<![.\w$])import\s*\(\s*([^'"`)\s])/g
+
+const norm = (p: string): string => p.replace(/\\/g, '/')
+
+export interface UntracedImport {
+  /** App-relative file. */
+  file: string
+  line: number
+  /** The call as written, truncated. */
+  source: string
+}
+
+export interface CopySetOptions {
+  /** App source root. */
+  root: string
+  /** Extra app-relative paths (directories or files) to copy verbatim — the
+   *  escape hatch for what no import graph can see, e.g. a directory read
+   *  through a runtime-built path. */
+  include?: string[]
+}
+
+export interface CopySet {
+  /** Top-level directories to copy whole. */
+  dirs: string[]
+  /** Root-level files to copy. */
+  files: string[]
+  /** Top-level directories present in the root that nothing reached. */
+  unused: string[]
+  /** Direct dependencies: the package name behind every bare specifier the
+   *  app's own code reached. NOT transitive — a dependency is external, so it
+   *  is never loaded and its own imports are never resolved. That is the right
+   *  granularity for a generated manifest (a package manager resolves
+   *  transitives from each dependency's own package.json) and for checking
+   *  runtime imports against `dependencies` rather than `devDependencies`:
+   *  a type-only import is elided before resolution, so it never lands here. */
+  packages: string[]
+  /** Reached files outside the app root — impossible to place in `dist/`. */
+  external: string[]
+  /** Specifiers esbuild could not resolve. Not fatal here: `stator check`
+   *  typechecks the same graph and is the gate for a genuinely broken import. */
+  unresolved: string[]
+  /** `import()` calls no static analysis can follow. */
+  untraced: UntracedImport[]
+  /** App-local files the graph reached, app-relative. */
+  reached: string[]
+  ms: number
+}
+
+const exists = (p: string): Promise<boolean> =>
+  stat(p).then(
+    () => true,
+    () => false,
+  )
+
+async function walk(dir: string, match: (f: string) => boolean): Promise<string[]> {
+  const out: string[] = []
+  let entries: Dirent[]
+  try {
+    entries = await readdir(dir, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const e of entries) {
+    const full = join(dir, e.name)
+    if (e.isDirectory()) out.push(...(await walk(full, match)))
+    else if (match(full)) out.push(full)
+  }
+  return out
+}
+
+/**
+ * Walk the app's server graph and report what `dist/` needs. Writes nothing and
+ * runs no app code — `.stator` is compiled, everything else is only parsed.
+ */
+export async function resolveCopySet(opts: CopySetOptions): Promise<CopySet> {
+  const root = resolve(opts.root)
+  // esbuild reports REAL paths (on macOS /var is a symlink to /private/var), so
+  // classify against the real root or every reached file looks external and
+  // nothing gets copied. Same lesson as `hashMachines`.
+  const realRoot = ((): string => {
+    try {
+      return realpathSync(root)
+    } catch {
+      return root
+    }
+  })()
+  /**
+   * Is this absolute path inside the app root? `path.relative` is the only
+   * correct test on Windows: paths there are case-insensitive and esbuild's
+   * spelling of a drive letter need not match ours, so comparing normalized
+   * strings with `startsWith` reports a perfectly good in-root file as
+   * external — and across drives `relative` returns an ABSOLUTE path, which a
+   * `..` check alone would miss. (win32's `relative` lowercases before
+   * comparing; posix is unaffected.)
+   */
+  const insideRoot = (abs: string): boolean => {
+    const rel = relative(realRoot, abs)
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel)
+  }
+
+  const t0 = performance.now()
+
+  const entries: string[] = []
+  for (const dir of ENTRY_DIRS) entries.push(...(await walk(join(root, dir), (f) => CODE.test(f))))
+  for (const name of ENTRY_FILES) {
+    const p = join(root, name)
+    if (await exists(p)) entries.push(p)
+  }
+  if (entries.length === 0) {
+    throw new Error(
+      `stator build: no entry points found — expected ${ENTRY_DIRS.map((d) => `${d}/`).join(' or ')} under ${root}`,
+    )
+  }
+
+  const reached = new Set<string>()
+  const assets = new Set<string>()
+  const packages = new Set<string>()
+  const external = new Set<string>()
+  const unresolved = new Set<string>()
+  const untraced: UntracedImport[] = []
+
+  /** Record the non-import dependencies a source text carries. */
+  const scan = (text: string, file: string): string => {
+    for (const m of text.matchAll(URL_ASSET_RE)) assets.add(resolve(dirname(file), m[2]!))
+    for (const m of text.matchAll(OPAQUE_IMPORT_RE)) {
+      untraced.push({
+        file: norm(relative(realRoot, file)),
+        line: text.slice(0, m.index).split('\n').length,
+        source: `${text
+          .slice(m.index, m.index + 60)
+          .split('\n')[0]!
+          .trim()}…`,
+      })
+    }
+    return text
+  }
+
+  try {
+    await build({
+      // Unique synthetic output name per entry: a `routes/x.stator` +
+      // `routes/x.ts` pair (the GET/POST route merge) otherwise collides on one
+      // output path and fails the whole pass.
+      entryPoints: entries.map((f) => ({
+        in: f,
+        out: norm(relative(root, f)).replace(/[\\/]/g, '_').replace(/\./g, '-'),
+      })),
+      absWorkingDir: root,
+      bundle: true,
+      write: false,
+      format: 'esm',
+      platform: 'node',
+      target: 'node20',
+      outdir: join(root, '.stator-copy-set'), // virtual — write: false
+      logLevel: 'silent',
+      plugins: [
+        {
+          name: 'stator-copy-set',
+          setup(b) {
+            b.onResolve({ filter: /.*/ }, async (args) => {
+              if (args.kind === 'entry-point' || args.pluginData?.resolved) return null
+              if (BUILTIN.has(args.path)) return { path: args.path, external: true }
+
+              const r = await b.resolve(args.path, {
+                kind: args.kind,
+                importer: args.importer,
+                resolveDir: args.resolveDir,
+                pluginData: { resolved: true },
+              })
+              if (r.errors.length > 0) {
+                unresolved.add(`${args.path} (from ${norm(relative(realRoot, args.importer))})`)
+                return { path: args.path, external: true }
+              }
+              const abs = r.path
+              // Package or app file? Neither the path nor the specifier settles
+              // it alone, so both are consulted. A dependency installed the
+              // ordinary way lives UNDER the app root in `node_modules`, so
+              // containment cannot exclude it; a dependency reached through a
+              // workspace link resolves to a real path with no `node_modules`
+              // segment, so the path cannot exclude it either. Meanwhile a
+              // tsconfig `paths` alias looks exactly like a bare specifier and
+              // is app code. So: under node_modules is always a package, and
+              // outside the root a bare specifier is a package while a relative
+              // one is an app file `dist` cannot contain.
+              const bare = !args.path.startsWith('.') && !isAbsolute(args.path)
+              const inRoot = isAbsolute(abs) && insideRoot(abs)
+              if (NODE_MODULES.test(abs) || (!inRoot && bare)) {
+                if (bare) {
+                  packages.add(
+                    args.path.startsWith('@')
+                      ? args.path.split('/').slice(0, 2).join('/')
+                      : args.path.split('/')[0]!,
+                  )
+                }
+                return { path: abs, external: true }
+              }
+              if (!inRoot) {
+                external.add(norm(abs))
+                return { path: abs, external: true }
+              }
+              if (!CODE.test(abs)) {
+                assets.add(abs) // data file: recorded, never parsed
+                return { path: abs, external: true }
+              }
+              return { path: abs, pluginData: { resolved: true } }
+            })
+
+            b.onLoad({ filter: /\.stator$/ }, async (args) => {
+              reached.add(args.path)
+              const source = await readFile(args.path, 'utf8')
+              const kind = /[\\/]routes[\\/].*\.stator$/.test(args.path) ? 'route' : 'component'
+              const out = compile(source, {
+                id: args.path,
+                kind,
+                resolveRegions: regionResolverFor(args.path, source),
+              })
+              return {
+                contents: scan(out.serverCode, args.path),
+                loader: 'ts',
+                resolveDir: dirname(args.path),
+              }
+            })
+
+            b.onLoad({ filter: CODE }, async (args) => {
+              reached.add(args.path)
+              const source = await readFile(args.path, 'utf8')
+              return {
+                contents: scan(source, args.path),
+                loader: /\.(tsx|jsx)$/.test(args.path)
+                  ? 'tsx'
+                  : /\.(js|mjs|cjs)$/.test(args.path)
+                    ? 'js'
+                    : 'ts',
+                resolveDir: dirname(args.path),
+              }
+            })
+          },
+        },
+      ],
+    })
+  } catch (err) {
+    const errors = (err as { errors?: Array<{ text: string }> }).errors ?? []
+    throw new Error(
+      `stator build: could not walk the app's module graph — ${
+        errors.length > 0 ? errors.map((e) => e.text).join('; ') : (err as Error).message
+      }`,
+    )
+  }
+
+  const dirs = new Set<string>()
+  const files = new Set<string>()
+  for (const abs of [...reached, ...assets]) {
+    // Assets come from the `new URL` scan rather than resolution, so they get
+    // the same containment test the resolver hook applies.
+    if (!insideRoot(abs)) continue
+    const rel = norm(relative(realRoot, abs))
+    if (rel.includes('/')) dirs.add(rel.split('/')[0]!)
+    else files.add(rel)
+  }
+  for (const dir of SERVED_DIRS) if (await exists(join(root, dir))) dirs.add(dir)
+  for (const extra of opts.include ?? []) {
+    const rel = norm(extra).replace(/^\.\//, '').replace(/\/+$/, '')
+    if (!(await exists(join(root, rel)))) continue
+    if ((await stat(join(root, rel))).isDirectory() || !rel.includes('/')) dirs.add(rel)
+    else files.add(rel)
+  }
+
+  const topLevel = (await readdir(root, { withFileTypes: true }))
+    .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !NEVER_SOURCE.has(e.name))
+    .map((e) => e.name)
+
+  return {
+    dirs: [...dirs].sort(),
+    files: [...files].sort(),
+    unused: topLevel.filter((d) => !dirs.has(d) && d !== 'dist').sort(),
+    packages: [...packages].sort(),
+    external: [...external].sort(),
+    unresolved: [...unresolved].sort(),
+    untraced,
+    reached: [...reached].map((f) => norm(relative(realRoot, f))).sort(),
+    ms: Math.round(performance.now() - t0),
+  }
+}

package/src/build/head.ts

@@ -20,6 +20,13 @@ export async function loadProductionHead(distDir: string): Promise<{
    *  `machineHashes` so hydration compares against what was built. Absent on
    *  a dist built before hashes existed — `createApp` then hashes live. */
   machines?: Record<string, string>
+  /** The config file the artifact carries, `null` when the app has none, and
+   *  `undefined` when the manifest predates the field — which `stator start`
+   *  reads as "rebuild", since it cannot otherwise tell a config-less app from
+   *  a config that never made the trip. */
+  config?: string | null
+  /** The `@statorjs/stator` version that produced the artifact, if recorded. */
+  statorVersion?: string
 }> {
   const dist = resolve(distDir)
 
@@ -34,6 +41,8 @@ export async function loadProductionHead(distDir: string): Promise<{
   let routes: StatorManifest['routes'] = {}
   let buildId: string | undefined
   let machines: Record<string, string> | undefined
+  let config: string | null | undefined
+  let statorVersion: string | undefined
   try {
     const manifest = JSON.parse(
       await readFile(join(dist, 'stator-manifest.json'), 'utf8'),
@@ -41,6 +50,8 @@ export async function loadProductionHead(distDir: string): Promise<{
     routes = manifest.routes ?? {}
     buildId = manifest.buildId
     machines = manifest.machines
+    config = manifest.config
+    statorVersion = manifest.statorVersion
   } catch {
     // no manifest
   }
@@ -52,5 +63,11 @@ export async function loadProductionHead(distDir: string): Promise<{
       .filter(Boolean)
       .join('\n')
   }
-  return { headExtras, buildId, ...(machines ? { machines } : {}) }
+  return {
+    headExtras,
+    buildId,
+    ...(machines ? { machines } : {}),
+    ...(config !== undefined ? { config } : {}),
+    ...(statorVersion ? { statorVersion } : {}),
+  }
 }

package/src/build/index.ts

@@ -3,8 +3,12 @@
  * plain `.ts` the runtime serves with no Vite. See `buildApp`.
  */
 
+export type { ArtifactDeps } from './artifact.ts'
+export { writeArtifactDeps } from './artifact.ts'
 export type { BuildConfig, BuildResult, StatorManifest } from './build.ts'
 export { buildApp } from './build.ts'
+export type { CopySet, CopySetOptions, UntracedImport } from './copy-set.ts'
+export { resolveCopySet } from './copy-set.ts'
 export { loadProductionHead } from './head.ts'
 export type {
   BundleIslandsOptions,

package/src/cli/commands/build.ts

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path'
 import { buildApp } from '../../build/index.ts'
+import { loadConfig } from '../config.ts'
 import type { CliContext } from '../run.ts'
 import { checkStack } from './check.ts'
 
@@ -7,12 +8,81 @@ import { checkStack } from './check.ts'
  *  server file fails the build instead of shipping silently. */
 export async function run(ctx: CliContext): Promise<void> {
   await checkStack(ctx.root)
-  const result = await buildApp({ root: ctx.root, outDir: resolve(ctx.root, 'dist') })
+  const config = await loadConfig(ctx.root)
+  const result = await buildApp({
+    root: ctx.root,
+    outDir: resolve(ctx.root, 'dist'),
+    include: config.build?.include,
+    untracedImports: config.build?.untracedImports,
+  })
+  const { copySet } = result
   process.stdout.write(
     `stator build: ${result.compiled} components → ${result.outDir}` +
       `${result.islands ? ` (${result.islands} island${result.islands === 1 ? '' : 's'})` : ''}` +
       ` · ${result.machines} machine${result.machines === 1 ? '' : 's'} hashed in ${result.machineHashMs} ms\n`,
   )
+  // What the module graph decided to copy. Printed because a copy set derived
+  // from code should be visible, not inferred from what turns up in dist/.
+  process.stdout.write(
+    `  copied: ${copySet.dirs.join(', ')}` +
+      `${copySet.files.length ? ` · ${copySet.files.length} root file${copySet.files.length === 1 ? '' : 's'} (${copySet.files.join(', ')})` : ''}` +
+      ` · graph walked in ${copySet.ms} ms\n`,
+  )
+  // How the artifact declares its dependencies — and, for a workspace member,
+  // that its transitives are not locked.
+  const { deps } = result
+  if (deps.kind === 'copied') {
+    process.stdout.write(
+      `  deps: ${deps.files.join(' + ')} copied · on the target run \`${deps.install}\`\n`,
+    )
+  } else if (deps.kind === 'generated') {
+    const n = Object.keys(deps.pinned ?? {}).length
+    process.stdout.write(
+      `  deps: no lockfile beside package.json (workspace app) — generated a package.json pinning ${n} direct dependenc${n === 1 ? 'y' : 'ies'}\n` +
+        `        on the target run \`${deps.install}\`; transitives are NOT locked, so prefer resolving at build time (\`pnpm deploy --prod\`, or build in the image)\n`,
+    )
+    if (deps.unpinned?.length) {
+      process.stdout.write(
+        `        warning: could not read an installed version for ${deps.unpinned.join(', ')} — used the declared range\n`,
+      )
+    }
+  }
+  // Layer 2 of the persistence story: whether the config DECLARES a session
+  // store is env-independent, so the build can say this soundly. Which store a
+  // declared one resolves to is not — that depends on the production
+  // environment, which a build machine does not have — so this is a notice
+  // about a shape, never a verdict about a value, and never an error: an app
+  // that wants in-memory made a real choice.
+  if (
+    result.copySet.files.some((f) => f.startsWith('stator.config.')) &&
+    !config.persistence?.session
+  ) {
+    process.stdout.write(
+      '  note: no session store configured — session state will not survive a restart' +
+        ' (see `persistence.session`, or `sessionStore({ redisUrl: process.env.REDIS_URL })`)\n',
+    )
+  }
+  if (copySet.unused.length > 0) {
+    process.stdout.write(
+      `  not copied: ${copySet.unused.join(', ')} — nothing in the app imports or opens them` +
+        ` (add to \`build.include\` if they're read at runtime)\n`,
+    )
+  }
+  if (copySet.untraced.length > 0) {
+    // Only reachable with `untracedImports: 'warn'` — the default throws.
+    process.stdout.write(
+      `  warning: ${copySet.untraced.length} untraceable dynamic import${copySet.untraced.length === 1 ? '' : 's'}` +
+        ` — dist may be missing what they load:\n${copySet.untraced
+          .map((u) => `    ${u.file}:${u.line}  ${u.source}\n`)
+          .join('')}`,
+    )
+  }
+  if (copySet.external.length > 0) {
+    process.stdout.write(
+      `  warning: ${copySet.external.length} file${copySet.external.length === 1 ? '' : 's'} reached outside the app root` +
+        ` — not copied, so dist is not self-contained:\n${copySet.external.map((f) => `    ${f}\n`).join('')}`,
+    )
+  }
   // Deploy awareness: which machines' sessions this build resets (see the
   // snapshot hydration policy — sessions never outlive the code that made them).
   if (result.resetMachines) {

package/src/cli/commands/start.ts

@@ -1,22 +1,88 @@
 import { stat } from 'node:fs/promises'
+import { createRequire } from 'node:module'
 import { resolve } from 'node:path'
 import { loadProductionHead } from '../../build/index.ts'
 import { createApp } from '../../server/index.ts'
 import { loadConfig, resolvePort } from '../config.ts'
 import type { CliContext } from '../run.ts'
 
-/** Serve a built `dist/` in production mode (no Vite). Same `stator.config.ts`
- *  as `dev` supplies the store/session/port. */
+const running: string = (
+  createRequire(import.meta.url)('../../../package.json') as { version: string }
+).version
+
+/** Same major.minor. A patch cannot change what the compiler emitted; a minor
+ *  can, and the artifact was emitted by one specific compiler. */
+const emitCompatible = (built: string, current: string): boolean =>
+  built.split('.').slice(0, 2).join('.') === current.split('.').slice(0, 2).join('.')
+
+const exists = (p: string): Promise<boolean> =>
+  stat(p).then(
+    () => true,
+    () => false,
+  )
+
+/**
+ * Serve a built artifact in production (no Vite).
+ *
+ * Everything comes from the artifact, `stator.config.ts` included. There is
+ * deliberately no fall back to the source tree: a config read from outside the
+ * artifact makes `dist/` a lie — the same build would then behave one way from
+ * a repo checkout and another way from a copied `dist/`, and a deploy that
+ * shipped only `dist/` would find no config at all and start on in-memory
+ * persistence without saying a word. It is also how two copies of a module end
+ * up live in one process: a root config importing `./lib/db.ts` while the
+ * machines import `dist/lib/db.ts` means two connections, two caches, and two
+ * versions of the same code.
+ */
 export async function run(ctx: CliContext): Promise<void> {
-  const dist = resolve(ctx.root, 'dist')
-  try {
-    await stat(resolve(dist, 'routes'))
-  } catch {
+  // The artifact can be the deploy root itself: point `--root` at a directory
+  // holding the manifest beside `routes/` and it is served in place, so `dist/`
+  // can be the only directory copied to a server.
+  const inPlace =
+    (await exists(resolve(ctx.root, 'stator-manifest.json'))) &&
+    (await exists(resolve(ctx.root, 'routes')))
+  const dist = inPlace ? resolve(ctx.root) : resolve(ctx.root, 'dist')
+
+  if (!(await exists(resolve(dist, 'routes')))) {
     throw new Error('no dist/ found — run `stator build` first')
   }
 
-  const config = await loadConfig(ctx.root)
-  const { headExtras, buildId, machines } = await loadProductionHead(dist)
+  const {
+    headExtras,
+    buildId,
+    machines,
+    config: configFile,
+    statorVersion: builtWith,
+  } = await loadProductionHead(dist)
+
+  // The artifact holds output emitted by one specific compiler. Running it
+  // against a different framework minor means the runtime and the emit
+  // disagree, and the failures are obscure — a template read that reports it
+  // was called outside a render, because two copies of the framework hold
+  // separate render state. An app whose lockfile pins an older version than
+  // the machine that built it produces exactly this, silently.
+  if (builtWith && !emitCompatible(builtWith, running)) {
+    throw new Error(
+      `this dist was compiled by @statorjs/stator ${builtWith} but ${running} is running — ` +
+        `rebuild with the installed version, or install ${builtWith} in the artifact`,
+    )
+  }
+
+  // An artifact built before the manifest recorded its config cannot be trusted
+  // to be complete: "no config" and "the config didn't travel" look identical,
+  // and guessing wrong silently downgrades persistence.
+  if (configFile === undefined) {
+    throw new Error(
+      'this dist was built by an older stator and does not record its config — run `stator build` again',
+    )
+  }
+  if (configFile !== null && !(await exists(resolve(dist, configFile)))) {
+    throw new Error(
+      `dist is incomplete: the build recorded ${configFile} but it is not in the artifact — copy the whole directory, or rebuild`,
+    )
+  }
+
+  const config = await loadConfig(dist)
   const app = await createApp({
     machinesDir: resolve(dist, 'machines'),
     routesDir: resolve(dist, 'routes'),

package/src/config.ts

@@ -73,6 +73,20 @@ export interface StatorConfig {
     /** Dev inspector toolbar (`dev` only). Default: on. */
     inspector?: boolean
   }
+  /** Production build policy (`build` only). What lands in `dist/` is derived
+   *  from the app's own module graph, so neither field is normally needed. */
+  build?: {
+    /** Extra app-relative paths (directories or files) to copy into `dist/`.
+     *  The escape hatch for what no import graph can see — a directory reached
+     *  through a runtime-built path, say `readFile('data/' + name)`. Anything
+     *  imported, or opened via a literal `new URL(..., import.meta.url)`, is
+     *  already found. */
+    include?: string[]
+    /** What to do about an `import()` whose specifier no static analysis can
+     *  follow. `error` (default) fails the build naming each one, because the
+     *  build cannot know what such a call needs; `warn` ships anyway. */
+    untracedImports?: 'error' | 'warn'
+  }
   /** Origins allowed to make cross-site writes despite the CSRF guard — exact
    *  (`https://app.example.com`) or wildcard-subdomain (`https://*.example.com`).
    *  Same-origin and same-site writes are already allowed; this is for decoupled