@friggframework/devtools 2.0.0--canary.625.6bef7de.0 → 2.0.0--canary.622.8425dec.0

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

@@ -1,15 +1,40 @@
 /**
  * Environment Builder Service
- * 
+ *
  * Domain Service - Hexagonal Architecture
- * 
+ *
  * Builds Lambda environment variable configuration from:
  * 1. AppDefinition environment flags
  * 2. Discovered AWS resources (VPC IDs, KMS keys, etc.)
  * 3. Generated resource references
  */
 
-const { isSsmOffloadActive, getOffloadedKeys } = require('../parameters/offload-utils');
+const {
+    isSsmOffloadActive,
+    getOffloadedKeys,
+} = require('../parameters/offload-utils');
+
+// OTLP-family exporters read their endpoint/headers from these standard env
+// vars (ADR-011). When such an exporter is configured we auto-register them as
+// Serverless passthroughs so the deployed Lambda inherits them from the deploy
+// environment — no need for the adopter to also list them under `environment`.
+//
+// NOTE (VPC egress): a Lambda in a private subnet needs a NAT gateway or a VPC
+// endpoint to reach an external OTLP backend (Honeycomb/Datadog). Without egress
+// the exporter fails silently within its flush timeout — see the deploy docs.
+const OTLP_EXPORTER_TYPES = new Set(['otlp', 'honeycomb', 'datadog']);
+const OTEL_PASSTHROUGH_VARS = [
+    'OTEL_EXPORTER_OTLP_ENDPOINT',
+    'OTEL_EXPORTER_OTLP_HEADERS',
+];
+
+function addTelemetryEnvPassthrough(appDefinition, envVars) {
+    const exporterType = appDefinition?.telemetry?.exporter?.type;
+    if (!OTLP_EXPORTER_TYPES.has(exporterType)) return;
+    for (const key of OTEL_PASSTHROUGH_VARS) {
+        envVars[key] = `\${env:${key}, ''}`;
+    }
+}
 
 /**
  * Get environment variables from AppDefinition
@@ -45,6 +70,8 @@ function getAppEnvironmentVars(appDefinition) {
         'AWS_SESSION_TOKEN',
     ]);
 
+    addTelemetryEnvPassthrough(appDefinition, envVars);
+
     const environment = appDefinition.environment || {};
 
     console.log('📋 Loading environment variables from appDefinition...');
@@ -94,15 +121,16 @@ function getAppEnvironmentVars(appDefinition) {
     }
     if (skippedKeys.length > 0) {
         console.log(
-            `   ⚠️  Skipped ${skippedKeys.length
+            `   ⚠️  Skipped ${
+                skippedKeys.length
             } reserved AWS Lambda variables: ${skippedKeys.join(', ')}`
         );
     }
     if (offloadedKeys.length > 0) {
         console.log(
-            `   🔒 Offloaded ${offloadedKeys.length} variables to SSM: ${offloadedKeys.join(
-                ', '
-            )}`
+            `   🔒 Offloaded ${
+                offloadedKeys.length
+            } variables to SSM: ${offloadedKeys.join(', ')}`
         );
     }
 
@@ -111,9 +139,9 @@ function getAppEnvironmentVars(appDefinition) {
 
 /**
  * Build complete environment configuration for Lambda functions
- * 
+ *
  * Combines app environment vars with discovered AWS resource references
- * 
+ *
  * @param {Object} appEnvironmentVars - Environment vars from AppDefinition
  * @param {Object} discoveredResources - Discovered AWS resources
  * @returns {Object} Complete environment configuration
@@ -121,7 +149,7 @@ function getAppEnvironmentVars(appDefinition) {
 function buildEnvironment(appEnvironmentVars, discoveredResources) {
     const environment = {
         ...appEnvironmentVars,
-        STAGE: '${self:provider.stage}',  // Used by encryption bypass logic
+        STAGE: '${self:provider.stage}', // Used by encryption bypass logic
         FRIGG_STACK: '${self:service}',
         FRIGG_STAGE: '${self:provider.stage}',
         FRIGG_REGION: '${self:provider.region}',
@@ -137,7 +165,9 @@ function buildEnvironment(appEnvironmentVars, discoveredResources) {
     // Add database connection info if discovered
     if (discoveredResources.auroraClusterEndpoint) {
         environment.DATABASE_HOST = discoveredResources.auroraClusterEndpoint;
-        environment.DATABASE_PORT = String(discoveredResources.auroraPort || 5432);
+        environment.DATABASE_PORT = String(
+            discoveredResources.auroraPort || 5432
+        );
     }
 
     // Add secrets manager secret ARN if discovered
@@ -152,4 +182,3 @@ module.exports = {
     getAppEnvironmentVars,
     buildEnvironment,
 };
-

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

@@ -1,10 +1,13 @@
 /**
  * Tests for Environment Builder Service
- * 
+ *
  * Tests environment variable extraction and building
  */
 
