@friggframework/devtools 2.0.0-next.100 → 2.0.0-next.102

package/infrastructure/domains/shared/environment-builder.js

@@ -9,12 +9,19 @@
  * 3. Generated resource references
  */
 
+const { isSsmOffloadActive, getOffloadedKeys } = require('../parameters/offload-utils');
+
 /**
  * Get environment variables from AppDefinition
- * 
+ *
  * Extracts environment variable definitions where value is true,
  * and creates Serverless variable references.
- * 
+ *
+ * A value of 'ssm' offloads the variable to Parameter Store when offload is
+ * active (see SsmBuilder), keeping it out of the Lambda env map. When offload
+ * is not active (local mode / ssm disabled) it falls back to the same
+ * `${env:KEY, ''}` reference as `true` so `frigg start` + dotenv keeps working.
+ *
  * @param {Object} appDefinition - Application definition
  * @returns {Object} Environment variable mappings
  */
@@ -38,16 +45,38 @@ function getAppEnvironmentVars(appDefinition) {
         'AWS_SESSION_TOKEN',
     ]);
 
-    if (!appDefinition.environment) {
-        return envVars;
-    }
+    const environment = appDefinition.environment || {};
 
     console.log('📋 Loading environment variables from appDefinition...');
     const envKeys = [];
     const skippedKeys = [];
+    const offloadedKeys = [];
+    const offloadActive = isSsmOffloadActive(appDefinition);
 
