@guren/server 1.3.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/dist/{Application-DImeY-VW.d.ts → Application-Bi-olFMF.d.ts} +387 -18
  2. package/dist/{AuthManager-BU8ZvenF.d.ts → AuthManager-C84xF5ks.d.ts} +1 -1
  3. package/dist/{BroadcastManager-CGWl9rUO.d.ts → BroadcastManager-D8KoJxiV.d.ts} +21 -0
  4. package/dist/{CacheManager-BkvHEOZX.d.ts → CacheManager-BmDzUKrF.d.ts} +17 -0
  5. package/dist/ConsoleKernel-D0dkFt6u.d.ts +101 -0
  6. package/dist/{McpServiceProvider-RNTDHZAZ.js → McpServiceProvider-TZWQWXCT.js} +2 -2
  7. package/dist/{Scheduler-BstvSca7.d.ts → Scheduler-pZiT8i57.d.ts} +2 -0
  8. package/dist/{api-token-CB12xnVg.d.ts → api-token-COQHXyM_.d.ts} +68 -1
  9. package/dist/auth/index.d.ts +5 -5
  10. package/dist/auth/index.js +1 -1
  11. package/dist/authorization/index.js +2 -2
  12. package/dist/broadcasting/index.d.ts +2 -2
  13. package/dist/broadcasting/index.js +2 -1
  14. package/dist/cache/index.d.ts +2 -2
  15. package/dist/cache/index.js +2 -1
  16. package/dist/{chunk-EGU5KB7V.js → chunk-4SBGSJNT.js} +31 -1
  17. package/dist/{chunk-CSDKWLFD.js → chunk-5AD7LYWO.js} +111 -35
  18. package/dist/{chunk-THSX7OOR.js → chunk-63SKW5PS.js} +3 -0
  19. package/dist/{chunk-R2TCP7D7.js → chunk-6J6B5KOB.js} +18 -2
  20. package/dist/{chunk-VY2JPS6V.js → chunk-AUXQISW5.js} +83 -11
  21. package/dist/chunk-DCYKSYAT.js +63 -0
  22. package/dist/{chunk-ZRBLZY3M.js → chunk-FZD2AKJI.js} +1 -1
  23. package/dist/{chunk-HKQSAFSN.js → chunk-MC752CQT.js} +15 -0
  24. package/dist/{chunk-J753UWAY.js → chunk-NQCZQAJL.js} +93 -28
  25. package/dist/{chunk-STZUODC3.js → chunk-NYQGAWDN.js} +44 -1
  26. package/dist/{chunk-EDRGAM6G.js → chunk-RNXTRWKL.js} +2 -1
  27. package/dist/{chunk-CSP7W3WY.js → chunk-SHYRVOMJ.js} +2 -2
  28. package/dist/{chunk-44F7JQ7I.js → chunk-XMQZENBP.js} +35 -1
  29. package/dist/{chunk-WJJ5CTNI.js → chunk-Z3HXKWI6.js} +2 -2
  30. package/dist/{client-CKXJLsTe.d.ts → client-BQwF2b9Y.d.ts} +7 -0
  31. package/dist/{email-verification-D9u7krkn.d.ts → email-verification-H_WlpsVH.d.ts} +1 -1
  32. package/dist/{errors-JOOPDDQ6.js → errors-PUNHAFL2.js} +1 -1
  33. package/dist/index.d.ts +35 -17
  34. package/dist/index.js +329 -132
  35. package/dist/lambda/index.d.ts +7 -7
  36. package/dist/lambda/index.js +1 -1
  37. package/dist/mail/index.js +3 -3
  38. package/dist/mcp/index.d.ts +53 -19
  39. package/dist/mcp/index.js +2 -2
  40. package/dist/notifications/index.d.ts +57 -8
  41. package/dist/notifications/index.js +11 -3
  42. package/dist/queue/index.d.ts +7 -7
  43. package/dist/queue/index.js +4 -2
  44. package/dist/redis/index.d.ts +11 -21
  45. package/dist/redis/index.js +42 -6
  46. package/dist/runtime/index.d.ts +7 -7
  47. package/dist/runtime/index.js +1 -1
  48. package/dist/scheduling/index.d.ts +2 -2
  49. package/dist/scheduling/index.js +2 -1
  50. package/package.json +2 -2
  51. package/dist/ConsoleKernel-COKndy_V.d.ts +0 -207
@@ -1,18 +1,18 @@
1
1
  import * as hono from 'hono';
2
2
  import { Context, MiddlewareHandler, Hono, Next, ExecutionContext } from 'hono';
3
- import { l as OAuthManager, g as AuthContext, j as ApiToken, C as CreateSessionMiddlewareOptions } from './api-token-CB12xnVg.js';
4
- import { A as AuthManager } from './AuthManager-BU8ZvenF.js';
3
+ import { l as OAuthManager, g as AuthContext, j as ApiToken, C as CreateSessionMiddlewareOptions } from './api-token-COQHXyM_.js';
4
+ import { A as AuthManager } from './AuthManager-C84xF5ks.js';
5
5
  import { InlineConfig, ViteDevServer } from 'vite';
6
6
  import { E as EventManager } from './EventManager-CmIoLt7r.js';
7
- import { C as CacheManager } from './CacheManager-BkvHEOZX.js';
7
+ import { C as CacheManager } from './CacheManager-BmDzUKrF.js';
8
8
  import { M as MailManager } from './MailManager-DpMvYiP9.js';
