@friggframework/devtools 2.0.0--canary.666.81647c4.0 → 2.0.0--canary.667.6dc4b39.0

package/infrastructure/docs/POSTGRES-CONFIGURATION.md

@@ -8,10 +8,10 @@ Frigg Framework supports automatic provisioning of Amazon Aurora Serverless v2 P
 
 ### Key Features
 
-- **Aurora Serverless v2**: Cost-efficient auto-scaling database (0.5-4 ACU default)
+- **Aurora Serverless v2**: Cost-efficient auto-scaling database (0.5-1.0 ACU default)
 - **VPC Integration**: Deployed in same private subnets as Lambda functions
 - **Secrets Manager**: Automatic credential management and rotation
-- **Three Management Modes**: discover, managed, use-existing
+- **Three Management Modes**: discover, create-new, use-existing
 - **Security**: Private subnet deployment with security group isolation
 - **High Availability**: Multi-AZ deployment with automatic failover
 
@@ -21,16 +21,12 @@ Frigg Framework supports automatic provisioning of Amazon Aurora Serverless v2 P
 
 ### App Definition Structure
 
-These are the keys the Aurora builder reads (see `database.postgres` in
-`packages/schemas/schemas/app-definition.schema.json`). `frigg validate`
-rejects any other key under `database.postgres`.
-
 ```javascript
 // backend/index.js
 const appDefinition = {
     name: 'my-frigg-app',
 
-    // VPC Configuration (required for Aurora)
+    // Enable VPC deployment (required for Aurora)
     vpc: {
         enable: true,
     },
@@ -40,24 +36,34 @@ const appDefinition = {
         postgres: {
             enable: true,
 
-            // 'discover' (also when omitted) | 'managed' | 'use-existing'
-            // Ignored when managementMode is 'managed' or 'existing'.
+            // Management mode: 'discover' | 'create-new' | 'use-existing'
             management: 'discover',
 
-            database: 'frigg',        // database name (default 'frigg')
-            username: 'postgres',     // master user (default 'postgres')
-            engineVersion: '15.13',   // Aurora PostgreSQL version (default '15.13')
+            // Basic Configuration
+            databaseName: 'frigg_db',
+            masterUsername: 'frigg_admin',
+
+            // Engine Configuration
+            engine: 'aurora-postgresql',
+            engineVersion: '15.3',
+
+            // Scaling Configuration (Aurora Serverless v2)
+            scaling: {
+                minCapacity: 0.5,  // ACUs (0.5 = ~1GB RAM, ~$43/month)
+                maxCapacity: 1.0,  // ACUs (1.0 = ~2GB RAM, ~$87/month)
+            },
 
-            // Aurora Serverless v2 capacity, in ACUs (0.5-128)
-            minCapacity: 0.5,         // default 0.5
-            maxCapacity: 4,           // default 4
+            // Backup Configuration
+            backupRetentionDays: 7,
+            preferredBackupWindow: '03:00-04:00',
 
-            publiclyAccessible: false,     // default false (private subnets)
-            autoCreateCredentials: false,  // discover only: create a secret for a discovered cluster
+            // Security & Advanced
+            deletionProtection: true,
+            enablePerformanceInsights: false,
 
-            // use-existing only
-            // endpoint: 'mydb.cluster-abc123.us-east-1.rds.amazonaws.com',
-            // port: 5432,
+            // For use-existing mode
+            clusterIdentifier: 'my-existing-cluster',
+            secretArn: 'arn:aws:secretsmanager:...',
         }
     }
 };
@@ -67,17 +73,13 @@ module.exports = {
 };
 ```
 
-Backup retention (7 days), the backup and maintenance windows and deletion
-settings are fixed by the builder and are not configurable through the app
-definition.
-
 ---
 
 ## Management Modes
 
 ### 1. Discover Mode (Default)
 
