@c9up/ream 0.2.16 → 0.2.18

package/src/Ignitor.ts

@@ -17,6 +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 type { DirectoriesNode } from './directories.js'
 import type { ErrorEvent } from './ErrorBoundary.js'
 import { ErrorBoundary } from './ErrorBoundary.js'
@@ -31,6 +32,7 @@ import type { HttpKernelRequest, HttpKernelResponse } from './HttpKernel.js'
 import { createHttpKernel } from './HttpKernel.js'
 import { ExceptionHandler } from './http/Exception.js'
 import { type ChildLoggerSource, HttpContext } from './http/HttpContext.js'
+import { RequestValidator } from './http/RequestValidator.js'
 import type { MiddlewareFunction } from './middleware/Pipeline.js'
 import { MiddlewareRegistry } from './middleware/Pipeline.js'
 import { MigrationRegistry } from './migrations/MigrationRegistry.js'
@@ -325,6 +327,11 @@ export class Ignitor {
     // must stay agnostic reaches it through the container instead of importing
     // ream at runtime.
     this.#app.container.singleton('HttpContext', () => HttpContext)
+    // The seam a package installs its per-request messages provider or error
+    // reporter on. Bound rather than imported so an i18n provider can reach it
+    // without depending on ream — which is the only reason it is a container
+    // token and not just an import.
+    this.#app.container.singleton('requestValidator', () => RequestValidator)
     // `appRoot` is the URL passed to `new Ignitor(new URL('../', import.meta.url))`.
     // Providers resolve it through the container so they can interpret
     // relative paths in config files (e.g. `pages.root: './resources/pages'`)
@@ -659,6 +666,12 @@ export class Ignitor {
   }
 
   async #phaseStart(): Promise<void> {
+    // What the injected reload script polls, mounted BEFORE the socket accepts
+    // 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
     // where an app writes its routes and kernel, and those reach for services
@@ -668,18 +681,28 @@ export class Ignitor {
       await callProviderPhase(provider, 'start')
     }
 
-    // Import preload files (routes.ts, kernel.ts, etc.)
+    // Import preload files (routes.ts, kernel.ts, etc.).
+    //
+    // Filtered on the environment first, then imported TOGETHER — upstream's
+    // `PreloadsManager.import()` is a filter followed by one `Promise.all`, and
+    // this used to walk them one at a time.
+    //
+    // The consequence is worth knowing: evaluation order between two preload
+    // files is now whichever finishes loading first, so an application cannot
+    // rely on the array's order to decide which of two overlapping routes
+    // answers. Work that must be ordered belongs inside ONE preload, where the
+    // order is the file's own — which is how upstream applications are written.
     if (this.#reamrc?.preloads) {
-      for (const preloadEntry of this.#reamrc.preloads) {
-        const preloadImport = typeof preloadEntry === 'function' ? preloadEntry : preloadEntry.file
-        const env =
-          typeof preloadEntry === 'function'
-            ? undefined
-            : (preloadEntry as { environment?: string[] }).environment
-
-        if (env && !env.includes(this.#app.getEnvironment())) continue
-        await preloadImport()
-      }
+      const applicable = this.#reamrc.preloads.filter((preloadEntry) => {
+        if (typeof preloadEntry === 'function') return true
+        const env = (preloadEntry as { environment?: string[] }).environment
+        return !env || env.includes(this.#app.getEnvironment())
+      })
+      await Promise.all(
+        applicable.map((preloadEntry) =>
+          typeof preloadEntry === 'function' ? preloadEntry() : preloadEntry.file(),
+        ),
+      )
     }
 
     // Auto-load module files (routes.ts, etc.) from modules directory
@@ -737,6 +760,7 @@ export class Ignitor {
           this.#server.getErrorHandler() ?? new ExceptionHandler(!this.#app.inProduction),
         serverMiddleware: this.#server.getServerMiddleware(),
         routerMiddleware: this.#router.getRouterMiddleware(),
+        devReloadScript: this.#devReloadScript(),
         onError: (error, ctx) => {
           this.#errorBoundary.serviceError('HttpKernel', error, ctx.id)
         },
@@ -799,15 +823,24 @@ export class Ignitor {
       }
       await this.#_httpServer.listen()
 
+      // Whoever opened the socket closes it. `app.terminate()` runs the
+      // `terminating` hooks in reverse before shutting the providers down, so
+      // an application terminated by ANY path — this Ignitor's signal handler,
+      // an `app.listen('SIGTERM', () => app.terminate())` the entry point wired
+      // itself, a crash handler — drains the HTTP server. It used to skip it:
+      // `terminate()` shut the providers down and called `process.exit(0)`,
+      // which could win the race against a drain already in progress.
+      this.#app.terminating(() => this.stop())
+
       // Wire OS-signal graceful shutdown. Without it the process never closes
       // the HTTP server on SIGTERM/SIGINT, so live keep-alive / SSE sockets keep
       // the event loop alive — a `ream dev` restart or Ctrl+C ends in a watcher
       // force-kill, and an orchestrator's rolling deploy drops in-flight work.
-      // onShutdown = this.stop(), which closes the port (aborting connections),
-      // shuts providers down (DB pools), and releases the locators.
+      // It terminates the APPLICATION rather than stopping this Ignitor, so
+      // there is one authority however the shutdown was triggered.
       if (this.#config.gracefulShutdown !== false) {
         this.#shutdownHandle = installGracefulShutdown({
-          onShutdown: () => this.stop(),
+          onShutdown: () => this.#app.terminate(),
           logger: {
             info: (message) => this.#emitSystemInfo('GracefulShutdown', message, 'info'),
             error: (message) => this.#emitSystemInfo('GracefulShutdown', message, 'error'),
@@ -850,11 +883,13 @@ export class Ignitor {
     // already-loaded ESM module returns the CACHED module without re-executing
     // its body (the thunk's specifier is opaque, so it cannot be cache-busted).
     // The "reload" therefore destroyed every preload-registered route on the
-    // first file save and never restored them. Process-level restart is the
-    // reload mechanism (`ream dev` runs `tsx watch`, which restarts on change);
-    // this watcher only surfaces an informational event for hosts that embed
-    // the Ignitor without a supervisor. A future true HMR needs a loader-hook
-    // (hot-hook style) that can invalidate the ESM cache — plug it in here.
+    // first file save and never restored them.
+    //
+    // Module-level reloading now happens OUTSIDE the Ignitor: `ream dev` loads
+    // `@c9up/ream/hot`, which registers hot-hook's loader and can invalidate
+    // the ESM cache — the loader hook this comment used to ask for. What is
+    // left here only surfaces an informational event for hosts that embed the
+    // Ignitor without a supervisor.
     if (this.isDevMode()) {
       const watchDirs = this.#config.watchDirs ?? ['app', 'start']
       this.#hotReloadCleanup = startHotReload({
@@ -1116,6 +1151,7 @@ export class Ignitor {
         this.#server.getErrorHandler() ?? new ExceptionHandler(!this.#app.inProduction),
       serverMiddleware: this.#server.getServerMiddleware(),
       routerMiddleware: this.#router.getRouterMiddleware(),
+      devReloadScript: this.#devReloadScript(),
     })
     return this.#kernel
   }
@@ -1126,6 +1162,33 @@ export class Ignitor {
     return this.#app.inDev
   }
 
+  /**
+   * The reload script, in development only.
+   *
+   * Gated on the environment rather than on `hot-hook` being present: the
+   * script is just as useful without it, since a restart is exactly what it
+   * detects. In production it is `undefined` and the response is untouched.
+   */
+  #devReloadScript(): ((nonce?: string) => string) | undefined {
+    return this.isDevMode() ? hmrClientScript : undefined
+  }
+
+  /**
+   * Serve the token the injected script polls.
+   *
+   * 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.
+   */
+  #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())
+    })
+  }
+
   getPhase(): string {
     return this.#phase
   }

package/src/commands/ScheduleList.ts

@@ -33,6 +33,9 @@ export default class ScheduleList extends BaseCommand {
     const tasks = scheduler.listTasks()
     if (tasks.length === 0) {
       this.logger.info('No scheduled tasks registered.')
+      for (const line of whyNothingWasFound(this.app.rcFile.modules)) {
+        this.logger.info(`  ${line}`)
+      }
       return
     }
 
@@ -64,3 +67,30 @@ export default class ScheduleList extends BaseCommand {
     }
   }
 }
