@c9up/ream 0.2.22 → 0.2.24

package/dist/dev/hotGraph.js

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ */
+export class HotGraph {
+    #nodes = new Map();
+    #isBoundary;
+    #isRestart;
+    constructor(options) {
+        this.#isBoundary = options.isBoundary;
+        this.#isRestart = options.isRestart;
+    }
+    #node(file) {
+        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, importer) {
+        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) {
+        return this.#nodes.get(file)?.version ?? 0;
+    }
+    /** Whether the resolver has ever seen this file. */
+    knows(file) {
+        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) {
+        if (this.#isRestart(file))
+            return { kind: 'reload', file, reason: 'restart-list' };
+        if (!this.#nodes.has(file))
+            return { kind: 'ignore' };
+        const collected = new Set();
+        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] };
+    }
+}
+//# sourceMappingURL=hotGraph.js.map

package/dist/dev/hotGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hotGraph.js","sourceRoot":"","sources":["../../src/dev/hotGraph.ts"],"names":[],"mappings":"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"}

package/dist/dev/hotWatcher.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ */
+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 declare function watchProject(options: WatcherOptions): Watcher;
+//# sourceMappingURL=hotWatcher.d.ts.map

package/dist/dev/hotWatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hotWatcher.d.ts","sourceRoot":"","sources":["../../src/dev/hotWatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAA;IACZ,4DAA4D;IAC5D,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9B,0FAA0F;IAC1F,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,6DAA6D;IAC7D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACjC;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CA+C7D"}

package/dist/dev/hotWatcher.js

