@c9up/ream 0.2.17 → 0.2.18

package/dist/openapi/OpenApiProvider.d.ts

@@ -1,11 +1,12 @@
 /**
  * `OpenApiProvider` — serves an auto-generated OpenAPI 3.1 spec + Swagger UI.
  *
- * `boot()` mounts a global middleware that, on the first GET to `/api-docs`
+ * `start()` mounts a global middleware that, on the first GET to `/api-docs`
  * (JSON) or `/docs` (Swagger UI), lazily generates the spec from the router's
- * registered routes — so every route registered during boot/start is included
- * (the spec must NOT be generated eagerly at boot, before other providers have
- * registered their routes). Opt-out via `config.openapi.enabled = false`.
+ * registered routes — so every route registered while the application starts
+ * up is included (the spec must NOT be generated eagerly, before the other
+ * providers and the preloads have registered their routes). Opt-out via
+ * `config.openapi.enabled = false`.
  *
  * @implements Story 24.4
  */
@@ -31,7 +32,17 @@ export interface OpenApiProviderOptions {
 export declare class OpenApiProvider extends Provider {
     #private;
     constructor(app: AppContext, options?: OpenApiProviderOptions);
-    boot(): Promise<void>;
+    /**
+     * Routes and server middleware go in `start`, not `boot`.
+     *
+     * Upstream documents that phase for exactly this, and the order is what makes
+     * it matter: providers boot, then providers START, then the preloads run —
+     * and the preloads are where an application writes its own routes and kernel.
+     * Mounted in `boot`, a framework route landed ahead of every application
+     * route, so an overlapping path was answered by the framework rather than by
+     * the app that meant to override it.
+     */
+    start(): Promise<void>;
 }
 export default OpenApiProvider;
 //# sourceMappingURL=OpenApiProvider.d.ts.map

package/dist/openapi/OpenApiProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OpenApiProvider.d.ts","sourceRoot":"","sources":["../../src/openapi/OpenApiProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAGzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAGxD,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,SAAS,CAAC,EAAE,gBAAgB,CAAA;CAC7B;AAED,qBAAa,eAAgB,SAAQ,QAAQ;;gBAG/B,GAAG,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B;IAKlD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAqBrC;AAGD,eAAe,eAAe,CAAA"}
+{"version":3,"file":"OpenApiProvider.d.ts","sourceRoot":"","sources":["../../src/openapi/OpenApiProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAGzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAGxD,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,SAAS,CAAC,EAAE,gBAAgB,CAAA;CAC7B;AAED,qBAAa,eAAgB,SAAQ,QAAQ;;gBAG/B,GAAG,EAAE,UAAU,EAAE,OAAO,GAAE,sBAA2B;IAKjE;;;;;;;;;OASG;IACY,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAyBtC;AAGD,eAAe,eAAe,CAAA"}

package/dist/openapi/OpenApiProvider.js

@@ -1,11 +1,12 @@
 /**
  * `OpenApiProvider` — serves an auto-generated OpenAPI 3.1 spec + Swagger UI.
  *
- * `boot()` mounts a global middleware that, on the first GET to `/api-docs`
+ * `start()` mounts a global middleware that, on the first GET to `/api-docs`
  * (JSON) or `/docs` (Swagger UI), lazily generates the spec from the router's
- * registered routes — so every route registered during boot/start is included
- * (the spec must NOT be generated eagerly at boot, before other providers have
- * registered their routes). Opt-out via `config.openapi.enabled = false`.
+ * registered routes — so every route registered while the application starts
+ * up is included (the spec must NOT be generated eagerly, before the other
+ * providers and the preloads have registered their routes). Opt-out via
+ * `config.openapi.enabled = false`.
  *
  * @implements Story 24.4
  */
@@ -18,7 +19,17 @@ export class OpenApiProvider extends Provider {
         super(app);
         this.#override = options.generator;
     }
-    async boot() {
+    /**
+     * Routes and server middleware go in `start`, not `boot`.
+     *
+     * Upstream documents that phase for exactly this, and the order is what makes
+     * it matter: providers boot, then providers START, then the preloads run —
+     * and the preloads are where an application writes its own routes and kernel.
+     * Mounted in `boot`, a framework route landed ahead of every application
+     * route, so an overlapping path was answered by the framework rather than by
+     * the app that meant to override it.
+     */
+    async start() {
         const config = this.app.config.get('openapi') ?? {};
         if (config.enabled === false)
             return;
@@ -33,10 +44,14 @@ export class OpenApiProvider extends Provider {
     }
     async #buildGenerator(config) {
         const router = await this.app.container.make('router');
-        return new OpenApiGenerator(router, {
+        const generator = new OpenApiGenerator(router, {
             title: config.title ?? 'API',
             version: config.version ?? '1.0.0',
         });
+        // The routes already name their validators; ask each one to describe
+        // itself instead of making the app repeat the shape by hand.
+        await generator.hydrateSchemas((token) => this.app.container.make(token));
+        return generator;
     }
 }
 // Default export so reamrc's provider loader can `() => import('@c9up/ream/<feature>/provider')` (resolves to { default }), matching events/rpc. Named export above stays.

package/dist/openapi/OpenApiProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"OpenApiProvider.js","sourceRoot":"","sources":["../../src/openapi/OpenApiProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAGzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAoB1D,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IAClC,SAAS,CAAmB;IAErC,YAAY,GAAe,EAAE,UAAkC,EAAE;QAC/D,KAAK,CAAC,GAAG,CAAC,CAAA;QACV,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAA;IACpC,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAoB,SAAS,CAAC,IAAI,EAAE,CAAA;QACtE,IAAI,MAAM,CAAC,OAAO,KAAK,KAAK;YAAE,OAAM;QAEpC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,MAAM,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAA;QACxE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAS,QAAQ,CAAC,CAAA;QAC9D,MAAM,UAAU,GAAG,IAAI,iBAAiB,CAAC;YACvC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE;SACjC,CAAC,CAAA;QACF,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;IAC3D,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,MAAyB;QAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAS,QAAQ,CAAC,CAAA;QAC9D,OAAO,IAAI,gBAAgB,CAAC,MAAM,EAAE;YAClC,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,KAAK;YAC5B,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,OAAO;SACnC,CAAC,CAAA;IACJ,CAAC;CACF;AAED,2KAA2K;AAC3K,eAAe,eAAe,CAAA"}
+{"version":3,"file":"OpenApiProvider.js","sourceRoot":"","sources":["../../src/openapi/OpenApiProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAGzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAoB1D,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IAClC,SAAS,CAAmB;IAErC,YAAY,GAAe,EAAE,UAAkC,EAAE;QAC/D,KAAK,CAAC,GAAG,CAAC,CAAA;QACV,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAA;IACpC,CAAC;IAED;;;;;;;;;OASG;IACM,KAAK,CAAC,KAAK;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAoB,SAAS,CAAC,IAAI,EAAE,CAAA;QACtE,IAAI,MAAM,CAAC,OAAO,KAAK,KAAK;YAAE,OAAM;QAEpC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,MAAM,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAA;QACxE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAS,QAAQ,CAAC,CAAA;QAC9D,MAAM,UAAU,GAAG,IAAI,iBAAiB,CAAC;YACvC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE;SACjC,CAAC,CAAA;QACF,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;IAC3D,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,MAAyB;QAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAS,QAAQ,CAAC,CAAA;QAC9D,MAAM,SAAS,GAAG,IAAI,gBAAgB,CAAC,MAAM,EAAE;YAC7C,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,KAAK;YAC5B,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,OAAO;SACnC,CAAC,CAAA;QACF,qEAAqE;QACrE,6DAA6D;QAC7D,MAAM,SAAS,CAAC,cAAc,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAU,KAAK,CAAC,CAAC,CAAA;QAClF,OAAO,SAAS,CAAA;IAClB,CAAC;CACF;AAED,2KAA2K;AAC3K,eAAe,eAAe,CAAA"}

package/dist/rpc/RpcProvider.d.ts

@@ -9,8 +9,9 @@
  *       rpc.method('task.validate', handler).guard('jwt')
  *       rpc.namespace('user', UserController)
  *
- *   - `boot()` — mount `POST <config.rpc.path ?? '/rpc'>` on the core router,
+ *   - `start()` — mount `POST <config.rpc.path ?? '/rpc'>` on the core router,
  *     dispatching every request body (single or batch) to `RpcRouter.handle()`.
+ *     In `start`, which is the phase upstream documents for routes.
  *
  * @implements Story 24.1, 24.2
  */
@@ -38,7 +39,17 @@ export declare class RpcProvider extends Provider {
     readonly rpc: RpcRouter;
     constructor(app: AppContext, options?: RpcProviderOptions);
     register(): void;
-    boot(): Promise<void>;
+    /**
+     * Routes and server middleware go in `start`, not `boot`.
+     *
+     * Upstream documents that phase for exactly this, and the order is what makes
+     * it matter: providers boot, then providers START, then the preloads run —
+     * and the preloads are where an application writes its own routes and kernel.
+     * Mounted in `boot`, a framework route landed ahead of every application
+     * route, so an overlapping path was answered by the framework rather than by
+     * the app that meant to override it.
+     */
+    start(): Promise<void>;
 }
 export default RpcProvider;
 //# sourceMappingURL=RpcProvider.d.ts.map

package/dist/rpc/RpcProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RpcProvider.d.ts","sourceRoot":"","sources":["../../src/rpc/RpcProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,qBAAa,WAAY,SAAQ,QAAQ;;IACvC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;gBAGX,GAAG,EAAE,UAAU,EAAE,OAAO,GAAE,kBAAuB;IAKpD,QAAQ,IAAI,IAAI;IAmBV,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAarC;AAMD,eAAe,WAAW,CAAA"}
+{"version":3,"file":"RpcProvider.d.ts","sourceRoot":"","sources":["../../src/rpc/RpcProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,qBAAa,WAAY,SAAQ,QAAQ;;IACvC,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;gBAGX,GAAG,EAAE,UAAU,EAAE,OAAO,GAAE,kBAAuB;IAKpD,QAAQ,IAAI,IAAI;IAmBzB;;;;;;;;;OASG;IACY,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAatC;AAMD,eAAe,WAAW,CAAA"}

package/dist/rpc/RpcProvider.js

@@ -9,8 +9,9 @@
  *       rpc.method('task.validate', handler).guard('jwt')
  *       rpc.namespace('user', UserController)
  *
- *   - `boot()` — mount `POST <config.rpc.path ?? '/rpc'>` on the core router,
+ *   - `start()` — mount `POST <config.rpc.path ?? '/rpc'>` on the core router,
  *     dispatching every request body (single or batch) to `RpcRouter.handle()`.
+ *     In `start`, which is the phase upstream documents for routes.
  *
  * @implements Story 24.1, 24.2
  */
@@ -39,7 +40,17 @@ export class RpcProvider extends Provider {
         container.singleton('rpc', () => this.rpc);
         this.#registered = true;
     }
-    async boot() {
+    /**
+     * Routes and server middleware go in `start`, not `boot`.
+     *
+     * Upstream documents that phase for exactly this, and the order is what makes
+     * it matter: providers boot, then providers START, then the preloads run —
+     * and the preloads are where an application writes its own routes and kernel.
+     * Mounted in `boot`, a framework route landed ahead of every application
+     * route, so an overlapping path was answered by the framework rather than by
+     * the app that meant to override it.
+     */
+    async start() {
         const config = this.app.config.get('rpc');
         const path = config?.path ?? '/rpc';
         const router = await this.app.container.make('router');

package/dist/rpc/RpcProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"RpcProvider.js","sourceRoot":"","sources":["../../src/rpc/RpcProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAGlD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAoB1C,MAAM,OAAO,WAAY,SAAQ,QAAQ;IAC9B,GAAG,CAAW;IACvB,WAAW,GAAG,KAAK,CAAA;IAEnB,YAAY,GAAe,EAAE,UAA8B,EAAE;QAC3D,KAAK,CAAC,GAAG,CAAC,CAAA;QACV,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,SAAS,EAAE,CAAA;IAC9C,CAAC;IAEQ,QAAQ;QACf,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAA;QACpC,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,0DAA0D;YAC1D,8DAA8D;YAC9D,IAAI,IAAI,CAAC,WAAW;gBAAE,OAAM;YAC5B,MAAM,IAAI,SAAS,CACjB,mCAAmC,EACnC,gEAAgE,EAChE;gBACE,IAAI,EAAE,kGAAkG;aACzG,CACF,CAAA;QACH,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,SAAS,CAAC,CAAA;QAChC,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAC1C,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;IACzB,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAY,KAAK,CAAC,CAAA;QACpD,MAAM,IAAI,GAAG,MAAM,EAAE,IAAI,IAAI,MAAM,CAAA;QACnC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAS,QAAQ,CAAC,CAAA;QAC9D,0EAA0E;QAC1E,2DAA2D;QAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QAC3E,sEAAsE;QACtE,wEAAwE;QACxE,gCAAgC;QAChC,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,EAAE,CAAA;QACnC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,CAAA;IAC/C,CAAC;CACF;AAED,uEAAuE;AACvE,+EAA+E;AAC/E,gFAAgF;AAChF,4BAA4B;AAC5B,eAAe,WAAW,CAAA"}
+{"version":3,"file":"RpcProvider.js","sourceRoot":"","sources":["../../src/rpc/RpcProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAGlD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAoB1C,MAAM,OAAO,WAAY,SAAQ,QAAQ;IAC9B,GAAG,CAAW;IACvB,WAAW,GAAG,KAAK,CAAA;IAEnB,YAAY,GAAe,EAAE,UAA8B,EAAE;QAC3D,KAAK,CAAC,GAAG,CAAC,CAAA;QACV,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,SAAS,EAAE,CAAA;IAC9C,CAAC;IAEQ,QAAQ;QACf,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAA;QACpC,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,0DAA0D;YAC1D,8DAA8D;YAC9D,IAAI,IAAI,CAAC,WAAW;gBAAE,OAAM;YAC5B,MAAM,IAAI,SAAS,CACjB,mCAAmC,EACnC,gEAAgE,EAChE;gBACE,IAAI,EAAE,kGAAkG;aACzG,CACF,CAAA;QACH,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,SAAS,CAAC,CAAA;QAChC,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAC1C,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;IACzB,CAAC;IAED;;;;;;;;;OASG;IACM,KAAK,CAAC,KAAK;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAY,KAAK,CAAC,CAAA;QACpD,MAAM,IAAI,GAAG,MAAM,EAAE,IAAI,IAAI,MAAM,CAAA;QACnC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAS,QAAQ,CAAC,CAAA;QAC9D,0EAA0E;QAC1E,2DAA2D;QAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QAC3E,sEAAsE;QACtE,wEAAwE;QACxE,gCAAgC;QAChC,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,IAAI,EAAE,CAAA;QACnC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,CAAA;IAC/C,CAAC;CACF;AAED,uEAAuE;AACvE,+EAA+E;AAC/E,gFAAgF;AAChF,4BAA4B;AAC5B,eAAe,WAAW,CAAA"}

package/dist/storage/StaticProvider.d.ts

@@ -2,7 +2,7 @@
  * `StaticProvider` — serves static files from a directory.
  *
  * Opt-in: does nothing unless `config.static.root` is set (or a middleware is
- * injected for tests). When configured, `boot()` mounts a global
+ * injected for tests). When configured, `start()` mounts a global
  * `StaticMiddleware` (path-traversal + symlink-escape guarded) that serves
  * matching requests and falls through (`next()`) otherwise.
  *
@@ -21,7 +21,17 @@ export interface StaticProviderOptions {
 export declare class StaticProvider extends Provider {
     #private;
     constructor(app: AppContext, options?: StaticProviderOptions);
-    boot(): Promise<void>;
+    /**
+     * Routes and server middleware go in `start`, not `boot`.
+     *
+     * Upstream documents that phase for exactly this, and the order is what makes
+     * it matter: providers boot, then providers START, then the preloads run —
+     * and the preloads are where an application writes its own routes and kernel.
+     * Mounted in `boot`, a framework route landed ahead of every application
+     * route, so an overlapping path was answered by the framework rather than by
+     * the app that meant to override it.
+     */
+    start(): Promise<void>;
 }
 export default StaticProvider;
 //# sourceMappingURL=StaticProvider.d.ts.map

package/dist/storage/StaticProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StaticProvider.d.ts","sourceRoot":"","sources":["../../src/storage/StaticProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC,OAAO,EAAqB,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE3E,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,UAAU,CAAC,EAAE,gBAAgB,CAAA;CAC9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;;gBAG9B,GAAG,EAAE,UAAU,EAAE,OAAO,GAAE,qBAA0B;IAKjD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAOrC;AAGD,eAAe,cAAc,CAAA"}
+{"version":3,"file":"StaticProvider.d.ts","sourceRoot":"","sources":["../../src/storage/StaticProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC,OAAO,EAAqB,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE3E,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,UAAU,CAAC,EAAE,gBAAgB,CAAA;CAC9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;;gBAG9B,GAAG,EAAE,UAAU,EAAE,OAAO,GAAE,qBAA0B;IAKhE;;;;;;;;;OASG;IACY,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAOtC;AAGD,eAAe,cAAc,CAAA"}

package/dist/storage/StaticProvider.js

@@ -2,7 +2,7 @@
  * `StaticProvider` — serves static files from a directory.
  *
  * Opt-in: does nothing unless `config.static.root` is set (or a middleware is
- * injected for tests). When configured, `boot()` mounts a global
+ * injected for tests). When configured, `start()` mounts a global
  * `StaticMiddleware` (path-traversal + symlink-escape guarded) that serves
  * matching requests and falls through (`next()`) otherwise.
  *
@@ -19,7 +19,17 @@ export class StaticProvider extends Provider {
         super(app);
         this.#override = options.middleware;
     }
-    async boot() {
+    /**
+     * Routes and server middleware go in `start`, not `boot`.
+     *
+     * Upstream documents that phase for exactly this, and the order is what makes
+     * it matter: providers boot, then providers START, then the preloads run —
+     * and the preloads are where an application writes its own routes and kernel.
+     * Mounted in `boot`, a framework route landed ahead of every application
+     * route, so an overlapping path was answered by the framework rather than by
+     * the app that meant to override it.
+     */
+    async start() {
         const config = this.app.config.get('static');
         const middleware = this.#override ?? (config?.root ? new StaticMiddleware(config) : undefined);
         if (!middleware)

package/dist/storage/StaticProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"StaticProvider.js","sourceRoot":"","sources":["../../src/storage/StaticProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC,OAAO,EAAqB,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAO3E,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACjC,SAAS,CAAmB;IAErC,YAAY,GAAe,EAAE,UAAiC,EAAE;QAC9D,KAAK,CAAC,GAAG,CAAC,CAAA;QACV,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,UAAU,CAAA;IACrC,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAe,QAAQ,CAAC,CAAA;QAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QAC9F,IAAI,CAAC,UAAU;YAAE,OAAM,CAAC,2BAA2B;QACnD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAS,QAAQ,CAAC,CAAA;QAC9D,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;IAC3D,CAAC;CACF;AAED,yKAAyK;AACzK,eAAe,cAAc,CAAA"}
+{"version":3,"file":"StaticProvider.js","sourceRoot":"","sources":["../../src/storage/StaticProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC,OAAO,EAAqB,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAO3E,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACjC,SAAS,CAAmB;IAErC,YAAY,GAAe,EAAE,UAAiC,EAAE;QAC9D,KAAK,CAAC,GAAG,CAAC,CAAA;QACV,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,UAAU,CAAA;IACrC,CAAC;IAED;;;;;;;;;OASG;IACM,KAAK,CAAC,KAAK;QAClB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAe,QAAQ,CAAC,CAAA;QAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QAC9F,IAAI,CAAC,UAAU;YAAE,OAAM,CAAC,2BAA2B;QACnD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAS,QAAQ,CAAC,CAAA;QAC9D,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;IAC3D,CAAC;CACF;AAED,yKAAyK;AACzK,eAAe,cAAc,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/ream",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "description": "Ream — Rust-powered Node.js application framework",
   "license": "MIT",
   "type": "module",
@@ -202,6 +202,14 @@
     "./bodyparser_middleware": {
       "types": "./dist/bodyparser/BodyParserMiddleware.d.ts",
       "import": "./dist/bodyparser/BodyParserMiddleware.js"
+    },
+    "./hot": {
+      "types": "./dist/hot.d.ts",
+      "import": "./dist/hot.js"
+    },
+    "./dev/hmr": {
+      "types": "./dist/dev/hmr.d.ts",
+      "import": "./dist/dev/hmr.js"
     }
   },
   "files": [
@@ -225,7 +233,8 @@
   },
   "peerDependencies": {
     "@c9up/comet": "^0.1.0",
-    "@c9up/quasar": "^0.1.0"
+    "@c9up/quasar": "^0.1.0",
+    "hot-hook": "^1.0.0"
   },
   "peerDependenciesMeta": {
     "@c9up/comet": {
@@ -233,6 +242,9 @@
     },
     "@c9up/quasar": {
       "optional": true
+    },
+    "hot-hook": {
+      "optional": true
     }
   },
   "devDependencies": {

package/src/HttpKernel.ts

@@ -32,6 +32,16 @@ export interface HttpKernelConfig {
   container?: Container
   exceptionHandler?: ExceptionHandler
   serverMiddleware?: MiddlewareFunction[]
+  /**
+   * A `<script>` appended to every HTML response, dev only.
+   *
+   * Set by the Ignitor when the application runs in development; `undefined`
+   * everywhere else, so a production response is byte-for-byte what the
+   * handler produced. It lives here rather than in a middleware because this
+   * is the one place every response passes through on its way out, whichever
+   * route or error handler produced it.
+   */
+  devReloadScript?: (nonce?: string) => string
   routerMiddleware?: MiddlewareFunction[]
   onError?: (error: unknown, ctx: HttpContext) => void
   debug?: boolean
@@ -345,7 +355,7 @@ export function createHttpKernel(
           correlationId,
         )
       }
-      const serialized = await serializeResponse(ctx)
+      const serialized = await serializeResponse(ctx, config.devReloadScript)
       // The body is built; anything registered with `response.onFinish()` runs
       // now — after the answer is ready, before we hand it back.
       ctx.response.runFinishCallbacks()
@@ -401,7 +411,7 @@ export function createHttpKernel(
           correlationId,
         )
       }
-      const serialized = await serializeResponse(ctx)
+      const serialized = await serializeResponse(ctx, config.devReloadScript)
       // The body is built; anything registered with `response.onFinish()` runs
       // now — after the answer is ready, before we hand it back.
       ctx.response.runFinishCallbacks()
@@ -452,15 +462,87 @@ function readControllerGuardMetadata(
   }
 }
 
-async function serializeResponse(ctx: HttpContext): Promise<HttpKernelResponse> {
+async function serializeResponse(
+  ctx: HttpContext,
+  devReloadScript?: (nonce?: string) => string,
+): Promise<HttpKernelResponse> {
   // The terminal step, as AdonisJS' server calls `response.finish()`: it
   // stamps the request id and waits for a body still being produced.
   await ctx.response.finish()
   const streamId = ctx.response.getStreamId()
+  const headers = ctx.response.getHeaders()
+  const body = withDevReloadScript(
+    ctx.response.getBody(),
+    headers,
+    streamId,
+    devReloadScript === undefined ? undefined : devReloadScript(ctx.response.nonce),
+  )
   return {
     status: ctx.response.getStatus(),
-    headers: ctx.response.getHeaders(),
-    body: ctx.response.getBody(),
+    headers: reconcileRepresentation(headers, ctx.response.getBody(), body),
+    body,
     ...(streamId !== undefined ? { streamId } : {}),
   }
 }
+
+/**
+ * Keep the representation headers describing the body that is actually sent.
+ *
+ * `content-length`, `etag` and the digest headers are computed from the body
+ * BEFORE the dev reload script is appended. Left alone they describe the
+ * previous one: a `content-length` short by the length of the script truncates
+ * it, and an `etag` computed before the change caches modified content under an
+ * unchanged validator.
+ *
+ * `content-length` is recomputed because it is cheap and exact; the validators
+ * are DROPPED rather than recomputed, because a validator this layer invents is
+ * not the one the handler meant.
+ */
+function reconcileRepresentation(
+  headers: Record<string, string>,
+  original: string,
+  sent: string,
+): Record<string, string> {
+  if (sent === original) return headers
+  const reconciled = { ...headers }
+  if (reconciled['content-length'] !== undefined) {
+    reconciled['content-length'] = String(Buffer.byteLength(sent, 'utf8'))
+  }
+  // Every validator, not the two that came to mind. `Content-Digest` and
+  // `Repr-Digest` (RFC 9530) are what replaced `Digest`, and leaving them
+  // describing the old body is the same defect one header along — a client
+  // that checks them rejects a response that is perfectly fine.
+  for (const name of [
+    'etag',
+    'content-md5',
+    'digest',
+    'content-digest',
+    'repr-digest',
+    'want-digest',
+    'want-content-digest',
+    'want-repr-digest',
+  ]) {
+    delete reconciled[name]
+  }
+  return reconciled
+}
+
+/**
+ * Append the dev reload script to an HTML body.
+ *
+ * Only HTML, and never a stream: appending to an SSE or a download would
+ * corrupt it, and a page is the only thing that can act on the script anyway.
+ * Before `</body>` when there is one, so the script is inside the document
+ * rather than trailing after it.
+ */
+function withDevReloadScript(
+  body: string,
+  headers: Record<string, string>,
+  streamId: string | undefined,
+  script?: string,
+): string {
+  if (script === undefined || streamId !== undefined || body === '') return body
+  if (!(headers['content-type'] ?? '').includes('text/html')) return body
+  const closing = body.lastIndexOf('</body>')
+  return closing === -1 ? body + script : body.slice(0, closing) + script + body.slice(closing)
+}

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)
         },
@@ -859,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({
@@ -1125,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
   }
@@ -1135,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
   }