+
+/**
+ * Why an empty list is empty.
+ *
+ * Discovery walks the IoC service registry, and a class the process never
+ * imported is not in it. `@Schedule` in `app/modules/**` therefore depends on
+ * the module auto-loader having imported the file, and that has two conditions
+ * a reader of the folder-structure guide would not expect. Saying "no tasks"
+ * and stopping leaves them to find both by reading the Ignitor.
+ */
+function whyNothingWasFound(modules: { path?: string; autoload?: string[] } | undefined): string[] {
+  if (modules?.path === undefined) {
+    return [
+      'A @Schedule is only found once something has imported the class that declares it.',
+      'reamrc.ts has no `modules.path`, so nothing under app/modules/ is auto-loaded at all.',
+      "Either add `modules: { path: './app/modules', autoload: ['routes', 'events'] }`,",
+      'or import the file from a preload — which is explicit, and works anywhere.',
+    ]
+  }
+  const autoload = modules.autoload ?? ['routes', 'events']
+  return [
+    'A @Schedule is only found once something has imported the class that declares it.',
+    `modules.autoload is [${autoload.map((f) => `'${f}'`).join(', ')}], so app/modules/<name>/<file>.ts`,
+    'is imported only under one of those names. Add the file name to that list,',
+    'or import it from a preload — which is explicit, and works anywhere.',
+  ]
+}

