@friggframework/core 2.0.0--canary.703.12b980b.0 → 2.0.0--canary.707.df80bfd.0

package/extensions/initialize-app.js

@@ -0,0 +1,123 @@
+/**
+ * Application Initialization with Extension Lifecycle
+ *
+ * Provides an async initialization function that runs extension bootstraps
+ * after database connection but before router creation. This is the integration
+ * point for providers (Lambda, Netlify) to hook into the extension lifecycle.
+ *
+ * Call `initializeApp()` during the async startup phase of your handler/function.
+ * It is safe to call multiple times — subsequent calls are no-ops.
+ *
+ * @example
+ * const { initializeApp } = require('@friggframework/core/extensions/initialize-app');
+ *
+ * // In a Lambda handler or Netlify function:
+ * await initializeApp();
+ * // Now extensions are bootstrapped and router can be created
+ */
+
+const { loadExtensions } = require('./extension-loader');
+const { runExtensionBootstraps } = require('./bootstrap-runner');
+
+let _initialized = false;
+let _initPromise = null;
+
+/**
+ * Initializes extensions by running bootstrap hooks.
+ *
+ * This function:
+ * 1. Loads the app definition
+ * 2. Loads and validates extensions
+ * 3. Runs extension bootstrap hooks in sequence
+ *
+ * Bootstrap hooks receive (prisma, appDefinition) and can:
+ * - Load credentials from database into integration Definition.env
+ * - Register services or middleware
+ * - Perform any one-time async initialization
+ *
+ * @param {Object} [options]
+ * @param {Object} [options.appDefinition] - Override app definition (skips loadAppDefinition)
+ * @param {Object} [options.prisma] - Override Prisma client instance
+ * @param {boolean} [options.force=false] - Force re-initialization
+ * @returns {Promise<{extensions: Array}>} The loaded extensions
+ */
+async function initializeApp(options = {}) {
+    const { force = false } = options;
+
+    // Return cached promise if already initializing (prevent race conditions)
+    if (_initPromise && !force) {
+        return _initPromise;
+    }
+
+    if (_initialized && !force) {
+        return { extensions: [] };
+    }
+
+    _initPromise = _doInitialize(options);
+
+    try {
+        const result = await _initPromise;
+        _initialized = true;
+        return result;
+    } catch (error) {
+        _initPromise = null;
+        throw error;
+    }
+}
+
+async function _doInitialize(options = {}) {
+    let { appDefinition, prisma } = options;
+
+    // Load app definition if not provided
+    if (!appDefinition) {
+        try {
+            const { loadAppDefinition } = require('../handlers/app-definition-loader');
+            const loaded = loadAppDefinition();
+            appDefinition = loaded.appDefinition;
+        } catch {
+            // No app definition available — skip extension bootstrap
+            return { extensions: [] };
+        }
+    }
+
+    if (!appDefinition) {
+        return { extensions: [] };
+    }
+
+    // Load extensions
+    const extensions = loadExtensions(appDefinition);
+
+    if (extensions.length === 0) {
+        return { extensions };
+    }
+
+    // Get Prisma client if not provided
+    if (!prisma) {
+        try {
+            const db = require('../database/prisma');
+            prisma = db.prisma;
+        } catch {
+            // Prisma not available — skip bootstrap
+            console.warn('Prisma client not available, skipping extension bootstraps');
+            return { extensions };
+        }
+    }
+
+    // Run bootstrap hooks
+    await runExtensionBootstraps(extensions, { prisma, appDefinition });
+
+    return { extensions };
+}
+
+/**
+ * Reset initialization state (for testing).
+ */
+function resetInitialization() {
+    _initialized = false;
+    _initPromise = null;
+}
+
+module.exports = {
+    initializeApp,
+    resetInitialization,
+};

package/extensions/prisma-composer.js

