@friggframework/devtools 2.0.0--canary.625.8f60019.0 → 2.0.0--canary.625.3f500f2.0

package/infrastructure/__tests__/ssm-preload-node-options.test.js

@@ -0,0 +1,79 @@
+/**
+ * The SSM INIT preload (NODE_OPTIONS=--import) must be scoped to skipEsbuild
+ * functions only. esbuild-bundled functions (e.g. defaultWebsocket) do not
+ * package the preload .mjs, and a missing --import target fatally aborts Node
+ * startup — so a global NODE_OPTIONS would brick them (ADR-027 review finding).
+ */
+
+const { composeServerlessDefinition } = require('../infrastructure-composer');
+
+jest.mock('../domains/shared/resource-discovery', () => {
+    const original = jest.requireActual('../domains/shared/resource-discovery');
+    return {
+        ...original,
+        gatherDiscoveredResources: jest.fn().mockResolvedValue({
+            defaultVpcId: 'vpc-123456',
+            defaultSecurityGroupId: 'sg-123456',
+            privateSubnetId1: 'subnet-1',
+            privateSubnetId2: 'subnet-2',
+            defaultKmsKeyId:
+                'arn:aws:kms:us-east-1:123456789012:key/abc-123',
+            auroraClusterEndpoint: 'c.cluster-x.us-east-1.rds.amazonaws.com',
+            auroraPort: 5432,
+        }),
+    };
+});
+
+const buildApp = (overrides = {}) => ({
+    name: 'preload-test',
+    provider: 'aws',
+    usePrismaLambdaLayer: false,
+    encryption: { fieldLevelEncryptionMethod: 'aes' },
+    vpc: { enable: false },
+    database: { postgres: { enable: true } },
+    websockets: { enable: true },
+    integrations: [{ Definition: { name: 'hubspot' } }],
+    ...overrides,
+});
+
+const IMPORT_FRAGMENT = '--import file:///var/task/node_modules/@friggframework/core/core/ssm-preload.mjs';
+
+describe('SSM preload NODE_OPTIONS scoping', () => {
+    beforeEach(() => {
+        process.argv = ['node', 'test'];
+        delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+    });
+
+    it('sets NODE_OPTIONS --import on skipEsbuild functions and NOT on esbuild-bundled ones when offload is active', async () => {
+        const definition = await composeServerlessDefinition(
+            buildApp({
+                ssm: { enable: true },
+                environment: { HUBSPOT_SECRET: 'ssm' },
+            })
+        );
+        const fns = definition.functions;
+
+        // skipEsbuild handlers (auth/user/health + integration) package the
+        // preload → they get the flag.
+        expect(fns.auth.skipEsbuild).toBe(true);
+        expect(fns.auth.environment.NODE_OPTIONS).toBe(IMPORT_FRAGMENT);
+        expect(fns.hubspot.environment.NODE_OPTIONS).toBe(IMPORT_FRAGMENT);
+
+        // defaultWebsocket is esbuild-bundled (no skipEsbuild) → MUST NOT get it.
+        expect(fns.defaultWebsocket.skipEsbuild).toBeFalsy();
+        expect(fns.defaultWebsocket.environment?.NODE_OPTIONS).toBeUndefined();
+
+        // Never global.
+        expect(definition.provider.environment.NODE_OPTIONS).toBeUndefined();
+    });
+
+    it('sets no NODE_OPTIONS anywhere when offload is inactive', async () => {
+        const definition = await composeServerlessDefinition(
+            buildApp({ ssm: { enable: true } }) // enabled, but no 'ssm' keys
+        );
+        for (const fn of Object.values(definition.functions)) {
+            expect(fn.environment?.NODE_OPTIONS).toBeUndefined();
+        }
+        expect(definition.provider.environment.NODE_OPTIONS).toBeUndefined();
+    });
+});

package/infrastructure/domains/parameters/offload-utils.js

@@ -16,6 +16,19 @@ const ENV_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
 const DEFAULT_PARAMETER_PREFIX =
     '/frigg/${self:service}/${self:provider.stage}';
 
