@friggframework/devtools 2.0.0-next.44 → 2.0.0-next.46

package/infrastructure/domains/shared/types/resource-ownership.js

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview Resource ownership types for clean architecture
+ *
+ * This file defines the core types for the three-layer resource architecture:
+ * 1. Ownership (STACK | EXTERNAL | AUTO)
+ * 2. Discovery (facts about what exists)
+ * 3. Resolution (decisions based on ownership + discovery)
+ */
+
+/**
+ * Resource ownership states
+ * @readonly
+ * @enum {string}
+ */
+const ResourceOwnership = {
+    /**
+     * Resource is managed by our CloudFormation stack
+     * CRITICAL: Must be added to template on every deploy or CloudFormation will delete it
+     */
+    STACK: 'stack',
+
+    /**
+     * Resource exists outside our stack (another stack, manually created, etc.)
+     * Should NOT be added to our template - reference by physical ID only
+     */
+    EXTERNAL: 'external',
+
+    /**
+     * Let the system decide based on discovery results
+     * - If found in our stack → STACK
+     * - If found externally → EXTERNAL
+     * - If not found → STACK (create new)
+     */
+    AUTO: 'auto'
+};
+
+/**
+ * Resource decision made by resolver
+ * @typedef {Object} ResourceDecision
+ * @property {string} ownership - The ownership decision (STACK | EXTERNAL)
+ * @property {string} [physicalId] - Physical resource ID (for EXTERNAL or existing STACK resources)
+ * @property {string[]} [physicalIds] - Multiple physical IDs (e.g., security groups, subnets)
+ * @property {string} reason - Human-readable reason for this decision
+ * @property {Object} [metadata] - Additional metadata about the resource
+ */
+
+/**
+ * Ownership intent from app definition
+ * @typedef {'stack' | 'external' | 'auto'} OwnershipIntent
+ */
+
+/**
+ * Validate ownership value
+ * @param {string} value - Value to validate
+ * @param {string} resourceName - Name of resource for error message
+ * @throws {Error} If value is not valid ownership
+ */
+function validateOwnership(value, resourceName) {
+    const validValues = Object.values(ResourceOwnership);
+    if (!validValues.includes(value)) {
+        throw new Error(
+            `Invalid ownership '${value}' for ${resourceName}. Must be one of: ${validValues.join(', ')}`
+        );
+    }
+}
+
+/**
+ * Resolve final ownership from intent and actual state
+ * @param {OwnershipIntent} intent - User's intent from app definition
+ * @param {boolean} inStack - Whether resource is in our CloudFormation stack
+ * @param {boolean} foundExternal - Whether resource was found externally
+ * @returns {string} Final ownership (STACK | EXTERNAL)
+ */
+function resolveOwnership(intent, inStack, foundExternal) {
+    // Explicit stack
+    if (intent === ResourceOwnership.STACK) {
+        return ResourceOwnership.STACK;
+    }
+
+    // Explicit external
+    if (intent === ResourceOwnership.EXTERNAL) {
+        return ResourceOwnership.EXTERNAL;
+    }
+
+    // Auto-decide
+    if (intent === ResourceOwnership.AUTO) {
+        // CRITICAL: If it's in our stack, it MUST stay in template
+        if (inStack) {
+            return ResourceOwnership.STACK;
+        }
+
+        // Found externally - use it
+        if (foundExternal) {
+            return ResourceOwnership.EXTERNAL;
+        }
+
+        // Not found - create new in stack
+        return ResourceOwnership.STACK;
+    }
+
+    throw new Error(`Invalid ownership intent: ${intent}`);
+}
+
+module.exports = {
+    ResourceOwnership,
+    validateOwnership,
+    resolveOwnership
+};

package/infrastructure/domains/shared/types/resource-ownership.test.js