-Discovers an existing Aurora cluster, or creates a new one in the stack if none is found.
+Automatically discovers existing Aurora clusters or creates new one if none found.
 
 ```javascript
 database: {
@@ -98,56 +100,63 @@ database: {
 
 ---
 
-### 2. Managed Mode
+### 2. Create-New Mode
 
-Creates the cluster, instance, subnet group and secret in the stack.
+Always creates a new Aurora cluster, even if existing clusters are found.
 
 ```javascript
 database: {
     postgres: {
         enable: true,
-        management: 'managed',
-        minCapacity: 1,
-        maxCapacity: 2,
+        management: 'create-new',
+
+        // Customization options
+        databaseName: 'my_app_db',
+        masterUsername: 'admin',
+        engineVersion: '15.3',
+        scaling: {
+            minCapacity: 1.0,
+            maxCapacity: 2.0,
+        },
+        backupRetentionDays: 14,
+        deletionProtection: true,
     }
 }
 ```
 
-With the top-level `managementMode: 'managed'` (and `vpcIsolation: 'isolated'`),
-Frigg manages the database per stage and `database.postgres.management` is ignored.
-
 **Best For**: Production environments where you want dedicated database resources.
 
 ---
 
 ### 3. Use-Existing Mode
 
-Connects to an existing PostgreSQL endpoint without creating database resources.
+Uses a specific existing Aurora cluster by identifier.
 
 ```javascript
 database: {
     postgres: {
         enable: true,
         management: 'use-existing',
-        endpoint: 'my-cluster.cluster-abc123.us-east-1.rds.amazonaws.com', // required
-        port: 5432,
-        database: 'frigg_db',
-        username: 'frigg_admin',
+
+        // Required: existing cluster identifier
+        clusterIdentifier: 'my-existing-aurora-cluster',
+
+        // Optional: secret ARN (discovered if not provided)
+        secretArn: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:my-db-secret',
+
+        // Database name to connect to
+        databaseName: 'frigg_db',
     }
 }
 ```
 
-To use an existing cluster by identifier instead, use the ownership form:
-`ownership: { cluster: 'external', instance: 'external' }` with
-`external: { clusterIdentifier, instanceIdentifier, secretArn }`.
-
 **Best For**: Shared database scenarios or when you manage Aurora outside of Frigg.
 
 ---
 
 ## Created AWS Resources
 
-When provisioning Aurora (`managed`, or `discover` mode without an existing cluster), Frigg creates:
+When provisioning Aurora (`create-new` or `discover` mode without existing cluster), Frigg creates:
 
 ### 1. RDS DB Subnet Group
 - **Name**: `{service}-{stage}-db-subnet-group`
@@ -212,15 +221,17 @@ database: {
 database: {
     postgres: {
         enable: true,
-        minCapacity: 1,  // Higher baseline for production
-        maxCapacity: 4,  // Handle traffic spikes
+        scaling: {
+            minCapacity: 1.0,  // Higher baseline for production
+            maxCapacity: 4.0,  // Handle traffic spikes
+        },
+        backupRetentionDays: 30,  // Longer retention
+        enablePerformanceInsights: true,  // Monitoring
+        deletionProtection: true,  // Prevent accidental deletion
     }
 }
 ```
 
-Backup retention, Performance Insights and deletion protection are not
-configurable through the app definition; change them on the cluster.
-
 **Estimated Monthly Costs**:
 - **Baseline**: $87/month (1.0 ACU minimum)
 - **Peak Traffic**: $348/month (4.0 ACU maximum)
@@ -265,9 +276,15 @@ const users = await prismaClient.user.findMany();
 
 ### 4. Deletion Protection
 
-Deletion protection is not configurable through the app definition. Enable it
-on the cluster in the AWS console (or with the AWS CLI); you must then disable
-it before deleting the stack.
+```javascript
+database: {
+    postgres: {
+        deletionProtection: true,  // Prevents accidental deletion
+    }
+}
+```
+
+**Important**: When enabled, you must manually disable deletion protection in AWS console before stack deletion.
 
 ---
 
