@guren/plugin-lambda 0.4.0 → 0.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.
package/README.md CHANGED
@@ -15,7 +15,7 @@ Installing registers a `lambda:build` command and scaffolds `src/lambda.ts` —
15
15
  bunx guren lambda:build
16
16
  ```
17
17
 
18
- `lambda:build` runs your app's `build` script, then assembles a `.lambda/` directory:
18
+ `lambda:build` runs the deploy-runtime checks `guren doctor` reports (a warning, never a failure, on an in-memory session or OAuth store, a `ScryptHasher`, or filesystem provider discovery), then your app's `build` script, then assembles a `.lambda/` directory:
19
19
 
20
20
  | Path | Contents |
21
21
  |------|----------|
@@ -1,18 +1,15 @@
1
- import { n as LAMBDA_HANDLER_MODULE, t as LAMBDA_HANDLER_EXPORTS } from "./handlers-CkWGWQQX.js";
1
+ import { n as LAMBDA_HANDLER_MODULE, t as LAMBDA_HANDLER_EXPORTS } from "./handlers-Dtt3k5Ue.js";
2
2
  import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
3
3
  import { resolve } from "node:path";
4
4
  import { MCP_SDK_SUBPATH_PREFIX, appUsesMcpPlugin, assertOutputDirOutsideRoot, clientManifestJson, importSpecifier, renderDevOnlyStub, resetOutputDir, resolveClientAssetEnv, resolvePathLike, resolveSsrEntryFile, ssrRuntimePaths, stageStaticAssets, stubbableDevOnlyModules, unusedSqlClients } from "@guren/core/internal/deploy-build";
5
+ import { reportDeployRuntimeHazards } from "@guren/core/internal/deploy-check";
5
6
  //#region src/build.ts
6
7
  const MCP_UNAVAILABLE = "The MCP endpoint is unavailable on AWS Lambda — it generates files on disk.";
7
8
  /**
8
- * Why the dev-only modules in `DEV_ONLY_MODULES` cannot run here, worded for
9
- * this platform: each names the Lambda-appropriate replacement.
10
- *
11
- * Keyed on the kinds this platform stubs unconditionally, not on every kind
12
- * that exists. The SQL clients are load-bearing on Lambda — the app connects
13
- * to Postgres or the Data API through them — so which of those are dead
14
- * weight is decided per app, not here, and their messages come from
15
- * `unusedSqlClients`.
9
+ * Why the dev-only modules in `DEV_ONLY_MODULES` cannot run here, each naming
10
+ * the Lambda-appropriate replacement. Keyed only on the kinds this platform
11
+ * stubs unconditionally: the SQL clients are load-bearing on Lambda, so which
12
+ * of those are dead weight is decided per app by `unusedSqlClients`.
16
13
  */
17
14
  const UNAVAILABLE_ON_LAMBDA = {
18
15
  sqlite: "bun:sqlite is unavailable on AWS Lambda — use createAwsDataApiDatabase() or createPostgresDatabase().",
@@ -20,32 +17,21 @@ const UNAVAILABLE_ON_LAMBDA = {
20
17
  mcp: MCP_UNAVAILABLE
21
18
  };
22
19
  /**
23
- * Dev-only modules replaced with throwing stubs rather than left external.
24
- * Inlining a lazily-imported module hoists that module's own static imports to
25
- * the bundle top level, so an external module reached this way (the MCP SDK)
26
- * would fail at import time on Lambda even though no code path ever runs it.
27
- * Stubbing also keeps megabytes of dev tooling out of the bundle.
28
- *
29
- * Which of them are in force is per app, and for one reason only: an app that
30
- * declares `@guren/plugin-mcp` serves the App MCP endpoint here, so its
31
- * transport must reach the bundle rather than a stub (RFC 0016 §7). The rest
32
- * are unconditional — nothing an app can declare makes the Vite dev server or
33
- * the *Dev* MCP's generators run on Lambda. `stubbableDevOnlyModules` owns
34
- * that distinction; this function only renders what it is handed.
20
+ * Stubs rather than externals: inlining a lazily-imported module hoists its
21
+ * static imports to the bundle top level, so an external reached that way (the
22
+ * MCP SDK) fails at import time though no code path runs it. An app declaring
23
+ * `@guren/plugin-mcp` serves the endpoint here, so its transport must reach the
24
+ * bundle (RFC 0016 §7) — `stubbableDevOnlyModules` owns that split.
35
25
  */
36
26
  function devOnlyStubs(mcpPlugin) {
37
27
  return Object.fromEntries(stubbableDevOnlyModules({ mcpPlugin }).map((module) => [module.specifier, renderDevOnlyStub(module, UNAVAILABLE_ON_LAMBDA[module.kind])]));
38
28
  }
39
29
  /**
40
30
  * The dev-only stubs plus one per database client this app does not connect
41
- * through. Both halves depend on the app, so it is built per build rather
42
- * than at module scope.
43
- *
44
- * A stub here also *overrides* `external`, verified against Bun 1.3.14: the
45
- * bundler consults plugins before it consults the external list, so stubbing
46
- * `@aws-sdk/client-rds-data` for a Postgres app really does replace it rather
47
- * than leaving `external: ['@aws-sdk/*']` to keep drizzle's hoisted top-level
48
- * import of a package the runtime may not provide.
31
+ * through. A stub also *overrides* `external`, verified against Bun 1.3.14: the
32
+ * bundler consults plugins before the external list, so stubbing
33
+ * `@aws-sdk/client-rds-data` for a Postgres app really does replace drizzle's
34
+ * hoisted top-level import of it.
49
35
  */
50
36
  function stubsFor(root, dialects, mcpPlugin) {
51
37
  const unused = unusedSqlClients({
@@ -60,16 +46,10 @@ function stubsFor(root, dialects, mcpPlugin) {
60
46
  }
61
47
  /**
62
48
  * Fallback for an MCP SDK subpath `DEV_ONLY_MODULES` does not name. It cannot
63
- * know which names the importer destructures, so it throws on evaluation
64
- * rather than resolving to an empty module: a subpath reached from app code
65
- * (not Guren's disabled MCP endpoint) must fail loudly at build or cold start,
66
- * never silently hand back missing exports.
67
- *
68
- * Reachable only for an app that does *not* declare `@guren/plugin-mcp`. For
69
- * one that does, the SDK is a dependency it deliberately ships, and this
70
- * fallback would stub `server/index.js` and `types.js` — which
71
- * `@guren/plugin-mcp` imports statically — leaving the endpoint just as
72
- * compiled shut as the transport stub did. See `stubFilter`.
49
+ * know which names the importer destructures, so it throws on evaluation rather
50
+ * than handing back missing exports. Reachable only for an app that does *not*
51
+ * declare `@guren/plugin-mcp`, whose statically imported `server/index.js` and
52
+ * `types.js` it would otherwise stub shut — see `stubFilter`.
73
53
  */
74
54
  const unlistedMcpStub = `throw new Error(${JSON.stringify(MCP_UNAVAILABLE)})\n`;
75
55
  function escapeRegExp(value) {
@@ -96,6 +76,10 @@ async function buildLambdaOutput(options = {}) {
96
76
  const clientEntryKey = options.clientEntryKey ?? "resources/js/app.tsx";
97
77
  const ssrEntryKey = options.ssrEntryKey ?? "resources/js/ssr.tsx";
98
78
  assertOutputDirOutsideRoot(out, root, "Lambda build");
79
+ await reportDeployRuntimeHazards({
80
+ root,
81
+ label: "Lambda build"
82
+ });
99
83
  if (!options.skipAppBuild) runAppBuild(root);
100
84
  if (!existsSync(entrypoint)) throw new Error(`Lambda build: entrypoint not found at ${entrypoint}. Run \`bunx guren plugin @guren/plugin-lambda\` to scaffold src/lambda.ts, or pass "entrypoint".`);
