@friggframework/devtools 2.0.0-next.11 → 2.0.0-next.110

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

@@ -0,0 +1,529 @@
+/**
+ * Tests for Environment Builder Service
+ *
+ * Tests environment variable extraction and building
+ */
+
+const {
+    getAppEnvironmentVars,
+    buildEnvironment,
+} = require('./environment-builder');
+
+describe('Environment Builder', () => {
+    describe('getAppEnvironmentVars()', () => {
+        it('should extract environment variables with value true', () => {
+            const appDefinition = {
+                environment: {
+                    API_KEY: true,
+                    DATABASE_URL: true,
+                    CUSTOM_VAR: true,
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.API_KEY).toBe("${env:API_KEY, ''}");
+            expect(result.DATABASE_URL).toBe("${env:DATABASE_URL, ''}");
+            expect(result.CUSTOM_VAR).toBe("${env:CUSTOM_VAR, ''}");
+        });
+
+        it('should ignore environment variables with value false', () => {
+            const appDefinition = {
+                environment: {
+                    ENABLED_VAR: true,
+                    DISABLED_VAR: false,
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.ENABLED_VAR).toBeDefined();
+            expect(result.DISABLED_VAR).toBeUndefined();
+        });
+
+        it("ignores non-boolean values other than the meaningful 'ssm' marker", () => {
+            const appDefinition = {
+                environment: {
+                    VALID: true,
+                    STRING_VALUE: 'some-value',
+                    NUMBER_VALUE: 123,
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.VALID).toBeDefined();
+            expect(result.STRING_VALUE).toBeUndefined();
+            expect(result.NUMBER_VALUE).toBeUndefined();
+        });
+
+        it('should skip reserved AWS Lambda variables', () => {
+            const appDefinition = {
+                environment: {
+                    CUSTOM_VAR: true,
+                    AWS_REGION: true,
+                    AWS_ACCESS_KEY_ID: true,
+                    AWS_SECRET_ACCESS_KEY: true,
+                    _HANDLER: true,
+                    AWS_LAMBDA_FUNCTION_NAME: true,
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.CUSTOM_VAR).toBeDefined();
+            expect(result.AWS_REGION).toBeUndefined();
+            expect(result.AWS_ACCESS_KEY_ID).toBeUndefined();
+            expect(result.AWS_SECRET_ACCESS_KEY).toBeUndefined();
+            expect(result._HANDLER).toBeUndefined();
+            expect(result.AWS_LAMBDA_FUNCTION_NAME).toBeUndefined();
+        });
+
+        it('should return empty object if no environment defined', () => {
+            const appDefinition = {};
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result).toEqual({});
+        });
+
+        it('should handle empty environment object', () => {
+            const appDefinition = {
+                environment: {},
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result).toEqual({});
+        });
+
+        it('should create serverless variable references', () => {
+            const appDefinition = {
+                environment: {
+                    MY_VAR: true,
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            // Should use serverless variable syntax with empty string fallback
+            expect(result.MY_VAR).toBe("${env:MY_VAR, ''}");
+        });
+    });
+
+    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;
+
+        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('telemetry env passthrough + SSM offload interaction', () => {
+        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("does not bake an OTEL passthrough var that is marked 'ssm' when offload is active", () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                telemetry: { exporter: { type: 'datadog' } },
+                ssm: { enable: true },
+                environment: {
+                    OTEL_EXPORTER_OTLP_ENDPOINT: 'ssm',
+                    OTEL_EXPORTER_OTLP_HEADERS: 'ssm',
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.OTEL_EXPORTER_OTLP_ENDPOINT).toBeUndefined();
+            expect(result.OTEL_EXPORTER_OTLP_HEADERS).toBeUndefined();
+        });
+
+        it("keeps the direct passthrough for an OTEL var not marked 'ssm' while offloading its sibling", () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                telemetry: { exporter: { type: 'otlp' } },
+                ssm: { enable: true },
+                environment: {
+                    OTEL_EXPORTER_OTLP_ENDPOINT: 'ssm',
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.OTEL_EXPORTER_OTLP_ENDPOINT).toBeUndefined();
+            expect(result.OTEL_EXPORTER_OTLP_HEADERS).toBe(
+                "${env:OTEL_EXPORTER_OTLP_HEADERS, ''}"
+            );
+        });
+
+        it("falls back to the env passthrough for an 'ssm'-marked OTEL var in local mode", () => {
+            process.env.FRIGG_SKIP_AWS_DISCOVERY = 'true';
+            const appDefinition = {
+                telemetry: { exporter: { type: 'datadog' } },
+                ssm: { enable: true },
+                environment: {
+                    OTEL_EXPORTER_OTLP_ENDPOINT: 'ssm',
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.OTEL_EXPORTER_OTLP_ENDPOINT).toBe(
+                "${env:OTEL_EXPORTER_OTLP_ENDPOINT, ''}"
+            );
+        });
+
+        it("leaves a 'true'-marked OTEL var as a direct passthrough even when offload is active for another key", () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                telemetry: { exporter: { type: 'datadog' } },
+                ssm: { enable: true },
+                environment: {
+                    OTEL_EXPORTER_OTLP_ENDPOINT: true,
+                    SOME_OFFLOADED_SECRET: 'ssm',
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.OTEL_EXPORTER_OTLP_ENDPOINT).toBe(
+                "${env:OTEL_EXPORTER_OTLP_ENDPOINT, ''}"
+            );
+            expect(result.SOME_OFFLOADED_SECRET).toBeUndefined();
+        });
+
+        it('does not bake an OTEL passthrough var offloaded only via ssm.parameters', () => {
+            delete process.env.FRIGG_SKIP_AWS_DISCOVERY;
+            const appDefinition = {
+                telemetry: { exporter: { type: 'datadog' } },
+                ssm: {
+                    enable: true,
+                    parameters: {
+                        OTEL_EXPORTER_OTLP_ENDPOINT: { type: 'SecureString' },
+                    },
+                },
+            };
+
+            const result = getAppEnvironmentVars(appDefinition);
+
+            expect(result.OTEL_EXPORTER_OTLP_ENDPOINT).toBeUndefined();
+        });
+    });
+
+    describe('buildEnvironment()', () => {
+        it('should combine app vars with standard Frigg variables', () => {
+            const appEnvironmentVars = {
+                API_KEY: "${env:API_KEY, ''}",
+            };
+            const discoveredResources = {};
+
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
+
+            expect(result.API_KEY).toBe("${env:API_KEY, ''}");
+            expect(result.STAGE).toBe('${self:provider.stage}');
+            expect(result.FRIGG_STACK).toBe('${self:service}');
+            expect(result.FRIGG_STAGE).toBe('${self:provider.stage}');
+            expect(result.FRIGG_REGION).toBe('${self:provider.region}');
+        });
+
+        it('should add KMS key ARN if discovered', () => {
+            const appEnvironmentVars = {};
+            const discoveredResources = {
+                kmsKeyId: 'arn:aws:kms:us-east-1:123456:key/abc-123',
+            };
+
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
+
+            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', () => {
+            const appEnvironmentVars = {};
+            const discoveredResources = {
+                kmsKeyId: 'arn:aws:kms:us-east-1:123456:key/primary',
+                kmsKeyArn: 'arn:aws:kms:us-east-1:123456:key/secondary',
+            };
+
+            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'
+            );
+        });
+
+        it('should add database connection info if discovered', () => {
+            const appEnvironmentVars = {};
+            const discoveredResources = {
+                auroraClusterEndpoint:
+                    'cluster.abc.us-east-1.rds.amazonaws.com',
+                auroraPort: 5432,
+            };
+
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
+
+            expect(result.DATABASE_HOST).toBe(
+                'cluster.abc.us-east-1.rds.amazonaws.com'
+            );
+            expect(result.DATABASE_PORT).toBe('5432');
+        });
+
+        it('should default database port to 5432 if not specified', () => {
+            const appEnvironmentVars = {};
+            const discoveredResources = {
+                auroraClusterEndpoint: 'cluster.example.com',
+            };
+
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
+
+            expect(result.DATABASE_HOST).toBe('cluster.example.com');
+            expect(result.DATABASE_PORT).toBe('5432');
+        });
+
+        it('should add database secret ARN if discovered', () => {
+            const appEnvironmentVars = {};
+            const discoveredResources = {
+                databaseSecretArn:
+                    'arn:aws:secretsmanager:us-east-1:123456:secret:db-secret',
+            };
+
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
+
+            expect(result.DATABASE_SECRET_ARN).toBe(
+                'arn:aws:secretsmanager:us-east-1:123456:secret:db-secret'
+            );
+        });
+
+        it('should combine all discovered resources', () => {
+            const appEnvironmentVars = {
+                CUSTOM_VAR: "${env:CUSTOM_VAR, ''}",
+            };
+            const discoveredResources = {
+                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',
+            };
+
+            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.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'
+            );
+        });
+
+        it('should handle empty discoveredResources', () => {
+            const appEnvironmentVars = {
+                API_KEY: "${env:API_KEY, ''}",
+            };
+            const discoveredResources = {};
+
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
+
+            expect(result.API_KEY).toBe("${env:API_KEY, ''}");
+            expect(result.FRIGG_STACK).toBe('${self:service}');
+            expect(result.KMS_KEY_ARN).toBeUndefined();
+            expect(result.DATABASE_HOST).toBeUndefined();
+        });
+
+        it('should handle empty discoveredResources gracefully', () => {
+            const appEnvironmentVars = {};
+
+            const result = buildEnvironment(appEnvironmentVars, {});
+
+            expect(result.FRIGG_STACK).toBe('${self:service}');
+            expect(result.KMS_KEY_ARN).toBeUndefined();
+        });
+
+        it('should convert database port to string', () => {
+            const appEnvironmentVars = {};
+            const discoveredResources = {
+                auroraClusterEndpoint: 'db.example.com',
+                auroraPort: 3306, // Number
+            };
+
+            const result = buildEnvironment(
+                appEnvironmentVars,
+                discoveredResources
+            );
+
+            expect(result.DATABASE_PORT).toBe('3306'); // String
+            expect(typeof result.DATABASE_PORT).toBe('string');
+        });
+    });
+});

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,
+};