@@ -0,0 +1,72 @@
+/**
+ * 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 { 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 function watchProject(options) {
+    const watchers = [];
+    const pending = new Map();
+    const report = (file) => {
+        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();
+        },
+    };
+}
+//# sourceMappingURL=hotWatcher.js.map

package/dist/dev/hotWatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hotWatcher.js","sourceRoot":"","sources":["../../src/dev/hotWatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAkB,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEzC,0EAA0E;AAC1E,MAAM,SAAS,GAAG,EAAE,CAAA;AAiBpB,MAAM,UAAU,YAAY,CAAC,OAAuB;IAClD,MAAM,QAAQ,GAAgB,EAAE,CAAA;IAChC,MAAM,OAAO,GAAG,IAAI,GAAG,EAA0B,CAAA;IAEjD,MAAM,MAAM,GAAG,CAAC,IAAY,EAAQ,EAAE;QACpC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAClC,IAAI,QAAQ,KAAK,SAAS;YAAE,YAAY,CAAC,QAAQ,CAAC,CAAA;QAClD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;YACpB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;QACxB,CAAC,EAAE,SAAS,CAAC,CAAA;QACb,sEAAsE;QACtE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAA;QACf,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IAC1B,CAAC,CAAA;IAED,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QAC5C,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;QACjD,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CACX,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE;gBACpD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE;oBAAE,OAAM;gBACnD,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAA;YAC9B,CAAC,CAAC,CACH,CAAA;QACH,CAAC;QAAC,MAAM,CAAC;YACP,sEAAsE;YACtE,0DAA0D;QAC5D,CAAC;IACH,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QAC5C,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,4DAA4D;QAC9D,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,EAAE,GAAG,EAAE;YACV,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAA;YACzD,OAAO,CAAC,KAAK,EAAE,CAAA;YACf,KAAK,MAAM,OAAO,IAAI,QAAQ;gBAAE,OAAO,CAAC,KAAK,EAAE,CAAA;QACjD,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/env/loadEnvFiles.d.ts

@@ -1,3 +1,16 @@
+/**
+ * The `.env*` files that will be read, most-specific first.
+ *
+ * Exported because `@c9up/ream/hot` has to WATCH exactly this list: nothing
+ * imports an env file, so hot-hook's dependency tree never sees one and an
+ * edit to `.env` changed nothing at all. A second copy of the list in the
+ * loader entry would drift from this one the first time the naming changes.
+ *
+ * @param options.skipEnvLocal Skip `.env.local` — see {@link loadEnvFiles}.
+ */
+export declare function envFileNames(options?: {
+    skipEnvLocal?: boolean;
+}): string[];
 /**
  * Load `.env` files into `process.env` — the shared primitive behind both the
  * Ignitor (HTTP/console boot) and `Env.create()` (config/test flow), mirroring

package/dist/env/loadEnvFiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loadEnvFiles.d.ts","sourceRoot":"","sources":["../../src/env/loadEnvFiles.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,IAAI,CAgCzF"}
+{"version":3,"file":"loadEnvFiles.d.ts","sourceRoot":"","sources":["../../src/env/loadEnvFiles.ts"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,EAAE,CAW/E;AA4BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,GAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,IAAI,CAsCzF"}

package/dist/env/loadEnvFiles.js

@@ -1,8 +1,56 @@
 import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parseEnv } from 'node:util';
 import { interpolate } from './interpolate.js';
 import { normalizeNodeEnv } from './nodeEnv.js';
+/**
+ * The `.env*` files that will be read, most-specific first.
+ *
+ * Exported because `@c9up/ream/hot` has to WATCH exactly this list: nothing
+ * imports an env file, so hot-hook's dependency tree never sees one and an
+ * edit to `.env` changed nothing at all. A second copy of the list in the
+ * loader entry would drift from this one the first time the naming changes.
+ *
+ * @param options.skipEnvLocal Skip `.env.local` — see {@link loadEnvFiles}.
+ */
+export function envFileNames(options = {}) {
+    // Normalised, so `NODE_ENV=prod` loads `.env.production` — the file the
+    // deployment actually wrote — instead of looking for `.env.prod`.
+    const raw = normalizeNodeEnv(process.env.NODE_ENV);
+    const nodeEnv = raw === 'unknown' ? undefined : raw;
+    return [
+        nodeEnv ? `.env.${nodeEnv}.local` : null,
+        options.skipEnvLocal ? null : '.env.local',
+        nodeEnv ? `.env.${nodeEnv}` : null,
+        '.env',
+    ].filter((name) => name !== null);
+}
+/**
+ * Where the `.env*` files are read from.
+ *
+ * Normally beside the application, which is what `appRoot` names. A BUILT
+ * application moves: `start/env.js` sits in `dist/`, so `new URL('../',
+ * import.meta.url)` resolves there and the files at the project root become
+ * invisible — `ream start` died on a `.env` it was standing next to.
+ *
+ * `ENV_PATH` is AdonisJS's own variable for this, named and shaped the same
+ * way: a DIRECTORY to read the files from, as in
+ * `ENV_PATH=/etc/secrets node server.js`. An application moving over keeps
+ * whatever it already sets.
+ *
+ * It is also why the ordering rule stays here rather than in the CLI: node's
+ * `--env-file` applies files last-wins while this loader applies them
+ * most-specific-first, and a second copy of that would be one to keep in step
+ * forever.
+ */
+function envDirectory(appRoot) {
+    const override = process.env.ENV_PATH;
+    if (override === undefined || override.trim() === '')
+        return appRoot;
+    // A directory URL, so `new URL('.env', directory)` lands inside it rather
+    // than beside it.
+    return pathToFileURL(override.endsWith('/') ? override : `${override}/`);
+}
 /**
  * Load `.env` files into `process.env` — the shared primitive behind both the
  * Ignitor (HTTP/console boot) and `Env.create()` (config/test flow), mirroring
@@ -17,24 +65,17 @@ import { normalizeNodeEnv } from './nodeEnv.js';
  *   developer's local overrides don't leak into tests).
  */
 export function loadEnvFiles(appRoot, options = {}) {
-    // Normalised, so `NODE_ENV=prod` loads `.env.production` — the file the
-    // deployment actually wrote — instead of looking for `.env.prod`.
-    const raw = normalizeNodeEnv(process.env.NODE_ENV);
-    const nodeEnv = raw === 'unknown' ? undefined : raw;
-    const files = [
-        nodeEnv ? `.env.${nodeEnv}.local` : null,
-        options.skipEnvLocal ? null : '.env.local',
-        nodeEnv ? `.env.${nodeEnv}` : null,
-        '.env',
-    ].filter((name) => name !== null);
-    for (const name of files) {
+    const directory = envDirectory(appRoot);
+    let found = false;
+    for (const name of envFileNames(options)) {
         let contents;
         try {
-            contents = readFileSync(fileURLToPath(new URL(name, appRoot)), 'utf8');
+            contents = readFileSync(fileURLToPath(new URL(name, directory)), 'utf8');
         }
         catch {
             continue; // file absent — nothing to load
         }
+        found = true;
         const parsed = parseEnv(contents);
         for (const [key, value] of Object.entries(parsed)) {
             if (typeof value !== 'string' || process.env[key] !== undefined)
@@ -50,5 +91,16 @@ export function loadEnvFiles(appRoot, options = {}) {
             });
         }
     }
+    // Upstream raises when `ENV_PATH` names a place with no env file in it, and
+    // for the reason silence would be wrong: the variable is somebody saying
+    // where the file IS. A typo in the path would otherwise start a server on
+    // whatever defaults happened to be around, which is how a deployment reads
+    // its staging config in production and nobody finds out until later.
+    //
+    // Without `ENV_PATH` a missing file stays silent: an application may have
+    // none at all, and every value may come from the environment.
+    if (!found && process.env.ENV_PATH !== undefined && process.env.ENV_PATH.trim() !== '') {
+        throw new Error(`ENV_PATH points at ${process.env.ENV_PATH}, which holds none of ${envFileNames(options).join(', ')}`);
+    }
 }
 //# sourceMappingURL=loadEnvFiles.js.map