@@ -0,0 +1,270 @@
+/**
+ * Prisma composer: puts core extensions' models into the Prisma client.
+ *
+ * Core ships one generated client per database (`generated/prisma-<db>`),
+ * built from `prisma-<db>/schema.prisma`. A core extension that declares a
+ * schema (`coreExtensions[].schema`) needs its models in that client, and on
+ * PostgreSQL its tables need migrations (`coreExtensions[].migrations`).
+ * Without this step the extension's models exist nowhere: every call to
+ * `prisma.<model>` is undefined, and the table is never created.
+ *
+ * At build time, for each database the app uses:
+ *   1. The pristine core schema is kept as `schema.base.prisma` (taken from
+ *      `schema.prisma` the first time), so composing again never appends twice.
+ *   2. `schema.prisma` becomes base + the extensions' models. Everything that
+ *      reads the schema (prisma generate, the migration runner, the Lambda
+ *      layer, which copies the generated client's schema) sees the composed one.
+ *   3. PostgreSQL: each extension migration folder is copied into
+ *      `prisma-postgresql/migrations`, so `prisma migrate deploy` applies it in
+ *      timestamp order with the core migrations.
+ *   4. `prisma generate` rebuilds `generated/prisma-<db>` from the composed
+ *      schema, only when the schema changed or the client is missing.
+ *
+ * Removing every extension restores the base schema and regenerates. Copied
+ * migrations are left in place: a migration that may already be applied must
+ * not disappear from the history.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const {
+    loadExtensions,
+    getExtensionSchemaPaths,
+} = require('./extension-loader');
+const { extractModelBlocks } = require('./schema-composer');
+
+const DB_TYPES = ['postgresql', 'mongodb'];
+
+/**
+ * The Prisma databases an app definition uses. DocumentDB uses the MongoDB client.
+ * @param {Object} appDefinition
+ * @returns {Array<'postgresql'|'mongodb'>}
+ */
+function resolvePrismaDbTypes(appDefinition) {
+    const db = appDefinition?.database || {};
+    const types = [];
+    if (db.postgres?.enable) types.push('postgresql');
+    if (db.mongoDB?.enable || db.documentDB?.enable) types.push('mongodb');
+    return types;
+}
+
+function blockNames(schemaContent) {
+    const names = [];
+    const re = /^\s*(model|enum|type|view)\s+(\w+)\s*\{/gm;
+    let match;
+    while ((match = re.exec(schemaContent)) !== null) names.push(match[2]);
+    return names;
+}
+
+/**
+ * Base schema + the extensions' model blocks. Throws when an extension
+ * declares a model, enum or type the base (or another extension) already has.
+ */
+function buildComposedSchema(baseContent, extensionSchemaPaths) {
+    const seen = new Map(
+        blockNames(baseContent).map((name) => [name, 'the core schema'])
+    );
+    const sections = [];
+
+    for (const extPath of extensionSchemaPaths) {
+        if (!fs.existsSync(extPath)) {
+            throw new Error(`Extension schema not found: ${extPath}`);
+        }
+        const blocks = extractModelBlocks(fs.readFileSync(extPath, 'utf-8'));
+        if (!blocks) continue;
+        for (const name of blockNames(blocks)) {
+            if (seen.has(name)) {
+                throw new Error(
+                    `Extension schema ${extPath} declares "${name}", already declared by ${seen.get(
+                        name
+                    )}`
+                );
+            }
+            seen.set(name, extPath);
+        }
+        sections.push(`// --- Extension schema: ${extPath} ---`, blocks, '');
+    }
+
+    if (sections.length === 0) return baseContent;
+
+    return [
+        baseContent.trimEnd(),
+        '',
+        '// =========================================================================',
+        '// Extension models (composed by @friggframework/core at build; do not edit)',
+        '// =========================================================================',
+        '',
+        ...sections,
+    ].join('\n');
+}
+
+/**
+ * Copies each extension's migration folders into the core migrations
+ * directory. A folder already there with the same migration.sql is skipped;
+ * a different one under the same name is an error (it would silently be a
+ * different migration with an applied migration's name).
+ * @returns {string[]} names of the folders copied
+ */
+function copyExtensionMigrations(extensions, migrationsDir) {
+    const copied = [];
+    for (const ext of extensions) {
+        if (!ext.migrations) continue;
+        if (
+            !fs.existsSync(ext.migrations) ||
+            !fs.statSync(ext.migrations).isDirectory()
+        ) {
+            throw new Error(
+                `Extension "${ext.name}" migrations directory not found: ${ext.migrations}`
+            );
+        }
+        const folders = fs
+            .readdirSync(ext.migrations, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+        for (const folder of folders) {
+            const source = path.join(ext.migrations, folder, 'migration.sql');
+            if (!fs.existsSync(source)) {
+                throw new Error(
+                    `Extension "${ext.name}" migration ${folder} has no migration.sql`
+                );
+            }
+            const sql = fs.readFileSync(source, 'utf-8');
+            const destDir = path.join(migrationsDir, folder);
+            const dest = path.join(destDir, 'migration.sql');
+            if (fs.existsSync(dest)) {
+                if (fs.readFileSync(dest, 'utf-8') !== sql) {
+                    throw new Error(
+                        `Migration ${folder} from extension "${ext.name}" conflicts with an existing migration of the same name`
+                    );
+                }
+                continue;
+            }
+            fs.mkdirSync(destDir, { recursive: true });
+            fs.writeFileSync(dest, sql, 'utf-8');
+            copied.push(folder);
+        }
+    }
+    return copied;
+}
+
+/**
+ * Runs `prisma generate` with the Prisma CLI installed beside core (the app's
+ * own `prisma`), falling back to npx.
+ */
+function defaultGenerate({ schemaPath, corePath }) {
+    let cli;
+    try {
+        cli = require.resolve('prisma/build/index.js', {
+            paths: [corePath, process.cwd()],
+        });
+    } catch {
+        cli = null;
+    }
+    const [command, args] = cli
+        ? [process.execPath, [cli, 'generate', `--schema=${schemaPath}`]]
+        : ['npx', ['prisma', 'generate', `--schema=${schemaPath}`]];
+    execFileSync(command, args, { cwd: corePath, stdio: 'inherit' });
+}
+
+/**
+ * Composes the extensions' schemas and migrations into core's Prisma schema
+ * and regenerates the client when it changed.
+ *
+ * @param {Object} params
+ * @param {Object} params.appDefinition
+ * @param {string} params.corePath - Directory of the installed @friggframework/core
+ * @param {Array<'postgresql'|'mongodb'>} [params.dbTypes] - Defaults to the app definition's databases
+ * @param {Function} [params.generate] - ({ schemaPath, corePath, dbType }) => void
+ * @param {Function} [params.log]
+ * @returns {{ changed: boolean, results: Array<Object> }}
+ */
+function composeExtensionPrisma({
+    appDefinition,
+    corePath,
+    dbTypes,
+    generate = defaultGenerate,
+    log = (message) => console.log(message),
+}) {
+    if (!corePath) throw new Error('corePath is required');
+    const extensions = loadExtensions(appDefinition);
+    const types = (dbTypes || resolvePrismaDbTypes(appDefinition)).filter((t) =>
+        DB_TYPES.includes(t)
+    );
+    const results = [];
+
+    for (const dbType of types) {
+        const schemaDir = path.join(corePath, `prisma-${dbType}`);
+        const schemaPath = path.join(schemaDir, 'schema.prisma');
+        const basePath = path.join(schemaDir, 'schema.base.prisma');
+        if (!fs.existsSync(schemaPath)) {
+            throw new Error(`Core Prisma schema not found: ${schemaPath}`);
+        }
+
+        const extensionSchemas = getExtensionSchemaPaths(extensions, dbType);
+        // Migrations do not depend on a schema: an extension may ship only
+        // SQL (a table it reads with raw queries), and it must still be applied.
+        const migrations =
+            dbType === 'postgresql'
+                ? copyExtensionMigrations(
+                      extensions,
+                      path.join(schemaDir, 'migrations')
+                  )
+                : [];
+        if (migrations.length > 0) {
+            log(`[Frigg] Added extension migrations: ${migrations.join(', ')}`);
+        }
+
+        // No schema to compose and none composed before: the schema and the
+        // client stay exactly as core shipped them.
+        if (extensionSchemas.length === 0 && !fs.existsSync(basePath)) {
+            results.push({
+                dbType,
+                changed: migrations.length > 0,
+                migrations,
+            });
+            continue;
+        }
+
+        if (!fs.existsSync(basePath)) fs.copyFileSync(schemaPath, basePath);
+        const target = buildComposedSchema(
+            fs.readFileSync(basePath, 'utf-8'),
+            extensionSchemas
+        );
+        const current = fs.readFileSync(schemaPath, 'utf-8');
+        const schemaChanged = current !== target;
+        if (schemaChanged) fs.writeFileSync(schemaPath, target, 'utf-8');
+
+        const clientPath = path.join(
+            corePath,
+            'generated',
+            `prisma-${dbType}`,
+            'schema.prisma'
+        );
+        const clientStale =
+            !fs.existsSync(clientPath) ||
+            fs.readFileSync(clientPath, 'utf-8') !== target;
+
+        if (schemaChanged || clientStale) {
+            log(
+                `[Frigg] Composing ${extensionSchemas.length} extension schema(s) into the ${dbType} Prisma client`
+            );
+            generate({ schemaPath, corePath, dbType });
+        }
+        results.push({
+            dbType,
+            changed: schemaChanged || clientStale || migrations.length > 0,
+            migrations,
+        });
+    }
+
+    return { changed: results.some((r) => r.changed), results };
+}
+
+module.exports = {
+    composeExtensionPrisma,
+    resolvePrismaDbTypes,
+    buildComposedSchema,
+    copyExtensionMigrations,
+};

package/extensions/route-mounter.js

@@ -0,0 +1,103 @@
+/**
+ * Route Mounter
+ *
+ * Mounts extension-defined Express routers onto the main app.
+ * Each extension can declare routes with a base path and a handler factory.
+ *
+ * The handler factory receives (prisma, appDefinition) and returns an Express Router.
+ * Routes are protected by the admin auth middleware by default.
+ *
+ * @example
+ * mountExtensionRoutes(app, extensions, { prisma, appDefinition });
+ */
+
+const { validateAdminApiKey } = require('../handlers/middleware/admin-auth');
+
+/**
+ * Mounts all extension routes onto an Express app.
+ *
+ * @param {import('express').Express} app - Express app or router to mount on
+ * @param {Array<Object>} extensions - Normalized extensions (from extension-loader)
+ * @param {Object} context
+ * @param {Object} context.prisma - Prisma client instance
+ * @param {Object} context.appDefinition - Full app definition
+ * @param {Function} [context.authMiddleware] - Override admin auth middleware
+ */
+function mountExtensionRoutes(app, extensions, context = {}) {
+    if (!extensions || extensions.length === 0) return;
+
+    const { prisma, appDefinition, authMiddleware } = context;
+    const adminAuth = authMiddleware || validateAdminApiKey;
+
+    for (const ext of extensions) {
+        if (!ext.routes) continue;
+
+        const { path: basePath, handler } = ext.routes;
+
+        let router;
+        if (typeof handler === 'function') {
+            // Handler factory: (prisma, appDefinition) => Router
+            router = handler(prisma, appDefinition);
+        } else if (handler && handler.router) {
+            // Direct router object export pattern: { router }
+            router = handler.router;
+        } else if (handler && handler.default && typeof handler.default === 'function') {
+            // ES module default export
+            router = handler.default(prisma, appDefinition);
+        } else {
+            console.warn(
+                `Extension "${ext.name}": routes.handler is not a function or router object, skipping`
+            );
+            continue;
+        }
+
+        // Mount with admin auth middleware
+        app.use(basePath, adminAuth, router);
+    }
+}
+
+module.exports = { mountExtensionRoutes };
+
+/**
+ * Builds one router serving every app-level extension's routes
+ * (`appDefinition.coreExtensions[].routes`), each behind the admin API key.
+ *
+ * Lazy by design: the extensions, their route factories and the Prisma
+ * client are only touched on the first request, so requiring a handler
+ * module never connects anything.
+ *
+ * @param {Object} [params]
+ * @param {Object} [params.appDefinition] - raw app Definition; defaults to
+ *   loadAppDefinition().appDefinition on first request.
+ * @param {Object} [params.prisma] - defaults to core's Prisma client.
+ * @returns {import('express').Router}
+ */
+function createExtensionRoutesRouter({ appDefinition, prisma } = {}) {
+    const express = require('express');
+    const outer = express.Router();
+    let inner = null;
+
+    outer.use((req, res, next) => {
+        if (!inner) {
+            const definition =
+                appDefinition ||
+                require('../handlers/app-definition-loader').loadAppDefinition()
+                    .appDefinition;
+            const { loadExtensions } = require('./extension-loader');
+            const extensions = loadExtensions(definition);
+            const built = express.Router();
+            if (extensions.some((ext) => ext.routes)) {
+                mountExtensionRoutes(built, extensions, {
+                    prisma: prisma || require('../database/prisma').prisma,
+                    appDefinition: definition,
+                });
+            }
+            inner = built;
+        }
+        return inner(req, res, next);
+    });
+
+    return outer;
+}
+
+module.exports.createExtensionRoutesRouter = createExtensionRoutesRouter;

package/extensions/schema-composer.js

@@ -0,0 +1,188 @@
+/**
+ * Schema Composer
+ *
+ * Merges extension .prisma schema fragments with a base Prisma schema.
+ * Extensions can add new models/enums that get composed into the final schema
+ * used for `prisma generate` and migrations.
+ *
+ * Two approaches are supported:
+ * 1. Build-time merge: Concatenate model definitions from extension files
+ *    into the base schema and write a merged output file.
+ * 2. Multi-file schema (Prisma 5.15+): Return a list of schema paths for
+ *    Prisma's native `prismaSchemaFolder` feature.
+ *
+ * @example
+ * const { composeSchemas } = require('@friggframework/core/extensions/schema-composer');
+ *
+ * // Build-time merge — writes a merged schema file
+ * await composeSchemas({
+ *   baseSchemaPath: '/path/to/prisma-postgresql/schema.prisma',
+ *   extensionSchemaPaths: ['/path/to/extensions/db-credentials/schema.prisma'],
+ *   outputPath: '/path/to/prisma-postgresql/schema.composed.prisma',
+ * });
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extracts model/enum blocks from a .prisma file, stripping out
+ * generator and datasource blocks (which should only appear in the base schema).
+ *
+ * @param {string} schemaContent - Raw .prisma file content
+ * @returns {string} Only model/enum/type definitions
+ */
+function extractModelBlocks(schemaContent) {
+    const lines = schemaContent.split('\n');
+    const result = [];
+    let depth = 0;
+    let inBlock = false;
+    let blockType = null;
+
+    for (const line of lines) {
+        const trimmed = line.trim();
+
+        // Detect block start
+        if (depth === 0 && !inBlock) {
+            const blockMatch = trimmed.match(
+                /^(model|enum|type)\s+\w+\s*\{/
+            );
+            if (blockMatch) {
+                inBlock = true;
+                blockType = blockMatch[1];
+                result.push(line);
+                depth += (line.match(/\{/g) || []).length;
+                depth -= (line.match(/\}/g) || []).length;
+                continue;
+            }
+
+            // Skip generator/datasource blocks
+            const skipMatch = trimmed.match(
+                /^(generator|datasource)\s+\w+\s*\{/
+            );
+            if (skipMatch) {
+                inBlock = true;
+                blockType = 'skip';
+                depth += (line.match(/\{/g) || []).length;
+                depth -= (line.match(/\}/g) || []).length;
+                continue;
+            }
+
+            // Keep standalone comments between blocks
+            if (trimmed.startsWith('//') || trimmed === '') {
+                // Only keep if we've already accumulated some model blocks
+                if (result.length > 0) {
+                    result.push(line);
+                }
+                continue;
+            }
+        } else if (inBlock) {
+            depth += (line.match(/\{/g) || []).length;
+            depth -= (line.match(/\}/g) || []).length;
+
+            if (blockType !== 'skip') {
+                result.push(line);
+            }
+
+            if (depth <= 0) {
+                inBlock = false;
+                blockType = null;
+                depth = 0;
+                if (result.length > 0) {
+                    result.push(''); // blank line between blocks
+                }
+            }
+        }
+    }
+
+    return result.join('\n').trim();
+}
+
+/**
+ * Composes a merged Prisma schema from a base schema + extension fragments.
+ *
+ * @param {Object} options
+ * @param {string} options.baseSchemaPath - Absolute path to the core .prisma file
+ * @param {string[]} options.extensionSchemaPaths - Absolute paths to extension .prisma files
+ * @param {string} [options.outputPath] - Where to write the merged schema.
+ *   Defaults to `<baseDir>/schema.composed.prisma`
+ * @returns {string} The merged schema content
+ */
+function composeSchemas({ baseSchemaPath, extensionSchemaPaths, outputPath }) {
+    if (!baseSchemaPath) {
+        throw new Error('baseSchemaPath is required');
+    }
+
+    if (
+        !extensionSchemaPaths ||
+        !Array.isArray(extensionSchemaPaths) ||
+        extensionSchemaPaths.length === 0
+    ) {
+        // No extensions — just return base schema as-is
+        const baseContent = fs.readFileSync(baseSchemaPath, 'utf-8');
+        return baseContent;
+    }
+
+    const baseContent = fs.readFileSync(baseSchemaPath, 'utf-8');
+
+    // Collect model blocks from each extension
+    const extensionBlocks = [];
+    for (const extPath of extensionSchemaPaths) {
+        if (!fs.existsSync(extPath)) {
+            throw new Error(
+                `Extension schema not found: ${extPath}`
+            );
+        }
+        const extContent = fs.readFileSync(extPath, 'utf-8');
+        const models = extractModelBlocks(extContent);
+        if (models) {
+            extensionBlocks.push(
+                `// --- Extension schema from: ${path.basename(path.dirname(extPath))}/${path.basename(extPath)} ---`,
+                models
+            );
+        }
+    }
+
+    if (extensionBlocks.length === 0) {
+        return baseContent;
+    }
+
+    // Append extension models to the base schema
+    const merged = [
+        baseContent.trimEnd(),
+        '',
+        '// =========================================================================',
+        '// Extension Models (auto-composed — do not edit manually)',
+        '// =========================================================================',
+        '',
+        ...extensionBlocks,
+        '',
+    ].join('\n');
+
+    // Write the merged schema if outputPath is specified
+    const resolvedOutput =
+        outputPath ||
+        path.join(path.dirname(baseSchemaPath), 'schema.composed.prisma');
+
+    fs.writeFileSync(resolvedOutput, merged, 'utf-8');
+
+    return merged;
+}
+
+/**
+ * Returns schema paths suitable for Prisma's native multi-file schema support
+ * (prismaSchemaFolder feature, Prisma 5.15+).
+ *
+ * @param {string} baseSchemaPath - Path to the core schema
+ * @param {string[]} extensionSchemaPaths - Paths to extension schemas
+ * @returns {string[]} All schema file paths
+ */
+function getSchemaFilePaths(baseSchemaPath, extensionSchemaPaths) {
+    return [baseSchemaPath, ...(extensionSchemaPaths || [])];
+}
+
+module.exports = {
+    composeSchemas,
+    extractModelBlocks,
+    getSchemaFilePaths,
+};