@@ -0,0 +1,101 @@
+const { ResourceOwnership, validateOwnership, resolveOwnership } = require('./resource-ownership');
+
+describe('ResourceOwnership', () => {
+    describe('enum values', () => {
+        it('should have correct enum values', () => {
+            expect(ResourceOwnership.STACK).toBe('stack');
+            expect(ResourceOwnership.EXTERNAL).toBe('external');
+            expect(ResourceOwnership.AUTO).toBe('auto');
+        });
+    });
+
+    describe('validateOwnership', () => {
+        it('should accept valid ownership values', () => {
+            expect(() => validateOwnership('stack', 'test')).not.toThrow();
+            expect(() => validateOwnership('external', 'test')).not.toThrow();
+            expect(() => validateOwnership('auto', 'test')).not.toThrow();
+        });
+
+        it('should reject invalid ownership values', () => {
+            expect(() => validateOwnership('invalid', 'test')).toThrow(
+                "Invalid ownership 'invalid' for test"
+            );
+            expect(() => validateOwnership('managed', 'test')).toThrow();
+            expect(() => validateOwnership('', 'test')).toThrow();
+        });
+    });
+
+    describe('resolveOwnership', () => {
+        describe('with explicit STACK intent', () => {
+            it('should return STACK regardless of discovery', () => {
+                expect(resolveOwnership('stack', false, false)).toBe('stack');
+                expect(resolveOwnership('stack', true, false)).toBe('stack');
+                expect(resolveOwnership('stack', false, true)).toBe('stack');
+                expect(resolveOwnership('stack', true, true)).toBe('stack');
+            });
+        });
+
+        describe('with explicit EXTERNAL intent', () => {
+            it('should return EXTERNAL regardless of discovery', () => {
+                expect(resolveOwnership('external', false, false)).toBe('external');
+                expect(resolveOwnership('external', true, false)).toBe('external');
+                expect(resolveOwnership('external', false, true)).toBe('external');
+                expect(resolveOwnership('external', true, true)).toBe('external');
+            });
+        });
+
+        describe('with AUTO intent', () => {
+            it('should return STACK if resource is in stack (CRITICAL: must keep in template)', () => {
+                expect(resolveOwnership('auto', true, false)).toBe('stack');
+                expect(resolveOwnership('auto', true, true)).toBe('stack');
+            });
+
+            it('should return EXTERNAL if found externally but not in stack', () => {
+                expect(resolveOwnership('auto', false, true)).toBe('external');
+            });
+
+            it('should return STACK if not found anywhere (will create new)', () => {
+                expect(resolveOwnership('auto', false, false)).toBe('stack');
+            });
+        });
+
+        describe('edge cases', () => {
+            it('should throw on invalid intent', () => {
+                expect(() => resolveOwnership('invalid', false, false)).toThrow(
+                    'Invalid ownership intent: invalid'
+                );
+            });
+
+            it('should handle undefined intent as invalid', () => {
+                expect(() => resolveOwnership(undefined, false, false)).toThrow();
+            });
+        });
+
+        describe('real-world scenarios', () => {
+            it('scenario: fresh deploy, no resources exist', () => {
+                const ownership = resolveOwnership('auto', false, false);
+                expect(ownership).toBe('stack');
+            });
+
+            it('scenario: redeploy existing stack, resource in stack', () => {
+                const ownership = resolveOwnership('auto', true, false);
+                expect(ownership).toBe('stack');
+            });
+
+            it('scenario: resource exists in another stack/manually created', () => {
+                const ownership = resolveOwnership('auto', false, true);
+                expect(ownership).toBe('external');
+            });
+
+            it('scenario: user explicitly wants to use external VPC', () => {
+                const ownership = resolveOwnership('external', false, false);
+                expect(ownership).toBe('external');
+            });
+
+            it('scenario: user explicitly manages in stack even if external exists', () => {
+                const ownership = resolveOwnership('stack', false, true);
+                expect(ownership).toBe('stack');
+            });
+        });
+    });
+});

package/infrastructure/domains/shared/utilities/base-definition-factory.js

