@guren/core 1.13.0 → 1.14.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.
@@ -1,5 +1,12 @@
1
1
  //#region src/internal/deploy-build.d.ts
2
2
  type PathLike = string | URL;
3
+ /**
4
+ * The agent registry (RFC 0017 §3), at a path neither side may choose. Shared
5
+ * rather than spelled twice: `guren check` reads it as source and a deploy build
6
+ * reads it to generate the worker's Durable Object exports, so a second spelling
7
+ * is a deploy exporting no agents while the check calls them registered.
8
+ */
9
+ declare const AGENTS_CONFIG_FILE = "config/agents.ts";
3
10
  type ManifestEntry = {
4
11
  file?: string;
5
12
  css?: string[];
@@ -7,59 +14,34 @@ type ManifestEntry = {
7
14
  type Manifest = Record<string, ManifestEntry>;
8
15
  declare function resolvePathLike(value: PathLike): string;
9
16
  /**
10
- * Read the first manifest that parses, tolerating both Vite layouts
11
- * (`.vite/manifest.json` and the flat `manifest.json` older configs emit), and
12
- * report which path it was. A malformed file is skipped rather than fatal —
13
- * the caller decides what a missing manifest means for its platform. The path
14
- * is part of the result because a caller publishing the manifest location to
15
- * the runtime has to name the file that was actually parsed: testing which one
16
- * *exists* picks the malformed one that was just skipped.
17
+ * Read the first manifest that parses, in either Vite layout (`.vite/manifest.json`,
18
+ * then flat `manifest.json`), and report its path: a caller publishing the location
19
+ * must name the file actually parsed, not the malformed one that was skipped. What a
20
+ * missing manifest means is the caller's call.
17
21
  */
18
22
  declare function readManifest(...paths: string[]): {
19
23
  manifest: Manifest;
20
24
  path: string;
21
25
  } | undefined;
22
26
  /**
23
- * Throw unless `out` is safe to delete: it must be neither the app root nor a
24
- * directory containing it.
25
- *
26
- * Relates two paths, so it canonicalizes both: comparing lexically would
27
- * accept `outputDir` values that reach the app root the long way, and the
28
- * delete that follows resolves the links regardless.
29
- *
30
- * Containment is then decided with `relative` rather than a string prefix
31
- * because `out + sep` is `//` at the filesystem root, which no absolute path
32
- * is prefixed by — a prefix test lets `outputDir: '/'` through. The escape
33
- * test is `'..'` exactly or a `'../'` prefix, not `startsWith('..')`: a
34
- * directory legitimately named `..-source` inside `out` yields the relative
35
- * path `..-source`, which the looser test would read as an escape.
36
- *
37
- * Exported separately from `resetOutputDir` so a caller can validate the
38
- * option early and delete later, but the delete itself should always go
39
- * through `resetOutputDir`.
40
- *
41
- * @param label Platform name for the error message, e.g. `'Lambda build'`.
27
+ * Throw unless `out` is safe to delete: neither the app root nor a directory
28
+ * containing it. Both paths are canonicalized (a lexical compare accepts an
29
+ * `outputDir` that reaches the root through links). Containment uses `relative`,
30
+ * not a prefix test (`out + sep` is `//` at the root, letting `'/'` through), and
31
+ * escape means `'..'` or a `'../'` prefix, so `..-source` inside `out` is not one.
42
32
  */
43
33
  declare function assertOutputDirOutsideRoot(out: string, root: string, label: string): void;
44
34
  /**
45
- * Delete the output directory so the build starts from a clean slate, after
46
- * checking it is safe to delete.
47
- *
48
- * The check and the delete are one call on purpose: they were separate
49
- * statements in each plugin, and a plugin that had only the delete has already
50
- * shipped.
51
- *
35
+ * Delete the output directory after checking it is safe to delete. One call on
36
+ * purpose: a plugin that carried only the delete has already shipped.
52
37
  * @param label Platform name for the error message, e.g. `'Lambda build'`.
53
38
  */
54
39
  declare function resetOutputDir(out: string, root: string, label: string): void;
55
40
  /**
56
- * Relative specifier for importing `target` from a module written into
57
- * `fromDir`, in POSIX form so the emitted source is platform-agnostic.
58
- *
59
- * Relates two paths, so it canonicalizes both: the bundler resolves the
60
- * emitted module from its real path, and a link that changes depth would
61
- * otherwise leave the specifier short a `..` segment.
62
- *
41
+ * POSIX relative specifier for importing `target` from a module written into
42
+ * `fromDir`. Both paths are canonicalized: the bundler resolves the emitted module
43
+ * from its real path, and a link that changes depth would leave the specifier a
44
+ * `..` short.
63
45
  * @param label Platform name for the error message, e.g. `'Lambda build'`.
64
46
  */
65
47
  declare function importSpecifier(fromDir: string, target: string, label: string): string;
@@ -68,107 +50,65 @@ interface ClientAssetEnv {
68
50
  styles?: string;
69
51
  }
70
52
  /**
71
- * Locate the built client entry and its CSS in the Vite client manifest, as
72
- * the `/assets/`-prefixed URLs the Inertia head expects.
73
- *
74
- * Takes the public directory rather than the app root so a caller passing a
75
- * custom `publicDir` is honoured.
76
- *
53
+ * Locate the built client entry and its CSS in the Vite client manifest, as the
54
+ * `/assets/`-prefixed URLs the Inertia head expects. Takes the public directory so
55
+ * a custom `publicDir` is honoured.
77
56
  * @param label Platform name for the warning message, e.g. `'Lambda build'`.
78
57
  */
79
58
  declare function resolveClientAssetEnv(publicDir: string, clientEntryKey: string, label: string): ClientAssetEnv;
80
59
  /**
81
- * The client build manifest as JSON text, for the deploy targets' runtime
82
- * manifest injection (`GUREN_VITE_MANIFEST`): `viteAsset()` resolves
83
- * content-page asset URLs from the client manifest at render time, and a
84
- * bundled function or worker has no `public/assets/manifest.json` to read.
85
- * How the payload reaches the runtime is per-plugin (a generated-entry
86
- * assignment, a bundler `define`); *what* the payload is, is this.
87
- *
88
- * Separate from `resolveClientAssetEnv` because that helper answers only for
89
- * the client *entry*: a content-page app can have a manifest of CSS build
90
- * inputs and no `resources/js/app.tsx` at all, and its `viteAsset()` calls
91
- * still need the whole manifest.
92
- *
93
- * The payload is trimmed to the fields the runtime rule reads — `file` and
94
- * `css` per entry (`getManifestFile`/`getManifestCss` in @guren/server's
95
- * vite-manifest.ts) — because it ships inside executable code: a large app's
96
- * manifest is dominated by per-chunk `imports`/`dynamicImports` graph
97
- * metadata nothing consumes, and Workers caps bundle size. Trimming also
98
- * validates the shape at build time, so a parseable-but-not-a-manifest file
99
- * (`null`, an array) is reported as "no manifest" here instead of being baked
100
- * in to fail at first render. String and array entry forms pass through
101
- * untrimmed — the runtime accepts them, and the two paths must not diverge.
60
+ * The client manifest as JSON for runtime injection (`GUREN_VITE_MANIFEST`): a
61
+ * bundled function has no `public/assets/manifest.json`. Separate from
62
+ * `resolveClientAssetEnv`, which answers only for the client entry. Trimmed to
63
+ * `file`/`css` per entry (all the runtime reads; chunk graph metadata dominates
64
+ * size and Workers caps bundles); a parseable non-manifest is rejected here.
102
65
  */
103
66
  declare function clientManifestJson(publicDir: string): string | undefined;
104
67
  /**
105
- * Absolute path of the built SSR entry chunk, or undefined when the app has no
106
- * SSR build. Verifying that the chunk actually exports a renderer is left to
107
- * the caller: the platforms disagree on whether importing it during a build is
108
- * acceptable.
109
- *
68
+ * Absolute path of the built SSR entry chunk, or undefined without an SSR build.
69
+ * Whether the chunk exports a renderer is the caller's check: platforms disagree
70
+ * on importing it during a build.
110
71
  * @param label Platform name for the error messages, e.g. `'Lambda build'`.
111
72
  */
112
73
  declare function resolveSsrEntryFile(ssrDir: string, ssrEntryKey: string, label: string): string | undefined;
113
74
  /**
114
- * Runtime locations of a staged SSR bundle, for platforms that copy `ssrDir`
115
- * under the function root and hand the layout to the server through
116
- * environment variables. `prefix` is where the caller stages the directory —
117
- * it cannot be derived here because staging happens later in the caller's own
118
- * flow.
119
- *
120
- * The manifest path is derived from the file that parsed rather than the
121
- * first one that exists: both Vite layouts occur in the wild, and a malformed
122
- * `.vite/manifest.json` alongside a valid flat one would otherwise publish the
123
- * path to the file that was skipped. It is optional only for the mid-build
124
- * race where the manifest vanishes between `resolveSsrEntryFile` and this
125
- * call — callers already hold a chunk path that manifest produced.
75
+ * Runtime locations of a staged SSR bundle, for platforms that copy `ssrDir` under
76
+ * the function root; `prefix` is where the caller stages it. The manifest path is
77
+ * the file that parsed, not the first that exists (a malformed `.vite/` file beside
78
+ * a valid flat one). Optional only for the race where the manifest vanishes after
79
+ * `resolveSsrEntryFile`.
126
80
  */
127
81
  declare function ssrRuntimePaths(ssrDir: string, ssrFile: string, prefix: string): {
128
82
  entry: string;
129
83
  manifest?: string;
130
84
  };
131
85
  /**
132
- * Copy `public/` into a platform's static-asset staging directory.
133
- *
134
- * Two pieces of Guren-specific knowledge, not platform policy, which is why
135
- * this is shared: the dev-mode `index.html` shell must never ship (it would
136
- * shadow the app's root route on any host that serves static files first), and
137
- * built assets self-reference the Vite plugin's derived base `/public/assets/`
138
- * while HTML references use `/assets/` — so on a host without rewrites the
139
- * built-assets directory has to appear under both prefixes.
86
+ * Delete the dev-mode `index.html` shell from a statically served directory: every
87
+ * deploy target answers for its static directory before the function runs, so the
88
+ * shell shadows the app's root route. Exact name only (the framework writes it).
89
+ * Separate from `stageStaticAssets` because `@guren/plugin-vercel` stages `public/`
90
+ * itself and needs this rule alone.
91
+ */
92
+ declare function removeShadowingIndex(assetsOut: string): void;
93
+ /**
94
+ * Copy `public/` into a platform's static staging directory. Built assets
95
+ * self-reference `/public/assets/` while HTML uses `/assets/`, so on a host without
96
+ * rewrites the assets directory must appear under both prefixes. Also applies
97
+ * `removeShadowingIndex`.
140
98
  */
141
99
  declare function stageStaticAssets(publicDir: string, assetsOut: string): void;
142
100
  /**
143
- * Extensions a browser renders as a *document* in the serving origin, for a
144
- * platform that answers for `public/` before the app ever runs.
145
- *
146
- * Exactly the set `@guren/server`'s `rendersAsDocument` matches over Hono's
147
- * mime table — the same two inputs the framework's own static guard reads, so
148
- * a file that downloads locally downloads on a deploy target too. Written out
149
- * rather than derived because this module imports nothing from the framework
150
- * (see the header); `packages/server/tests/http/static-documents.test.ts`
151
- * recomputes it from that table and fails when the two disagree, so a document
152
- * type Hono adds cannot pass unnoticed.
153
- *
154
- * Two things the list does not reach, both of them the framework's own
155
- * blind spots rather than new ones. `text/xsl` is a document type
156
- * `rendersAsDocument` matches, but Hono's table names no extension for it, so
157
- * `getMimeType` returns nothing for a `.xsl` file and the framework serves it
158
- * unguarded too — adding it here would make a deploy target stricter than the
159
- * app it deployed. And extension *case*: `getMimeType` lowercases before its
160
- * lookup, so the framework guard does fire for `logo.SVG`, and a platform
161
- * matching a literal pattern does not. Each plugin closes that where its own
162
- * matcher allows, and the three answers differ — see each one's own comment
163
- * rather than a list here that goes stale on the next target.
101
+ * Extensions a browser renders as a document, for platforms serving `public/`
102
+ * before the app runs: exactly what `@guren/server`'s `rendersAsDocument` matches
103
+ * over Hono's mime table (`tests/http/static-documents.test.ts` fails on drift).
104
+ * Like the framework it misses `.xsl` (Hono names no extension) and extension
105
+ * case, which each plugin closes as its own matcher allows.
164
106
  */
165
107
  declare const DOCUMENT_ASSET_EXTENSIONS: readonly ['htm', 'html', 'svg', 'xhtml', 'xml'];
166
108
  /**
167
- * The pair `applyDocumentDisposition` sets, for a platform to set on the same
168
- * files. Same reasoning as the framework's: `attachment` is honoured for
169
- * navigations and ignored for subresource loads, so `<img src="/logo.svg">`
170
- * and a CSS `url()` keep working while the URL opened directly downloads;
171
- * `nosniff` stops the promotion a browser would otherwise do on its own.
109
+ * The headers `applyDocumentDisposition` sets: `attachment` is honoured for
110
+ * navigations and ignored for subresource loads, so `<img>` and CSS `url()` keep
111
+ * working while a directly opened URL downloads; `nosniff` stops browser promotion.
172
112
  */
173
113
  declare const DOCUMENT_ASSET_HEADERS: Readonly<Record<string, string>>;
174
114
  /** What a dev-only module is needed for, so a plugin can word its own message. */
@@ -177,35 +117,17 @@ interface DevOnlyModule {
177
117
  readonly specifier: string;
178
118
  readonly kind: DevOnlyModuleKind;
179
119
  /**
180
- * Names the importing code destructures. A stub must declare every one of
181
- * them: an empty module fails the bundle with "no matching export" rather
182
- * than at runtime. Empty means the module is only ever read through
183
- * namespace property access, so an empty module suffices.
120
+ * Names the importing code destructures; a stub must declare every one or the
121
+ * bundle fails with "no matching export". Empty means namespace access only.
184
122
  */
185
123
  readonly exportNames: readonly string[];
186
124
  }
187
125
  /**
188
- * Modules that cannot run off Bun but sit in the graph of any app importing
189
- * `@guren/core`, reached only through dev-time branches. Core aggregates
190
- * `@guren/server` and `@guren/orm`, where these imports actually live, so it
191
- * is the one package that sees the whole set — which is why the list lives
192
- * here rather than in each plugin, where two copies had already drifted apart.
193
- *
194
- * Bundlers follow these imports even when they are dynamic, so without stubs
195
- * the build either fails to resolve them or ships megabytes of dev tooling.
196
- *
197
- * - `sqlite` — the local sqlite ORM factory, opposite the platform's own
198
- * database branch in `config/database.ts`.
199
- * - `vite` — the dev asset server `Application` starts when serving locally.
200
- * - `mcp` — the opt-in MCP endpoint's lazy imports, which drag the CLI
201
- * generators (and Babel) plus the MCP SDK in behind them.
202
- *
203
- * SQL client libraries are deliberately *not* here: they are dev-only on
204
- * Workers, where D1 is the only database, and load-bearing on Lambda and
205
- * Vercel, which connect to Postgres. See `SQL_CLIENT_MODULES`.
206
- *
207
- * `as const` so a consumer can key an exhaustive table on the specifiers and
208
- * have a new entry here surface as a compile error there.
126
+ * Dev-only modules in the graph of any app importing `@guren/core`, listed here
127
+ * because core alone sees the whole set (two plugin copies had drifted). Bundlers
128
+ * follow even dynamic imports, so unstubbed they fail the build or ship dev tooling.
129
+ * SQL clients are deliberately elsewhere (`SQL_CLIENT_MODULES`): dev-only on
130
+ * Workers, load-bearing on Lambda/Vercel. `as const` keys consumers' exhaustive tables.
209
131
  */
210
132
  declare const DEV_ONLY_MODULES: readonly [{
211
133
  readonly specifier: 'bun:sqlite';
@@ -231,88 +153,37 @@ declare const DEV_ONLY_MODULES: readonly [{
231
153
  /** One entry of `DEV_ONLY_MODULES`, with its `kind` still narrowed. */
232
154
  type DevOnlyModuleEntry = (typeof DEV_ONLY_MODULES)[number];
233
155
  /**
234
- * The specifier `@guren/plugin-mcp` dynamically imports to serve the App MCP
235
- * endpoint (RFC 0016 §7). Named here rather than inline in three plugins
236
- * because it is the one entry of `DEV_ONLY_MODULES` whose stubbing is
237
- * conditional, and each platform has to recognise it.
156
+ * The specifier `@guren/plugin-mcp` lazily imports for the App MCP endpoint (RFC
157
+ * 0016 §7): the one `DEV_ONLY_MODULES` entry whose stubbing is conditional.
238
158
  */
239
159
  declare const MCP_TRANSPORT_SPECIFIER = "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
240
160
  /** The package an app declares to opt into the App MCP endpoint. */
241
161
  declare const MCP_PLUGIN_PACKAGE = "@guren/plugin-mcp";
242
162
  /**
243
- * Whether the app has opted into the App MCP endpoint (RFC 0016 §7).
244
- *
245
- * Resolves the RFC's Open Question 5 — how a build learns that an app wants
246
- * the MCP transport — as **dependency sniffing**: declaring
247
- * `@guren/plugin-mcp` in `dependencies` *is* the opt-in. Nothing else is
248
- * asked of the developer, because there is nothing else to ask: an app that
249
- * installed the plugin and mounted it wants the endpoint to work, and a build
250
- * flag it must also remember to pass is a way for the endpoint to be silently
251
- * compiled shut on a platform. The build does not *enable* anything here — it
252
- * stops sabotaging what the app already configured.
253
- *
254
- * `dependencies` only, never `devDependencies`: a devDependency does not ship,
255
- * so an app that has one has no MCP endpoint at runtime to protect. Reading
256
- * both would keep the transport in the bundle of every app that merely
257
- * develops against the plugin.
258
- *
259
- * Absent, unreadable, or malformed manifest answers `false` — no opt-in
260
- * evidence is not the same as opt-in, and the false direction is the safe
261
- * one: the transport stays stubbed, which is exactly today's behaviour.
163
+ * Whether the app opted into the App MCP endpoint (RFC 0016 §7, Open Question 5):
164
+ * declaring `@guren/plugin-mcp` in `dependencies` is the opt-in, so no build flag
165
+ * can silently compile the endpoint shut. `devDependencies` do not count (they do
166
+ * not ship). An absent, unreadable, or malformed manifest answers `false`: the
167
+ * transport stays stubbed, which is the safe direction.
262
168
  */
263
169
  declare function appUsesMcpPlugin(root: string): boolean;
264
170
  /**
265
- * The dev-only modules that must stay stubbed for this app.
266
- *
267
- * The policy layer over `DEV_ONLY_MODULES`, which stays exported and
268
- * unchanged: it is the full inventory, and other consumers (the wrangler
269
- * bundle probe, the stub-filename table) read it as such. What varies per app
270
- * is only whether the *transport* entry is in force.
271
- *
272
- * `@guren/plugin-mcp` reaches the App MCP endpoint through exactly one lazy
273
- * import — `MCP_TRANSPORT_SPECIFIER` — plus static imports of the SDK's
274
- * `server/index.js` and `types.js`, which no entry here names. Stubbing the
275
- * transport therefore compiles the endpoint shut on every platform, which is
276
- * what the three deploy plugins did until RFC 0016 Phase 4a. Dropping the
277
- * entry for an app that declared the plugin is the whole of the fix.
278
- *
279
- * `@modelcontextprotocol/sdk/server/mcp.js` stays stubbed regardless, and the
280
- * distinction matters: that is the **Dev** MCP's `McpServer`, reached from
281
- * `@guren/server`'s `McpServiceProvider`, which drives the CLI's code
282
- * generators against the filesystem. It is compiled shut by the `NODE_ENV`
283
- * define anyway; the stub is the second guard, and a deployed app has no use
284
- * for it either way. Same for `@guren/cli` behind it, and for `bun:sqlite`
285
- * and `vite`, none of which the App MCP endpoint touches.
286
- *
287
- * The return type keeps each entry's narrow `kind` so that a platform can
288
- * index its `Record<kind, message>` table with `module.kind` at all. What
289
- * makes those tables exhaustive is not this function — each is keyed off
290
- * `DEV_ONLY_MODULES` directly (on Workers, that list plus
291
- * `SQL_CLIENT_MODULES`), which is what turns a new kind there into a compile
292
- * error there. Widening the return to `readonly DevOnlyModule[]` would leave
293
- * that exhaustiveness untouched and instead break every one of the lookups,
294
- * since `DevOnlyModuleKind` includes `'sql-driver'` — a kind Lambda's and
295
- * Vercel's tables deliberately omit, because those two platforms decide the
296
- * SQL clients per app rather than per platform.
171
+ * The dev-only modules that must stay stubbed for this app: `DEV_ONLY_MODULES`
172
+ * minus the transport entry when the app declared `@guren/plugin-mcp` (stubbing
173
+ * `MCP_TRANSPORT_SPECIFIER` compiled the endpoint shut everywhere before RFC 0016
174
+ * Phase 4a). `server/mcp.js` stays stubbed: that is the Dev MCP. Each entry keeps
175
+ * its narrow `kind` so platform `Record<kind, message>` tables stay indexable.
297
176
  */
298
177
  declare function stubbableDevOnlyModules(options: {
299
178
  mcpPlugin: boolean;
300
179
  }): readonly DevOnlyModuleEntry[];
301
- /**
302
- * A database `@guren/orm` can connect through, named after the factory an
303
- * app's database config calls to declare it.
304
- */
180
+ /** A database `@guren/orm` can connect through, named after the factory the app's config calls. */
305
181
  type DatabaseDialect = 'postgres' | 'mysql' | 'sqlite' | 'aws-data-api' | 'd1';
306
182
  /**
307
- * The `@guren/orm` factory names an app's database config calls, and the
308
- * dialect each one declares.
309
- *
310
- * Taken from `@guren/core`'s export allowlist rather than from the ORM's
311
- * implementation files, and pinned there by a test: a list built from the
312
- * implementation admits names that were never exported and misses the aliases
313
- * that were. The spelling is `createMySqlDatabase`, not `createMysqlDatabase`
314
- * — a build that filters on a name nobody exports detects nothing and stubs
315
- * nothing, which is silent.
183
+ * The `@guren/orm` factory names an app's config calls, with each one's dialect.
184
+ * Taken from `@guren/core`'s export allowlist (pinned by a test), not the ORM's
185
+ * files: it is `createMySqlDatabase`, and a filter on a name nobody exports stubs
186
+ * nothing, silently.
316
187
  */
317
188
  declare const DATABASE_FACTORIES: {
318
189
  readonly createPostgresDatabase: 'postgres';
@@ -326,29 +197,11 @@ interface SqlClientModule extends DevOnlyModule {
326
197
  readonly dialect: DatabaseDialect;
327
198
  }
328
199
  /**
329
- * The database client libraries `@guren/orm`'s Postgres, MySQL and Aurora
330
- * Data API factories reach for.
331
- *
332
- * They sit apart from `DEV_ONLY_MODULES` because whether they are dead weight
333
- * depends on the platform: on Workers, D1 is the only database there is, so
334
- * every one of these is unreachable; on Lambda and Vercel the app connects to
335
- * Postgres through them and stubbing them would break a working deploy.
336
- *
337
- * That makes the list itself the wrong granularity for a platform that hosts
338
- * more than one dialect. Workers stubs all of it; Lambda and Vercel stub the
339
- * entries whose `dialect` the app's config does not declare, which is what
340
- * `unusedSqlClients` decides.
341
- *
342
- * A platform where they are unreachable has to stub them rather than ignore
343
- * them. `@guren/orm` names them in *literal* dynamic imports, which a bundler
344
- * follows whether or not the branch can be taken — so a D1 app failed to
345
- * bundle on `Could not resolve "postgres"`, naming a database its author had
346
- * deliberately not chosen. Both the client and the drizzle entry point that
347
- * imports it need stubbing: aliasing only the client leaves drizzle's own
348
- * `import pgClient from "postgres"` to resolve.
349
- *
350
- * Export names are read off drizzle-orm's driver and session modules, which
351
- * is what a bundler checks a stub against.
200
+ * Client libraries the Postgres, MySQL and Aurora Data API factories reach for.
201
+ * Apart from `DEV_ONLY_MODULES` because their fate is per platform: unreachable on
202
+ * Workers (D1 only), load-bearing on Lambda/Vercel, which stub only undeclared
203
+ * dialects (`unusedSqlClients`). Stub the client *and* drizzle's entry importing it,
204
+ * or a D1 app fails on `Could not resolve "postgres"`; export names mirror drizzle-orm's.
352
205
  */
353
206
  declare const SQL_CLIENT_MODULES: readonly [{
354
207
  readonly specifier: 'postgres';
@@ -373,13 +226,9 @@ declare const SQL_CLIENT_MODULES: readonly [{
373
226
  }];
374
227
  type SqlClientSpecifier = (typeof SQL_CLIENT_MODULES)[number]['specifier'];
375
228
  /**
376
- * Where an app declares its database, in the order it is looked for.
377
- *
378
- * The same pair `guren doctor` checks, kept as a copy for the same reason
379
- * `realpathOfNearestExisting` above is one: this module must not import
380
- * beyond node builtins, and cli cannot be imported from core. If the two ever
381
- * disagree, a build would stub clients for an app whose config the doctor
382
- * says is fine — so a change to either belongs in both.
229
+ * Where an app declares its database, in lookup order. Same pair `guren doctor`
230
+ * checks, copied because this module imports only node builtins; a change to
231
+ * either belongs in both.
383
232
  */
384
233
  declare const DATABASE_CONFIG_CANDIDATES: readonly ['config/database.ts', 'db/config.ts'];
385
234
  interface DatabaseDialectDetection {
@@ -393,22 +242,11 @@ interface DatabaseDialectDetection {
393
242
  source?: string;
394
243
  }
395
244
  /**
396
- * Which databases an app connects to, read off its database config.
397
- *
398
- * A *union*, never a single answer: an app legitimately names two factories in
399
- * one file, picking between them at runtime — the Workers app in this
400
- * repository declares D1 for the deployed worker and sqlite for local
401
- * development, and a Lambda app can pair Postgres with sqlite the same way.
402
- * Taking the first match would stub a client the app really does reach for.
403
- *
404
- * Matching is a scan for the factory names, not a parse: every way of being
405
- * wrong about a name that *is* in the file — mentioned in a comment, imported
406
- * but never called, called in a branch this deploy will not take — errs
407
- * toward reporting a dialect the app might not use, and the caller stubs
408
- * fewer clients as a result. The opposite error is the dangerous one, so the
409
- * cheap reading is the right one. A config that reaches a factory without
410
- * naming it (a re-export, an indirection through another module) reports
411
- * nothing, and the caller stubs nothing.
245
+ * Which databases an app connects to, read off its config. A union, never a single
246
+ * answer: a config may name two factories and pick at runtime (D1 plus sqlite).
247
+ * A name scan, not a parse: every way of being wrong about a name that is in the
248
+ * file errs toward reporting an unused dialect, which only stubs fewer clients.
249
+ * A factory reached without being named reports nothing, and nothing is stubbed.
412
250
  */
413
251
  declare function detectDatabaseDialects(root: string): DatabaseDialectDetection;
414
252
  /** Every dialect name `databaseDialects` accepts, for validation and messages. */
@@ -425,22 +263,11 @@ interface UnusedSqlClient {
425
263
  readonly message: string;
426
264
  }
427
265
  /**
428
- * The database clients an app does not connect through, for a platform where
429
- * the ones it *does* connect through are load-bearing — Lambda and Vercel,
430
- * as opposed to Workers, where D1 is the only database and every client in
431
- * `SQL_CLIENT_MODULES` is unreachable regardless of what the config says.
432
- *
433
- * Fails open: when the dialects cannot be read, this warns and returns
434
- * nothing to stub. The two errors are not symmetric. Under-stubbing leaves
435
- * today's behaviour — the build fails to resolve a client the app never
436
- * installed, loudly, at build time. Over-stubbing produces a bundle that
437
- * builds clean and then cannot reach its own database, at runtime, in
438
- * production. Only the second is worth protecting against, so anything less
439
- * than positive evidence means stub nothing.
440
- *
441
- * @param dialects Overrides detection when the caller already knows, for an
442
- * app whose config the scan cannot read.
443
- * @param label Platform name for the messages, e.g. `'Lambda build'`.
266
+ * The database clients an app does not connect through, for Lambda and Vercel
267
+ * (on Workers every client is unreachable). Fails open: unreadable dialects warn
268
+ * and stub nothing, because under-stubbing fails loudly at build time while
269
+ * over-stubbing ships a bundle that cannot reach its database in production.
270
+ * @param dialects Overrides detection when the caller already knows.
444
271
  */
445
272
  declare function unusedSqlClients(input: {
446
273
  root: string;
@@ -449,24 +276,18 @@ declare function unusedSqlClients(input: {
449
276
  }): readonly UnusedSqlClient[];
450
277
  type DevOnlySpecifier = (typeof DEV_ONLY_MODULES)[number]['specifier'];
451
278
  /**
452
- * Source for a stub replacing one dev-only module. Shared because what it
453
- * encodes is a bundler constraint, not a platform choice: every name the
454
- * importer destructures must be present or the bundle fails with "no matching
455
- * export", and each is emitted as a throwing *function* because the stubbed
456
- * names mix constructors (`new Database()`) with plain calls
457
- * (`createServer()`) — a class invoked without `new` reports "Class
458
- * constructor cannot be invoked without 'new'" instead of the real reason.
459
- *
279
+ * Source for a stub replacing one dev-only module. Every destructured name must be
280
+ * present or the bundle fails with "no matching export", and each is a throwing
281
+ * *function* because stubbed names mix constructors and plain calls (a class
282
+ * called without `new` would hide the real reason).
460
283
  * @param message Platform-specific explanation, including the replacement API.
461
284
  */
462
285
  declare function renderDevOnlyStub(module: DevOnlyModule, message: string): string;
463
286
  /**
464
- * The MCP SDK is only ever reached through subpaths, and a bundler alias on a
465
- * package name does not cover them — which is why `DEV_ONLY_MODULES` lists
466
- * each one. A platform whose aliasing supports prefixes should also route
467
- * unlisted subpaths under this prefix to a stub, so a new subpath added
468
- * upstream cannot pull the real SDK into a deployed bundle.
287
+ * The MCP SDK is reached only through subpaths, which a package-name alias does not
288
+ * cover (hence each one in `DEV_ONLY_MODULES`). A platform whose aliasing supports
289
+ * prefixes should route unlisted subpaths under this prefix to a stub too.
469
290
  */
470
291
  declare const MCP_SDK_SUBPATH_PREFIX = "@modelcontextprotocol/sdk/";
471
292
  //#endregion
472
- export { ClientAssetEnv, DATABASE_CONFIG_CANDIDATES, DATABASE_DIALECTS, DATABASE_FACTORIES, DEV_ONLY_MODULES, DOCUMENT_ASSET_EXTENSIONS, DOCUMENT_ASSET_HEADERS, DatabaseDialect, DatabaseDialectDetection, DevOnlyModule, DevOnlyModuleEntry, DevOnlyModuleKind, DevOnlySpecifier, MCP_PLUGIN_PACKAGE, MCP_SDK_SUBPATH_PREFIX, MCP_TRANSPORT_SPECIFIER, Manifest, ManifestEntry, PathLike, SQL_CLIENT_MODULES, SqlClientModule, SqlClientSpecifier, UnusedSqlClient, appUsesMcpPlugin, assertOutputDirOutsideRoot, clientManifestJson, detectDatabaseDialects, importSpecifier, parseDatabaseDialects, readManifest, renderDevOnlyStub, resetOutputDir, resolveClientAssetEnv, resolvePathLike, resolveSsrEntryFile, ssrRuntimePaths, stageStaticAssets, stubbableDevOnlyModules, unusedSqlClients };
293
+ export { AGENTS_CONFIG_FILE, ClientAssetEnv, DATABASE_CONFIG_CANDIDATES, DATABASE_DIALECTS, DATABASE_FACTORIES, DEV_ONLY_MODULES, DOCUMENT_ASSET_EXTENSIONS, DOCUMENT_ASSET_HEADERS, DatabaseDialect, DatabaseDialectDetection, DevOnlyModule, DevOnlyModuleEntry, DevOnlyModuleKind, DevOnlySpecifier, MCP_PLUGIN_PACKAGE, MCP_SDK_SUBPATH_PREFIX, MCP_TRANSPORT_SPECIFIER, Manifest, ManifestEntry, PathLike, SQL_CLIENT_MODULES, SqlClientModule, SqlClientSpecifier, UnusedSqlClient, appUsesMcpPlugin, assertOutputDirOutsideRoot, clientManifestJson, detectDatabaseDialects, importSpecifier, parseDatabaseDialects, readManifest, removeShadowingIndex, renderDevOnlyStub, resetOutputDir, resolveClientAssetEnv, resolvePathLike, resolveSsrEntryFile, ssrRuntimePaths, stageStaticAssets, stubbableDevOnlyModules, unusedSqlClients };