@friggframework/core 2.0.0--canary.707.df80bfd.0 → 2.0.0--canary.680.d670696.0

package/extensions/extension-loader.js

@@ -1,230 +0,0 @@
-/**
- * Extension Loader
- *
- * Validates and normalizes the core extensions of the app definition
- * (`appDefinition.coreExtensions`, an array). Core extensions add custom
- * Prisma models, encryption schemas, admin routes and bootstrap logic to a
- * Frigg app. The key is `coreExtensions`, not `extensions`: ADR-017 keeps
- * `appDefinition.extensions` for its keyed object form.
- *
- * @example
- * const extensions = loadExtensions(appDefinition);
- * // extensions is a normalized array, safe to iterate
- */
-
-const path = require('path');
-const {
-    coreExtensionRoutePathError,
-} = require('../management-api/route-registry');
-
-const SCHEMA_DB_TYPES = ['postgresql', 'mongodb'];
-
-function schemaErrors(schema, label) {
-    if (typeof schema === 'string') {
-        return schema.endsWith('.prisma') ? [] : [`${label}: must end with .prisma`];
-    }
-    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
-        return [`${label}: must be a string (path to .prisma file) or { postgresql, mongodb } paths`];
-    }
-    const errors = [];
-    const keys = Object.keys(schema);
-    if (keys.length === 0) errors.push(`${label}: names no database type`);
-    for (const key of keys) {
-        if (!SCHEMA_DB_TYPES.includes(key)) {
-            errors.push(`${label}.${key}: unknown database type (expected ${SCHEMA_DB_TYPES.join(' or ')})`);
-        } else if (typeof schema[key] !== 'string' || !schema[key].endsWith('.prisma')) {
-            errors.push(`${label}.${key}: must be a path ending in .prisma`);
-        }
-    }
-    return errors;
-}
-
-/**
- * Validates a single extension definition.
- * @param {Object} ext - Raw extension config from app definition
- * @param {number} index - Position in the coreExtensions array (for error messages)
- * @returns {{valid: boolean, errors: string[]}}
- */
-function validateExtension(ext, index) {
-    const prefix = `coreExtensions[${index}]`;
-    const errors = [];
-
-    if (!ext || typeof ext !== 'object') {
-        errors.push(`${prefix}: must be an object`);
-        return { valid: false, errors };
-    }
-
-    if (!ext.name || typeof ext.name !== 'string') {
-        errors.push(`${prefix}.name: required string`);
-    }
-
-    // schema is optional: a .prisma file for every database, or one per
-    // database type ({ postgresql, mongodb }), since a model written for one
-    // (an autoincrement Int id, a String[] column) does not compile for the other.
-    if (ext.schema !== undefined) {
-        errors.push(...schemaErrors(ext.schema, `${prefix}.schema`));
-    }
-
-    // migrations is optional: a directory of Prisma migration folders
-    // (<timestamp>_<name>/migration.sql) for the extension's PostgreSQL models.
-    // They are applied with the core migrations. MongoDB has no migrations.
-    if (ext.migrations !== undefined && (typeof ext.migrations !== 'string' || ext.migrations === '')) {
-        errors.push(`${prefix}.migrations: must be a string (path to a migrations directory)`);
-    }
-
-    // encryption is optional — object with model names → { fields: [...] }
-    if (ext.encryption !== undefined) {
-        if (!ext.encryption || typeof ext.encryption !== 'object') {
-            errors.push(`${prefix}.encryption: must be an object`);
-        } else {
-            for (const [model, config] of Object.entries(ext.encryption)) {
-                if (!config || !Array.isArray(config.fields)) {
-                    errors.push(
-                        `${prefix}.encryption.${model}: must have a "fields" array`
-                    );
-                }
-            }
-        }
-    }
-
-    // routes is optional — { path, handler }
-    if (ext.routes !== undefined) {
-        if (!ext.routes || typeof ext.routes !== 'object') {
-            errors.push(`${prefix}.routes: must be an object with { path, handler }`);
-        } else {
-            if (!ext.routes.path || typeof ext.routes.path !== 'string') {
-                errors.push(`${prefix}.routes.path: required string`);
-            } else {
-                const pathError = coreExtensionRoutePathError(ext.routes.path);
-                if (pathError) {
-                    errors.push(`${prefix}.routes.path: ${pathError}`);
-                }
-            }
-            if (!ext.routes.handler) {
-                errors.push(`${prefix}.routes.handler: required (function or module path)`);
-            }
-        }
-    }
-
-    // bootstrap is optional — function or module path
-    if (ext.bootstrap !== undefined) {
-        if (typeof ext.bootstrap !== 'function' && typeof ext.bootstrap !== 'string') {
-            errors.push(
-                `${prefix}.bootstrap: must be a function or a string (module path)`
-            );
-        }
-    }
-
-    return { valid: errors.length === 0, errors };
-}
-
-/**
- * Loads and validates extensions from the app definition.
- *
- * @param {Object} appDefinition - The full app definition
- * @returns {Array<Object>} Normalized extensions array (empty if none)
- * @throws {Error} If any extension fails validation
- */
-function loadExtensions(appDefinition) {
-    if (!appDefinition) return [];
-
-    // The array this loader reads used to be `appDefinition.extensions`;
-    // that key now belongs to ADR-017's keyed object. An array there is the
-    // old spelling: stop at load rather than silently dropping the extensions.
-    if (Array.isArray(appDefinition.extensions)) {
-        throw new Error(
-            'appDefinition.extensions (array) was renamed to appDefinition.coreExtensions; ' +
-                'move the array to coreExtensions'
-        );
-    }
-
-    const raw = appDefinition.coreExtensions;
-    if (!raw) return [];
-
-    if (!Array.isArray(raw)) {
-        throw new Error('appDefinition.coreExtensions must be an array');
-    }
-
-    if (raw.length === 0) return [];
-
-    const allErrors = [];
-
-    const normalized = raw.map((ext, index) => {
-        const { valid, errors } = validateExtension(ext, index);
-        if (!valid) {
-            allErrors.push(...errors);
-            return null;
-        }
-
-        // Normalize bootstrap — resolve string paths to functions
-        let bootstrapFn = null;
-        if (typeof ext.bootstrap === 'function') {
-            bootstrapFn = ext.bootstrap;
-        } else if (typeof ext.bootstrap === 'string') {
-            bootstrapFn = require(ext.bootstrap);
-        }
-
-        // Normalize route handler — resolve string paths to functions
-        let routeHandler = null;
-        if (ext.routes) {
-            if (typeof ext.routes.handler === 'function') {
-                routeHandler = ext.routes.handler;
-            } else if (typeof ext.routes.handler === 'string') {
-                routeHandler = require(ext.routes.handler);
-            } else {
-                routeHandler = ext.routes.handler;
-            }
-        }
-
-        return {
-            name: ext.name,
-            schema: ext.schema || null,
-            migrations: ext.migrations || null,
-            encryption: ext.encryption || null,
-            routes: ext.routes
-                ? { path: ext.routes.path, handler: routeHandler }
-                : null,
-            bootstrap: bootstrapFn,
-        };
-    });
-
-    if (allErrors.length > 0) {
-        throw new Error(
-            `Invalid extension configuration:\n- ${allErrors.join('\n- ')}`
-        );
-    }
-
-    return normalized.filter(Boolean);
-}
-
-/**
- * The .prisma file an extension adds for one database type.
- * @param {Object} ext - Normalized extension
- * @param {'postgresql'|'mongodb'} [dbType] - Omitted: a string schema only
- * @returns {string|null}
- */
-function extensionSchemaPath(ext, dbType) {
-    if (!ext?.schema) return null;
-    if (typeof ext.schema === 'string') return ext.schema;
-    return dbType ? ext.schema[dbType] || null : null;
-}
-
-/**
- * Get extension schema file paths from loaded extensions.
- * @param {Array<Object>} extensions - Normalized extensions
- * @param {'postgresql'|'mongodb'} [dbType] - Database the paths are for. A
- *   per-database schema ({ postgresql, mongodb }) only answers when given one.
- * @returns {string[]} Array of absolute paths to .prisma schema files
- */
-function getExtensionSchemaPaths(extensions, dbType) {
-    return extensions
-        .map((ext) => extensionSchemaPath(ext, dbType))
-        .filter(Boolean);
-}
-
-module.exports = {
-    loadExtensions,
-    validateExtension,
-    getExtensionSchemaPaths,
-    extensionSchemaPath,
-};