@@ -367,7 +384,7 @@ DB_TYPE=postgresql
    database: {
        postgres: {
            enable: true,
-           management: 'managed',
+           management: 'create-new',
        }
    }
    ```
@@ -394,7 +411,7 @@ DB_TYPE=postgresql
    database: {
        postgres: {
            enable: true,
-           management: 'managed',
+           management: 'create-new',
        }
    }
    ```
@@ -439,13 +456,13 @@ DB_TYPE=postgresql
 
 **Error**:
 ```
-No Aurora cluster found in discovery mode. Set management to "managed" or provide endpoint with "use-existing".
+No Aurora cluster found in discovery mode. Set management to "create-new"...
 ```
 
 **Solution**:
 1. Check VPC is enabled: `vpc.enable: true`
-2. Set management mode: `management: 'managed'`
-3. Or connect to a known endpoint: `management: 'use-existing'`, `endpoint: '...'`
+2. Set management mode: `management: 'create-new'`
+3. Or provide cluster identifier: `clusterIdentifier: 'my-cluster'`
 
 ---
 
@@ -527,19 +544,40 @@ Cannot create Aurora cluster: InsufficientDBInstanceCapacity
 
 ## Advanced Configuration
 
-### Custom Engine Version
+### Custom Backup Window
 
 ```javascript
 database: {
     postgres: {
         enable: true,
-        engineVersion: '16.4',  // Default: 15.13
+        backupRetentionDays: 30,
+        preferredBackupWindow: '02:00-03:00',  // UTC
     }
 }
 ```
 
-The backup window, backup retention and Performance Insights are set by the
-builder and are not configurable through the app definition.
+### Enhanced Monitoring
+
+```javascript
+database: {
+    postgres: {
+        enable: true,
+        enablePerformanceInsights: true,
+        // Performance Insights retention: 7 days (default) or 731 days
+    }
+}
+```
+
+### Custom Engine Version
+
+```javascript
+database: {
+    postgres: {
+        enable: true,
+        engineVersion: '14.6',  // Default: 15.3
+    }
+}
+```
 
 ### Read Replicas (Not Supported Yet)
 

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