-    for (const [key, value] of Object.entries(appDefinition.environment)) {
-        if (value !== true) continue;
+    for (const [key, value] of Object.entries(environment)) {
+        if (value === 'ssm' && offloadActive) {
+            offloadedKeys.push(key);
+            continue;
+        }
+        if (value !== true && value !== 'ssm') continue;
+        if (reservedVars.has(key)) {
+            skippedKeys.push(key);
+            continue;
+        }
+        envVars[key] = `\${env:${key}, ''}`;
+        envKeys.push(key);
+    }
+
+    // Keys declared only in ssm.parameters (no matching `environment` entry)
+    // get the same local-fallback treatment as `environment`-valued 'ssm' keys.
+    const ssmOnlyKeys = getOffloadedKeys(appDefinition).filter(
+        (key) => !(key in environment)
+    );
+    for (const key of ssmOnlyKeys) {
+        if (offloadActive) {
+            offloadedKeys.push(key);
+            continue;
+        }
         if (reservedVars.has(key)) {
             skippedKeys.push(key);
             continue;
@@ -69,6 +98,13 @@ function getAppEnvironmentVars(appDefinition) {
             } reserved AWS Lambda variables: ${skippedKeys.join(', ')}`
         );
     }
+    if (offloadedKeys.length > 0) {
+        console.log(
+            `   🔒 Offloaded ${offloadedKeys.length} variables to SSM: ${offloadedKeys.join(
+                ', '
+            )}`
+        );
+    }
 
     return envVars;
 }

package/infrastructure/domains/shared/environment-builder.test.js

@@ -38,7 +38,7 @@ describe('Environment Builder', () => {
             expect(result.DISABLED_VAR).toBeUndefined();
         });
 
-        it('should ignore environment variables with non-boolean values', () => {
+        it("ignores non-boolean values other than the meaningful 'ssm' marker", () => {
             const appDefinition = {
                 environment: {
                     VALID: true,
@@ -108,6 +108,102 @@ describe('Environment Builder', () => {
         });
     });
 
+    describe("getAppEnvironmentVars() - 'ssm' offload", () => {
+        const originalSkipDiscovery = process.env.FRIGG_SKIP_AWS_DISCOVERY;
+
+        afterEach(() => {
+            if (originalSkipDiscovery === undefined) {
+                delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            } else {
+                process.env.FRIGG_SKIP_AWS_DISCOVERY = originalSkipDiscovery;
+            }
+        });
+
+        it("excludes 'ssm' keys when offload is active", () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                ssm: { enable: true },
+                environment: { FOO: 'ssm', BAR: true },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.FOO).toBeUndefined();
+            expect(result.BAR).toBe("${env:BAR, ''}");
+        });
+
+        it("falls back to env reference for 'ssm' keys when FRIGG_SKIP_AWS_DISCOVERY is set", () => {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = 'true';
+            const appDefinition = {
+                ssm: { enable: true },
+                environment: { FOO: 'ssm' },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.FOO).toBe("${env:FOO, ''}");
+        });
+
+        it("falls back to env reference for 'ssm' keys when ssm is disabled", () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                ssm: { enable: false },
+                environment: { FOO: 'ssm' },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.FOO).toBe("${env:FOO, ''}");
+        });
+
+        it('falls back to env reference for a key declared only in ssm.parameters when FRIGG_SKIP_AWS_DISCOVERY is set', () => {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = 'true';
+            const appDefinition = {
+                ssm: {
+                    enable: true,
+                    parameters: { HUBSPOT_CLIENT_SECRET: { type: 'SecureString' } },
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.HUBSPOT_CLIENT_SECRET).toBe("${env:HUBSPOT_CLIENT_SECRET, ''}");
+        });
+
+        it('excludes a key declared only in ssm.parameters when offload is active', () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                ssm: {
+                    enable: true,
+                    parameters: { HUBSPOT_CLIENT_SECRET: { type: 'SecureString' } },
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.HUBSPOT_CLIENT_SECRET).toBeUndefined();
+        });
+
+        it("does not double-process a key present in both environment:'ssm' and ssm.parameters", () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                ssm: {
+                    enable: true,
+                    parameters: { FOO: { type: 'SecureString' } },
+                },
+                environment: { FOO: 'ssm' },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.FOO).toBeUndefined();
+
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = 'true';
+            const fallbackResult = getAppEnvironmentVars(appDefinition);
+            expect(fallbackResult.FOO).toBe("${env:FOO, ''}");
+        });
+    });
+
     describe('buildEnvironment()', () => {
         it('should combine app vars with standard Frigg variables', () => {
             const appEnvironmentVars = {

package/infrastructure/domains/shared/function-environments.js

@@ -0,0 +1,97 @@
+/**
+ * Per-function environment scoping (ADR-027)
+ *
+ * Builders emit `result.functionEnvironments` — a map of function name to
+ * env vars — instead of broadcasting framework vars app-wide through
+ * `result.environment`. The composer applies the merged map onto the final
+ * function definitions after every function (base + builder) exists.
+ */
+
+/**
+ * Whether builders should scope framework env vars per function. Skipped in
+ * local mode: the serverless-plugin injects LocalStack queue URLs at
+ * provider level only, and function-level values would shadow them.
+ *
+ * @param {Object} appDefinition
+ * @returns {boolean}
+ */
+function isScopedEnvironmentActive(appDefinition = {}) {
+    if (process.env.FRIGG_SKIP_AWS_DISCOVERY === 'true') return false;
+    return appDefinition.lambda?.scopedEnvironment === true;
+}
+
+/**
+ * Apply a merged functionEnvironments map onto the composed functions.
+ * A key a builder already set directly on a function wins (e.g. the
+ * admin-script router's own SCHEDULER_ROLE_ARN must not be clobbered by
+ * the integration-scheduler value). An unknown function name is a hard
+ * error — silently dropping a var would surface as a runtime failure.
+ *
+ * @param {Object} functions - definition.functions (mutated)
+ * @param {Object} functionEnvironments - { fnName: { KEY: value } }
+ */
+function applyFunctionEnvironments(functions, functionEnvironments = {}) {
+    for (const [fnName, env] of Object.entries(functionEnvironments)) {
+        const fn = functions[fnName];
+        if (!fn) {
+            throw new Error(
+                `functionEnvironments targets unknown function '${fnName}' (known: ${Object.keys(
+                    functions
+                ).join(', ')})`
+            );
+        }
+        fn.environment = { ...env, ...(fn.environment || {}) };
+    }
+}
+
+/**
+ * Function names the integration builder creates for one integration.
+ * Wire contract: must stay in sync with
+ * IntegrationBuilder.createFunctionDefinitions — a drift here surfaces as a
+ * hard unknown-function error at compose time, not a silent var drop.
+ *
+ * @param {Object} integration - entry from appDefinition.integrations
+ * @returns {string[]}
+ */
+function getIntegrationFunctionNames(integration) {
+    const name = integration.Definition.name;
+    const names = [name, `${name}QueueWorker`];
+
+    const webhooks = integration.Definition.webhooks;
+    if (webhooks === true || webhooks?.enabled === true) {
+        names.splice(1, 0, `${name}Webhook`);
+    }
+
+    for (const [bindingKey, binding] of Object.entries(
+        integration.Definition.extensions || {}
+    )) {
+        const routes = binding?.extension?.routes || [];
+        if (routes.length === 0) continue;
+        names.push(`${name}__${String(bindingKey).replace(/[^A-Za-z0-9]/g, '')}`);
+    }
+
+    return names;
+}
+
+/**
+ * Admin-script functions, when the feature is on (mirrors
+ * AdminScriptBuilder.shouldExecute). Both can instantiate arbitrary
+ * integrations, so they belong in every integration's queue-URL consumer
+ * set.
+ *
+ * @param {Object} appDefinition
+ * @returns {string[]}
+ */
+function getAdminFunctionNames(appDefinition = {}) {
+    return Array.isArray(appDefinition.adminScripts) &&
+        appDefinition.adminScripts.length > 0
+        ? ['adminScriptRouter', 'adminScriptExecutor']
+        : [];
+}
+
+module.exports = {
+    isScopedEnvironmentActive,
+    applyFunctionEnvironments,
+    getIntegrationFunctionNames,
+    getAdminFunctionNames,
+};

package/infrastructure/domains/shared/function-environments.test.js

@@ -0,0 +1,146 @@
+const {
+    isScopedEnvironmentActive,
+    applyFunctionEnvironments,
+} = require('./function-environments');
+
+describe('function-environments', () => {
+    const originalSkipDiscovery = process.env.FRIGG_SKIP_AWS_DISCOVERY;
+
+    afterEach(() => {
+        if (originalSkipDiscovery === undefined) {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+        } else {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = originalSkipDiscovery;
+        }
+    });
+
+    describe('isScopedEnvironmentActive', () => {
+        it('is true only when lambda.scopedEnvironment is set', () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            expect(
+                isScopedEnvironmentActive({
+                    lambda: { scopedEnvironment: true },
+                })
+            ).toBe(true);
+            expect(isScopedEnvironmentActive({})).toBe(false);
+            expect(
+                isScopedEnvironmentActive({
+                    lambda: { scopedEnvironment: false },
+                })
+            ).toBe(false);
+        });
+
+        it('is false in local mode: the serverless-plugin injects LocalStack queue URLs at provider level only', () => {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = 'true';
+            expect(
+                isScopedEnvironmentActive({
+                    lambda: { scopedEnvironment: true },
+                })
+            ).toBe(false);
+        });
+    });
+
+    describe('getIntegrationFunctionNames', () => {
+        const { getIntegrationFunctionNames } = require('./function-environments');
+
+        it('always includes the router and queue worker', () => {
+            expect(
+                getIntegrationFunctionNames({ Definition: { name: 'hubspot' } })
+            ).toEqual(['hubspot', 'hubspotQueueWorker']);
+        });
+
+        it('includes the webhook handler when webhooks are enabled', () => {
+            expect(
+                getIntegrationFunctionNames({
+                    Definition: { name: 'hubspot', webhooks: true },
+                })
+            ).toContain('hubspotWebhook');
+            expect(
+                getIntegrationFunctionNames({
+                    Definition: { name: 'hubspot', webhooks: { enabled: true } },
+                })
+            ).toContain('hubspotWebhook');
+            expect(
+                getIntegrationFunctionNames({
+                    Definition: { name: 'hubspot', webhooks: { enabled: false } },
+                })
+            ).not.toContain('hubspotWebhook');
+        });
+
+        it('includes one function per routed extension binding, sanitized', () => {
+            const names = getIntegrationFunctionNames({
+                Definition: {
+                    name: 'hubspot',
+                    extensions: {
+                        'my-ext': { extension: { routes: [{ path: '/x', method: 'GET' }] } },
+                        routeless: { extension: { routes: [] } },
+                    },
+                },
+            });
+            expect(names).toContain('hubspot__myext');
+            expect(names).not.toContain('hubspot__routeless');
+        });
+    });
+
+    describe('getAdminFunctionNames', () => {
+        const { getAdminFunctionNames } = require('./function-environments');
+
+        it('returns the admin functions only when admin scripts are configured', () => {
+            expect(
+                getAdminFunctionNames({ adminScripts: [{ Definition: { name: 'x' } }] })
+            ).toEqual(['adminScriptRouter', 'adminScriptExecutor']);
+            expect(getAdminFunctionNames({})).toEqual([]);
+            expect(getAdminFunctionNames({ adminScripts: [] })).toEqual([]);
+        });
+    });
+
+    describe('applyFunctionEnvironments', () => {
+        const makeFunctions = () => ({
+            auth: { handler: 'auth.handler' },
+            hubspot: {
+                handler: 'hubspot.handler',
+                environment: { EXISTING: 'builder-set' },
+            },
+        });
+
+        it('assigns scoped env vars onto the target functions', () => {
+            const functions = makeFunctions();
+            applyFunctionEnvironments(functions, {
+                auth: { HUBSPOT_QUEUE_URL: 'url-1' },
+                hubspot: { HUBSPOT_QUEUE_URL: 'url-1' },
+            });
+
+            expect(functions.auth.environment).toEqual({
+                HUBSPOT_QUEUE_URL: 'url-1',
+            });
+            expect(functions.hubspot.environment).toEqual({
+                EXISTING: 'builder-set',
+                HUBSPOT_QUEUE_URL: 'url-1',
+            });
+        });
+
+        it('never clobbers a key a builder already set directly on the function', () => {
+            const functions = makeFunctions();
+            applyFunctionEnvironments(functions, {
+                hubspot: { EXISTING: 'scoped-value', OTHER: 'x' },
+            });
+
+            expect(functions.hubspot.environment.EXISTING).toBe('builder-set');
+            expect(functions.hubspot.environment.OTHER).toBe('x');
+        });
+
+        it('throws on an unknown function name instead of silently dropping vars', () => {
+            expect(() =>
+                applyFunctionEnvironments(makeFunctions(), {
+                    typoFunction: { A: '1' },
+                })
+            ).toThrow(/typoFunction/);
+        });
+
+        it('is a no-op for an empty map', () => {
+            const functions = makeFunctions();
+            applyFunctionEnvironments(functions, {});
+            expect(functions.auth.environment).toBeUndefined();
+        });
+    });
+});

package/infrastructure/infrastructure-composer.js

@@ -20,6 +20,44 @@ const { SchedulerBuilder } = require('./domains/scheduler/scheduler-builder');
 const { AdminScriptBuilder } = require('./domains/admin-scripts/admin-script-builder');
 
 // 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), APPENDED to any
+ * NODE_OPTIONS already on the function or provider — so an app's own flags
+ * (OTel auto-instrumentation, source maps, memory tuning) survive instead of
+ * being clobbered. A function-level assignment shadows provider env in Lambda,
+ * so the provider value must be folded in here. Only a value already in the
+ * definition is appended — never a synthesized ${env:NODE_OPTIONS}, which would
+ * leak the deploy host's shell into every Lambda.
+ */
+function applySsmPreloadNodeOptions(appDefinition, functions, providerEnvironment = {}) {
+    if (!isSsmOffloadActive(appDefinition)) {
+        return;
+    }
+    for (const fn of Object.values(functions)) {
+        if (!fn.skipEsbuild) {
+            continue;
+        }
+        fn.environment = fn.environment || {};
+        const existing =
+            fn.environment.NODE_OPTIONS ?? providerEnvironment.NODE_OPTIONS;
+        fn.environment.NODE_OPTIONS = existing
+            ? `${existing} ${SSM_PRELOAD_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');
@@ -75,6 +113,15 @@ const composeServerlessDefinition = async (AppDefinition) => {
     definition.provider.iamRoleStatements.push(...merged.iamStatements);
     Object.assign(definition.provider.environment, merged.environment);
     Object.assign(definition.functions, merged.functions);
+    applyFunctionEnvironments(
+        definition.functions,
+        merged.functionEnvironments
+    );
+    applySsmPreloadNodeOptions(
+        AppDefinition,
+        definition.functions,
+        definition.provider.environment
+    );
 
     if (merged.vpcConfig) {
         definition.provider.vpc = merged.vpcConfig;
@@ -117,5 +164,5 @@ const composeServerlessDefinition = async (AppDefinition) => {
     return definition;
 };
 
-module.exports = { composeServerlessDefinition };
+module.exports = { composeServerlessDefinition, applySsmPreloadNodeOptions };