-const { getAppEnvironmentVars, buildEnvironment } = require('./environment-builder');
+const {
+    getAppEnvironmentVars,
+    buildEnvironment,
+} = require('./environment-builder');
 
 describe('Environment Builder', () => {
     describe('getAppEnvironmentVars()', () => {
@@ -108,6 +111,42 @@ describe('Environment Builder', () => {
         });
     });
 
+    describe('telemetry env passthrough (ADR-011)', () => {
+        it('auto-adds OTLP env passthroughs when an OTLP-family exporter is configured', () => {
+            const result = getAppEnvironmentVars({
+                telemetry: { exporter: { type: 'otlp' } },
+            });
+
+            expect(result.OTEL_EXPORTER_OTLP_ENDPOINT).toBe(
+                "${env:OTEL_EXPORTER_OTLP_ENDPOINT, ''}"
+            );
+            expect(result.OTEL_EXPORTER_OTLP_HEADERS).toBe(
+                "${env:OTEL_EXPORTER_OTLP_HEADERS, ''}"
+            );
+        });
+
+        it.each(['honeycomb', 'datadog'])(
+            'adds OTLP passthroughs for the "%s" preset',
+            (type) => {
+                const result = getAppEnvironmentVars({
+                    telemetry: { exporter: { type } },
+                });
+                expect(result.OTEL_EXPORTER_OTLP_ENDPOINT).toBeDefined();
+            }
+        );
+
+        it('adds no OTLP env vars for console/none exporters or absent telemetry', () => {
+            expect(
+                getAppEnvironmentVars({
+                    telemetry: { exporter: { type: 'console' } },
+                }).OTEL_EXPORTER_OTLP_ENDPOINT
+            ).toBeUndefined();
+            expect(
+                getAppEnvironmentVars({}).OTEL_EXPORTER_OTLP_ENDPOINT
+            ).toBeUndefined();
+        });
+    });
+
     describe("getAppEnvironmentVars() - 'ssm' offload", () => {
         const originalSkipDiscovery = process.env.FRIGG_SKIP_AWS_DISCOVERY;
 
@@ -161,13 +200,17 @@ describe('Environment Builder', () => {
             const appDefinition = {
                 ssm: {
                     enable: true,
-                    parameters: { HUBSPOT_CLIENT_SECRET: { type: 'SecureString' } },
+                    parameters: {
+                        HUBSPOT_CLIENT_SECRET: { type: 'SecureString' },
+                    },
                 },
             };
 
             const result = getAppEnvironmentVars(appDefinition);
 
-            expect(result.HUBSPOT_CLIENT_SECRET).toBe("${env:HUBSPOT_CLIENT_SECRET, ''}");
+            expect(result.HUBSPOT_CLIENT_SECRET).toBe(
+                "${env:HUBSPOT_CLIENT_SECRET, ''}"
+            );
         });
 
         it('excludes a key declared only in ssm.parameters when offload is active', () => {
@@ -175,7 +218,9 @@ describe('Environment Builder', () => {
             const appDefinition = {
                 ssm: {
                     enable: true,
-                    parameters: { HUBSPOT_CLIENT_SECRET: { type: 'SecureString' } },
+                    parameters: {
+                        HUBSPOT_CLIENT_SECRET: { type: 'SecureString' },
+                    },
                 },
             };
 
@@ -211,7 +256,10 @@ describe('Environment Builder', () => {
             };
             const discoveredResources = {};
 
-            const result = buildEnvironment(appEnvironmentVars, discoveredResources);
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
 
             expect(result.API_KEY).toBe("${env:API_KEY, ''}");
             expect(result.STAGE).toBe('${self:provider.stage}');
@@ -226,9 +274,14 @@ describe('Environment Builder', () => {
                 kmsKeyId: 'arn:aws:kms:us-east-1:123456:key/abc-123',
             };
 
-            const result = buildEnvironment(appEnvironmentVars, discoveredResources);
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
 
-            expect(result.KMS_KEY_ARN).toBe('arn:aws:kms:us-east-1:123456:key/abc-123');
+            expect(result.KMS_KEY_ARN).toBe(
+                'arn:aws:kms:us-east-1:123456:key/abc-123'
+            );
         });
 
         it('should prefer kmsKeyId over kmsKeyArn if both present', () => {
@@ -238,22 +291,33 @@ describe('Environment Builder', () => {
                 kmsKeyArn: 'arn:aws:kms:us-east-1:123456:key/secondary',
             };
 
-            const result = buildEnvironment(appEnvironmentVars, discoveredResources);
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
 
             // Implementation uses if/else-if, so kmsKeyId takes priority
-            expect(result.KMS_KEY_ARN).toBe('arn:aws:kms:us-east-1:123456:key/primary');
+            expect(result.KMS_KEY_ARN).toBe(
+                'arn:aws:kms:us-east-1:123456:key/primary'
+            );
         });
 
         it('should add database connection info if discovered', () => {
             const appEnvironmentVars = {};
             const discoveredResources = {
-                auroraClusterEndpoint: 'cluster.abc.us-east-1.rds.amazonaws.com',
+                auroraClusterEndpoint:
+                    'cluster.abc.us-east-1.rds.amazonaws.com',
                 auroraPort: 5432,
             };
 
-            const result = buildEnvironment(appEnvironmentVars, discoveredResources);
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
 
-            expect(result.DATABASE_HOST).toBe('cluster.abc.us-east-1.rds.amazonaws.com');
+            expect(result.DATABASE_HOST).toBe(
+                'cluster.abc.us-east-1.rds.amazonaws.com'
+            );
             expect(result.DATABASE_PORT).toBe('5432');
         });
 
@@ -263,7 +327,10 @@ describe('Environment Builder', () => {
                 auroraClusterEndpoint: 'cluster.example.com',
             };
 
-            const result = buildEnvironment(appEnvironmentVars, discoveredResources);
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
 
             expect(result.DATABASE_HOST).toBe('cluster.example.com');
             expect(result.DATABASE_PORT).toBe('5432');
@@ -272,12 +339,18 @@ describe('Environment Builder', () => {
         it('should add database secret ARN if discovered', () => {
             const appEnvironmentVars = {};
             const discoveredResources = {
-                databaseSecretArn: 'arn:aws:secretsmanager:us-east-1:123456:secret:db-secret',
+                databaseSecretArn:
+                    'arn:aws:secretsmanager:us-east-1:123456:secret:db-secret',
             };
 
-            const result = buildEnvironment(appEnvironmentVars, discoveredResources);
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
 
-            expect(result.DATABASE_SECRET_ARN).toBe('arn:aws:secretsmanager:us-east-1:123456:secret:db-secret');
+            expect(result.DATABASE_SECRET_ARN).toBe(
+                'arn:aws:secretsmanager:us-east-1:123456:secret:db-secret'
+            );
         });
 
         it('should combine all discovered resources', () => {
@@ -288,19 +361,27 @@ describe('Environment Builder', () => {
                 kmsKeyArn: 'arn:aws:kms:us-east-1:123456:key/abc',
                 auroraClusterEndpoint: 'db.example.com',
                 auroraPort: 3306,
-                databaseSecretArn: 'arn:aws:secretsmanager:us-east-1:123456:secret:db',
+                databaseSecretArn:
+                    'arn:aws:secretsmanager:us-east-1:123456:secret:db',
             };
 
-            const result = buildEnvironment(appEnvironmentVars, discoveredResources);
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
 
             expect(result.CUSTOM_VAR).toBe("${env:CUSTOM_VAR, ''}");
             expect(result.FRIGG_STACK).toBe('${self:service}');
             expect(result.FRIGG_STAGE).toBe('${self:provider.stage}');
             expect(result.FRIGG_REGION).toBe('${self:provider.region}');
-            expect(result.KMS_KEY_ARN).toBe('arn:aws:kms:us-east-1:123456:key/abc');
+            expect(result.KMS_KEY_ARN).toBe(
+                'arn:aws:kms:us-east-1:123456:key/abc'
+            );
             expect(result.DATABASE_HOST).toBe('db.example.com');
             expect(result.DATABASE_PORT).toBe('3306');
-            expect(result.DATABASE_SECRET_ARN).toBe('arn:aws:secretsmanager:us-east-1:123456:secret:db');
+            expect(result.DATABASE_SECRET_ARN).toBe(
+                'arn:aws:secretsmanager:us-east-1:123456:secret:db'
+            );
         });
 
         it('should handle empty discoveredResources', () => {
@@ -309,7 +390,10 @@ describe('Environment Builder', () => {
             };
             const discoveredResources = {};
 
-            const result = buildEnvironment(appEnvironmentVars, discoveredResources);
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
 
             expect(result.API_KEY).toBe("${env:API_KEY, ''}");
             expect(result.FRIGG_STACK).toBe('${self:service}');
@@ -333,11 +417,13 @@ describe('Environment Builder', () => {
                 auroraPort: 3306, // Number
             };
 
-            const result = buildEnvironment(appEnvironmentVars, discoveredResources);
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
 
             expect(result.DATABASE_PORT).toBe('3306'); // String
             expect(typeof result.DATABASE_PORT).toBe('string');
         });
     });
 });
-

package/infrastructure/infrastructure-composer.js

@@ -32,17 +32,30 @@ const {
  * 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).
+ * 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) {
+function applySsmPreloadNodeOptions(appDefinition, functions, providerEnvironment = {}) {
     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;
+        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');
@@ -104,7 +117,11 @@ const composeServerlessDefinition = async (AppDefinition) => {
         definition.functions,
         merged.functionEnvironments
     );
-    applySsmPreloadNodeOptions(AppDefinition, definition.functions);
+    applySsmPreloadNodeOptions(
+        AppDefinition,
+        definition.functions,
+        definition.provider.environment
+    );
 
     if (merged.vpcConfig) {
         definition.provider.vpc = merged.vpcConfig;
@@ -147,5 +164,5 @@ const composeServerlessDefinition = async (AppDefinition) => {
     return definition;
 };
 
-module.exports = { composeServerlessDefinition };
+module.exports = { composeServerlessDefinition, applySsmPreloadNodeOptions };
 

package/infrastructure/infrastructure-composer.test.js

@@ -1,4 +1,10 @@
-const { composeServerlessDefinition } = require('./infrastructure-composer');
+const {
+    composeServerlessDefinition,
+    applySsmPreloadNodeOptions,
+} = require('./infrastructure-composer');
+const {
+    SSM_PRELOAD_NODE_OPTIONS,
+} = require('./domains/parameters/offload-utils');
 
 // Helper to build discovery responses with overridable fields
 const createDiscoveryResponse = (overrides = {}) => ({
@@ -1949,3 +1955,88 @@ describe('composeServerlessDefinition', () => {
         });
     });
 });
+
+describe('applySsmPreloadNodeOptions', () => {
+    const appDefinition = {
+        ssm: { enable: true },
+        environment: { FOO: 'ssm' },
+    };
+    const savedSkip = process.env.FRIGG_SKIP_AWS_DISCOVERY;
+
+    beforeEach(() => {
+        delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+    });
+
+    afterEach(() => {
+        if (savedSkip === undefined) {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+        } else {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = savedSkip;
+        }
+    });
+
+    it('sets the preload NODE_OPTIONS on a skipEsbuild function with no existing value', () => {
+        const functions = { auth: { skipEsbuild: true } };
+        applySsmPreloadNodeOptions(appDefinition, functions);
+        expect(functions.auth.environment.NODE_OPTIONS).toBe(
+            SSM_PRELOAD_NODE_OPTIONS
+        );
+    });
+
+    it('appends to an existing function-level NODE_OPTIONS instead of clobbering it', () => {
+        const functions = {
+            auth: {
+                skipEsbuild: true,
+                environment: { NODE_OPTIONS: '--enable-source-maps' },
+            },
+        };
+        applySsmPreloadNodeOptions(appDefinition, functions);
+        expect(functions.auth.environment.NODE_OPTIONS).toBe(
+            `--enable-source-maps ${SSM_PRELOAD_NODE_OPTIONS}`
+        );
+    });
+
+    it('folds in a provider-level NODE_OPTIONS (which the function env would otherwise shadow)', () => {
+        const functions = { auth: { skipEsbuild: true } };
+        applySsmPreloadNodeOptions(appDefinition, functions, {
+            NODE_OPTIONS: '--require ./otel.js',
+        });
+        expect(functions.auth.environment.NODE_OPTIONS).toBe(
+            `--require ./otel.js ${SSM_PRELOAD_NODE_OPTIONS}`
+        );
+    });
+
+    it('prefers a function-level value over the provider-level one', () => {
+        const functions = {
+            auth: {
+                skipEsbuild: true,
+                environment: { NODE_OPTIONS: '--fn-flag' },
+            },
+        };
+        applySsmPreloadNodeOptions(appDefinition, functions, {
+            NODE_OPTIONS: '--provider-flag',
+        });
+        expect(functions.auth.environment.NODE_OPTIONS).toBe(
+            `--fn-flag ${SSM_PRELOAD_NODE_OPTIONS}`
+        );
+    });
+
+    it('never touches esbuild-bundled functions', () => {
+        const functions = {
+            websocket: { environment: { NODE_OPTIONS: '--keep-me' } },
+        };
+        applySsmPreloadNodeOptions(appDefinition, functions, {
+            NODE_OPTIONS: '--provider',
+        });
+        expect(functions.websocket.environment.NODE_OPTIONS).toBe('--keep-me');
+    });
+
+    it('is a no-op when offload is inactive', () => {
+        const functions = { auth: { skipEsbuild: true } };
+        applySsmPreloadNodeOptions(
+            { ssm: { enable: true } }, // no offloaded keys → inactive
+            functions
+        );
+        expect(functions.auth.environment).toBeUndefined();
+    });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@friggframework/devtools",
   "prettier": "@friggframework/prettier-config",
-  "version": "2.0.0--canary.625.6bef7de.0",
+  "version": "2.0.0--canary.622.8425dec.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.6bef7de.0",
-    "@friggframework/schemas": "2.0.0--canary.625.6bef7de.0",
-    "@friggframework/test": "2.0.0--canary.625.6bef7de.0",
+    "@friggframework/core": "2.0.0--canary.622.8425dec.0",
+    "@friggframework/schemas": "2.0.0--canary.622.8425dec.0",
+    "@friggframework/test": "2.0.0--canary.622.8425dec.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.6bef7de.0",
-    "@friggframework/prettier-config": "2.0.0--canary.625.6bef7de.0",
+    "@friggframework/eslint-config": "2.0.0--canary.622.8425dec.0",
+    "@friggframework/prettier-config": "2.0.0--canary.622.8425dec.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": "6bef7de84e4deea31c8dea40c177e2f7343eea4c"
+  "gitHead": "8425dec6d3f2c09f7906f1e36c6856f63e1e69f9"
 }