package/extensions/index.js

@@ -1,44 +0,0 @@
-/**
- * Frigg Extension System
- *
- * Extensions allow integration developers to extend Frigg Core with:
- * - Custom Prisma models (schema composition)
- * - Encrypted fields (encryption registry merge)
- * - Admin API routes (route mounting)
- * - Bootstrap lifecycle hooks (credential loading, etc.)
- *
- * @module @friggframework/core/extensions
- */
-
-const { loadExtensions, validateExtension, getExtensionSchemaPaths } = require('./extension-loader');
-const { composeSchemas, extractModelBlocks, getSchemaFilePaths } = require('./schema-composer');
-const { composeExtensionPrisma, resolvePrismaDbTypes } = require('./prisma-composer');
-const {
-    mountExtensionRoutes,
-    createExtensionRoutesRouter,
-} = require('./route-mounter');
-const { runExtensionBootstraps } = require('./bootstrap-runner');
-const { initializeApp, resetInitialization } = require('./initialize-app');
-
-module.exports = {
-    // Extension loading & validation
-    loadExtensions,
-    validateExtension,
-    getExtensionSchemaPaths,
-
-    // Schema composition
-    composeSchemas,
-    extractModelBlocks,
-    getSchemaFilePaths,
-    composeExtensionPrisma,
-    resolvePrismaDbTypes,
-
-    // Route mounting
-    mountExtensionRoutes,
-    createExtensionRoutesRouter,
-
-    // Bootstrap lifecycle
-    runExtensionBootstraps,
-    initializeApp,
-    resetInitialization,
-};

package/extensions/initialize-app.js

@@ -1,123 +0,0 @@
-/**
- * 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

@@ -1,270 +0,0 @@
-/**
- * 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,
-};