@@ -286,6 +286,11 @@ function createBaseDefinition(
                 ...(usePrismaLayer && { layers: [{ Ref: 'PrismaLambdaLayer' }] }),
                 skipEsbuild: true,  // Handlers in node_modules don't need bundling
                 package: skipEsbuildPackageConfig,
+                // Every path prefix the core integration router
+                // (createIntegrationRouter) registers must be routed here;
+                // HTTP API has no implicit catch-all, so an unlisted prefix
+                // 404s at the gateway before Express sees it. Guarded by
+                // __tests__/management-api-gateway-routes.test.js.
                 events: [
                     { httpApi: { path: '/api/integrations', method: 'ANY' } },
                     {
@@ -295,6 +300,20 @@ function createBaseDefinition(
                         },
                     },
                     { httpApi: { path: '/api/authorize', method: 'ANY' } },
+                    { httpApi: { path: '/api/entity', method: 'ANY' } },
+                    {
+                        httpApi: {
+                            path: '/api/entity/{proxy+}',
+                            method: 'ANY',
+                        },
+                    },
+                    { httpApi: { path: '/api/entities', method: 'ANY' } },
+                    {
+                        httpApi: {
+                            path: '/api/entities/{proxy+}',
+                            method: 'ANY',
+                        },
+                    },
                 ],
             },
             user: {

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

@@ -94,7 +94,19 @@ describe('Base Definition Factory', () => {
 
             expect(result.functions.auth.handler).toBe('node_modules/@friggframework/core/handlers/routers/auth.handler');
             expect(result.functions.auth.layers).toEqual([{ Ref: 'PrismaLambdaLayer' }]);
-            expect(result.functions.auth.events).toHaveLength(3);
+            expect(
+                result.functions.auth.events.map(
+                    (e) => `${e.httpApi.method} ${e.httpApi.path}`
+                )
+            ).toEqual([
+                'ANY /api/integrations',
+                'ANY /api/integrations/{proxy+}',
+                'ANY /api/authorize',
+                'ANY /api/entity',
+                'ANY /api/entity/{proxy+}',
+                'ANY /api/entities',
+                'ANY /api/entities/{proxy+}',
+            ]);
         });
 
         it('should NOT include legacy dbMigrate function', () => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@friggframework/devtools",
   "prettier": "@friggframework/prettier-config",
-  "version": "2.0.0--canary.666.81647c4.0",
+  "version": "2.0.0--canary.667.6dc4b39.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.666.81647c4.0",
-    "@friggframework/schemas": "2.0.0--canary.666.81647c4.0",
-    "@friggframework/test": "2.0.0--canary.666.81647c4.0",
+    "@friggframework/core": "2.0.0--canary.667.6dc4b39.0",
+    "@friggframework/schemas": "2.0.0--canary.667.6dc4b39.0",
+    "@friggframework/test": "2.0.0--canary.667.6dc4b39.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.666.81647c4.0",
-    "@friggframework/prettier-config": "2.0.0--canary.666.81647c4.0",
+    "@friggframework/eslint-config": "2.0.0--canary.667.6dc4b39.0",
+    "@friggframework/prettier-config": "2.0.0--canary.667.6dc4b39.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": "81647c4f85dd9b1e8e69b2bddcb09b1759341bf8"
+  "gitHead": "6dc4b398e9de7b24d84754021d06e948ebcf7431"
 }

package/frigg-cli/__tests__/unit/commands/validate-wiring.test.js

@@ -1,92 +0,0 @@
-/**
- * build and deploy validate the app definition first and stop on errors;
- * start validates and only warns (ADR-051).
- */
-
-// child_process and node:child_process are one module to jest: one mock.
-const mockChildProcess = {
-    spawnSync: jest.fn(() => ({ status: 0 })),
-    spawn: jest.fn(),
-};
-jest.mock('child_process', () => mockChildProcess);
-jest.mock('node:child_process', () => mockChildProcess);
-jest.mock('../../../validate-command', () => ({
-    preflightValidation: jest.fn(),
-}));
-jest.mock('../../../doctor-command', () => ({ doctorCommand: jest.fn() }));
-jest.mock('../../../utils/database-validator', () => ({
-    validateDatabaseUrl: jest.fn(() => ({ valid: true })),
-    getDatabaseType: jest.fn(() => ({ dbType: 'postgresql' })),
-    checkPrismaClientGenerated: jest.fn(() => ({ generated: true })),
-}));
-jest.mock('dotenv', () => ({ config: jest.fn() }));
-
-const childProcess = mockChildProcess;
-const nodeChildProcess = mockChildProcess;
-const { preflightValidation } = require('../../../validate-command');
-const { buildCommand } = require('../../../build-command');
-const { deployCommand } = require('../../../deploy-command');
-const { startCommand } = require('../../../start-command');
-
-describe('validation before build, deploy and start', () => {
-    beforeEach(() => {
-        jest.clearAllMocks();
-        jest.spyOn(console, 'log').mockImplementation(() => {});
-        jest.spyOn(console, 'warn').mockImplementation(() => {});
-        jest.spyOn(console, 'error').mockImplementation(() => {});
-        jest.spyOn(process, 'exit').mockImplementation(() => {});
-    });
-
-    afterEach(() => jest.restoreAllMocks());
-
-    it('build validates first and fails on errors', async () => {
-        preflightValidation.mockReturnValue(false);
-
-        await buildCommand({ stage: 'prod' });
-
-        expect(preflightValidation).toHaveBeenCalledWith({
-            command: 'build',
-            options: { stage: 'prod' },
-            failOnErrors: true,
-        });
-        expect(childProcess.spawnSync).not.toHaveBeenCalled();
-    });
-
-    it('build packages after a passing validation', async () => {
-        preflightValidation.mockReturnValue(true);
-
-        await buildCommand({ stage: 'prod' });
-
-        expect(childProcess.spawnSync).toHaveBeenCalled();
-    });
-
-    it('deploy validates first and fails on errors', async () => {
-        preflightValidation.mockReturnValue(false);
-
-        await deployCommand({ stage: 'prod', skipValidate: false });
-
-        expect(preflightValidation).toHaveBeenCalledWith({
-            command: 'deploy',
-            options: { stage: 'prod', skipValidate: false },
-            failOnErrors: true,
-        });
-        expect(childProcess.spawn).not.toHaveBeenCalled();
-    });
-
-    it('start validates and only warns', async () => {
-        preflightValidation.mockReturnValue(true);
-        nodeChildProcess.spawn.mockReturnValue({ on: jest.fn() });
-        const previous = process.env.DATABASE_URL;
-        process.env.DATABASE_URL = 'postgresql://localhost/frigg';
-
-        await startCommand({ stage: 'dev' });
-
-        process.env.DATABASE_URL = previous;
-        expect(preflightValidation).toHaveBeenCalledWith({
-            command: 'start',
-            options: { stage: 'dev' },
-            failOnErrors: false,
-        });
-        expect(nodeChildProcess.spawn).toHaveBeenCalled();
-    });
-});

package/frigg-cli/validate-command/__tests__/init-validation.test.js

@@ -1,63 +0,0 @@
-/**
- * `frigg init` validates the generated app with the same code path as
- * `frigg validate`, and never fails because of it (ADR-051).
- */
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-jest.mock('@inquirer/prompts', () => ({}));
-
-const BackendFirstHandler = require('../../init-command/backend-first-handler');
-
-function writeApp(source) {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'frigg-init-'));
-    fs.writeFileSync(path.join(dir, 'package.json'), '{"name":"backend"}');
-    fs.writeFileSync(path.join(dir, 'index.js'), source);
-    return dir;
-}
-
-describe('frigg init validation', () => {
-    const dirs = [];
-    let log;
-
-    beforeEach(() => {
-        log = jest.spyOn(console, 'log').mockImplementation(() => {});
-    });
-
-    afterEach(() => {
-        jest.restoreAllMocks();
-        for (const dir of dirs.splice(0))
-            fs.rmSync(dir, { recursive: true, force: true });
-    });
-
-    it('validates the real generated definition, not a stand-in', async () => {
-        const dir = writeApp(
-            "module.exports = { Definition: { integrations: [], database: { postgres: { enable: true, management: 'create-new' } } } };"
-        );
-        dirs.push(dir);
-        const handler = new BackendFirstHandler(dir, {});
-
-        const ok = await handler.validateGeneratedAppDefinition(
-            path.join(dir, 'index.js')
-        );
-
-        expect(ok).toBe(false);
-        expect(log.mock.calls.flat().join('\n')).toContain(
-            '/database/postgres/management'
-        );
-    });
-
-    it('stays quiet before npm install, when index.js cannot load its dependencies', async () => {
-        const dir = writeApp(
-            "require('@friggframework/api-module-does-not-exist');"
-        );
-        dirs.push(dir);
-        const handler = new BackendFirstHandler(dir, {});
-
-        await expect(
-            handler.validateGeneratedAppDefinition(path.join(dir, 'index.js'))
-        ).resolves.toBe(true);
-        expect(log).not.toHaveBeenCalled();
-    });
-});

