@c9up/ream 0.2.23 → 0.2.25

package/src/env/loadEnvFiles.ts

@@ -1,41 +1,82 @@
 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'
 
 /**
- * Load `.env` files into `process.env` — the shared primitive behind both the
- * Ignitor (HTTP/console boot) and `Env.create()` (config/test flow), mirroring
- * AdonisJS which loads env in every flow.
+ * The `.env*` files that will be read, most-specific first.
  *
- * Order is most-specific-first and "already-present wins", so the shell / CI
- * always overrides the files. Missing files are skipped silently. Uses Node's
- * built-in parser — no dependency.
+ * 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 appRoot Directory URL the `.env*` files are resolved against.
- * @param options.skipEnvLocal Skip `.env.local` (the test flow does, so a
- *   developer's local overrides don't leak into tests).
+ * @param options.skipEnvLocal Skip `.env.local` — see {@link loadEnvFiles}.
  */
-export function loadEnvFiles(appRoot: URL, options: { skipEnvLocal?: boolean } = {}): void {
+export function envFileNames(options: { skipEnvLocal?: boolean } = {}): string[] {
   // 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 = [
+  return [
     nodeEnv ? `.env.${nodeEnv}.local` : null,
     options.skipEnvLocal ? null : '.env.local',
     nodeEnv ? `.env.${nodeEnv}` : null,
     '.env',
   ].filter((name): name is string => 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: URL): URL {
+  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}/`)
+}
 
-  for (const name of files) {
+/**
+ * Load `.env` files into `process.env` — the shared primitive behind both the
+ * Ignitor (HTTP/console boot) and `Env.create()` (config/test flow), mirroring
+ * AdonisJS which loads env in every flow.
+ *
+ * Order is most-specific-first and "already-present wins", so the shell / CI
+ * always overrides the files. Missing files are skipped silently. Uses Node's
+ * built-in parser — no dependency.
+ *
+ * @param appRoot Directory URL the `.env*` files are resolved against.
+ * @param options.skipEnvLocal Skip `.env.local` (the test flow does, so a
+ *   developer's local overrides don't leak into tests).
+ */
+export function loadEnvFiles(appRoot: URL, options: { skipEnvLocal?: boolean } = {}): void {
+  const directory = envDirectory(appRoot)
+  let found = false
+  for (const name of envFileNames(options)) {
     let contents: string
     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) continue
@@ -49,4 +90,18 @@ export function loadEnvFiles(appRoot: URL, options: { skipEnvLocal?: boolean } =
       })
     }
   }
+
+  // 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(', ')}`,
+    )
+  }
 }

package/src/hot.ts

@@ -5,132 +5,199 @@
  *
  *   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, pathToFileURL } from 'node:url'
+import { fullReloadNotice } from './dev/fullReload.js'
 import { hotReloadHappened } from './dev/hmr.js'
-import { type HotHookConfig, readHotHookConfig } from './dev/hotConfig.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
 
-interface HotHook {
-  init(options: {
-    rootDirectory: string
-    root?: string
-    boundaries?: string[]
-    restart?: string[]
-    ignore?: string[]
-    throwWhenBoundariesAreNotDynamicallyImported?: boolean
-    onFullReloadAsked?: () => void
-  }): Promise<void>
-}
+/** 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 { readFile } = await import('node:fs/promises')
-const { dirname, resolve } = await import('node:path')
+const packageJsonPath = resolvePath(process.cwd(), 'package.json')
+const root = dirname(packageJsonPath)
 
-const packageJsonPath = resolve(process.cwd(), 'package.json')
-let config: HotHookConfig = {}
+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.
 }
+const { boundaries = [], restart = [] } = config as { boundaries?: string[]; restart?: string[] }
 
-// `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: unknown): value is HotHook {
-  return (
-    typeof value === 'object' && value !== null && typeof Reflect.get(value, 'init') === 'function'
-  )
+// 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)),
+)
+
+/**
+ * `metaFiles` entries that asked for a restart.
+ *
+ * Non-module files the application owns — translations, view templates — live
+ * in `reamrc.ts` because the BUILD has to copy them. A change to one is
+ * invisible to the import graph, so the only way it can do anything in
+ * development is by being named here.
+ *
+ * `reloadServer: false` is the interesting default, and the one upstream picks
+ * for translations: the entry exists so the file ships, and an edit does NOT
+ * restart. NAMED DEVIATION — upstream still logs such a change, because its
+ * watcher covers the whole project anyway. This one watches a fixed list of
+ * directories on purpose (`resources/` belongs to the asset watcher, and a
+ * stylesheet edit must not restart the server), so a `false` entry is simply
+ * not watched. The observable behaviour is the same: nothing happens.
+ */
+async function readReloadPatterns(): Promise<string[]> {
+  try {
+    const rc = (await import(pathToFileURL(resolvePath(root, 'reamrc.ts')).href)) as {
+      default?: { metaFiles?: Array<{ pattern?: unknown; reloadServer?: unknown }> }
+    }
+    return (rc.default?.metaFiles ?? [])
+      .filter((entry) => entry.reloadServer === true && typeof entry.pattern === 'string')
+      .map((entry) => String(entry.pattern))
+  } catch {
+    // No rc file, or one that does not load. The server itself reports a broken
+    // rc far more clearly than the loader could, and a dev server that refuses
+    // to start because of a watch list helps nobody.
+    return []
+  }
 }
 
-// `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')
+const reloadPatterns = await readReloadPatterns()
 
-let hot: HotHook | undefined
-try {
-  const resolved = createRequire(packageJsonPath).resolve('hot-hook')
-  const module: unknown = 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()')
+/**
+ * The directory a pattern lives under — everything before its first wildcard.
+ *
+ * `resources/lang/**\/*.json` is watched as `resources/lang`. Watching the
+ * project root instead would pull in `node_modules` and the build output.
+ */
+function watchRootOf(pattern: string): string {
+  const segments = pattern.replace(/^\.\//, '').split('/')
+  const fixed: string[] = []
+  for (const segment of segments) {
+    if (/[*?{[]/.test(segment)) break
+    fixed.push(segment)
   }
-  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.',
-  )
+  // A pattern that is a bare glob has no directory to narrow to.
+  return fixed.slice(0, -1).join('/') || fixed.join('/')
 }
 
-// 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: unknown, ...rest: unknown[]): boolean => {
-  const type =
-    typeof message === 'object' && message !== null ? Reflect.get(message, 'type') : undefined
-  if (type === 'hot-hook:invalidated') {
-    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
+const relativeToRoot = (file: string): string => relative(root, file).replace(/\\/g, '/')
+const matchesBoundary = globMatcher(boundaries)
+const matchesRestartGlob = globMatcher([...restart, ...reloadPatterns])
+
+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: string | undefined
+    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: string): void {
+  // 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.
   }
-  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),
+watchProject({
+  root,
+  directories: [
+    ...WATCH_DIRS,
+    // Whatever a `reloadServer: true` entry named, and nothing else: the
+    // directories above are the ones the graph can reason about.
+    ...reloadPatterns.map(watchRootOf).filter((dir) => dir !== ''),
+  ],
+  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()
+    sayNow(`[ream] hot swap — ${relativeToRoot(file)}`)
+  },
 })

package/src/index.ts

@@ -385,4 +385,4 @@ export {
   StatsTracker,
 } from './scheduler/index.js'
 
-export const VERSION = '0.2.23'
+export const VERSION = '0.2.25'