+// INIT-phase preload shipped in @friggframework/core, present at this path in
+// every skipEsbuild handler (which packages the full node_modules tree).
+// LAMBDA_TASK_ROOT = /var/task.
+const SSM_PRELOAD_PATH =
+    '/var/task/node_modules/@friggframework/core/core/ssm-preload.mjs';
+
+// NODE_OPTIONS value that loads the INIT preload. Set ONLY on skipEsbuild
+// functions (esbuild-bundled functions do not package the .mjs, and a missing
+// --import target is a fatal Node startup error). No `${env:NODE_OPTIONS}`
+// prefix: that source resolves the deploy host's shell at package time, which
+// would leak an unrelated value into every Lambda.
+const SSM_PRELOAD_NODE_OPTIONS = `--import file://${SSM_PRELOAD_PATH}`;
+
 // Keys the framework itself sets (from discovered resources or the base
 // template) or that the loader/bypass handlers depend on before SSM values
 // are available. Never offloadable.
@@ -172,4 +185,6 @@ module.exports = {
     validateOffloadConfig,
     FRAMEWORK_ENV_BLOCKLIST,
     DEFAULT_PARAMETER_PREFIX,
+    SSM_PRELOAD_PATH,
+    SSM_PRELOAD_NODE_OPTIONS,
 };

package/infrastructure/domains/parameters/ssm-builder.js

@@ -16,11 +16,6 @@ const {
     validateOffloadConfig,
 } = require('./offload-utils');
 