package/frigg-cli/validate-command/__tests__/integrations-checks.test.js

@@ -1,133 +0,0 @@
-const { checkIntegrations } = require('../checks/integrations');
-
-class FakeApi {
-    static requesterType = 'oauth2';
-}
-
-const moduleDefinition = () => ({
-    moduleName: 'acme',
-    API: FakeApi,
-    requiredAuthMethods: {
-        getToken: async () => {},
-        getEntityDetails: async () => {},
-        getCredentialDetails: async () => {},
-        testAuthRequest: async () => {},
-        apiPropertiesToPersist: { credential: [], entity: [] },
-    },
-});
-
-function integrationClass(definition) {
-    return class Integration {
-        static Definition = definition;
-    };
-}
-
-const goodIntegration = () =>
-    integrationClass({
-        name: 'acme',
-        version: '1.0.0',
-        modules: { acme: { definition: moduleDefinition() } },
-    });
-
-const codes = (issues) =>
-    issues.map((i) => `${i.severity}:${i.code}:${i.pointer}`);
-
-describe('checkIntegrations', () => {
-    it('accepts a well-formed integration class', () => {
-        expect(
-            checkIntegrations({ integrations: [goodIntegration()] })
-        ).toEqual([]);
-    });
-
-    it('warns when the app lists no integrations', () => {
-        expect(codes(checkIntegrations({ integrations: [] }))).toEqual([
-            'warning:no-integrations:/integrations',
-        ]);
-    });
-
-    it('rejects an entry that is not a class', () => {
-        expect(
-            codes(
-                checkIntegrations({
-                    integrations: [{ Definition: { name: 'x' } }],
-                })
-            )
-        ).toEqual(['error:integration-not-a-class:/integrations/0']);
-    });
-
-    it('rejects a class without a static Definition', () => {
-        class Bare {}
-        expect(codes(checkIntegrations({ integrations: [Bare] }))).toEqual([
-            'error:integration-definition-missing:/integrations/0/Definition',
-        ]);
-    });
-
-    it('requires a valid name and modules, and warns on a missing version', () => {
-        const Cls = integrationClass({ name: '1 bad name' });
-        expect(codes(checkIntegrations({ integrations: [Cls] }))).toEqual([
-            'error:integration-name-invalid:/integrations/0/Definition/name',
-            'warning:integration-version-missing:/integrations/0/Definition/version',
-            'error:integration-modules-missing:/integrations/0/Definition/modules',
-        ]);
-    });
-
-    it('reports duplicate integration names', () => {
-        expect(
-            codes(
-                checkIntegrations({
-                    integrations: [goodIntegration(), goodIntegration()],
-                })
-            )
-        ).toEqual([
-            'error:integration-name-duplicate:/integrations/1/Definition/name',
-        ]);
-    });
-
-    it('checks module definitions the way Module.validateDefinition does', () => {
-        const definition = moduleDefinition();
-        delete definition.requiredAuthMethods.getToken;
-        delete definition.moduleName;
-        const Cls = integrationClass({
-            name: 'acme',
-            version: '1',
-            modules: { acme: { definition }, other: {} },
-        });
-
-        expect(codes(checkIntegrations({ integrations: [Cls] }))).toEqual([
-            'error:module-name-missing:/integrations/0/Definition/modules/acme/definition/moduleName',
-            'error:module-auth-method-missing:/integrations/0/Definition/modules/acme/definition/requiredAuthMethods/getToken',
-            'error:module-definition-missing:/integrations/0/Definition/modules/other/definition',
-        ]);
-    });
-
-    it('does not require getToken for non-OAuth2 modules', () => {
-        const definition = moduleDefinition();
-        definition.API = class {
-            static requesterType = 'apiKey';
-        };
-        delete definition.requiredAuthMethods.getToken;
-        const Cls = integrationClass({
-            name: 'acme',
-            version: '1',
-            modules: { acme: { definition } },
-        });
-
-        expect(checkIntegrations({ integrations: [Cls] })).toEqual([]);
-    });
-
-    it('warns that a module rateLimit is not applied', () => {
-        const definition = {
-            ...moduleDefinition(),
-            rateLimit: { requests: 10, period: 'second' },
-        };
-        const Cls = integrationClass({
-            name: 'acme',
-            version: '1',
-            modules: { acme: { definition } },
-        });
-
-        expect(codes(checkIntegrations({ integrations: [Cls] }))).toEqual([
-            'warning:module-rate-limit-ignored:/integrations/0/Definition/modules/acme/definition/rateLimit',
-        ]);
-    });
-});