@@ -0,0 +1,380 @@
+/**
+ * Base Serverless Definition Factory
+ * 
+ * Utility Layer - Hexagonal Architecture
+ * 
+ * Creates the base serverless.yml configuration with core functions,
+ * resources, plugins, and provider settings.
+ */
+
+const { buildEnvironment } = require('../environment-builder');
+
+/**
+ * Create base serverless definition with core functions and resources
+ * 
+ * This creates the foundation serverless configuration that all
+ * Frigg applications need, including:
+ * - Core Lambda functions (auth, user, health, dbMigrate)
+ * - Error handling infrastructure (SQS, SNS, CloudWatch)
+ * - Prisma Lambda Layer
+ * - Base plugins and esbuild configuration
+ * 
+ * @param {Object} AppDefinition - Application definition
+ * @param {Object} appEnvironmentVars - Environment variables from app definition
+ * @param {Object} discoveredResources - AWS resources discovered during build
+ * @returns {Object} Base serverless definition
+ */
+function createBaseDefinition(
+    AppDefinition,
+    appEnvironmentVars,
+    discoveredResources
+) {
+    const region = process.env.AWS_REGION || 'us-east-1';
+
+    // Package config for handlers that skip esbuild (need node_modules dependencies)
+    // Include backend src/ and index.js since handlers load the app definition
+    const skipEsbuildPackageConfig = {
+        // Explicitly include project files that handlers need
+        include: [
+            // Include DocumentDB TLS certificate if configured
+            ...(AppDefinition.database?.documentDB?.tlsCAFile 
+                ? [AppDefinition.database.documentDB.tlsCAFile.replace(/^\.\//, '')] 
+                : []),
+        ],
+        exclude: [
+            // Exclude Prisma (provided via Lambda Layer)
+            'node_modules/@prisma/**',
+            'node_modules/.prisma/**',
+            'node_modules/prisma/**',
+            'node_modules/@friggframework/core/generated/**',
+
+            // Exclude AWS SDK (provided by Lambda runtime)
+            'node_modules/aws-sdk/**',
+            'node_modules/@aws-sdk/**',
+
+            // Exclude dev/test dependencies
+            'node_modules/@friggframework/test/**',
+            'node_modules/@friggframework/eslint-config/**',
+            'node_modules/@friggframework/prettier-config/**',
+            'node_modules/jest/**',
+            'node_modules/prettier/**',
+            'node_modules/eslint/**',
+
+            // Exclude ALL nested node_modules (catch any package with nested dependencies)
+            'node_modules/**/node_modules/**',
+
+            // Exclude build tools (not needed at runtime)
+            'node_modules/esbuild/**',
+            'node_modules/@esbuild/**',
+            'node_modules/typescript/**',
+            'node_modules/webpack/**',
+            'node_modules/osls/**',
+            'node_modules/serverless-esbuild/**',
+            'node_modules/serverless-jetpack/**',
+            'node_modules/serverless-offline/**',
+            'node_modules/serverless-offline-sqs/**',
+            'node_modules/serverless-dotenv-plugin/**',
+            'node_modules/serverless-kms-grants/**',
+            // Note: DO NOT exclude serverless-http - it's a runtime dependency!
+
+            // Exclude local dev files
+            'deploy.log',
+            '.env.backup',
+            'docker-compose.yml',
+            'jest.config.js',
+            'jest.unit.config.js',
+            '.eslintrc.json',
+            '.prettierrc',
+            '.prettierignore',
+            '.markdownlintignore',
+            'package-lock.json',
+
+            // Exclude test files and layers (keep src/ - needed for app definition and integrations)
+            'test/**',
+            'layers/**',
+            'coverage/**',
+            // Note: DO NOT exclude src/** - handlers need src/integrations and src/api-modules at runtime
+            '**/*.test.js',
+            '**/*.spec.js',
+            '**/.claude-flow/**',
+            '**/.swarm/**',
+        ],
+    };
+
+    // Function-level package config to exclude Prisma and AWS SDK
+    const functionPackageConfig = {
+        exclude: [
+            // Exclude AWS SDK (already in Lambda runtime or externalized by esbuild)
+            'node_modules/aws-sdk/**',
+            'node_modules/@aws-sdk/**',
+
+            // Exclude Prisma (provided via Lambda Layer)
+            'node_modules/@prisma/**',
+            'node_modules/.prisma/**',
+            'node_modules/prisma/**',
+            'node_modules/@friggframework/core/generated/**',
+
+            // Exclude nested node_modules from symlinked frigg packages (for npm link development)
+            'node_modules/@friggframework/core/node_modules/**',
+            'node_modules/@friggframework/devtools/node_modules/**',
+
+            // Exclude development/test files from backend project
+            'coverage/**',
+            'test/**',
+            'src/**',
+            'layers/**',
+            '**/*.test.js',
+            '**/*.spec.js',
+            '.git/**',
+            '.github/**',
+
+            // Exclude AI assistant and development artifacts
+            '**/.claude-flow/**',
+            '**/.swarm/**',
+            '**/CLAUDE.md',
+            '**/README.md',
+            '**/*.md',
+
+            // Exclude config and meta files from core
+            'node_modules/@friggframework/core/.eslintrc.json',
+            'node_modules/@friggframework/core/.gitignore',
+            'node_modules/@friggframework/core/jest.config.js',
+            'node_modules/@friggframework/core/CHANGELOG.md',
+        ],
+    };
+
+    return {
+        frameworkVersion: '>=3.17.0',
+        service: AppDefinition.name || 'create-frigg-app',
+        package: {
+            individually: true,
+        },
+        // Only use .env for local development (offline mode)
+        // Production deployments should use environment vars from infrastructure
+        useDotenv: process.argv.includes('offline'),
+        provider: {
+            name: AppDefinition.provider || 'aws',
+            ...(process.env.AWS_PROFILE && { profile: process.env.AWS_PROFILE }),
+            runtime: 'nodejs22.x',  // Node.js 22.x (latest Lambda runtime with AWS SDK v3)
+            timeout: 29,  // Set to 29s to give buffer before API Gateway's 30s timeout
+            region,
+            stage: '${opt:stage}',
+            environment: buildEnvironment(appEnvironmentVars, discoveredResources),
+            iamRoleStatements: [
+                {
+                    Effect: 'Allow',
+                    Action: ['sns:Publish'],
+                    Resource: { Ref: 'InternalErrorBridgeTopic' },
+                },
+                {
+                    Effect: 'Allow',
+                    Action: [
+                        'sqs:SendMessage',
+                        'sqs:SendMessageBatch',
+                        'sqs:GetQueueUrl',
+                        'sqs:GetQueueAttributes',
+                    ],
+                    Resource: [
+                        { 'Fn::GetAtt': ['InternalErrorQueue', 'Arn'] },
+                        {
+                            'Fn::Join': [
+                                ':',
+                                [
+                                    'arn:aws:sqs:${self:provider.region}:*:${self:service}--${self:provider.stage}-*Queue',
+                                ],
+                            ],
+                        },
+                    ],
+                },
+            ],
+            httpApi: {
+                payload: '2.0',
+                cors: {
+                    allowedOrigins: ['*'],
+                    allowedHeaders: ['*'],
+                    allowedMethods: ['*'],
+                    allowCredentials: false,
+                },
+                name: '${opt:stage, "dev"}-${self:service}',
+                disableDefaultEndpoint: false,
+            },
+        },
+        plugins: [
+            'serverless-esbuild',
+            // Only load dotenv plugin for offline mode
+            ...(process.argv.includes('offline') ? ['serverless-dotenv-plugin'] : []),
+            'serverless-offline-sqs',
+            'serverless-offline',
+            '@friggframework/serverless-plugin',
+        ],
+        custom: {
+            esbuild: {
+                bundle: true,
+                minify: true,
+                sourcemap: true,
+                target: 'node22',
+                platform: 'node',
+                format: 'cjs',
+                external: [
+                    '@aws-sdk/*',
+                    'aws-sdk',
+                    '@prisma/client',
+                    'prisma',
+                    '.prisma/*',
+                ],
+                packager: 'npm',
+                keepNames: true,
+                keepOutputDirectory: false,  // Clean up .esbuild directory after packaging
+                exclude: [
+                    'aws-sdk',
+                    '@aws-sdk/*',
+                    '@prisma/client',
+                    'prisma',
+                ],
+            },
+            'serverless-offline': {
+                httpPort: 3001,
+                lambdaPort: 4001,
+                websocketPort: 3002,
+                location: '.',  // Set base directory for handler resolution to current directory
+                skipCacheInvalidation: false,
+            },
+            'serverless-offline-sqs': {
+                autoCreate: false,
+                apiVersion: '2012-11-05',
+                endpoint: 'http://localhost:4566',
+                region,
+                accessKeyId: 'root',
+                secretAccessKey: 'root',
+                skipCacheInvalidation: false,
+            },
+        },
+        functions: {
+            auth: {
+                handler: 'node_modules/@friggframework/core/handlers/routers/auth.handler',
+                layers: [{ Ref: 'PrismaLambdaLayer' }],
+                skipEsbuild: true,  // Handlers in node_modules don't need bundling
+                package: skipEsbuildPackageConfig,
+                events: [
+                    { httpApi: { path: '/api/integrations', method: 'ANY' } },
+                    {
+                        httpApi: {
+                            path: '/api/integrations/{proxy+}',
+                            method: 'ANY',
+                        },
+                    },
+                    { httpApi: { path: '/api/authorize', method: 'ANY' } },
+                ],
+            },
+            user: {
+                handler: 'node_modules/@friggframework/core/handlers/routers/user.handler',
+                layers: [{ Ref: 'PrismaLambdaLayer' }],
+                skipEsbuild: true,  // Handlers in node_modules don't need bundling
+                package: skipEsbuildPackageConfig,
+                events: [{ httpApi: { path: '/user/{proxy+}', method: 'ANY' } }],
+            },
+            health: {
+                handler: 'node_modules/@friggframework/core/handlers/routers/health.handler',
+                layers: [{ Ref: 'PrismaLambdaLayer' }],
+                skipEsbuild: true,  // Handlers in node_modules don't need bundling
+                package: skipEsbuildPackageConfig,
+                events: [
+                    { httpApi: { path: '/health', method: 'GET' } },
+                    { httpApi: { path: '/health/{proxy+}', method: 'GET' } },
+                ],
+            },
+            // Note: dbMigrate removed - MigrationBuilder now handles migration infrastructure
+            // See: packages/devtools/infrastructure/domains/database/migration-builder.js
+        },
+        layers: {
+            prisma: {
+                path: 'layers/prisma',
+                name: '${self:service}-prisma-${sls:stage}',
+                description: 'Prisma runtime client only (NO CLI) with rhel-openssl-3.0.x binaries (~10-15MB). CLI packaged separately in dbMigrate function.',
+                compatibleRuntimes: ['nodejs20.x', 'nodejs22.x'],
+                retain: false,
+            },
+        },
+        resources: {
+            Resources: {
+                InternalErrorQueue: {
+                    Type: 'AWS::SQS::Queue',
+                    Properties: {
+                        QueueName:
+                            '${self:service}-internal-error-queue-${self:provider.stage}',
+                        MessageRetentionPeriod: 300,
+                    },
+                },
+                InternalErrorBridgeTopic: {
+                    Type: 'AWS::SNS::Topic',
+                    Properties: {
+                        Subscription: [
+                            {
+                                Protocol: 'sqs',
+                                Endpoint: {
+                                    'Fn::GetAtt': ['InternalErrorQueue', 'Arn'],
+                                },
+                            },
+                        ],
+                    },
+                },
+                InternalErrorBridgePolicy: {
+                    Type: 'AWS::SQS::QueuePolicy',
+                    Properties: {
+                        Queues: [{ Ref: 'InternalErrorQueue' }],
+                        PolicyDocument: {
+                            Version: '2012-10-17',
+                            Statement: [
+                                {
+                                    Sid: 'Allow Dead Letter SNS to publish to SQS',
+                                    Effect: 'Allow',
+                                    Principal: { Service: 'sns.amazonaws.com' },
+                                    Resource: {
+                                        'Fn::GetAtt': [
+                                            'InternalErrorQueue',
+                                            'Arn',
+                                        ],
+                                    },
+                                    Action: [
+                                        'SQS:SendMessage',
+                                        'SQS:SendMessageBatch',
+                                    ],
+                                    Condition: {
+                                        ArnEquals: {
+                                            'aws:SourceArn': {
+                                                Ref: 'InternalErrorBridgeTopic',
+                                            },
+                                        },
+                                    },
+                                },
+                            ],
+                        },
+                    },
+                },
+                ApiGatewayAlarm5xx: {
+                    Type: 'AWS::CloudWatch::Alarm',
+                    Properties: {
+                        AlarmDescription: 'API Gateway 5xx Errors',
+                        Namespace: 'AWS/ApiGateway',
+                        MetricName: '5XXError',
+                        Statistic: 'Sum',
+                        Threshold: 0,
+                        ComparisonOperator: 'GreaterThanThreshold',
+                        EvaluationPeriods: 1,
+                        Period: 60,
+                        AlarmActions: [{ Ref: 'InternalErrorBridgeTopic' }],
+                        Dimensions: [
+                            { Name: 'ApiId', Value: { Ref: 'HttpApi' } },
+                            { Name: 'Stage', Value: '${self:provider.stage}' },
+                        ],
+                    },
+                },
+            },
+        },
+    };
+}
+
+module.exports = {
+    createBaseDefinition,
+};
+