9
9
  import { L as LogManager } from './LogManager-7mxnkaPM.js';
10
10
  import { I as I18nManager } from './I18nManager-CmUqj6bU.js';
11
- import { B as BroadcastManager } from './BroadcastManager-CGWl9rUO.js';
11
+ import { B as BroadcastManager } from './BroadcastManager-D8KoJxiV.js';
12
12
  import { E as Encrypter, A as AppKeyring } from './app-key-CsBfRC_Q.js';
13
13
  import { S as StorageManager } from './StorageManager-oZTHqaza.js';
14
14
  import { H as HealthManager } from './HealthManager-DUyMIzsZ.js';
15
- import { S as Scheduler } from './Scheduler-BstvSca7.js';
15
+ import { S as Scheduler } from './Scheduler-pZiT8i57.js';
16
16
  import { G as Gate } from './Gate-CynjZCtS.js';
17
17
  import { M as Middleware } from './index-9_Jzj5jo.js';
18
18
 
@@ -52,8 +52,13 @@ interface CsrfOptions {
52
52
  };
53
53
  }
54
54
  /**
55
- * Get the CSRF token from the current session.
56
- * Creates a new token if one doesn't exist.
55
+ * Get the request's CSRF token.
56
+ *
57
+ * Signed token bound to the session when a stable one exists, otherwise a
58
+ * stateless signed double-submit token for guests. Nothing is stored
59
+ * server-side, so anonymous page views cost no session writes. A cookie
60
+ * token that is still valid for this request's mode is reused; otherwise a
61
+ * fresh token is minted and set on the response by the middleware.
57
62
  */
58
63
  declare function getCsrfToken(ctx: Context): string;
59
64
  /**
@@ -61,16 +66,43 @@ declare function getCsrfToken(ctx: Context): string;
61
66
  */
62
67
  declare function csrfField(ctx: Context): string;
63
68
  /**
64
- * Verify that the provided token matches the session's CSRF token.
69
+ * Verify a request token.
70
+ *
71
+ * The token must first carry a valid app-key signature (proving this server
72
+ * minted it). Then, by mode:
73
+ * - **Session-bound** (token carries a `sid`): the id must match the live
74
+ * session. This is immune to cookie injection — a sibling-subdomain
75
+ * attacker can plant a cookie but cannot know the victim's session id.
76
+ * - **Stateless** (guest, no `sid`): the token must match the `XSRF-TOKEN`
77
+ * cookie (double-submit). Guests hold no authenticated state to protect.
78
+ *
79
+ * Legacy fallback: tokens stored in sessions by earlier releases keep
80
+ * verifying against the session until those sessions expire. Remove this
81
+ * branch once all pre-upgrade sessions have aged out (a major release).
65
82
  */
66
83
  declare function verifyCsrfToken(ctx: Context, token: string | undefined): boolean;
67
84
  /**
68
85
  * Creates a CSRF protection middleware.
69
86
  *
70
87
  * This middleware:
71
- * - Generates and stores a CSRF token in the session for GET requests
72
- * - Validates the CSRF token for state-changing HTTP methods (POST, PUT, PATCH, DELETE)
88
+ * - Issues a signed token in the `XSRF-TOKEN` cookie on safe requests.
89
+ * With a logged-in session the token is bound to the session id; for
90
+ * guests it is a stateless double-submit token. Nothing is stored
91
+ * server-side, so anonymous traffic costs no session writes and session
92
+ * middleware is optional.
93
+ * - Validates the token for state-changing HTTP methods (POST, PUT, PATCH,
94
+ * DELETE): always requires a valid app-key signature, then the bound
95
+ * session id or (guest) the cookie match.
73
96
  * - Supports token submission via form field (_token) or header (X-CSRF-TOKEN)
97
+ * - Keeps verifying tokens stored in sessions by earlier releases until
98
+ * those sessions expire
99
+ * - Exempts the dev-only MCP endpoint while it is mounted, since agent
100
+ * clients cannot fetch a token first (it guards local-only access instead)
101
+ *
102
+ * `cookie: false` disables the `XSRF-TOKEN` cookie for apps that deliver the
103
+ * token themselves (meta tag / form field). Session-bound tokens still
104
+ * verify without the cookie; guest (stateless) tokens require the cookie, so
105
+ * disable it only for session-authenticated flows.
74
106
  *
75
107
  * @example
76
108
  * ```ts
@@ -84,7 +116,15 @@ declare function verifyCsrfToken(ctx: Context, token: string | undefined): boole
84
116
  */
85
117
  declare function createCsrfMiddleware(options?: CsrfOptions): MiddlewareHandler;
86
118
 
