@c9up/ream 0.2.16 → 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.16",
+  "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/Application.ts

@@ -56,11 +56,26 @@ export type ApplicationState =
   | 'terminating'
   | 'terminated'
 
+/**
+ * What the application keeps of the rc file.
+ *
+ * Structurally a subset of `ReamrcConfig`, declared here rather than imported:
+ * that type lives in `Ignitor.ts`, which imports this module, and naming it
+ * from here would close the cycle. Only the keys something reads back through
+ * `app.rcFile` are spelt out; the rest rides along untouched.
+ */
+export interface ReamrcContents {
+  directories?: Partial<DirectoriesNode>
+  /** `app/modules/**` auto-loading — opt-in, and scoped to named files. */
+  modules?: { path?: string; autoload?: string[] }
+}
+
 export class Application implements AppContext {
   readonly container: Container
   readonly config: ConfigStore
   #appRoot?: URL
   #directories: DirectoriesNode = { ...defaultDirectories }
+  #rcFile: ReamrcContents = {}
   #providers: ProviderContract[] = []
   #booted = false
   #environment: AppEnvironment = 'unknown'
@@ -68,6 +83,10 @@ export class Application implements AppContext {
   #packageJsonRead = false
   #packageJsonCache: { name?: string; version?: string } | undefined
   #mode: ApplicationMode = 'run'
+  /** Hooks that run — in reverse — when `terminate()` begins. */
+  #terminatingHooks: Array<() => Promise<void> | void> = []
+  /** Re-entrancy guard: two signals must terminate the application once. */
+  #terminating = false
   #bootingHooks: Array<() => Promise<void> | void> = []
   #bootedHooks: Array<() => Promise<void> | void> = []
   #shutdownHooks: Array<() => Promise<void> | void> = []
@@ -161,14 +180,27 @@ export class Application implements AppContext {
     return this.#directories
   }
 
+  /**
+   * The parsed rc file (AdonisJS `app.rcFile`).
+   *
+   * Kept whole, not just the keys this class acts on. A console command has the
+   * application and nothing else, so anything it needs to explain itself — why
+   * `app/modules/**` loaded nothing, say — has to be reachable from here. Empty
+   * until `rcContents()` has run.
+   */
+  get rcFile(): ReamrcContents {
+    return this.#rcFile
+  }
+
   /**
    * Feed the loaded rc file to the application (AdonisJS `rcContents`).
    *
-   * Today it reads one key, `directories`, merged over the defaults; the rest
-   * of the rc file is consumed by the Ignitor and the CLI, which own providers,
-   * preloads, commands and test suites.
+   * `directories` is merged over the defaults; the rest is stored as-is and
+   * read back through {@link rcFile}. Providers, preloads, commands and test
+   * suites are still consumed by the Ignitor and the CLI, which own them.
    */
-  rcContents(value: { directories?: Partial<DirectoriesNode> }): this {
+  rcContents(value: ReamrcContents): this {
+    this.#rcFile = value
     if (value.directories) {
       // Skip the undefined entries a `Partial` may carry: spreading them would
       // blank a default rather than leave it alone.
@@ -576,12 +608,56 @@ export class Application implements AppContext {
   }
 
   /**
-   * Graceful shutdown — stop all providers and exit.
-   * Like AdonisJS app.terminate().
+   * Register a hook that runs when the application begins to terminate
+   * (AdonisJS `app.terminating`).
+   *
+   * This is how the HTTP server closes on a signal: whoever opened the socket
+   * registers a hook that closes it, and `terminate()` runs them in reverse —
+   * last opened, first closed. Upstream's HTTP process does exactly this.
+   */
+  terminating(callback: () => Promise<void> | void): void {
+    this.#terminatingHooks.push(callback)
+  }
+
+  /**
+   * Graceful shutdown (AdonisJS `app.terminate()`).
+   *
+   * Runs the `terminating` hooks in reverse, then shuts the providers down.
+   * Two things it deliberately does NOT do:
+   *
+   * - It does not close the HTTP server itself. Whoever opened the socket
+   *   registers a `terminating` hook for it; the application does not know
+   *   what a server is. Terminating without one used to skip the close, the
+   *   error boundary and the service locators entirely.
+   * - It does not call `process.exit()`. Exiting from here cut the shutdown
+   *   short whenever a second path was already draining the server — and the
+   *   documented signal wiring set up exactly that race. The process ends when
+   *   nothing is left holding the loop, which is what "graceful" means.
+   *
+   * Re-entrant calls are ignored, so a SIGTERM handler and a crash handler
+   * firing together terminate once.
    */
   async terminate(): Promise<void> {
-    await this.shutdown()
-    process.exit(0)
+    if (this.#terminating) return
+    this.#terminating = true
+    const errors: unknown[] = []
+    for (const hook of [...this.#terminatingHooks].reverse()) {
+      try {
+        await hook()
+      } catch (err) {
+        errors.push(err)
+      }
+    }
+    this.#terminatingHooks = []
+    try {
+      await this.shutdown()
+    } catch (err) {
+      errors.push(err)
+    }
+    if (errors.length === 1) throw errors[0]
+    if (errors.length > 1) {
+      throw new AggregateError(errors, 'Application.terminate() completed with errors')
+    }
   }
 
   // ─── Provider lifecycle ───────────────────────────────────
@@ -640,6 +716,11 @@ export class Application implements AppContext {
    * from closing their resources (DB pools, queues). Errors are aggregated.
    */
   async shutdown(): Promise<void> {
+    // Idempotent: `terminate()` runs the `terminating` hooks and one of them is
+    // the Ignitor's `stop()`, which shuts the application down on its way. The
+    // second pass must not call every provider's `shutdown()` again — a pool
+    // closed twice, a socket destroyed twice.
+    if (this.#state === 'terminated') return
     const errors: unknown[] = []
     this.#state = 'terminating'
 

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)
+}