101
85
  const ssrFile = resolveSsrEntry(ssrDir, ssrEntryKey);
@@ -53,20 +53,11 @@ interface GurenLambdaAppProps {
53
53
  dataApi?: GurenLambdaDataApiProps;
54
54
  }
55
55
  /**
56
- * The full serverless topology for a Guren app in one construct: an HTTP API
57
- * in front of the `http` handler, and opt-in SQS/EventBridge/console wiring
58
- * plus CloudFront + S3 for static assets. Handler names follow the module
59
- * `guren lambda:build` emits (`handler.http`, `handler.queue`, ...).
56
+ * The full serverless topology in one construct: an HTTP API in front of the
57
+ * `http` handler, opt-in SQS/EventBridge/console wiring, and CloudFront + S3
58
+ * assets. Handler names follow `guren lambda:build` (`handler.http`, ...).
60
59
  *
61
- * @example
62
- * ```typescript
63
- * new GurenLambdaApp(this, 'App', {
64
- * functionDir: '../.lambda/function',
65
- * assets: { dir: '../.lambda/assets' },
66
- * queue: {},
67
- * environment: { DATABASE_NAME: 'appdb', DATABASE_RESOURCE_ARN: '...', DATABASE_SECRET_ARN: '...' },
68
- * })
69
- * ```
60
+ * @example new GurenLambdaApp(this, 'App', { functionDir: '../.lambda/function' })
70
61
  */