-// INIT-phase preload shipped in @friggframework/core, packaged into every
-// skipEsbuild handler at this stable path (LAMBDA_TASK_ROOT = /var/task).
-const SSM_PRELOAD_PATH =
-    '/var/task/node_modules/@friggframework/core/core/ssm-preload.mjs';
-
 class SsmBuilder extends InfrastructureBuilder {
     constructor() {
         super();
@@ -98,15 +93,12 @@ class SsmBuilder extends InfrastructureBuilder {
             result.environment.SSM_PARAMETER_PREFIX = prefix;
             result.environment.FRIGG_SSM_OFFLOADED_KEYS = offloadedKeys.join(',');
 
-            // Populate offloaded values into process.env during Lambda INIT,
-            // BEFORE app modules load. api-modules capture OAuth client
-            // credentials at module-require time (top-level Definition.env), so
-            // the handler-time loader (parametersToEnv) is too late for them.
-            // NODE_OPTIONS=--import runs this ESM preload (top-level await) before
-            // the entry module. Shipped in @friggframework/core (packaged into
-            // every skipEsbuild handler at a stable path). Appended to any
-            // app-provided NODE_OPTIONS.
-            result.environment.NODE_OPTIONS = `\${env:NODE_OPTIONS, ''} --import file://${SSM_PRELOAD_PATH}`;
+            // The INIT-phase preload (NODE_OPTIONS=--import) that populates
+            // process.env before app modules load is set per-function on
+            // skipEsbuild handlers only — see infrastructure-composer.js. It
+            // cannot go here (provider.environment is global) because a missing
+            // --import target fatally aborts Node startup, and esbuild-bundled
+            // functions do not package the preload file.
 
             // Prefix-scoped read grant. Built as a plain serverless string (not
             // Fn::Sub) because the prefix contains serverless variables like

package/infrastructure/domains/parameters/ssm-builder.test.js

@@ -234,7 +234,7 @@ describe('SsmBuilder', () => {
             expect(result.environment.FRIGG_SSM_OFFLOADED_KEYS).toBe('BAR,FOO');
         });
 
-        it('sets NODE_OPTIONS to --import the INIT preload (appended to any app value)', async () => {
+        it('does not set NODE_OPTIONS globally (the composer scopes it to skipEsbuild functions)', async () => {
             const appDefinition = {
                 ssm: { enable: true },
                 environment: { FOO: 'ssm' },
@@ -242,18 +242,8 @@ describe('SsmBuilder', () => {
 
             const result = await ssmBuilder.build(appDefinition, {});
 
-            expect(result.environment.NODE_OPTIONS).toContain('--import');
-            expect(result.environment.NODE_OPTIONS).toContain(
-                '@friggframework/core/core/ssm-preload.mjs'
-            );
-            // Appends to any app-provided NODE_OPTIONS rather than clobbering it.
-            expect(result.environment.NODE_OPTIONS).toContain(
-                "${env:NODE_OPTIONS, ''}"
-            );
-        });
-
-        it('does not set NODE_OPTIONS when no keys are offloaded', async () => {
-            const result = await ssmBuilder.build({ ssm: { enable: true } }, {});
+            // NODE_OPTIONS=--import would fatally abort esbuild-bundled functions
+            // that lack the preload file, so it must never be provider-global.
             expect(result.environment.NODE_OPTIONS).toBeUndefined();
         });
 

package/infrastructure/infrastructure-composer.js

@@ -21,6 +21,30 @@ const { AdminScriptBuilder } = require('./domains/admin-scripts/admin-script-bui
 
 // Utilities
 const { applyFunctionEnvironments } = require('./domains/shared/function-environments');
+const {
+    isSsmOffloadActive,
+    SSM_PRELOAD_NODE_OPTIONS,
+} = require('./domains/parameters/offload-utils');
+
+/**
+ * Load the SSM INIT preload (NODE_OPTIONS=--import) on skipEsbuild handlers
+ * only. Those package the full node_modules tree, so the preload .mjs is
+ * present at /var/task. esbuild-bundled functions (e.g. defaultWebsocket,
+ * adopter custom functions) do NOT ship it — and a missing --import target is a
+ * fatal Node startup error — so they are left with the handler-time loader
+ * fallback instead. Set at function scope (function env wins over provider env).
+ */
+function applySsmPreloadNodeOptions(appDefinition, functions) {
+    if (!isSsmOffloadActive(appDefinition)) {
+        return;
+    }
+    for (const fn of Object.values(functions)) {
+        if (fn.skipEsbuild) {
+            fn.environment = fn.environment || {};
+            fn.environment.NODE_OPTIONS = SSM_PRELOAD_NODE_OPTIONS;
+        }
+    }
+}
 const { modifyHandlerPaths } = require('./domains/shared/utilities/handler-path-resolver');
 const { createBaseDefinition } = require('./domains/shared/utilities/base-definition-factory');
 const { ensurePrismaLayerExists } = require('./domains/shared/utilities/prisma-layer-manager');
@@ -80,6 +104,7 @@ const composeServerlessDefinition = async (AppDefinition) => {
         definition.functions,
         merged.functionEnvironments
     );
+    applySsmPreloadNodeOptions(AppDefinition, definition.functions);
 
     if (merged.vpcConfig) {
         definition.provider.vpc = merged.vpcConfig;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@friggframework/devtools",
   "prettier": "@friggframework/prettier-config",
-  "version": "2.0.0--canary.625.8f60019.0",
+  "version": "2.0.0--canary.625.3f500f2.0",
   "bin": {
     "frigg": "./frigg-cli/index.js"
   },
@@ -26,9 +26,9 @@
     "@babel/eslint-parser": "^7.18.9",
     "@babel/parser": "^7.25.3",
     "@babel/traverse": "^7.25.3",
-    "@friggframework/core": "2.0.0--canary.625.8f60019.0",
-    "@friggframework/schemas": "2.0.0--canary.625.8f60019.0",
-    "@friggframework/test": "2.0.0--canary.625.8f60019.0",
+    "@friggframework/core": "2.0.0--canary.625.3f500f2.0",
+    "@friggframework/schemas": "2.0.0--canary.625.3f500f2.0",
+    "@friggframework/test": "2.0.0--canary.625.3f500f2.0",
     "@hapi/boom": "^10.0.1",
     "@inquirer/prompts": "^5.3.8",
     "axios": "^1.18.0",
@@ -56,8 +56,8 @@
     "validate-npm-package-name": "^5.0.0"
   },
   "devDependencies": {
-    "@friggframework/eslint-config": "2.0.0--canary.625.8f60019.0",
-    "@friggframework/prettier-config": "2.0.0--canary.625.8f60019.0",
+    "@friggframework/eslint-config": "2.0.0--canary.625.3f500f2.0",
+    "@friggframework/prettier-config": "2.0.0--canary.625.3f500f2.0",
     "aws-sdk-client-mock": "^4.1.0",
     "aws-sdk-client-mock-jest": "^4.1.0",
     "jest": "^30.1.3",
@@ -89,5 +89,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8f600193664963446e2c59c4b05ee076b0fbdc2a"
+  "gitHead": "3f500f202c8dcf2210c07835c76abbab30e0d0ee"
 }