@sigil-dev/grimoire 0.9.3 → 0.9.5

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 (78) hide show
  1. package/index.ts +37 -35
  2. package/package.json +9 -12
  3. package/preload.js +3 -3
  4. package/server.ts +19 -19
  5. package/src/client/deps.ts +36 -19
  6. package/src/client/enhance.ts +102 -98
  7. package/src/client/head.ts +30 -30
  8. package/src/client/index.ts +2 -2
  9. package/src/client/router.ts +174 -68
  10. package/src/client/scope.ts +22 -22
  11. package/src/dev/compile-module.ts +215 -163
  12. package/src/dev/effect-registry.ts +23 -23
  13. package/src/dev/graph.ts +109 -114
  14. package/src/dev/hmr-client.ts +202 -185
  15. package/src/dev/hmr-server.ts +261 -187
  16. package/src/dev/loader.ts +120 -47
  17. package/src/dev/paths.ts +14 -14
  18. package/src/dev/resolve.ts +70 -0
  19. package/src/dev/runtime-bundle.ts +52 -52
  20. package/src/dev/scan.ts +78 -0
  21. package/src/dev/watcher.ts +69 -47
  22. package/src/env/dynamic-private.ts +19 -19
  23. package/src/env/dynamic-public.ts +22 -22
  24. package/src/env/index.ts +25 -25
  25. package/src/env/plugin.ts +19 -19
  26. package/src/env/private.ts +5 -5
  27. package/src/env/public.ts +7 -7
  28. package/src/env/typegen.ts +61 -61
  29. package/src/headers.ts +114 -114
  30. package/src/integrations/vite.ts +73 -73
  31. package/src/logger/index.ts +4 -4
  32. package/src/logger/instance.ts +6 -6
  33. package/src/logger/logger.ts +113 -113
  34. package/src/logger/request-middleware.ts +24 -24
  35. package/src/logger/transports.ts +117 -117
  36. package/src/logger/types.ts +39 -39
  37. package/src/rendering/head.ts +52 -47
  38. package/src/rendering/hydrate.ts +159 -138
  39. package/src/rendering/index.ts +140 -18
  40. package/src/rendering/ssrPlugin.ts +78 -69
  41. package/src/routing/manifest-gen.ts +13 -1
  42. package/src/routing/router.ts +135 -109
  43. package/src/routing/scanner.ts +196 -141
  44. package/src/routing/transform-routes.ts +102 -102
  45. package/src/sentinels/error.ts +52 -52
  46. package/src/sentinels/fail.ts +41 -41
  47. package/src/sentinels/redirect.ts +35 -35
  48. package/src/server/build.ts +250 -243
  49. package/src/server/context.ts +10 -10
  50. package/src/server/cookie-utils.ts +66 -66
  51. package/src/server/coordinator.ts +364 -364
  52. package/src/server/hooks.ts +114 -114
  53. package/src/server/index.ts +711 -655
  54. package/src/server/interactive.ts +56 -56
  55. package/src/server/plugins.ts +121 -121
  56. package/src/server/worker.ts +58 -58
  57. package/src/typegen/index.ts +389 -356
  58. package/src/types.ts +286 -282
  59. package/test/client-router.test.ts +295 -44
  60. package/test/context.test.ts +52 -52
  61. package/test/env.test.ts +90 -90
  62. package/test/exports.test.ts +37 -37
  63. package/test/fail.test.ts +46 -46
  64. package/test/headers.test.ts +100 -100
  65. package/test/hmr.test.ts +426 -0
  66. package/test/hydration.test.ts +119 -119
  67. package/test/middleware.test.ts +223 -223
  68. package/test/preload.ts +5 -5
  69. package/test/redirect-error.test.ts +112 -112
  70. package/test/rendering.test.ts +719 -615
  71. package/test/routing.test.ts +197 -81
  72. package/test/scanning.test.ts +314 -200
  73. package/test/scope.test.ts +195 -195
  74. package/test/server.test.ts +360 -249
  75. package/test/streaming.test.ts +242 -125
  76. package/test/transform-routes.test.ts +87 -84
  77. package/test/typegen.test.ts +697 -682
  78. package/tsconfig.json +10 -10