package/src/container/Container.ts

@@ -115,15 +115,36 @@ export class Container {
   /** Register a singleton binding (factory called once, cached). */
   singleton<_T>(token: ServiceToken, factory: ServiceFactory): void {
     const key = this.#tokenToKey(token)
+    this.#forgetCached(key)
     this.#bindings.set(key, { token, factory, scope: 'singleton', dependencies: [] })
   }
 
   /** Register a transient binding (new instance per resolve). */
   bind<_T>(token: ServiceToken, factory: ServiceFactory): void {
     const key = this.#tokenToKey(token)
+    this.#forgetCached(key)
     this.#bindings.set(key, { token, factory, scope: 'transient', dependencies: [] })
   }
 
+  /**
+   * Drop what a previous binding produced, because the binding is being
+   * replaced.
+   *
+   * Resolution reads the cache BEFORE the binding, so a token re-registered
+   * with a new factory kept answering with the old instance — a rebind that
+   * changed nothing, silently. That is what a provider does when it boots a
+   * second time in one process (a hot reload, a test that restarts the app):
+   * it rebinds, and the container went on handing out the connection the
+   * previous shutdown had closed.
+   *
+   * The in-flight promise goes too: a resolution already awaiting the OLD
+   * factory must not become the value of the new binding.
+   */
+  #forgetCached(key: ServiceToken): void {
+    this.#singletons.delete(key)
+    this.#pendingSingletons.delete(key)
+  }
+
   /** Bind an existing value directly. */
   bindValue<T>(token: ServiceToken, value: T): void {
     const key = this.#tokenToKey(token)
@@ -348,38 +369,48 @@ export class Container {
       )
     }
     const outerParent = chain.parent