87
- interface InertiaOptions {
119
+ /**
120
+ * Per-response form of {@link InertiaDocumentOptions}: the same fields, already
121
+ * resolved to strings. Each one overrides the app-wide default registered
122
+ * through {@link setInertiaDocument}.
123
+ */
124
+ type InertiaDocumentOverrides = {
125
+ readonly [K in keyof InertiaDocumentOptions]?: string;
126
+ };
127
+ interface InertiaOptions extends InertiaDocumentOverrides {
88
128
  readonly url?: string;
89
129
  readonly version?: string;
90
130
  readonly status?: number;
@@ -120,6 +160,74 @@ interface InertiaSsrOptions {
120
160
  manifest?: string;
121
161
  render?: InertiaSsrRenderer;
122
162
  }
163
+ interface InertiaDocumentContext {
164
+ /** Page component being rendered, e.g. `"Docs/Show"`. */
165
+ readonly component: string;
166
+ }
167
+ type InertiaDocumentValue = string | ((context: InertiaDocumentContext) => string | undefined);
168
+ interface InertiaDocumentOptions {
169
+ /**
170
+ * Class attribute for the root `<body>` element. Pass a function to vary it
171
+ * per page component — a docs section that needs a light surface while the
172
+ * marketing pages keep a dark one, for instance.
173
+ */
174
+ readonly bodyClass?: InertiaDocumentValue;
175
+ /**
176
+ * CSS inlined into `<head>` ahead of the stylesheet links. Keep it to the
177
+ * few declarations that decide the first paint (surface and text colors);
178
+ * the main stylesheet still wins for everything it defines later.
179
+ */
180
+ readonly criticalCss?: InertiaDocumentValue;
181
+ /**
182
+ * Body of a blocking inline `<script>` executed before the first paint.
183
+ * Use it for theme prepaint logic that has to read `localStorage` or
184
+ * `matchMedia` before React hydrates.
185
+ */
186
+ readonly prepaintScript?: InertiaDocumentValue;
187
+ /**
188
+ * Raw markup inlined into `<head>`, ahead of the critical CSS and stylesheet
189
+ * links. Unescaped — the app author owns this string. Use it for static,
190
+ * site-wide tags the framework has no way to infer on its own, such as
191
+ * `<link rel="icon">` favicons.
192
+ */
193
+ readonly head?: InertiaDocumentValue;
194
+ }
195
+ /**
196
+ * Register app-wide document defaults for server-rendered Inertia responses.
197
+ *
198
+ * Without this, the `<body>` ships without a class and nothing is inlined into
199
+ * `<head>`, so a page whose theme is applied by a client effect flashes the
200
+ * stylesheet's default surface color until React hydrates. Call it at module
201
+ * scope in the app entry so every runtime (Bun, serverless handlers, generated
202
+ * worker bundles) picks it up.
203
+ *
204
+ * Registration is process-wide and not request-scoped: calling this while
205
+ * requests are in flight leaks the new policy into them. Use the matching
206
+ * {@link InertiaOptions} fields for a single response instead.
207
+ *
208
+ * The values are emitted verbatim — inside `<style>` / `<script>` elements,
209
+ * or as raw markup for `head` — they are developer-authored assets, never
210
+ * user input.
211
+ *
212
+ * ```typescript
213
+ * setInertiaDocument({
214
+ * bodyClass: ({ component }) => (component.startsWith('Docs/') ? 'docs-theme' : undefined),
215
+ * })
216
+ * ```
217
+ *
218
+ * Pass `undefined` to clear (test isolation).
219
+ */
220
+ declare function setInertiaDocument(options: InertiaDocumentOptions | undefined): void;
221
+ /**
222
+ * Register a process-wide default SSR renderer.
223
+ *
224
+ * Serverless adapters whose bundlers cannot resolve a runtime file path
225
+ * (Cloudflare Workers has no filesystem for `GUREN_INERTIA_SSR_ENTRY`'s
226
+ * dynamic import) register the statically imported renderer once at module
227
+ * scope. Per-call `ssr.render` still takes precedence; pass `undefined` to
228
+ * clear (test isolation).
229
+ */
230
+ declare function setInertiaSsrRenderer(renderer: InertiaSsrRenderer | undefined): void;
123
231
  declare function inertia(component: string, props: Record<string, unknown>, options?: InertiaOptions): Promise<Response>;
124
232
 
125
233
  /**
@@ -531,6 +639,17 @@ declare function getQueueDriver(): QueueDriver | null;
531
639
  * ```
532
640
  */
533
641
  declare abstract class Job<T = unknown> {
642
+ /**
643
+ * Stable wire name for this job.
644
+ *
645
+ * Queued messages record this name, and the worker resolves the class back
646
+ * from it. When omitted the class name is used, which breaks if a bundler
647
+ * mangles identifiers or if the class is later renamed while messages are
648
+ * still in flight. Set it to pin the name across both.
649
+ *
650
+ * @default the class name
651
+ */
652
+ static jobName?: string;
534
653
  /**
535
654
  * The queue this job should be dispatched to.
536
655
  * @default 'default'
@@ -587,6 +706,7 @@ declare abstract class Job<T = unknown> {
587
706
  interface JobClass<T = unknown> {
588
707
  new (): Job<T>;
589
708
  name: string;
709
+ jobName?: string;
590
710
  queue: string;
591
711
  maxAttempts: number;
592
712
  backoff: 'exponential' | 'linear' | number;
@@ -594,6 +714,18 @@ interface JobClass<T = unknown> {
594
714
  dispatchAfter(delayMs: number, payload: T, options?: Omit<JobOptions, 'delay'>): Promise<string>;
595
715
  calculateRetryDelay(attempts: number): number;
596
716
  }
717
+ /**
718
+ * Resolve the wire name a job is queued and looked up under.
719
+ *
720
+ * Prefers an explicit `jobName` over the class name so that renaming the class
721
+ * or bundling with identifier mangling does not orphan queued messages.
722
+ *
723
+ * Only an *own* `jobName` counts. Static members are inherited, so reading it
724
+ * off the prototype chain would make every subclass of a pinned job claim its
725
+ * parent's identity and overwrite it in the registry. A subclass that wants a
726
+ * pinned name declares its own.
727
+ */
728
+ declare function resolveJobName(jobClass: Pick<JobClass, 'name' | 'jobName'>): string;
597
729
  /**
598
730
  * Register a job class for the worker to use.
599
731
  */
@@ -804,6 +936,14 @@ interface Notifiable {
804
936
  * Get the notification routing information for a given channel.
805
937
  */
806
938
  routeNotificationFor(channel: string): string | null;
939
+ /**
940
+ * Stable type name for this notifiable (optional).
941
+ *
942
+ * Defaults to the constructor name. Set this when the notifiable is rebuilt
943
+ * from a queue payload, or when the class name is not durable (bundlers that
944
+ * mangle identifiers).
945
+ */
946
+ notifiableType?: string;
807
947
  /**
808
948
  * Database notifications (optional).
809
949
  */
@@ -1013,16 +1153,28 @@ declare class NotificationManager {
1013
1153
  sendNowToMany(notifiables: Notifiable[], notification: Notification): Promise<void>;
1014
1154
  /**
1015
1155
  * Serialize notifiable for queue storage.
1156
+ *
1157
+ * Routing is resolved here rather than in the worker: `routeNotificationFor`
1158
+ * is arbitrary user code — often a closure on an object literal — and cannot
1159
+ * be reconstructed from a payload.
1160
+ *
1161
+ * @param channels - Channels to resolve routes for
1016
1162
  */
1017
- protected serializeNotifiable(notifiable: Notifiable): SerializedNotifiable;
1163
+ protected serializeNotifiable(notifiable: Notifiable, channels?: string[]): SerializedNotifiable;
1018
1164
  /**
1019
1165
  * Serialize notification for queue storage.
1166
+ *
1167
+ * Only own enumerable properties are captured. Behaviour is restored by
1168
+ * rebuilding the registered class in the job handler, not by serializing it.
1020
1169
  */
1021
1170
  protected serializeNotification(notification: Notification): SerializedNotification;
1022
1171
  /**
1023
- * Create the notification job class.
1172
+ * Bind this manager to the queued-notification job and register it.
1173
+ *
1174
+ * Call this during boot in a process that runs a worker but may never send
1175
+ * a notification itself: without it, the worker cannot resolve the job.
1024
1176
  */
1025
- protected createNotificationJob(): typeof SendNotificationJob;
1177
+ registerQueueJob(): typeof SendNotificationJob;
1026
1178
  }
1027
1179
  /**
1028
1180
  * Payload for queued notifications.
@@ -1034,11 +1186,13 @@ interface SendNotificationPayload {
1034
1186
  }
1035
1187
  interface SerializedNotifiable {
1036
1188
  type: string;
1189
+ /** Channel routes resolved at dispatch time. Absent on legacy payloads. */
1190
+ routes?: Record<string, string | null>;
1037
1191
  data: Record<string, unknown>;
1038
1192
  }
1039
1193
  interface SerializedNotification {
1040
- type: string;
1041
1194
  id: string;
1195
+ createdAt: string;
1042
1196
  data: Record<string, unknown>;
1043
1197
  }
1044
1198
  /**
@@ -1050,6 +1204,18 @@ declare class SendNotificationJob extends Job<SendNotificationPayload> {
1050
1204
  static maxAttempts: number;
1051
1205
  static notificationManager: NotificationManager | null;
1052
1206
  handle(payload: SendNotificationPayload): Promise<void>;
1207
+ /**
1208
+ * Rebuild the notifiable from its serialized data.
1209
+ */
1210
+ protected rebuildNotifiable(serialized: SerializedNotifiable): Notifiable;
1211
+ /**
1212
+ * Rebuild a real notification instance from its serialized data.
1213
+ *
1214
+ * The class is looked up in the notification registry and instantiated via
1215
+ * its prototype, so prototype methods (`via`, `toMail`, `toDatabase`,
1216
+ * `toSlack`, `shouldSend`) are restored without running the constructor.
1217
+ */
1218
+ protected rebuildNotification(type: string, serialized: SerializedNotification): Notification;
1053
1219
  }
1054
1220
  /**
1055
1221
  * Set the global notification manager.
@@ -1787,6 +1953,8 @@ type ModelBindingResolver = (value: string) => Promise<unknown>;
1787
1953
  */
1788
1954
  interface BindableModel {
1789
1955
  findOrFail(id: unknown, key?: string): Promise<unknown>;
1956
+ /** Bound values are model classes at runtime; the constructor name is the introspection payload. */
1957
+ readonly name?: string;
1790
1958
  }
1791
1959
  type SchemaLike<T = unknown> = ValidationSchema<T> | undefined;
1792
1960
  type InferSchema<TSchema extends SchemaLike<unknown>> = TSchema extends ValidationSchema<infer TValue> ? TValue : never;
@@ -1848,6 +2016,8 @@ interface RouteDefinition {
1848
2016
  name: string;
1849
2017
  action: string;
1850
2018
  };
2019
+ /** Route model bindings: param name → bound model class name (from `bind`) */
2020
+ bindings?: Record<string, string>;
1851
2021
  summary?: string;
1852
2022
  description?: string;
1853
2023
  tags?: string[];
@@ -1892,6 +2062,8 @@ declare class Router<M extends string = never> {
1892
2062
  private readonly middlewareAliases;
1893
2063
  private readonly middlewareGroups;
1894
2064
  private readonly modelBindings;
2065
+ /** Model class names for router-level bind(param, Model) calls — resolver-only binds carry no name. */
2066
+ private readonly modelBindingNames;
1895
2067
  aliasMiddleware<N extends string>(name: N, handler: MiddlewareHandler): Router<M | N>;
1896
2068
  groupMiddleware<N extends string>(name: N, middlewareNames: M[]): Router<M | N>;
1897
2069
  middleware(...names: M[]): RouterMiddlewareGroupBuilder<M>;
@@ -2046,6 +2218,198 @@ declare class ProviderManager {
2046
2218
  getDeferredServices(): string[];
2047
2219
  }
2048
2220
 
2221
+ /**
2222
+ * Parsed argument definition.
2223
+ */
2224
+ interface ArgumentDefinition {
2225
+ name: string;
2226
+ description?: string;
2227
+ required: boolean;
2228
+ array: boolean;
2229
+ defaultValue?: string;
2230
+ }
2231
+ /**
2232
+ * Parsed option definition.
2233
+ */
2234
+ interface OptionDefinition {
2235
+ name: string;
2236
+ shortcut?: string;
2237
+ description?: string;
2238
+ requiresValue: boolean;
2239
+ defaultValue?: string | boolean;
2240
+ array: boolean;
2241
+ }
2242
+ /**
2243
+ * Parsed signature.
2244
+ */
2245
+ interface ParsedSignature {
2246
+ name: string;
2247
+ arguments: ArgumentDefinition[];
2248
+ options: OptionDefinition[];
2249
+ }
2250
+ /**
2251
+ * Command class type.
2252
+ */
2253
+ interface CommandClass {
2254
+ signature: string;
2255
+ description: string;
2256
+ new (container?: Container): CommandInstance;
2257
+ }
2258
+ /**
2259
+ * Command instance type.
2260
+ */
2261
+ interface CommandInstance {
2262
+ setInput(argv: string[]): void;
2263
+ setOutput(output: OutputInterface): void;
2264
+ setKernel(kernel: {
2265
+ handle(argv: string[]): Promise<number>;
2266
+ }): void;
2267
+ run(): Promise<number>;
2268
+ }
2269
+ /**
2270
+ * Output interface.
2271
+ */
2272
+ interface OutputInterface {
2273
+ info(message: string): void;
2274
+ error(message: string): void;
2275
+ warn(message: string): void;
2276
+ success(message: string): void;
2277
+ line(message: string): void;
2278
+ newLine(count?: number): void;
2279
+ table(headers: string[], rows: string[][]): void;
2280
+ write(message: string): void;
2281
+ }
2282
+ /**
2283
+ * Input interface.
2284
+ */
2285
+ interface InputInterface {
2286
+ argument<T = string>(name: string): T;
2287
+ arguments(): Record<string, string | string[]>;
2288
+ option<T = string | boolean>(name: string): T | undefined;
2289
+ options(): Record<string, string | boolean | string[]>;
2290
+ hasOption(name: string): boolean;
2291
+ }
2292
+ /**
2293
+ * Console kernel options.
2294
+ */
2295
+ interface ConsoleKernelOptions {
2296
+ container?: Container;
2297
+ }
2298
+ /**
2299
+ * Schedule definition for a command.
2300
+ */
2301
+ interface ScheduledCommand {
2302
+ command: string;
2303
+ args?: string[];
2304
+ expression: string;
2305
+ timezone?: string;
2306
+ description?: string;
2307
+ }
2308
+ /**
2309
+ * Interactive prompt types.
2310
+ */
2311
+ interface PromptInterface {
2312
+ ask(question: string, defaultValue?: string): Promise<string>;
2313
+ confirm(question: string, defaultValue?: boolean): Promise<boolean>;
2314
+ choice<T extends string>(question: string, choices: T[], defaultValue?: T): Promise<T>;
2315
+ secret(question: string): Promise<string>;
2316
+ }
2317
+ /**
2318
+ * Progress bar interface.
2319
+ */
2320
+ interface ProgressInterface {
2321
+ start(total: number): void;
2322
+ advance(step?: number): void;
2323
+ finish(): void;
2324
+ setProgress(current: number): void;
2325
+ }
2326
+
2327
+ /**
2328
+ * Declarative definition of an application module — a self-contained
2329
+ * `modules/<name>/` directory that can register routes and providers, per
2330
+ * RFC 0002. Unlike `definePlugin()`, a module has no config stage and no
2331
+ * register/boot lifecycle of its own: it's a plain descriptor bundling
2332
+ * providers and a route registrar that `Application` folds into its own
2333
+ * provider list and route mounting.
2334
+ */
2335
+ interface ModuleDefinition {
2336
+ /** Diagnostic name; also the expected directory name under `modules/`. */
2337
+ name: string;
2338
+ /**
2339
+ * URL prefix applied to all module routes via `router.group(prefix, ...)`.
2340
+ * Declarative on purpose — tooling can read a module's URL surface
2341
+ * statically without executing the registrar.
2342
+ */
2343
+ prefix?: string;
2344
+ /** Route registrar, invoked after `options.routes` during boot. */
2345
+ routes?: (router: Router) => void | Promise<void>;
2346
+ /** Providers appended to the application's provider list. */
2347
+ providers?: ServiceProviderConstructor[];
2348
+ /**
2349
+ * Console commands the module owns, exposed so the project's console
2350
+ * entrypoint can register them without importing module internals:
2351
+ * `kernel.registerMany(billingModule.commands)`. Nothing registers them
2352
+ * automatically — `Application` never builds a `ConsoleKernel`, and
2353
+ * command registration stays explicit so a bundled deployment resolves
2354
+ * the same commands as a local checkout.
2355
+ */
2356
+ commands?: CommandClass[];
2357
+ }
2358
+ /**
2359
+ * A module as `Application` consumes it — `providers` and `commands`
2360
+ * normalized to always be arrays so callers don't repeat the `?? []`
2361
+ * fallback. `commands` in particular is read by hand-written console
2362
+ * entrypoints (`kernel.registerMany(billingModule.commands)`), where an
2363
+ * `undefined` would be a runtime error rather than a no-op.
2364
+ */
2365
+ interface GurenModule {
2366
+ name: string;
2367
+ prefix?: string;
2368
+ routes?: (router: Router) => void | Promise<void>;
2369
+ providers: ServiceProviderConstructor[];
2370
+ commands: CommandClass[];
2371
+ }
2372
+ /**
2373
+ * Define a Guren application module without boilerplate.
2374
+ *
2375
+ * @example
2376
+ * ```typescript
2377
+ * // modules/billing/index.ts
2378
+ * export const billingModule = defineModule({
2379
+ * name: 'billing',
2380
+ * prefix: '/billing',
2381
+ * routes: registerBillingRoutes,
2382
+ * providers: [BillingServiceProvider],
2383
+ * commands: [InvoiceCommand],
2384
+ * })
2385
+ *
2386
+ * // src/app.ts
2387
+ * createApp({ routes, providers, modules: [billingModule] })
2388
+ *
2389
+ * // src/console.ts
2390
+ * kernel.registerMany(billingModule.commands)
2391
+ * ```
2392
+ */
2393
+ declare function defineModule(definition: ModuleDefinition): GurenModule;
2394
+ /**
2395
+ * Runs a module's route registrar against `router`, applying its `prefix`
2396
+ * via `router.group()` when set. Shared by `Application.mountRoutes()` (at
2397
+ * boot) and the CLI's route loader (for `guren codegen`/`audit`/`routes`/
2398
+ * `openapi:generate`, which need the same route set without booting a real
2399
+ * app) so both stay in sync — a bugfix to one path fixes the other.
2400
+ *
2401
+ * `router.group(prefix, callback)`'s callback is synchronous — it pushes
2402
+ * the prefix, invokes the callback, then pops it, with no support for
2403
+ * awaiting inside. Capturing the registrar's return value and awaiting it
2404
+ * after `group()` returns preserves prefixing for the common case (a
2405
+ * synchronous registrar, or an async one that calls `router.get`/`post`/
2406
+ * etc. before its first `await`); route calls after an `await` inside an
2407
+ * async, prefixed module registrar would run with the prefix already
2408
+ * popped. Registrars with no prefix don't go through group() and have no
2409
+ * such limitation.
2410
+ */
2411
+ declare function mountModuleRoutes(router: Router, gurenModule: GurenModule): Promise<void>;
2412
+
2049
2413
  declare const GUREN_ASCII_ART: string;
2050
2414
  interface DevBannerOptions {
2051
2415
  hostname: string;
@@ -2077,6 +2441,12 @@ interface ApplicationOptions {
2077
2441
  readonly auth?: AuthPluginOptions;
2078
2442
  readonly discover?: boolean;
2079
2443
  readonly routes?: RouteRegistration;
2444
+ /**
2445
+ * Application modules (RFC 0002) — each module's providers are appended
2446
+ * to `providers` below, and its route registrar runs after `routes`
2447
+ * (wrapped in `router.group(prefix, ...)` when the module declares one).
2448
+ */
2449
+ readonly modules?: GurenModule[];
2080
2450
  readonly features?: ApplicationFeatures;
2081
2451
  /**
2082
2452
  * Configure or disable the default security headers middleware.
@@ -2152,8 +2522,7 @@ declare class Application {
2152
2522
  private mountSecurityDefaults;
2153
2523
  private mountHostAuthorization;
2154
2524
  /**
2155
- * Mounts the MCP endpoint at /_guren/mcp when explicitly enabled.
2156
- * Requires GUREN_MCP=1 environment variable. Never active in production.
2525
+ * Mounts the MCP endpoint at /_guren/mcp when enabled.
2157
2526
  * This allows AI coding agents to introspect the project.
2158
2527
  */
2159
2528
  private mountMcpEndpoint;
@@ -2183,4 +2552,4 @@ declare class Application {
2183
2552
  }
2184
2553
  declare function createApp(options?: ApplicationOptions): Application;
2185
2554
 
2186
- export { Notification as $, Application as A, type HstsOptions as B, Container as C, type DevBannerOptions as D, type ErrorResponse as E, type FailedJob as F, GUREN_ASCII_ART as G, type HostAuthorizationOptions as H, type InertiaOptions as I, type InertiaPagePayload as J, type InertiaResponse as K, type InertiaSharedProps as L, type InertiaSsrContext as M, NotificationManager as N, type InertiaSsrOptions as O, type Provider as P, QueueManager as Q, type InertiaSsrRenderer as R, ServiceProvider as S, type InertiaSsrResult as T, type InferInertiaProps as U, Job as V, type JobClass as W, type JobFailureHandler as X, type JobHandler as Y, type JobOptions as Z, type Notifiable as _, type StartViteDevServerOptions as a, setExceptionHandler as a$, type NotificationAttachment as a0, type NotificationChannel as a1, type NotificationChannelFactory as a2, type NotificationClass as a3, type NotificationMailMessage as a4, type NotificationManagerOptions as a5, ProviderManager as a6, type QueueConfig as a7, type QueueDriver as a8, type QueueDriverFactory as a9, abortIf as aA, abortUnless as aB, clearJobRegistry as aC, createApp as aD, createContainer as aE, createCsrfMiddleware as aF, createExceptionHandler as aG, createHostAuthorizationMiddleware as aH, createNotificationManager as aI, createQueueManager as aJ, createSecurityHeaders as aK, csrfField as aL, formatValidationErrors as aM, getContainer as aN, getCsrfToken as aO, getExceptionHandler as aP, getInertiaSharedPropsResolver as aQ, getJob as aR, getNotificationManager as aS, getQueueDriver as aT, getRegisteredJobs as aU, getValidatedData as aV, inertia as aW, parseRequestPayload as aX, registerJob as aY, resolve as aZ, setContainer as a_, type QueuedJob as aa, type RendererRegistration as ab, type ResolvedSharedInertiaProps as ac, type ResourceRouteOptions as ad, type RouteBuilder as ae, type RouteContractOptions as af, type RouteDefinition as ag, type RouteOpenApiMetadata as ah, type ResourceAction as ai, Router as aj, type SecurityHeadersOptions as ak, type SentNotification as al, type ServiceBinding as am, type ServiceClass as an, type ServiceFactory as ao, type ServiceProviderClass as ap, type ServiceProviderOptions as aq, type SharedInertiaPropsResolver as ar, type SlackAttachment as as, type SlackBlock as at, type SlackMessage as au, VALIDATED_DATA_KEY as av, type ValidateRequestOptions as aw, type ValidationSchema as ax, type WorkerOptions as ay, abort as az, type StartedViteDevServer as b, setInertiaSharedProps as b0, setNotificationManager as b1, setQueueDriver as b2, shareInertiaProps as b3, validate as b4, validateRequest as b5, validateRequestWith as b6, validateSafe as b7, verifyCsrfToken as b8, type ServiceProviderConstructor as c, type ServiceBindings as d, type ApplicationListenOptions as e, type ApplicationOptions as f, type AuthPayload as g, type AuthPluginOptions as h, CSRF_FORM_FIELD as i, CSRF_HEADER_NAME as j, CSRF_TOKEN_KEY as k, logDevServerBanner as l, type ContextualBinding as m, type ContextualBindingBuilder as n, type ContextualNeedsBuilder as o, Controller as p, type ControllerInertiaProps as q, type CsrfOptions as r, startViteDevServer as s, type DatabaseChannelOptions as t, type DatabaseNotification as u, type ExceptionClass as v, ExceptionHandler as w, type ExceptionHandlerOptions as x, type ExceptionRenderer as y, type ExceptionReporter as z };
2555
+ export { type InertiaSsrContext as $, Application as A, type DatabaseNotification as B, type CommandClass as C, type DevBannerOptions as D, type ErrorResponse as E, type ExceptionClass as F, GUREN_ASCII_ART as G, ExceptionHandler as H, type InputInterface as I, type ExceptionHandlerOptions as J, type ExceptionRenderer as K, type ExceptionReporter as L, type FailedJob as M, NotificationManager as N, type OutputInterface as O, type ParsedSignature as P, QueueManager as Q, type GurenModule as R, ServiceProvider as S, type HostAuthorizationOptions as T, type HstsOptions as U, type InertiaDocumentContext as V, type InertiaDocumentOptions as W, type InertiaOptions as X, type InertiaPagePayload as Y, type InertiaResponse as Z, type InertiaSharedProps as _, Container as a, defineModule as a$, type InertiaSsrOptions as a0, type InertiaSsrRenderer as a1, type InertiaSsrResult as a2, type InferInertiaProps as a3, Job as a4, type JobClass as a5, type JobFailureHandler as a6, type JobHandler as a7, type JobOptions as a8, type ModuleDefinition as a9, type SentNotification as aA, type ServiceBinding as aB, type ServiceClass as aC, type ServiceFactory as aD, type ServiceProviderClass as aE, type ServiceProviderOptions as aF, type SharedInertiaPropsResolver as aG, type SlackAttachment as aH, type SlackBlock as aI, type SlackMessage as aJ, VALIDATED_DATA_KEY as aK, type ValidateRequestOptions as aL, type ValidationSchema as aM, type WorkerOptions as aN, abort as aO, abortIf as aP, abortUnless as aQ, clearJobRegistry as aR, createApp as aS, createContainer as aT, createCsrfMiddleware as aU, createExceptionHandler as aV, createHostAuthorizationMiddleware as aW, createNotificationManager as aX, createQueueManager as aY, createSecurityHeaders as aZ, csrfField as a_, type Notifiable as aa, Notification as ab, type NotificationAttachment as ac, type NotificationChannel as ad, type NotificationChannelFactory as ae, type NotificationClass as af, type NotificationMailMessage as ag, type NotificationManagerOptions as ah, type ProgressInterface as ai, type PromptInterface as aj, ProviderManager as ak, type QueueConfig as al, type QueueDriver as am, type QueueDriverFactory as an, type QueuedJob as ao, type RendererRegistration as ap, type ResolvedSharedInertiaProps as aq, type ResourceRouteOptions as ar, type RouteBuilder as as, type RouteContractOptions as at, type RouteDefinition as au, type RouteOpenApiMetadata as av, type ResourceAction as aw, Router as ax, type ScheduledCommand as ay, type SecurityHeadersOptions as az, type ConsoleKernelOptions as b, formatValidationErrors as b0, getContainer as b1, getCsrfToken as b2, getExceptionHandler as b3, getInertiaSharedPropsResolver as b4, getJob as b5, getNotificationManager as b6, getQueueDriver as b7, getRegisteredJobs as b8, getValidatedData as b9, inertia as ba, mountModuleRoutes as bb, parseRequestPayload as bc, registerJob as bd, resolve as be, resolveJobName as bf, setContainer as bg, setExceptionHandler as bh, setInertiaDocument as bi, setInertiaSharedProps as bj, setInertiaSsrRenderer as bk, setNotificationManager as bl, setQueueDriver as bm, shareInertiaProps as bn, validate as bo, validateRequest as bp, validateRequestWith as bq, validateSafe as br, verifyCsrfToken as bs, type StartViteDevServerOptions as c, type StartedViteDevServer as d, type ServiceProviderConstructor as e, type OptionDefinition as f, type CommandInstance as g, type ServiceBindings as h, type ApplicationListenOptions as i, type ApplicationOptions as j, type ArgumentDefinition as k, logDevServerBanner as l, type AuthPayload as m, type AuthPluginOptions as n, CSRF_FORM_FIELD as o, CSRF_HEADER_NAME as p, CSRF_TOKEN_KEY as q, type Provider as r, startViteDevServer as s, type ContextualBinding as t, type ContextualBindingBuilder as u, type ContextualNeedsBuilder as v, Controller as w, type ControllerInertiaProps as x, type CsrfOptions as y, type DatabaseChannelOptions as z };
@@ -1,6 +1,6 @@
1
1
  import { Context } from 'hono';
2
2
  import { Model } from '@guren/orm';
3
- import { A as Authenticatable, U as UserProvider, a as AuthCredentials, b as AuthManagerContract, c as AuthManagerOptions, G as GuardFactory, P as ProviderFactory, d as GuardContext, e as Guard, f as AttachContextOptions, g as AuthContext } from './api-token-CB12xnVg.js';
3
+ import { A as Authenticatable, U as UserProvider, a as AuthCredentials, b as AuthManagerContract, c as AuthManagerOptions, G as GuardFactory, P as ProviderFactory, d as GuardContext, e as Guard, f as AttachContextOptions, g as AuthContext } from './api-token-COQHXyM_.js';
4
4
 
5
5
  interface PasswordHasher {
6
6
  hash(plain: string): Promise<string>;
@@ -450,6 +450,21 @@ declare class BroadcastManager {
450
450
  * Get clients subscribed to a channel.
451
451
  */
452
452
  getChannelClients(channel: string): SSEClient[];
453
+ /**
454
+ * Close every SSE connection this manager is holding.
455
+ *
456
+ * Each connection owns a ping timer that is only cleared when the stream is
457
+ * cancelled or the request aborts. `Bun.serve().stop()` without forcing waits
458
+ * for in-flight requests instead of cutting them, and an SSE response never
459
+ * finishes — so on a hot reload those connections outlive the manager, and
460
+ * their timers go on pinging a stream nobody reads.
461
+ *
462
+ * `getClients()` returns a snapshot. A `Map` iterator does tolerate an entry
463
+ * deleting itself, which is all `cleanup()` does today — but not a `close()`
464
+ * that reaches another client, which would drop that one from the iteration
465
+ * unvisited and leave its timer running.
466
+ */
467
+ disconnectAll(): void;
453
468
  /**
454
469
  * Generate a unique client ID.
455
470
  */
@@ -465,6 +480,12 @@ declare function setBroadcastManager(manager: BroadcastManager): void;
465
480
  declare function getBroadcastManager(): BroadcastManager;
466
481
  /**
467
482
  * Create a broadcast manager.
483
+ *
484
+ * Under `bun --hot`, the manager this one replaces has its SSE connections
485
+ * closed first, so their ping timers stop with it. Registered from the factory
486
+ * rather than the constructor because the factory is what application code
487
+ * calls: frame 2 of the stack is the provider that built the manager, not this
488
+ * file. A bare `new BroadcastManager()` is left alone.
468
489
  */
469
490
  declare function createBroadcastManager(options?: BroadcastManagerOptions): BroadcastManager;
470
491
 
@@ -200,6 +200,15 @@ declare class CacheManager {
200
200
  private readonly defaultStoreName;
201
201
  private readonly storeFactories;
202
202
  private readonly resolvedStores;
203
+ /**
204
+ * Where this manager was built, for identifying its stores across hot reloads.
205
+ *
206
+ * Captured here rather than in `store()` because stores resolve lazily, from
207
+ * whichever request first asks for one — a call site that says nothing about
208
+ * which manager owns the result. Skipped outside `--hot`, where it would be a
209
+ * formatted stack string held for the manager's lifetime and never read.
210
+ */
211
+ private readonly builtAt;
203
212
  constructor(config?: CacheConfig);
204
213
  private driverFactories;
205
214
  /**
@@ -215,6 +224,14 @@ declare class CacheManager {
215
224
  * Returns the default store if no name is specified.
216
225
  */
217
226
  store(name?: string): TaggableCacheStore;
227
+ /**
228
+ * Under `bun --hot`, stops the sweep timer held by the store this one replaces.
229
+ *
230
+ * Registered from here rather than from `MemoryStore` itself because this is
231
+ * where the store's name is known, and the name is what keeps two memory
232
+ * stores in one config from sharing a slot and cancelling each other's sweep.
233
+ */
234
+ private stopPreviousStore;
218
235
  /**
219
236
  * Register a custom store factory.
220
237
  */