71
62
  declare class GurenLambdaApp extends Construct {
72
63
  readonly httpFunction: lambda.Function;
package/dist/cdk/index.js CHANGED
@@ -1,4 +1,4 @@
1
- import { r as lambdaHandlerId } from "../handlers-CkWGWQQX.js";
1
+ import { r as lambdaHandlerId } from "../handlers-Dtt3k5Ue.js";
2
2
  import { existsSync, readFileSync, readdirSync } from "node:fs";
3
3
  import { resolve } from "node:path";
4
4
  import { DOCUMENT_ASSET_EXTENSIONS, DOCUMENT_ASSET_HEADERS } from "@guren/core/internal/deploy-build";
@@ -18,20 +18,11 @@ import * as sqs from "aws-cdk-lib/aws-sqs";
18
18
  import { Construct } from "constructs";
19
19
  //#region src/cdk/index.ts
20
20
  /**
21
- * The full serverless topology for a Guren app in one construct: an HTTP API
22
- * in front of the `http` handler, and opt-in SQS/EventBridge/console wiring
23
- * plus CloudFront + S3 for static assets. Handler names follow the module
24
- * `guren lambda:build` emits (`handler.http`, `handler.queue`, ...).
21
+ * The full serverless topology in one construct: an HTTP API in front of the
22
+ * `http` handler, opt-in SQS/EventBridge/console wiring, and CloudFront + S3
23
+ * assets. Handler names follow `guren lambda:build` (`handler.http`, ...).
25
24
  *
26
- * @example
27
- * ```typescript
28
- * new GurenLambdaApp(this, 'App', {
29
- * functionDir: '../.lambda/function',
30
- * assets: { dir: '../.lambda/assets' },
31
- * queue: {},
32
- * environment: { DATABASE_NAME: 'appdb', DATABASE_RESOURCE_ARN: '...', DATABASE_SECRET_ARN: '...' },
33
- * })
34
- * ```
25
+ * @example new GurenLambdaApp(this, 'App', { functionDir: '../.lambda/function' })
35
26
  */
36
27
  var GurenLambdaApp = class extends Construct {
37
28
  httpFunction;
@@ -174,32 +165,11 @@ var GurenLambdaApp = class extends Construct {
174
165
  }
175
166
  };
176
167
  /**
177
- * The CloudFront function body that turns a staged document into a download.
178
- *
179
- * CloudFront answers every asset behaviour from S3 directly, so
180
- * `guardStaticDocument` — which the framework applies on each mount that
181
- * reaches `public/` — never sees these files. Without this the same app
182
- * downloads an SVG locally and renders it inline, script and all, on its own
183
- * origin in production.
184
- *
185
- * A viewer-response function rather than one cache behaviour per extension:
186
- * a behaviour is chosen by path, so `*.svg` would also capture a `/feed.svg`
187
- * the *app* renders and send it to S3, and the default limit of 25
188
- * behaviours is already spent one per staged root entry. The association
189
- * rides on `assetBehavior` alone, which is what keeps it off the default
190
- * behaviour — the app, whose responses carry the framework's own headers.
191
- *
192
- * The extension is read from the request path because that path is the S3
193
- * key here: this distribution sets no `defaultRootObject` and rewrites no
194
- * index, so nothing stands between `/page.html` and the document. A platform
195
- * that served `public/page.html` at `/page` would leave the `.html` half of
196
- * this rule matching only the redirect.
197
- *
198
- * `toLowerCase()` covers the extension case `DOCUMENT_ASSET_EXTENSIONS`
199
- * records as unreachable from a literal pattern: `getMimeType` lowercases
200
- * before its lookup, so `logo.SVG` downloads under the framework's own guard,
201
- * and reading the extension rather than matching a pattern is what lets this
202
- * target agree with it.
168
+ * CloudFront answers asset behaviours from S3 directly, so `guardStaticDocument`
169
+ * never sees these files and an SVG would render inline, script and all. A
170
+ * viewer-response function, not a cache behaviour per extension: those match by
171
+ * path, so `*.svg` would also capture a `/feed.svg` the *app* renders, and the
172
+ * limit of 25 is spent one per staged root entry. Lowercased, so `logo.SVG` too.
203
173
  */
204
174
  function renderAssetDocumentGuard() {
205
175
  const headers = Object.fromEntries(Object.entries(DOCUMENT_ASSET_HEADERS).map(([name, value]) => [name.toLowerCase(), value]));
@@ -212,14 +182,9 @@ function renderAssetDocumentGuard() {
212
182
  }
213
183
  /**
214
184
  * The function CloudFront runs, verbatim, reading the two constants
215
- * {@link renderAssetDocumentGuard} declares above it.
216
- *
217
- * Free of interpolation on purpose. A template that substitutes into its own
218
- * body has to be read twice, once as TypeScript and once as the JavaScript it
219
- * becomes, and a `$` or a backtick in the JavaScript changes the result of the
220
- * first reading. Here the string is the program: it can be pasted into the
221
- * CloudFront console, or run beside the two `var` lines anywhere else, and
222
- * behave exactly as it does deployed.
185
+ * {@link renderAssetDocumentGuard} declares above it. Free of interpolation on
186
+ * purpose: a `$` or a backtick in the JavaScript would change how the
187
+ * TypeScript reads, and as written the string is exactly the deployed program.
223
188
  */
224
189
  const ASSET_DOCUMENT_GUARD_BODY = `function handler(event) {
225
190
  var uri = event.request.uri
package/dist/commands.js CHANGED
@@ -1,4 +1,4 @@
1
- import { t as buildLambdaOutput } from "./build-CHTrBLNm.js";
1
+ import { t as buildLambdaOutput } from "./build-Dn_V0LNZ.js";
2
2
  import { DATABASE_DIALECTS, parseDatabaseDialects } from "@guren/core/internal/deploy-build";
3
3
  import { defineCommand } from "citty";
4
4
  var commands_default = { "lambda:build": defineCommand({
@@ -11,7 +11,7 @@ const LAMBDA_HANDLER_EXPORTS = [
11
11
  "schedule",
12
12
  "console"
13
13
  ];
14
- /** Lambda handler identifier for an export, e.g. `handler.http`. */
14
+ /** Lambda handler identifier for an export. */
15
15
  function lambdaHandlerId(name) {
16
16
  return `${LAMBDA_HANDLER_MODULE}.${name}`;
17
17
  }
package/dist/index.d.ts CHANGED
@@ -47,7 +47,7 @@ declare function buildLambdaOutput(options?: BuildLambdaOutputOptions): Promise<
47
47
  declare const LAMBDA_HANDLER_MODULE = "handler";
48
48
  declare const LAMBDA_HANDLER_EXPORTS: readonly ['http', 'queue', 'schedule', 'console'];
49
49
  type LambdaHandlerExport = (typeof LAMBDA_HANDLER_EXPORTS)[number];
50
- /** Lambda handler identifier for an export, e.g. `handler.http`. */
50
+ /** Lambda handler identifier for an export. */
51
51
  declare function lambdaHandlerId(name: LambdaHandlerExport): string;
52
52
  //#endregion
53
53
  //#region src/index.d.ts
@@ -59,10 +59,7 @@ interface LambdaPluginConfig {}
59
59
  /**
60
60
  * Register the Lambda plugin.
61
61
  *
62
- * @example
63
- * ```typescript
64
- * createApp({ providers: [lambdaPlugin()] })
65
- * ```
62
+ * @example createApp({ providers: [lambdaPlugin()] })
66
63
  */
67
64
  declare function lambdaPlugin(config?: LambdaPluginConfig): ServiceProviderConstructor;
68
65
  //#endregion
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
- import { n as LAMBDA_HANDLER_MODULE, r as lambdaHandlerId, t as LAMBDA_HANDLER_EXPORTS } from "./handlers-CkWGWQQX.js";
2
- import { t as buildLambdaOutput } from "./build-CHTrBLNm.js";
1
+ import { n as LAMBDA_HANDLER_MODULE, r as lambdaHandlerId, t as LAMBDA_HANDLER_EXPORTS } from "./handlers-Dtt3k5Ue.js";
2
+ import { t as buildLambdaOutput } from "./build-Dn_V0LNZ.js";
3
3
  import { definePlugin } from "@guren/core";
4
4
  //#region src/index.ts
5
5
  const factory = definePlugin({
@@ -9,10 +9,7 @@ const factory = definePlugin({
9
9
  /**
10
10
  * Register the Lambda plugin.
11
11
  *
12
- * @example
13
- * ```typescript
14
- * createApp({ providers: [lambdaPlugin()] })
15
- * ```
12
+ * @example createApp({ providers: [lambdaPlugin()] })
16
13
  */
17
14
  function lambdaPlugin(config = {}) {
18
15
  return factory(config);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@guren/plugin-lambda",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -45,7 +45,7 @@
45
45
  "typecheck": "tsc --noEmit"
46
46
  },
47
47
  "dependencies": {
48
- "@guren/core": "^1.13.0",
48
+ "@guren/core": "^1.15.0",
49
49
  "citty": "^0.1.6"
50
50
  },
51
51
  "peerDependencies": {