package/dist/env/loadEnvFiles.js.map

@@ -1 +1 @@
-{"version":3,"file":"loadEnvFiles.js","sourceRoot":"","sources":["../../src/env/loadEnvFiles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAE/C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAAC,OAAY,EAAE,UAAsC,EAAE;IACjF,wEAAwE;IACxE,kEAAkE;IAClE,MAAM,GAAG,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAClD,MAAM,OAAO,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAA;IACnD,MAAM,KAAK,GAAG;QACZ,OAAO,CAAC,CAAC,CAAC,QAAQ,OAAO,QAAQ,CAAC,CAAC,CAAC,IAAI;QACxC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY;QAC1C,OAAO,CAAC,CAAC,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI;QAClC,MAAM;KACP,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;IAEjD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,QAAgB,CAAA;QACpB,IAAI,CAAC;YACH,QAAQ,GAAG,YAAY,CAAC,aAAa,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;QACxE,CAAC;QAAC,MAAM,CAAC;YACP,SAAQ,CAAC,gCAAgC;QAC3C,CAAC;QACD,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAA;QACjC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS;gBAAE,SAAQ;YACzE,uEAAuE;YACvE,iEAAiE;YACjE,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE;gBAC7C,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;gBACrC,IAAI,WAAW,KAAK,SAAS;oBAAE,OAAO,WAAW,CAAA;gBACjD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAA;gBAC7B,OAAO,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAA;YAC5D,CAAC,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"loadEnvFiles.js","sourceRoot":"","sources":["../../src/env/loadEnvFiles.ts"],"names":[],"mappings":"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"}

package/dist/hot.d.ts

@@ -5,25 +5,22 @@
  *
  *   node --import @swc-node/register/esm-register --import @c9up/ream/hot bin/server.ts
  *
- * It is a thin shim over `hot-hook`, which does the actual work: it registers
- * an ESM loader that tracks the import graph, and when a file inside a declared
- * boundary changes it invalidates just that module instead of the process. The
- * `hotHook` key in the application's `package.json` configures it, exactly as
- * upstream reads it.
+ * It replaces a module that changed instead of the process that was serving it,
+ * so the container, the pools and the connections survive a save.
  *
- * NAMED DEVIATION — why this file exists at all.
+ * NAMED DEVIATION — this is ream's own, where AdonisJS uses `hot-hook`.
  *
- * Upstream's dev server is itself a Node process: it forks the app, so the two
- * talk over Node's IPC channel, and `hot-hook` reports a change it cannot swap
- * by calling `process.send({ type: 'hot-hook:full-reload' })`. Our dev server is
- * a Rust binary. A process it spawns has NO IPC channel, so `process.send` is
- * `undefined` and that message goes nowhere: the server would keep serving the
- * old module and say nothing.
+ * Upstream ships that package in its starter kit, which means every application
+ * installs it, and one created before the convention existed silently loses hot
+ * reloading. The parts that once justified a library are now in Node:
+ * `module.registerHooks` gives the import graph, `fs.watch` gives the changes.
+ * What is left is the decision of what to invalidate, which is this file and
+ * its three neighbours — and no entry in anyone's `package.json`.
  *
- * `hot.init()` takes an `onFullReloadAsked` callback for exactly this case, and
- * that is the whole of the shim: turn "I cannot hot-swap this" into an exit
- * code the Rust parent understands and restarts on. Everything else is
- * upstream's behaviour, unmodified.
+ * The graph comes from the resolver rather than from reading files: a resolve
+ * hook is handed the importer and the imported, which is exactly an edge, and
+ * it sees a dynamic import at the moment it happens rather than guessing at it
+ * from the source.
  */
 export {};
 //# sourceMappingURL=hot.d.ts.map

package/dist/hot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hot.d.ts","sourceRoot":"","sources":["../src/hot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}
+{"version":3,"file":"hot.d.ts","sourceRoot":"","sources":["../src/hot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}

package/dist/hot.js

@@ -5,108 +5,132 @@
  *
  *   node --import @swc-node/register/esm-register --import @c9up/ream/hot bin/server.ts
  *
- * It is a thin shim over `hot-hook`, which does the actual work: it registers
- * an ESM loader that tracks the import graph, and when a file inside a declared
- * boundary changes it invalidates just that module instead of the process. The
- * `hotHook` key in the application's `package.json` configures it, exactly as
- * upstream reads it.
+ * It replaces a module that changed instead of the process that was serving it,
+ * so the container, the pools and the connections survive a save.
  *
- * NAMED DEVIATION — why this file exists at all.
+ * NAMED DEVIATION — this is ream's own, where AdonisJS uses `hot-hook`.
  *
- * Upstream's dev server is itself a Node process: it forks the app, so the two
- * talk over Node's IPC channel, and `hot-hook` reports a change it cannot swap
- * by calling `process.send({ type: 'hot-hook:full-reload' })`. Our dev server is
- * a Rust binary. A process it spawns has NO IPC channel, so `process.send` is
- * `undefined` and that message goes nowhere: the server would keep serving the
- * old module and say nothing.
+ * Upstream ships that package in its starter kit, which means every application
+ * installs it, and one created before the convention existed silently loses hot
+ * reloading. The parts that once justified a library are now in Node:
+ * `module.registerHooks` gives the import graph, `fs.watch` gives the changes.
+ * What is left is the decision of what to invalidate, which is this file and
+ * its three neighbours — and no entry in anyone's `package.json`.
  *
- * `hot.init()` takes an `onFullReloadAsked` callback for exactly this case, and
- * that is the whole of the shim: turn "I cannot hot-swap this" into an exit
- * code the Rust parent understands and restarts on. Everything else is
- * upstream's behaviour, unmodified.
+ * The graph comes from the resolver rather than from reading files: a resolve
+ * hook is handed the importer and the imported, which is exactly an edge, and
+ * it sees a dynamic import at the moment it happens rather than guessing at it
+ * from the source.
  */
+import { existsSync, writeSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { registerHooks } from 'node:module';
+import { dirname, relative, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fullReloadNotice } from './dev/fullReload.js';
 import { hotReloadHappened } from './dev/hmr.js';
 import { readHotHookConfig } from './dev/hotConfig.js';
+import { globMatcher } from './dev/hotGlob.js';
+import { HotGraph } from './dev/hotGraph.js';
+import { watchProject } from './dev/hotWatcher.js';
+import { envFileNames } from './env/loadEnvFiles.js';
 /** Exit code meaning "restart me" — see `EXIT_RESTART` in the CLI's dev module. */
 const FULL_RELOAD_EXIT_CODE = 75;
-const { readFile } = await import('node:fs/promises');
-const { dirname, resolve } = await import('node:path');
-const packageJsonPath = resolve(process.cwd(), 'package.json');
+/** The query parameter that makes the loader fetch a module again. */
+const VERSION_PARAM = 'ream_hot';
+/** Directories a project keeps its own code in — the CLI watches the same list. */
+const WATCH_DIRS = ['app', 'bin', 'config', 'start', 'database', 'providers', 'commands'];
+const packageJsonPath = resolvePath(process.cwd(), 'package.json');
+const root = dirname(packageJsonPath);
 let config = {};
 try {
     config = readHotHookConfig(JSON.parse(await readFile(packageJsonPath, 'utf8')));
 }
 catch {
-    // No package.json, or unreadable: fall through to the conventional
-    // boundaries below rather than stopping dev over it.
+    // No package.json, or unreadable: a project with no boundaries declared gets
+    // a working server that restarts on change, which is the old behaviour.
 }
-// `hot-hook` is an optional peer, declared by the application because it is a
-// dev dependency there and has no business in a production install. Imported by
-// specifier built at runtime so a production bundle never resolves it.
-function isHotHook(value) {
-    return (typeof value === 'object' && value !== null && typeof Reflect.get(value, 'init') === 'function');
-}
-// `hot-hook` belongs to the APPLICATION: it is a dev dependency there and has
-// no business in a production install of the framework. So it is resolved from
-// the project directory rather than from this file — under pnpm's strict layout
-// a bare `import("hot-hook")` here looks inside @c9up/ream and finds nothing.
-// It is the same reason upstream passes `hot-hook/register` from the app's own
-// cwd instead of re-exporting it from the framework.
-const { createRequire } = await import('node:module');
-const { pathToFileURL } = await import('node:url');
-let hot;
-try {
-    const resolved = createRequire(packageJsonPath).resolve('hot-hook');
-    const module = await import(pathToFileURL(resolved).href);
-    const candidate = typeof module === 'object' && module !== null ? Reflect.get(module, 'hot') : undefined;
-    if (!isHotHook(candidate)) {
-        throw new Error('hot-hook did not expose a `hot` object with init()');
+const { boundaries = [], restart = [] } = config;
+// Env files are not modules: nothing imports one, so the graph never sees them
+// and an edit to `.env` did nothing at all — the values are read once, at boot.
+// They always restart.
+const restartFiles = new Set(envFileNames()
+    .map((name) => resolvePath(root, name))
+    .filter((file) => existsSync(file)));
+const relativeToRoot = (file) => relative(root, file).replace(/\\/g, '/');
+const matchesBoundary = globMatcher(boundaries);
+const matchesRestartGlob = globMatcher(restart);
+const graph = new HotGraph({
+    isBoundary: (file) => matchesBoundary(relativeToRoot(file)),
+    isRestart: (file) => restartFiles.has(file) || matchesRestartGlob(relativeToRoot(file)),
+});
+/**
+ * Track every edge the resolver reports, and hand back a versioned URL for a
+ * module that has been invalidated.
+ *
+ * The version travels in the URL because that is the only handle V8 offers: a
+ * module is keyed by its URL, so a different one is a different module. The
+ * parameter is stripped off the importer before delegating, or a relative
+ * specifier would be resolved against a URL that does not name a directory.
+ */
+registerHooks({
+    resolve(specifier, context, nextResolve) {
+        let parentURL = context.parentURL;
+        let parentPath;
+        if (typeof parentURL === 'string' && parentURL.startsWith('file:')) {
+            const url = new URL(parentURL);
+            if (url.searchParams.has(VERSION_PARAM)) {
+                url.searchParams.delete(VERSION_PARAM);
+                parentURL = url.href;
+            }
+            parentPath = fileURLToPath(url);
+        }
+        const result = nextResolve(specifier, { ...context, parentURL });
+        if (!result.url.startsWith('file:'))
+            return result;
+        const resolved = new URL(result.url);
+        resolved.searchParams.delete(VERSION_PARAM);
+        const file = fileURLToPath(resolved);
+        graph.link(file, parentPath);
+        const version = graph.version(file);
+        if (version === 0)
+            return result;
+        resolved.searchParams.set(VERSION_PARAM, String(version));
+        return { ...result, url: resolved.href };
+    },
+});
+/** Print a line that must survive the exit on the very next statement. */
+function sayNow(line) {
+    // Synchronously: a piped stdout — what `ream dev` hands this process when it
+    // runs an asset watcher alongside — is asynchronous, and the line would be
+    // dropped on the way out.
+    try {
+        writeSync(1, `${line}\n`);
+    }
+    catch {
+        // The parent can close the pipe first on Ctrl-C. Losing the line is fine.
     }
-    hot = candidate;
-}
-catch (error) {
-    // Loud, and it names the fix. Silence here would start a perfectly healthy
-    // server that never picks up an edit, which reads as "HMR is broken" rather
-    // than "HMR is not installed".
-    //
-    // It does NOT throw: a dev server that refuses to start is worse than one
-    // without hot reloading, and the CLI only loads this file when it has
-    // already seen hot-hook in the project — so reaching here means it went
-    // missing under a running session.
-    console.error(`[ream] hot module replacement is unavailable: ${error instanceof Error ? error.message : String(error)}\n` +
-        '[ream] Install it with: pnpm add -D hot-hook, then restart `ream dev`.\n' +
-        '[ream] Until then the server runs, but an edit will not be picked up.');
 }
-// Impersonate the IPC channel upstream's dev server provides.
-//
-// hot-hook reports BOTH of its outcomes through `process.send`: a change it
-// swapped in place (`hot-hook:invalidated`) and one it could not
-// (`hot-hook:full-reload`). Under a Node parent that function exists and both
-// arrive; under our Rust parent it is `undefined` and both are dropped —
-// `onFullReloadAsked` alone recovers only half of that, leaving a hot swap
-// invisible to the very process it happened in, and so to the browser.
-//
-// This is not a trick played on hot-hook: it is exactly the contract it
-// expects, provided by us instead of by Node.
-const previousSend = process.send;
-process.send = (message, ...rest) => {
-    const type = typeof message === 'object' && message !== null ? Reflect.get(message, 'type') : undefined;
-    if (type === 'hot-hook:invalidated') {
+watchProject({
+    root,
+    directories: WATCH_DIRS,
+    files: [...restartFiles].map((file) => relative(root, file)),
+    onChange: (file) => {
+        const decision = graph.decide(file);
+        if (decision.kind === 'ignore')
+            return;
+        if (decision.kind === 'reload') {
+            sayNow(fullReloadNotice(decision.file, decision.reason, relativeToRoot));
+            // Exiting on a known code is how the Rust parent learns it must restart —
+            // see `EXIT_RESTART` in the CLI's dev module.
+            process.exit(FULL_RELOAD_EXIT_CODE);
+        }
+        // The router caches a promoted controller per route, and the kernel drops
+        // that cache when this counter moves. Without it the swap happens and the
+        // process keeps serving the class it promoted: a stable PID and stale
+        // output, which is exactly how it was first reported.
         hotReloadHappened();
-    }
-    // If a real channel ever exists (embedded under a Node supervisor) it still
-    // gets its message: this observes, it does not intercept.
-    if (typeof previousSend === 'function') {
-        return Reflect.apply(previousSend, process, [message, ...rest]) === true;
-    }
-    return true;
-};
-await hot?.init({
-    ...config,
-    rootDirectory: dirname(packageJsonPath),
-    root: config.root ? resolve(dirname(packageJsonPath), config.root) : undefined,
-    // Exiting on a known code is how the Rust parent learns it must restart —
-    // see `EXIT_RESTART` in the CLI's dev module.
-    onFullReloadAsked: () => process.exit(FULL_RELOAD_EXIT_CODE),
+        sayNow(`[ream] hot swap — ${relativeToRoot(file)}`);
+    },
 });
 //# sourceMappingURL=hot.js.map