-    chain.parent = target
-    const paramTypes: unknown[] =
-      Reflect.getMetadata('design:paramtypes', target.prototype, method) ?? []
-    // `@Inject('token')` on a method parameter — a named binding the reflected
-    // type cannot express (an interface, or a class registered under a name).
-    const injectTokens = getMethodInjectTokens(target.prototype, method)
-
-    // `@Inject` counts towards the parameter span too: a method may carry named
-    // tokens without `design:paramtypes` being emitted for it, and computing the
-    // span from the reflected types alone left the loop at zero iterations —
-    // the tokens were read and then never used.
-    const injectSpan = injectTokens.size === 0 ? 0 : Math.max(...injectTokens.keys()) + 1
-    const len = Math.max(paramTypes.length, runtimeValues?.length ?? 0, injectSpan)
-    // Sequential resolution keeps the shared cycle-detection stack consistent.
+    // Declared outside the try so the call below can still read it: only the
+    // RESOLUTION is guarded, because that is what can throw with the parent
+    // installed.
     const args: unknown[] = []
-    for (let index = 0; index < len; index += 1) {
-      // Runtime values take precedence (and fill slots beyond paramTypes).
-      if (runtimeValues && index < runtimeValues.length) {
-        args.push(runtimeValues[index])
-        continue
-      }
-      const named = injectTokens.get(index)
-      if (named !== undefined) {
-        args.push(await this.resolve(named))
-        continue
+    chain.parent = target
+    try {
+      const paramTypes: unknown[] =
+        Reflect.getMetadata('design:paramtypes', target.prototype, method) ?? []
+      // `@Inject('token')` on a method parameter — a named binding the reflected
+      // type cannot express (an interface, or a class registered under a name).
+      const injectTokens = getMethodInjectTokens(target.prototype, method)
+
+      // `@Inject` counts towards the parameter span too: a method may carry named
+      // tokens without `design:paramtypes` being emitted for it, and computing the
+      // span from the reflected types alone left the loop at zero iterations —
+      // the tokens were read and then never used.
+      const injectSpan = injectTokens.size === 0 ? 0 : Math.max(...injectTokens.keys()) + 1
+      const len = Math.max(paramTypes.length, runtimeValues?.length ?? 0, injectSpan)
+      // Sequential resolution keeps the shared cycle-detection stack consistent.
+      for (let index = 0; index < len; index += 1) {
+        // Runtime values take precedence (and fill slots beyond paramTypes).
+        if (runtimeValues && index < runtimeValues.length) {
+          args.push(runtimeValues[index])
+          continue
+        }
+        const named = injectTokens.get(index)
+        if (named !== undefined) {
+          args.push(await this.resolve(named))
+          continue
+        }
+        const type = paramTypes[index]
+        args.push(isInjectableClass(type) ? await this.resolve(type) : undefined)
       }
-      const type = paramTypes[index]
-      args.push(isInjectableClass(type) ? await this.resolve(type) : undefined)
+    } finally {
+      // RESTORED whatever happened. Without the `finally`, a parameter that
+      // failed to resolve left the called class installed as the parent, so a
+      // caller that caught the error saw its contextual bindings applied to
+      // every later resolution — a binding meant for one handler leaking into
+      // the whole application.
+      chain.parent = outerParent
     }
 
-    chain.parent = outerParent
-
     const member: unknown = instance[method]
     if (!isCallable(member)) {
       throw new Error(`Container.call: '${method}' is not a callable method`)
@@ -576,19 +607,47 @@ export class Container {
         return instance as T
       }
 
-      // A build already under way: join it rather than start a second one.
+      // A build already under way: join it rather than start a second one —
+      // but only take its result if it was actually PUBLISHED. A factory that
+      // reads a request-scoped value builds that request's instance, and
+      // `#cacheIfAppWide` deliberately refuses to cache it; handing it to the
+      // resolver waiting behind was one request's HttpContext, identity or
+      // tenant answering for another. That resolution builds its own instead.
       const inFlight = this.#pendingSingletons.get(key)
-      if (inFlight) return (await inFlight) as T
+      if (inFlight) {
+        const shared = await inFlight
+        if (this.#wasPublished(key, shared)) return shared as T
+      }
 
       const readsBefore = store?.scopedReads ?? 0
       const building = (async (): Promise<unknown> => {
         const instance = binding.factory ? await binding.factory(this) : undefined
+        // Only cache while this is still the binding that started the build.
+        // A rebind that landed mid-flight already dropped the cache; letting
+        // the old factory write its result afterwards restored exactly what the
+        // rebind existed to replace.
+        if (this.#bindings.get(key) !== binding) return instance
+        // Hooks FIRST, cache after. Published before they ran, a singleton
+        // whose `resolving` hook threw was already in the cache: the caller saw
+        // the error, and the next resolution was handed the same half-built
+        // instance with no hook, no error and nothing to say a step had been
+        // skipped. A hook that opens a connection, validates a config or wraps
+        // a security decorator failing is precisely when the instance must not
+        // be reachable.
+        //
+        // Upstream's hooks are documented as modifying the value BEFORE it is
+        // returned, which only holds if the value is not already shared.
+        //
+        // Inside the promise, so the hooks run exactly once per instance no
+        // matter how many callers were waiting; the pending promise is what
+        // keeps concurrent callers from building a second one.
+        await this.#runResolvingHooks(key, instance)
+        // Re-checked: a rebind can land while the hooks run, and the cache it
+        // dropped must not be refilled by the build it replaced.
+        if (this.#bindings.get(key) !== binding) return instance
         // See `ResolutionChain.scopedReads`: a build that consumed a
         // request-scoped value is that request's, not the application's.
         this.#cacheIfAppWide('singleton', key, instance, store, readsBefore)
-        // Inside the promise, so the hooks run exactly once per instance no
-        // matter how many callers were waiting.
-        await this.#runResolvingHooks(key, instance)
         return instance
       })()
       this.#pendingSingletons.set(key, building)
@@ -596,15 +655,17 @@ export class Container {
         return (await building) as T
       } finally {
         // Cleared either way: a failed build must not poison later attempts.
-        this.#pendingSingletons.delete(key)
+        // Guarded, so a rebind that installed its own pending build is not
+        // undone by the old one finishing afterwards.
+        if (this.#pendingSingletons.get(key) === building) {
+          this.#pendingSingletons.delete(key)
+        }
       }
     }
 
     // 6. Auto-construct if it's a class
     if (typeof token === 'function') {
-      const instance = (await this.#autoConstruct(token, runtimeValues)) as T
-      await this.#runResolvingHooks(key, instance)
-      return instance
+      return (await this.#resolveAutoConstructed(token, runtimeValues)) as T
     }
 
     // 7. Not found
@@ -628,6 +689,66 @@ export class Container {
    * 2. Reflect.getMetadata('design:paramtypes') — decorator metadata (requires SWC/tsc)
    * 3. No params → plain `new Class()`
    */
+  /**
+   * Resolve a class the container builds itself — through the SAME pipeline as
+   * an explicit singleton binding.
+   *
+   * `@Service({ scope: 'singleton' })` never goes through a binding, so this
+   * path had its own, weaker rules: the instance was cached on the way out of
+   * construction and the `resolving` hooks ran afterwards, so a hook that threw
+   * left a half-built object in the cache for the next caller — the failure the
+   * explicit path was fixed for, on the path most applications actually use.
+   * It also never joined `#pendingSingletons`, so two resolutions in flight at
+   * once each built their own and whichever finished last was the one everybody
+   * got.
+   *
+   * Pending promise, then construction, then hooks, then publication. In that
+   * order, on both paths.
+   */
+  async #resolveAutoConstructed(
+    target: abstract new (...args: never[]) => unknown,
+    runtimeValues?: unknown[],
+  ): Promise<unknown> {
+    const metadata = getServiceMetadata(target)
+    const key = metadata?.as ?? target
+
+    if (metadata?.scope !== 'singleton') {
+      const instance = await this.#autoConstruct(target, runtimeValues)
+      await this.#runResolvingHooks(key, instance)
+      return instance
+    }
+
+    if (this.#singletons.has(key)) return this.#singletons.get(key)
+    const inFlight = this.#pendingSingletons.get(key)
+    if (inFlight) {
+      const shared = await inFlight
+      // Joined ONLY if that build was published application-wide. A build that
+      // consumed a request-scoped value belongs to its request — handing it to
+      // another one is exactly the leak `createResolver()` exists to prevent —
+      // so this resolution falls through and builds its own instead.
+      if (this.#wasPublished(key, shared)) return shared
+    }
+
+    // Same rule as the explicit bindings: see `ResolutionChain.scopedReads`.
+    const store = this.#chain.getStore()
+    const readsBefore = store?.scopedReads ?? 0
+    const building = (async (): Promise<unknown> => {
+      const instance = await this.#autoConstruct(target, runtimeValues)
+      await this.#runResolvingHooks(key, instance)
+      this.#cacheIfAppWide('singleton', key, instance, store, readsBefore)
+      return instance
+    })()
+    this.#pendingSingletons.set(key, building)
+    try {
+      return await building
+    } finally {
+      // Cleared either way: a failed build must not poison later attempts.
+      if (this.#pendingSingletons.get(key) === building) {
+        this.#pendingSingletons.delete(key)
+      }
+    }
+  }
+
   async #autoConstruct(
     target: abstract new (...args: never[]) => unknown,
     runtimeValues?: unknown[],
@@ -649,20 +770,19 @@ export class Container {
     target: abstract new (...args: never[]) => unknown,
     runtimeValues?: unknown[],
   ): Promise<unknown> {
-    const metadata = getServiceMetadata(target)
-    const scope = metadata?.scope ?? 'transient'
     // The class itself, not `target.name`: two classes called `Service` share a
     // name and must not share a singleton cache entry.
+    const metadata = getServiceMetadata(target)
     const key = metadata?.as ?? target
 
-    if (scope === 'singleton' && this.#singletons.has(key)) {
+    // A cached singleton short-circuits construction — for the callers that
+    // reach this directly (`autoRegister`'s factory). PUBLISHING it is not this
+    // method's business: it builds, and `#resolveAutoConstructed` decides when
+    // the result may be shared, after the hooks have had their say.
+    if (metadata?.scope === 'singleton' && this.#singletons.has(key)) {
       return this.#singletons.get(key)
     }
 
-    // Same rule as the explicit singleton bindings: see `scopedReads`.
-    const store = this.#chain.getStore()
-    const readsBefore = store?.scopedReads ?? 0
-
     // A runtime value at this index (from `make(Class, [req, res])`) wins over
     // container resolution for that constructor slot.
     const runtimeAt = (index: number): unknown => runtimeValues?.[index]
@@ -698,7 +818,6 @@ export class Container {
           deps.push(depToken ? await this.resolve(depToken) : undefined)
         }
         const instance = Reflect.construct(target, deps)
-        this.#cacheIfAppWide(scope, key, instance, store, readsBefore)
         return instance
       }
       // (b) No @Inject/metadata, but the caller supplied runtime values — build
@@ -707,7 +826,6 @@ export class Container {
       if (target.length > 0 && (runtimeValues?.length ?? 0) > 0) {
         const deps = Array.from({ length: target.length }, (_value, index) => runtimeAt(index))
         const instance = Reflect.construct(target, deps)
-        this.#cacheIfAppWide(scope, key, instance, store, readsBefore)
         return instance
       }
       // (c) The constructor declares parameters but we have no way to resolve
@@ -729,7 +847,6 @@ export class Container {
       // one is a compile error even though the runtime constructs it happily —
       // `abstract` exists only at compile time.
       const instance = Reflect.construct(target, [])
-      this.#cacheIfAppWide(scope, key, instance, store, readsBefore)
       return instance
     }
 
@@ -752,7 +869,6 @@ export class Container {
     }
 
     const instance = Reflect.construct(target, deps)
-    this.#cacheIfAppWide(scope, key, instance, store, readsBefore)
     return instance
   }
 
@@ -764,6 +880,20 @@ export class Container {
    * later one. AdonisJS does not guard this; it is the kind of silent
    * cross-request leak worth refusing.
    */
+  /**
+   * Is `instance` the value that was published under `key`?
+   *
+   * `Object.is`, not `===`: a factory answering `NaN` compares unequal to
+   * itself, so a waiter concluded the build had not been published and built a
+   * second singleton. And `has()` before the comparison, because an absent
+   * entry and one holding `undefined` both read back as `undefined` — a
+   * request-scoped build that produced nothing was then shared with the next
+   * request, which is the whole thing this check exists to prevent.
+   */
+  #wasPublished(key: ServiceToken, instance: unknown): boolean {
+    return this.#singletons.has(key) && Object.is(this.#singletons.get(key), instance)
+  }
+
   #cacheIfAppWide(
     scope: string,
     key: ServiceToken,

package/src/container/types.ts

@@ -38,6 +38,17 @@ export type ServiceToken = (abstract new (...args: never[]) => unknown) | string
  */
 export interface FactoryResolver {
   make<T>(token: ServiceToken, runtimeValues?: unknown[]): Promise<T>
+  /**
+   * Call a method with its dependencies injected. Declared here because a
+   * factory that dispatches to a handler needs it and both implementations
+   * have it — leaving it off did not make the capability go away, it only
+   * hid it from the callers allowed to use it.
+   */
+  call<T, K extends string & keyof T>(
+    instance: T,
+    method: K,
+    runtimeValues?: unknown[],
+  ): Promise<unknown>
 }
 
 /**

package/src/dev/hmr.ts

@@ -0,0 +1,83 @@
+/**
+ * What the browser watches to know the server changed under it.
+ *
+ * Two things can happen while `ream dev` runs, and the page has no way to see
+ * either: a module is swapped in the running process (hot-hook invalidated it),
+ * or the process restarts. Both change what the server would render, and both
+ * used to leave a stale page on screen until someone pressed reload.
+ *
+ * NAMED DEVIATION — upstream has no equivalent. AdonisJS' assembler does not
+ * refresh the browser; that comes from its Vite integration, i.e. from the
+ * asset pipeline. Ream has no such pipeline in the general case, so this lives
+ * in the framework, and it is deliberately the smallest thing that works: a
+ * token the page polls, not a socket. A socket would still need a reconnect
+ * loop and a boot identity to survive the restart half, which is most of a
+ * poller with more moving parts.
+ */
+
+/** Where the token is served, and what the injected script polls. */
+export const HMR_PATH = '/__ream/hmr'
+
+/**
+ * Identifies THIS process. A restart produces a new one, which is how the page
+ * detects a reboot without the server having to survive it to say so.
+ */
+const BOOT_ID = `${process.pid}-${Date.now().toString(36)}`
+
+/** Bumped by `@c9up/ream/hot` every time hot-hook swaps a module. */
+const COUNTER = Symbol.for('ream.dev.hotReloadCount')
+
+interface CounterHolder {
+  [COUNTER]?: number
+}
+
+/**
+ * A module-level variable would not do: `@c9up/ream/hot` is loaded through a
+ * different module graph than the running application (it is an `--import`
+ * entry), so the two would each hold their own copy. A well-known symbol on
+ * `globalThis` is the one place both can see.
+ */
+function holder(): CounterHolder {
+  return globalThis as unknown as CounterHolder
+}
+
+/** Called by the hot entry when hot-hook reports a module was swapped. */
+export function hotReloadHappened(): void {
+  const store = holder()
+  store[COUNTER] = (store[COUNTER] ?? 0) + 1
+}
+
+/** How many hot swaps this process has seen. */
+export function hotReloadCount(): number {
+  return holder()[COUNTER] ?? 0
+}
+
+/**
+ * The token. Changes on a restart (new boot id) and on a hot swap (new count),
+ * which are exactly the two cases the page must react to.
+ */
+export function hmrToken(): string {
+  return `${BOOT_ID}.${hotReloadCount()}`
+}
+
+/**
+ * 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.
+ */
+export function hmrClientScript(nonce?: string): string {
+  // A nonce-based CSP — which the scaffold ships, via `@c9up/blackhole` —
+  // rejects an inline script that does not carry the request's nonce, and the
+  // page simply never reloads. `response.nonce` is where it lives; the quotes
+  // 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, '"')}"`
+  // 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>`
+}