package/src/types.ts CHANGED
@@ -1,282 +1,286 @@
1
- import type { Server, ServerWebSocket } from "bun";
2
- import type { ScopedLogger } from "./logger";
3
- import type { RouteFile, RouteTree } from "./routing/scanner";
4
-
5
- /// <reference types="bun-types">
6
- declare global {
7
- namespace App {
8
- // augment in your own project via src/app.d.ts
9
- interface Locals {}
10
- interface Error {
11
- message: string;
12
- status?: number;
13
- }
14
- interface PageData {}
15
- interface Platform {}
16
- }
17
- }
18
-
19
- export interface Route {
20
- path: string; // /blog/:slug
21
- params: Record<string, string>;
22
- filePath: string; // absolute path to +page.tsx
23
- loadPath?: string; // absolute path to +page.ts
24
- serverPath?: string; // absolute path to +server.ts
25
- layoutPath?: string; // absolute path to +layout.tsx
26
- }
27
-
28
- export interface RouteInfo {
29
- path: string; // /blog/:slug
30
- filePath: string; // absolute path
31
- type: string; // page, layout etc
32
- }
33
-
34
- export interface LoadContext {
35
- request: Request;
36
- params: Record<string, string>;
37
- url: URL;
38
- locals: Record<string, unknown>; // set by plugins/hooks
39
- fetch: typeof globalThis.fetch; // ← add
40
- }
41
-
42
- export interface TypedLoadContext<
43
- P extends Record<string, string> = Record<string, string>,
44
- > {
45
- request: Request;
46
- params: P;
47
- url: URL;
48
- locals: App.Locals;
49
- fetch: typeof fetch;
50
- }
51
-
52
- export interface RenderContext {
53
- route: RouteInfo;
54
- request: Request;
55
- params: Record<string, string>;
56
- data: unknown; // return value of load()
57
- }
58
-
59
- export interface PluginContext {
60
- mode: "development" | "production";
61
- plugins: ReadonlyMap<string, GrimoirePlugin>;
62
- logger: ScopedLogger;
63
- }
64
-
65
- export interface BuildResult {
66
- success: boolean;
67
- outputs: string[];
68
- errors: string[];
69
- }
70
-
71
- export interface GrimoirePlugin {
72
- name: string;
73
-
74
- // plugin lifecycle
75
- onPluginsResolved?(ctx: PluginContext): void | Promise<void>;
76
-
77
- // server lifecycle
78
- // we dont care about what the impl puts as websocket data therefore unknown.
79
- onStart?(server: Server<unknown>): void | Promise<void>;
80
- onStop?(reason: "shutdown" | "restart"): void | Promise<void>;
81
-
82
- // request pipeline
83
- onRequest?(
84
- req: Request,
85
- next: () => Promise<Response>,
86
- ): Response | Promise<Response>;
87
-
88
- // route lifecycle
89
- onRouteLoad?(route: Route, context: LoadContext): void | Promise<void>;
90
- /**
91
- * Called after the page HTML is fully rendered.
92
- * NOTE: When any plugin implements this hook, the streaming response is
93
- * buffered into a single string. Streaming is preserved for routes where
94
- * no plugin uses this hook. To avoid buffering, use onRequest to intercept
95
- * at the Response level.
96
- */
97
- onRouteRender?(
98
- html: string,
99
- context: RenderContext,
100
- ): string | Promise<string>;
101
-
102
- // build
103
- onBuildStart?(): void | Promise<void>;
104
- onBuildEnd?(result: BuildResult): void | Promise<void>;
105
-
106
- // config
107
- config?: (config: GrimoireConfig) => GrimoireConfig | undefined;
108
-
109
- // process lifecycle
110
-
111
- /**
112
- * Runs AFTER Sigil/Babel compilation. Receives compiled JS, not source TSX.
113
- * Suitable for string-level transforms (import rewriting, comment injection, etc.).
114
- * Return null/undefined to pass through unchanged.
115
- */
116
- transform?(
117
- code: string,
118
- id: string,
119
- ): string | null | undefined | Promise<string | null | undefined>;
120
-
121
- /**
122
- * Fires once after all workers are spawned and ready.
123
- * Use for coordinator-level setup (e.g. opening a shared store).
124
- */
125
- onCoordinatorStart?(ctx: CoordinatorContext): void | Promise<void>;
126
-
127
- /**
128
- * Fires for each worker before Bun.spawn is called.
129
- * Return WorkerEnv to inject env vars or set the worker name.
130
- * ALL plugins are called and results are merged.
131
- */
132
- onWorkerSpawn?(
133
- worker: WorkerDescriptor,
134
- // biome-ignore lint/suspicious/noConfusingVoidType: doesn't have to return a thing.
135
- ): WorkerEnv | void | Promise<WorkerEnv | void>;
136
-
137
- /**
138
- * Fires when a worker process is up and accepting requests.
139
- */
140
- onWorkerReady?(worker: WorkerDescriptor): void | Promise<void>;
141
-
142
- /**
143
- * Fires when a worker process exits.
144
- * reason "crash" = unexpected exit, "intentional" = coordinator stopped it.
145
- * Use for cleanup or respawn logic (see plugin-scale).
146
- */
147
- onWorkerDeath?(
148
- worker: WorkerDescriptor,
149
- reason: "crash" | "intentional",
150
- ): void | Promise<void>;
151
-
152
- // ── Locals boundary ────────────────────────────────────────
153
-
154
- /**
155
- * Called by coordinator before forwarding a request to a worker.
156
- * Return a serialized string representation of locals.
157
- * First plugin to return non-null wins. Default: signed JSON header.
158
- */
159
- serializeLocals?(locals: App.Locals): string | Promise<string>;
160
-
161
- /**
162
- * Called by worker on receiving a forwarded request.
163
- * Return the deserialized locals object.
164
- * First plugin to return non-null wins. Default: verify + JSON.parse.
165
- */
166
- deserializeLocals?(raw: string): App.Locals | Promise<App.Locals>;
167
-
168
- // ── Routing policy ─────────────────────────────────────────
169
-
170
- /**
171
- * Called by coordinator to decide which worker handles a request.
172
- * First plugin to return non-null wins.
173
- * Default: ws routes → consistent hash, everything else → round robin.
174
- * routes is the full RouteTree so plugins can make route-aware decisions.
175
- */
176
- routeRequest?(
177
- req: Request,
178
- workers: WorkerDescriptor[],
179
- routes: RouteTree,
180
- ): WorkerDescriptor | Promise<WorkerDescriptor>;
181
- }
182
-
183
- export interface GrimoireConfig {
184
- port?: number;
185
- host?: string;
186
- plugins?: GrimoirePlugin[];
187
- routes?: string; // glob, default 'src/routes/**';
188
- dev?: boolean;
189
- devEditor?: boolean;
190
- vitePort?: number;
191
- alias?: Record<string, string>; // e.g. { "$lib": "src/lib" } — resolved relative to cwd
192
- cspNonce?: string; // CSP nonce for <script>/<style> tags
193
- bundleStrategy?: "split" | "single"; // 'split' (default) or 'single' bundle
194
- _skipBuild?: boolean;
195
- }
196
-
197
- export function defineConfig(config: GrimoireConfig): GrimoireConfig {
198
- return config;
199
- }
200
-
201
- /** Generic load type for +page.server.ts. For per-route typed params import PageServerLoad from './$types'. */
202
- export type PageServerLoad<
203
- P extends Record<string, string> = Record<string, string>,
204
- > = (
205
- ctx: TypedLoadContext<P>,
206
- ) => Record<string, unknown> | Promise<Record<string, unknown>>;
207
-
208
- /** Generic load type for +layout.server.ts. For per-route typed params import LayoutServerLoad from './$types'. */
209
- export type LayoutServerLoad<
210
- P extends Record<string, string> = Record<string, string>,
211
- > = (
212
- ctx: TypedLoadContext<P>,
213
- ) => Record<string, unknown> | Promise<Record<string, unknown>>;
214
-
215
- /** Generic handler type for +server.ts API routes. For per-route typed params import RequestHandler from './$types'. */
216
- export type RequestHandler<
217
- P extends Record<string, string> = Record<string, string>,
218
- > = (ctx: TypedLoadContext<P>) => Response | Promise<Response>;
219
-
220
- /**
221
- * Shape of the `websocket` export in a +server.ts file.
222
- * T is the resolved ws.data shape (params + upgrade() return value).
223
- * For per-route typing import WebSocketHandler from './$types'.
224
- */
225
- export interface WsRouteHandler<T = Record<string, unknown>> {
226
- open?(ws: ServerWebSocket<T>): void | Promise<void>;
227
- message?(ws: ServerWebSocket<T>, data: string | Buffer): void | Promise<void>;
228
- close?(
229
- ws: ServerWebSocket<T>,
230
- code: number,
231
- reason?: string,
232
- ): void | Promise<void>;
233
- drain?(ws: ServerWebSocket<T>): void | Promise<void>;
234
- }
235
-
236
- // ***BIG ONE***
237
-
238
- /**
239
- * Built-in worker modes understood by the coordinator.
240
- * Plugins may define custom modes via WorkerMode.
241
- */
242
- export type BuiltinWorkerMode = "api" | "frontend" | "ws" | "full";
243
-
244
- /**
245
- * Open union — (string & {}) preserves autocomplete for built-in
246
- * values while allowing plugin-defined modes like "db" or "queue".
247
- */
248
- export type WorkerMode = BuiltinWorkerMode | (string & {});
249
-
250
- /**
251
- * Describes a single worker process managed by the coordinator.
252
- * Coordinator derives behavior from routes, not mode string —
253
- * mode is informational and for plugin use only.
254
- */
255
- export interface WorkerDescriptor {
256
- mode: WorkerMode;
257
- index: number; // index within this mode (api-0, api-1...)
258
- globalIndex: number; // index across all workers
259
- internalUrl: string; // coordinator → worker base URL
260
- name?: string; // set by namepool or onWorkerSpawn
261
- routes: RouteFile[]; // route slice assigned by coordinator
262
- pid?: number; // set after Bun.spawn
263
- }
264
-
265
- /**
266
- * Return value of onWorkerSpawn. All plugins are called and results
267
- * are merged — env from all plugins is combined, last name wins.
268
- */
269
- export interface WorkerEnv {
270
- env?: Record<string, string>;
271
- name?: string;
272
- }
273
-
274
- /**
275
- * Passed to onCoordinatorStart once the coordinator is fully initialized.
276
- */
277
- export interface CoordinatorContext {
278
- workers: WorkerDescriptor[];
279
- port: number;
280
- secret: string; // ephemeral signing secret, generated per-run
281
- routes: RouteTree;
282
- }
1
+ import type { Server, ServerWebSocket } from "bun";
2
+ import type { ScopedLogger } from "./logger";
3
+ import type { RouteFile, RouteTree } from "./routing/scanner";
4
+
5
+ /// <reference types="bun-types">
6
+ declare global {
7
+ namespace App {
8
+ // augment in your own project via src/app.d.ts
9
+ interface Locals {}
10
+ interface Error {
11
+ message: string;
12
+ status?: number;
13
+ }
14
+ interface PageData {}
15
+ interface Platform {}
16
+ }
17
+ }
18
+
19
+ export interface Route {
20
+ path: string; // /blog/:slug
21
+ params: Record<string, string>;
22
+ filePath: string; // absolute path to +page.tsx
23
+ loadPath?: string; // absolute path to +page.ts
24
+ serverPath?: string; // absolute path to +server.ts
25
+ layoutPath?: string; // absolute path to +layout.tsx
26
+ }
27
+
28
+ export interface RouteInfo {
29
+ path: string; // /blog/:slug
30
+ filePath: string; // absolute path
31
+ type: string; // page, layout etc
32
+ }
33
+
34
+ export interface LoadContext {
35
+ request: Request;
36
+ params: Record<string, string>;
37
+ url: URL;
38
+ locals: Record<string, unknown>; // set by plugins/hooks
39
+ fetch: typeof globalThis.fetch; // ← add
40
+ /** Data returned by parent layouts' loads, merged outermost-first. */
41
+ parent: () => Promise<Record<string, unknown>>;
42
+ }
43
+
44
+ export interface TypedLoadContext<
45
+ P extends Record<string, string> = Record<string, string>,
46
+ > {
47
+ request: Request;
48
+ params: P;
49
+ url: URL;
50
+ locals: App.Locals;
51
+ fetch: typeof fetch;
52
+ /** Data returned by parent layouts' loads, merged outermost-first. */
53
+ parent: () => Promise<Record<string, unknown>>;
54
+ }
55
+
56
+ export interface RenderContext {
57
+ route: RouteInfo;
58
+ request: Request;
59
+ params: Record<string, string>;
60
+ data: unknown; // return value of load()
61
+ }
62
+
63
+ export interface PluginContext {
64
+ mode: "development" | "production";
65
+ plugins: ReadonlyMap<string, GrimoirePlugin>;
66
+ logger: ScopedLogger;
67
+ }
68
+
69
+ export interface BuildResult {
70
+ success: boolean;
71
+ outputs: string[];
72
+ errors: string[];
73
+ }
74
+
75
+ export interface GrimoirePlugin {
76
+ name: string;
77
+
78
+ // plugin lifecycle
79
+ onPluginsResolved?(ctx: PluginContext): void | Promise<void>;
80
+
81
+ // server lifecycle
82
+ // we dont care about what the impl puts as websocket data therefore unknown.
83
+ onStart?(server: Server<unknown>): void | Promise<void>;
84
+ onStop?(reason: "shutdown" | "restart"): void | Promise<void>;
85
+
86
+ // request pipeline
87
+ onRequest?(
88
+ req: Request,
89
+ next: () => Promise<Response>,
90
+ ): Response | Promise<Response>;
91
+
92
+ // route lifecycle
93
+ onRouteLoad?(route: Route, context: LoadContext): void | Promise<void>;
94
+ /**
95
+ * Called after the page HTML is fully rendered.
96
+ * NOTE: When any plugin implements this hook, the streaming response is
97
+ * buffered into a single string. Streaming is preserved for routes where
98
+ * no plugin uses this hook. To avoid buffering, use onRequest to intercept
99
+ * at the Response level.
100
+ */
101
+ onRouteRender?(
102
+ html: string,
103
+ context: RenderContext,
104
+ ): string | Promise<string>;
105
+
106
+ // build
107
+ onBuildStart?(): void | Promise<void>;
108
+ onBuildEnd?(result: BuildResult): void | Promise<void>;
109
+
110
+ // config
111
+ config?: (config: GrimoireConfig) => GrimoireConfig | undefined;
112
+
113
+ // process lifecycle
114
+
115
+ /**
116
+ * Runs AFTER Sigil/Babel compilation. Receives compiled JS, not source TSX.
117
+ * Suitable for string-level transforms (import rewriting, comment injection, etc.).
118
+ * Return null/undefined to pass through unchanged.
119
+ */
120
+ transform?(
121
+ code: string,
122
+ id: string,
123
+ ): string | null | undefined | Promise<string | null | undefined>;
124
+
125
+ /**
126
+ * Fires once after all workers are spawned and ready.
127
+ * Use for coordinator-level setup (e.g. opening a shared store).
128
+ */
129
+ onCoordinatorStart?(ctx: CoordinatorContext): void | Promise<void>;
130
+
131
+ /**
132
+ * Fires for each worker before Bun.spawn is called.
133
+ * Return WorkerEnv to inject env vars or set the worker name.
134
+ * ALL plugins are called and results are merged.
135
+ */
136
+ onWorkerSpawn?(
137
+ worker: WorkerDescriptor,
138
+ // biome-ignore lint/suspicious/noConfusingVoidType: doesn't have to return a thing.
139
+ ): WorkerEnv | void | Promise<WorkerEnv | void>;
140
+
141
+ /**
142
+ * Fires when a worker process is up and accepting requests.
143
+ */
144
+ onWorkerReady?(worker: WorkerDescriptor): void | Promise<void>;
145
+
146
+ /**
147
+ * Fires when a worker process exits.
148
+ * reason "crash" = unexpected exit, "intentional" = coordinator stopped it.
149
+ * Use for cleanup or respawn logic (see plugin-scale).
150
+ */
151
+ onWorkerDeath?(
152
+ worker: WorkerDescriptor,
153
+ reason: "crash" | "intentional",
154
+ ): void | Promise<void>;
155
+
156
+ // ── Locals boundary ────────────────────────────────────────
157
+
158
+ /**
159
+ * Called by coordinator before forwarding a request to a worker.
160
+ * Return a serialized string representation of locals.
161
+ * First plugin to return non-null wins. Default: signed JSON header.
162
+ */
163
+ serializeLocals?(locals: App.Locals): string | Promise<string>;
164
+
165
+ /**
166
+ * Called by worker on receiving a forwarded request.
167
+ * Return the deserialized locals object.
168
+ * First plugin to return non-null wins. Default: verify + JSON.parse.
169
+ */
170
+ deserializeLocals?(raw: string): App.Locals | Promise<App.Locals>;
171
+
172
+ // ── Routing policy ─────────────────────────────────────────
173
+
174
+ /**
175
+ * Called by coordinator to decide which worker handles a request.
176
+ * First plugin to return non-null wins.
177
+ * Default: ws routes → consistent hash, everything else → round robin.
178
+ * routes is the full RouteTree so plugins can make route-aware decisions.
179
+ */
180
+ routeRequest?(
181
+ req: Request,
182
+ workers: WorkerDescriptor[],
183
+ routes: RouteTree,
184
+ ): WorkerDescriptor | Promise<WorkerDescriptor>;
185
+ }
186
+
187
+ export interface GrimoireConfig {
188
+ port?: number;
189
+ host?: string;
190
+ plugins?: GrimoirePlugin[];
191
+ routes?: string; // glob, default 'src/routes/**';
192
+ dev?: boolean;
193
+ devEditor?: boolean;
194
+ vitePort?: number;
195
+ alias?: Record<string, string>; // e.g. { "$lib": "src/lib" } — resolved relative to cwd
196
+ cspNonce?: string; // CSP nonce for <script>/<style> tags
197
+ bundleStrategy?: "split" | "single"; // 'split' (default) or 'single' bundle
198
+ _skipBuild?: boolean;
199
+ }
200
+
201
+ export function defineConfig(config: GrimoireConfig): GrimoireConfig {
202
+ return config;
203
+ }
204
+
205
+ /** Generic load type for +page.server.ts. For per-route typed params import PageServerLoad from './$types'. */
206
+ export type PageServerLoad<
207
+ P extends Record<string, string> = Record<string, string>,
208
+ > = (
209
+ ctx: TypedLoadContext<P>,
210
+ ) => Record<string, unknown> | Promise<Record<string, unknown>>;
211
+
212
+ /** Generic load type for +layout.server.ts. For per-route typed params import LayoutServerLoad from './$types'. */
213
+ export type LayoutServerLoad<
214
+ P extends Record<string, string> = Record<string, string>,
215
+ > = (
216
+ ctx: TypedLoadContext<P>,
217
+ ) => Record<string, unknown> | Promise<Record<string, unknown>>;
218
+
219
+ /** Generic handler type for +server.ts API routes. For per-route typed params import RequestHandler from './$types'. */
220
+ export type RequestHandler<
221
+ P extends Record<string, string> = Record<string, string>,
222
+ > = (ctx: TypedLoadContext<P>) => Response | Promise<Response>;
223
+
224
+ /**
225
+ * Shape of the `websocket` export in a +server.ts file.
226
+ * T is the resolved ws.data shape (params + upgrade() return value).
227
+ * For per-route typing import WebSocketHandler from './$types'.
228
+ */
229
+ export interface WsRouteHandler<T = Record<string, unknown>> {
230
+ open?(ws: ServerWebSocket<T>): void | Promise<void>;
231
+ message?(ws: ServerWebSocket<T>, data: string | Buffer): void | Promise<void>;
232
+ close?(
233
+ ws: ServerWebSocket<T>,
234
+ code: number,
235
+ reason?: string,
236
+ ): void | Promise<void>;
237
+ drain?(ws: ServerWebSocket<T>): void | Promise<void>;
238
+ }
239
+
240
+ // ***BIG ONE***
241
+
242
+ /**
243
+ * Built-in worker modes understood by the coordinator.
244
+ * Plugins may define custom modes via WorkerMode.
245
+ */
246
+ export type BuiltinWorkerMode = "api" | "frontend" | "ws" | "full";
247
+
248
+ /**
249
+ * Open union — (string & {}) preserves autocomplete for built-in
250
+ * values while allowing plugin-defined modes like "db" or "queue".
251
+ */
252
+ export type WorkerMode = BuiltinWorkerMode | (string & {});
253
+
254
+ /**
255
+ * Describes a single worker process managed by the coordinator.
256
+ * Coordinator derives behavior from routes, not mode string —
257
+ * mode is informational and for plugin use only.
258
+ */
259
+ export interface WorkerDescriptor {
260
+ mode: WorkerMode;
261
+ index: number; // index within this mode (api-0, api-1...)
262
+ globalIndex: number; // index across all workers
263
+ internalUrl: string; // coordinator → worker base URL
264
+ name?: string; // set by namepool or onWorkerSpawn
265
+ routes: RouteFile[]; // route slice assigned by coordinator
266
+ pid?: number; // set after Bun.spawn
267
+ }
268
+
269
+ /**
270
+ * Return value of onWorkerSpawn. All plugins are called and results
271
+ * are merged — env from all plugins is combined, last name wins.
272
+ */
273
+ export interface WorkerEnv {
274
+ env?: Record<string, string>;
275
+ name?: string;
276
+ }
277
+
278
+ /**
279
+ * Passed to onCoordinatorStart once the coordinator is fully initialized.
280
+ */
281
+ export interface CoordinatorContext {
282
+ workers: WorkerDescriptor[];
283
+ port: number;
284
+ secret: string; // ephemeral signing secret, generated per-run
285
+ routes: RouteTree;
286
+ }