@c9up/ream 0.2.23 → 0.2.25

package/src/Codemods.ts

@@ -3,6 +3,7 @@ import * as path from 'node:path'
 
 export interface Codemods {
   addProvider(importPath: string): Promise<void>
+  addMetaFile(pattern: string, reloadServer?: boolean): Promise<void>
   addEnvVars(vars: Record<string, string>): Promise<void>
   writeFile(filePath: string, content: string, options?: { force?: boolean }): Promise<void>
   registerCommand(importPath: string): Promise<void>
@@ -120,6 +121,58 @@ export function createCodemods(options?: { force?: boolean; cwd?: string }): Cod
       fs.writeFileSync(rcPath, content)
     },
 
+    /**
+     * Record a non-module file the application owns.
+     *
+     * A package calls this from `configure()` so its files reach the build:
+     * `addMetaFile('resources/lang/**\/*.json', false)`. The second argument
+     * is DELIBERATELY explicit at every call site — whether an edit costs a
+     * development restart is the decision the entry exists to record.
+     *
+     * Same regex codemod as `addProvider`, and the same limits: a `metaFiles`
+     * assembled by a spread or extracted into a `const` above the config is not
+     * rewritten. The block is created when absent, which `addProvider` cannot
+     * do — `providers` is always there, `metaFiles` usually is not.
+     */
+    async addMetaFile(pattern: string, reloadServer = false): Promise<void> {
+      const rcPath = path.join(root, 'reamrc.ts')
+      if (!fs.existsSync(rcPath)) {
+        throw new Error(
+          `[configure] reamrc.ts not found — cannot register meta file ${pattern}. Run 'ream new' first.`,
+        )
+      }
+      assertCanonicallyInside(root, rcPath, 'reamrc.ts')
+
+      let content = fs.readFileSync(rcPath, 'utf8')
+      // Dedup on the PATTERN alone: the same glob registered twice with
+      // different flags is a contradiction, and the first one wins rather than
+      // both being written.
+      if (content.includes(`'${pattern}'`) || content.includes(`"${pattern}"`)) return
+
+      const eol = detectLineEnding(content)
+      const entry = `    { pattern: '${pattern}', reloadServer: ${reloadServer} },`
+
+      const existing = /metaFiles\s*:\s*(?:\/\*[\s\S]*?\*\/\s*)?\[/.exec(content)
+      if (existing !== null) {
+        const insertAt = existing.index + existing[0].length
+        content = `${content.slice(0, insertAt)}${eol}${entry}${content.slice(insertAt)}`
+        fs.writeFileSync(rcPath, content)
+        return
+      }
+
+      // No block yet — open one beside `providers`, which every rc file has.
+      const providers = /providers\s*:\s*(?:\/\*[\s\S]*?\*\/\s*)?\[/.exec(content)
+      if (providers === null) {
+        throw new Error(
+          `[configure] Could not find 'providers: [' in reamrc.ts — meta file ${pattern} not added. Check your reamrc.ts format.`,
+        )
+      }
+      const blockAt = providers.index
+      const block = `metaFiles: [${eol}${entry}${eol}  ],${eol}  `
+      content = `${content.slice(0, blockAt)}${block}${content.slice(blockAt)}`
+      fs.writeFileSync(rcPath, content)
+    },
+
     async addEnvVars(vars: Record<string, string>): Promise<void> {
       const envPath = path.join(root, '.env')
       // A symlinked .env must not redirect the write outside the root.

package/src/Ignitor.ts

@@ -17,7 +17,7 @@ import { Application } from './Application.js'
 import type { Console } from './console/Console.js'
 import type { CommandLoader, Kernel as ConsoleKernelInstance } from './console/Kernel.js'
 import { type CommandClass, isCommandClass } from './console/types.js'
-import { HMR_PATH, hmrClientScript, hmrToken } from './dev/hmr.js'
+import { hmrClientScript, hmrEndpoint } from './dev/hmr.js'
 import type { DirectoriesNode } from './directories.js'
 import type { ErrorEvent } from './ErrorBoundary.js'
 import { ErrorBoundary } from './ErrorBoundary.js'
@@ -63,6 +63,18 @@ import type { AppEnvironment } from './Application.js'
 /**
  * Reamrc config — like AdonisJS adonisrc.ts with defineConfig().
  */
+/** A command the CLI runs on the application's behalf. */
+export interface AssetsCommand {
+  command: string
+  args?: string[]
+}
+
+/** What `assets` declares: a watcher for `dev`, a one-shot for `build`. */
+export interface AssetsConfig {
+  devServer?: AssetsCommand
+  build?: AssetsCommand
+}
+
 export interface ReamrcConfig {
   providers?: Array<
     | (() => Promise<{ default: new (app: AppContext) => ProviderContract }>)
@@ -113,6 +125,47 @@ export interface ReamrcConfig {
   }
   /** Test suites and runner settings — the `tests` block of adonisrc.ts. */
   tests?: TestsConfig
+  /**
+   * The asset pipeline `ream dev` and `ream build` drive alongside the app.
+   *
+   * `devServer` is started beside the development server and killed with it;
+   * `build` runs once, before the TypeScript build, and a non-zero exit stops
+   * the build rather than shipping a bundle nobody rebuilt.
+   *
+   * Declared here because the CLI already reads it: without the type an app
+   * that configures its asset build gets an excess-property error from
+   * `defineConfig`, which is a strange way to learn that the option exists.
+   */
+  assets?: AssetsConfig
+  /**
+   * Files that are not modules but belong to the application.
+   *
+   * Translations, view templates, a mail signature: the build has no reason to
+   * know about them, and without being told it ships a `dist/` that boots and
+   * then cannot find them. Every pattern here is copied into the build output,
+   * keeping its path relative to the project root.
+   *
+   * `reloadServer` decides what a change does in DEVELOPMENT, and the default
+   * is the interesting half. Upstream registers translations with `false` —
+   * the files are watched so the build copies them, and an edit does NOT
+   * restart the server. A package that genuinely needs a restart asks for one
+   * by passing `true`.
+   */
+  metaFiles?: MetaFileConfig[]
+}
+
+/**
+ * One `metaFiles` entry.
+ *
+ * `reloadServer` is required rather than defaulted: whether an edit costs a
+ * restart is the whole decision this entry exists to record, and a default
+ * would let it be made by accident.
+ */
+export interface MetaFileConfig {
+  /** Glob, relative to the project root — `resources/lang/**\/*.json`. */
+  pattern: string
+  /** Restart the development server when a matching file changes. */
+  reloadServer: boolean
 }
 
 /** One test suite, as declared in the rc file (AdonisJS `tests.suites[]`). */
@@ -685,7 +738,6 @@ export class Ignitor {
     // anything. Registered in `ready()` it came up after the server was already
     // serving, so a page loaded in that window polled a route that did not
     // exist yet.
-    this.#registerDevReloadRoute()
 
     // Providers start BEFORE the preload files, matching upstream's warm-up
     // order (`providers.start()` → `starting` hooks → preloads). A preload is
@@ -773,7 +825,10 @@ export class Ignitor {
         container: this.#app.container,
         exceptionHandler:
           this.#server.getErrorHandler() ?? new ExceptionHandler(!this.#app.inProduction),
-        serverMiddleware: this.#server.getServerMiddleware(),
+        serverMiddleware: [
+          ...this.#frameworkServerMiddleware(),
+          ...this.#server.getServerMiddleware(),
+        ],
         routerMiddleware: this.#router.getRouterMiddleware(),
         devReloadScript: this.#devReloadScript(),
         onError: (error, ctx) => {
@@ -1264,19 +1319,18 @@ export class Ignitor {
   }
 
   /**
-   * Serve the token the injected script polls.
+   * The server middleware the framework itself contributes, ahead of the
+   * application's.
    *
-   * Registered on the router in development, next to the application's own
-   * routes, so it goes through the same server as everything else. Plain text
-   * and uncached: it is read once a second and its whole content is the answer.
+   * Only the hot-reload token, and only in development. It answers first
+   * because the poll arrives once a second per open tab and its content
+   * depends on nothing — no user, no session, no body. Behind an application's
+   * middleware it paid for the whole stack each time, which for anything that
+   * resolves a user from a cookie meant a `SELECT` per second for a string
+   * holding a process id and a counter.
    */
-  #registerDevReloadRoute(): void {
-    if (!this.isDevMode()) return
-    this.#router.get(HMR_PATH, ({ response }) => {
-      response.header('cache-control', 'no-store')
-      response.header('content-type', 'text/plain; charset=utf-8')
-      response.send(hmrToken())
-    })
+  #frameworkServerMiddleware(): MiddlewareFunction[] {
+    return this.isDevMode() ? [hmrEndpoint()] : []
   }
 
   getPhase(): string {

package/src/dev/fullReload.ts

@@ -0,0 +1,34 @@
+/**
+ * Saying why the process is about to restart.
+ *
+ * A change the loader cannot swap in place becomes an exit code the dev server
+ * restarts on. From the terminal the only trace of it was the boot banner
+ * printing itself a second time — which reads as a server rebooting on its own
+ * rather than as a file that fell outside `hotHook.boundaries`. Upstream's dev
+ * server logs the file it reloaded for; this is that line.
+ *
+ * Kept apart from the loader entry so it can be tested: importing that entry
+ * registers module hooks, which a test cannot undo.
+ */
+
+/** Why a change could not be swapped in place. */
+export type ReloadReason = 'outside-boundaries' | 'restart-list'
+
+/**
+ * The line to print before restarting.
+ *
+ * @param file - absolute path of the file that changed.
+ * @param relativise - turns it into the path the editor shows, so the line can
+ *   be read at a glance.
+ */
+export function fullReloadNotice(
+  file: string,
+  reason: ReloadReason,
+  relativise: (file: string) => string,
+): string {
+  const why =
+    reason === 'restart-list'
+      ? ' (it is on `hotHook.restart`, which always restarts)'
+      : ' (nothing importing it is inside a `hotHook.boundaries` entry, so it could not be swapped)'
+  return `[ream] full reload — ${relativise(file)}${why}`
+}

package/src/dev/hmr.ts

@@ -45,6 +45,90 @@ function holder(): CounterHolder {
 export function hotReloadHappened(): void {
   const store = holder()
   store[COUNTER] = (store[COUNTER] ?? 0) + 1
+  notifyClients()
+}
+
+/**
+ * The dev clients currently listening.
+ *
+ * A `Set` and not a count: each entry is pushed to on a swap, and dropped when
+ * the tab closes. `unknown`-typed on purpose — this module must not import the
+ * HTTP layer, which imports it back.
+ */
+interface DevClient {
+  send: (event: string, data: unknown) => Promise<boolean>
+  onClose: (callback: () => void) => void
+}
+
+const clients = new Set<DevClient>()
+
+/** The event name the injected script listens for. */
+const HMR_EVENT = 'ream:hmr'
+
+/**
+ * Answer the dev client BEFORE any application middleware runs, and PUSH.
+ *
+ * Two problems, one change.
+ *
+ * It used to be an ordinary route polled once a second, per open tab, and a
+ * route runs the whole middleware stack. An application that resolves a user
+ * from a session cookie therefore ran `SELECT * FROM users` once a second for
+ * a response whose entire content is a process id and a counter, and which
+ * depends on no user, no session and no body.
+ *
+ * It is a stream now, so the cost is paid ONCE per tab instead of once a
+ * second, and a change reaches the browser immediately rather than up to a
+ * second later. Upstream gets the same thing from Vite's websocket; this needs
+ * no bundler, because the server already speaks SSE.
+ *
+ * Registered FIRST rather than merely outside the router: middleware that
+ * authenticates lives at either tier, and an application is free to put it in
+ * `server.use([...])` — many do, because it must run before routing.
+ *
+ * Development only. In production nothing injects the script and nothing
+ * registers this.
+ */
+export function hmrEndpoint(): (
+  ctx: {
+    request: { url: () => string }
+    response: { sse: () => Promise<DevClient> }
+  },
+  next: () => Promise<void>,
+) => Promise<void> {
+  return async (ctx, next) => {
+    // `url()` carries the query string; a client may append a cache-buster.
+    const path = ctx.request.url().split('?')[0]
+    if (path !== HMR_PATH) {
+      await next()
+      return
+    }
+
+    let stream: DevClient
+    try {
+      stream = await ctx.response.sse()
+    } catch {
+      // A host without the streaming NAPI — a mock server in a test, say.
+      // Losing the reload is fine; failing the request is not.
+      await next()
+      return
+    }
+
+    clients.add(stream)
+    stream.onClose(() => clients.delete(stream))
+    // Immediately, so a tab that connects after a restart compares against the
+    // CURRENT token rather than waiting for the next swap to learn anything.
+    await stream.send(HMR_EVENT, hmrToken())
+  }
+}
+
+/** Tell every open tab the token moved. */
+function notifyClients(): void {
+  const token = hmrToken()
+  for (const client of clients) {
+    // Detached: a swap must not wait on a socket, and a dead one is dropped by
+    // its own close handler.
+    void client.send(HMR_EVENT, token).catch(() => clients.delete(client))
+  }
 }
 
 /** How many hot swaps this process has seen. */
@@ -63,10 +147,15 @@ export function hmrToken(): string {
 /**
  * The script injected into HTML pages in dev.
  *
- * It reloads when the token changes, NOT when the request fails: a server that
- * is restarting is unreachable for a moment, and reloading then would only show
- * the browser's error page. It waits for an answer, and the answer carries a
- * new boot id.
+ * An `EventSource`, not a poll. The server pushes the token, so a change
+ * reaches the page immediately and an idle tab costs one open connection
+ * rather than a request per second through the whole middleware stack.
+ *
+ * It reloads when the token CHANGES, never when the connection fails: a
+ * restarting server is unreachable for a moment, and reloading then would only
+ * show the browser's error page. `EventSource` reconnects on its own, and the
+ * server greets the new connection with its token — which after a restart is a
+ * different boot id, so the reload happens then, once the server can serve it.
  */
 export function hmrClientScript(nonce?: string): string {
   // A nonce-based CSP — which the scaffold ships, via `@c9up/blackhole` —
@@ -75,9 +164,13 @@ export function hmrClientScript(nonce?: string): string {
   // are escaped because a nonce is generated, not user input, but a broken
   // attribute would silently disable the tag rather than fail loudly.
   const attribute = nonce === undefined ? '' : ` nonce="${nonce.replace(/"/g, '&quot;')}"`
-  // A failed poll RETRIES. Returning on `!r.ok` stopped the loop for good, so a
-  // page opened in the window before the endpoint is mounted — or during any
-  // blip — never reloaded again for the life of that tab, which looks exactly
-  // like the feature not working.
-  return `<script${attribute}>(()=>{let t=null;const p=${JSON.stringify(HMR_PATH)};const tick=async()=>{try{const r=await fetch(p,{cache:'no-store'});if(r.ok){const n=(await r.text()).trim();if(t===null){t=n}else if(n!==t){location.reload();return}}}catch(e){}setTimeout(tick,1000)};tick()})()</script>`
+  // `addEventListener(HMR_EVENT)`, NOT `onmessage`: the stream names its
+  // events, and `onmessage` fires only for unnamed ones — a client wired that
+  // way receives nothing at all, silently, which is a mistake this codebase
+  // has already made once with relay.
+  return `<script${attribute}>(()=>{let t=null;const s=new EventSource(${JSON.stringify(
+    HMR_PATH,
+  )});s.addEventListener(${JSON.stringify(
+    HMR_EVENT,
+  )},e=>{let n;try{n=JSON.parse(e.data)}catch(_){n=e.data}if(t===null){t=n}else if(n!==t){s.close();location.reload()}})})()</script>`
 }

package/src/dev/hotGlob.ts

@@ -0,0 +1,91 @@
+/**
+ * Matching the globs an application declares under `hotHook.boundaries`.
+ *
+ * A dependency for this would be `picomatch` plus `fast-glob`, which is two
+ * packages and their trees for the three wildcards these patterns actually use.
+ * The patterns are written by hand in a `package.json` and read once at boot;
+ * what they need is to be right, not fast.
+ *
+ * The dialect is the one those files already use:
+ *   *      any run of characters inside one path segment
+ *   **     any number of segments, including none
+ *   ?      exactly one character inside a segment
+ *   {a,b}  either alternative
+ *
+ * The brace form is the one a `metaFiles` entry uses —
+ * `resources/lang/**\/*.{json,yaml,yml}` — and it has to be understood on this
+ * side too: the CLI matches the same pattern when it copies those files into
+ * the build, and a dialect that differed between the two would let an entry
+ * copy at build time and never fire in development, or the reverse.
+ *
+ * A leading `./` is optional, and matching is done on POSIX-shaped paths
+ * relative to the project root, so a Windows checkout and a Linux one read the
+ * same pattern the same way.
+ */
+
+/** Turn one glob into an anchored regular expression. */
+export function globToRegExp(pattern: string): RegExp {
+  const cleaned = pattern.replace(/^\.\//, '')
+  let out = ''
+  for (let i = 0; i < cleaned.length; i += 1) {
+    const char = cleaned[i]
+    if (char === '*') {
+      if (cleaned[i + 1] === '*') {
+        // `**/` swallows the separator so that `a/**/b` also matches `a/b`;
+        // a trailing `**` simply matches the rest.
+        i += 1
+        if (cleaned[i + 1] === '/') {
+          i += 1
+          out += '(?:[^/]+/)*'
+        } else {
+          out += '.*'
+        }
+        continue
+      }
+      out += '[^/]*'
+      continue
+    }
+    if (char === '?') {
+      out += '[^/]'
+      continue
+    }
+    if (char === '{') {
+      const close = cleaned.indexOf('}', i)
+      if (close !== -1) {
+        // Alternatives are literal text, never nested globs: that is the whole
+        // of the form these patterns use, and a recursive reading would accept
+        // shapes the CLI's matcher does not.
+        const options = cleaned
+          .slice(i + 1, close)
+          .split(',')
+          .map((option) => option.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+        out += `(?:${options.join('|')})`
+        i = close
+        continue
+      }
+      // Unclosed: read literally rather than throwing. A pattern is a string in
+      // a config file, and a malformed one should match nothing, not take the
+      // dev server down at boot.
+    }
+    // Everything else is literal, including the characters a regular
+    // expression would otherwise read as syntax.
+    out += (char ?? '').replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`^${out}$`)
+}
+
+/**
+ * A matcher over several globs.
+ *
+ * Returns a predicate rather than a class: the graph takes a function, and a
+ * project with no boundaries gets one that is honestly always false instead of
+ * an empty object that has to be checked for.
+ */
+export function globMatcher(patterns: readonly string[]): (path: string) => boolean {
+  const expressions = patterns.map(globToRegExp)
+  if (expressions.length === 0) return () => false
+  return (path: string) => {
+    const normalised = path.replace(/\\/g, '/').replace(/^\.\//, '')
+    return expressions.some((expression) => expression.test(normalised))
+  }
+}

package/src/dev/hotGraph.ts

@@ -0,0 +1,109 @@
+/**
+ * The import graph a hot reload reasons over, and what it decides.
+ *
+ * Owned here rather than taken from `hot-hook`, which used to do this job. The
+ * package is 655 lines and four npm dependencies, and it had to be installed by
+ * every application because a dev-only loader has no business in a production
+ * install of the framework — so a project created before that convention simply
+ * lost hot reloading and was told nothing. The part that genuinely needs a
+ * library is the part Node now provides itself: `module.registerHooks` for the
+ * graph, `fs.watch` for the changes.
+ *
+ * NO node_modules dependency, deliberately: everything below is arithmetic on
+ * paths.
+ *
+ * The graph is built by the resolver as the program runs, never by reading
+ * files. A `resolve` hook is handed the importer and the imported, which is
+ * exactly an edge, and it sees dynamic imports as they happen — a static parse
+ * of the source could only guess at those.
+ */
+
+/** A module's place in the graph: who imports it, and which version is live. */
+interface Node {
+  /** Modules that imported this one. The graph is walked upward, so this is the direction stored. */
+  readonly importers: Set<string>
+  /** Bumped on invalidation; appended to the URL so the loader fetches the file again. */
+  version: number
+}
+
+/** What a change to one file means. */
+export type Decision =
+  | { kind: 'swap'; invalidated: string[] }
+  | { kind: 'reload'; file: string; reason: 'outside-boundaries' | 'restart-list' }
+  | { kind: 'ignore' }
+
+export class HotGraph {
+  readonly #nodes = new Map<string, Node>()
+  readonly #isBoundary: (file: string) => boolean
+  readonly #isRestart: (file: string) => boolean
+
+  constructor(options: {
+    isBoundary: (file: string) => boolean
+    isRestart: (file: string) => boolean
+  }) {
+    this.#isBoundary = options.isBoundary
+    this.#isRestart = options.isRestart
+  }
+
+  #node(file: string): Node {
+    let node = this.#nodes.get(file)
+    if (node === undefined) {
+      node = { importers: new Set(), version: 0 }
+      this.#nodes.set(file, node)
+    }
+    return node
+  }
+
+  /** Record that `importer` imported `file`. Called from the resolve hook. */
+  link(file: string, importer: string | undefined): void {
+    const node = this.#node(file)
+    if (importer !== undefined && importer !== file) node.importers.add(importer)
+  }
+
+  /** The version to hang off the URL, or 0 while the module has never been invalidated. */
+  version(file: string): number {
+    return this.#nodes.get(file)?.version ?? 0
+  }
+
+  /** Whether the resolver has ever seen this file. */
+  knows(file: string): boolean {
+    return this.#nodes.has(file)
+  }
+
+  /**
+   * What to do about `file` having changed.
+   *
+   * Walks up from the changed file collecting what has to be re-imported, and
+   * stops at each boundary: a boundary is imported dynamically, so the next
+   * import of it re-resolves, and with it everything below that was collected
+   * on the way. A path that reaches a module nobody imports without crossing a
+   * boundary cannot be re-imported by anyone, and that is a full reload.
+   *
+   * Deciding before invalidating matters: a decision that turns out to be a
+   * full reload must leave no version bumped behind, or a later swap would
+   * hand the caller a URL for a module the process never re-imported.
+   */
+  decide(file: string): Decision {
+    if (this.#isRestart(file)) return { kind: 'reload', file, reason: 'restart-list' }
+    if (!this.#nodes.has(file)) return { kind: 'ignore' }
+
+    const collected = new Set<string>()
+    const queue = [file]
+    while (queue.length > 0) {
+      const current = queue.pop()
+      if (current === undefined || collected.has(current)) continue
+      collected.add(current)
+      // A boundary is where the walk stops: whoever imports it does so
+      // dynamically and will ask for it again.
+      if (this.#isBoundary(current)) continue
+      const importers = this.#nodes.get(current)?.importers
+      if (importers === undefined || importers.size === 0) {
+        return { kind: 'reload', file, reason: 'outside-boundaries' }
+      }
+      for (const importer of importers) queue.push(importer)
+    }
+
+    for (const path of collected) this.#node(path).version += 1
+    return { kind: 'swap', invalidated: [...collected] }
+  }
+}

package/src/dev/hotWatcher.ts

@@ -0,0 +1,89 @@
+/**
+ * Watching the project for the changes a hot reload reacts to.
+ *
+ * `fs.watch` with `recursive: true`, which Node implements on Linux, macOS and
+ * Windows alike — the reason a watcher used to be a dependency here, and is not
+ * any more.
+ *
+ * Two behaviours are worth stating because they are not obvious from the API:
+ *
+ * A save is rarely one event. Editors write, rename and touch, and a single
+ * Ctrl-S can arrive as several notifications for the same file within a few
+ * milliseconds. Each one would walk the graph and bump a version, so they are
+ * coalesced.
+ *
+ * `ream dev` also watches from the outside, in Rust. That is not a duplicate:
+ * this watcher dies with the process it lives in, so a server that crashed on a
+ * syntax error has nothing left to notice the fix. The outer one covers exactly
+ * that window, and hands back over by restarting the process.
+ */
+
+import { type FSWatcher, watch } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+/** How long to wait for a save to finish arriving before acting on it. */
+const SETTLE_MS = 40
+
+export interface WatcherOptions {
+  /** Project root; every reported path is absolute, resolved against it. */
+  root: string
+  /** Directories under the root to watch, when they exist. */
+  directories: readonly string[]
+  /** Individual files to watch — env files sit at the root, so no directory covers them. */
+  files: readonly string[]
+  /** Called once per settled change, with an absolute path. */
+  onChange: (file: string) => void
+}
+
+export interface Watcher {
+  close: () => void
+}
+
+export function watchProject(options: WatcherOptions): Watcher {
+  const watchers: FSWatcher[] = []
+  const pending = new Map<string, NodeJS.Timeout>()
+
+  const report = (file: string): void => {
+    const existing = pending.get(file)
+    if (existing !== undefined) clearTimeout(existing)
+    const timer = setTimeout(() => {
+      pending.delete(file)
+      options.onChange(file)
+    }, SETTLE_MS)
+    // The dev server must still be able to exit while a save is settling.
+    timer.unref?.()
+    pending.set(file, timer)
+  }
+
+  for (const directory of options.directories) {
+    const absolute = resolve(options.root, directory)
+    try {
+      watchers.push(
+        watch(absolute, { recursive: true }, (_event, name) => {
+          if (typeof name !== 'string' || name === '') return
+          report(join(absolute, name))
+        }),
+      )
+    } catch {
+      // A directory this project does not have is not an error: the list is
+      // the framework's conventional layout, not a requirement.
+    }
+  }
+
+  for (const file of options.files) {
+    const absolute = resolve(options.root, file)
+    try {
+      watchers.push(watch(absolute, () => report(absolute)))
+    } catch {
+      // Same: a `.env` that does not exist is simply not watched.
+    }
+  }
+
+  return {
+    close: () => {
+      for (const timer of pending.values()) clearTimeout(timer)
+      pending.clear()
+      for (const watcher of watchers) watcher.close()
+    },
+  }
+}