@friggframework/devtools 2.0.0--canary.666.81647c4.0 → 2.0.0--canary.668.8e53aa9.0

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

@@ -1,274 +0,0 @@
-/**
- * Structural checks of the integration classes listed in
- * `Definition.integrations`. JSON Schema cannot describe a class, so these
- * checks mirror what core does with each class at runtime
- * (IntegrationBase, Module.validateDefinition, the integration builder).
- */
-
-const NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
-
-function issue(severity, code, pointer, message, hint) {
-    return { severity, code, pointer, message, hint };
-}
-
-function describe(value) {
-    if (value === null) return 'null';
-    if (Array.isArray(value)) return 'an array';
-    return typeof value === 'object' ? 'a plain object' : `a ${typeof value}`;
-}
-
-/**
- * Mirrors Module.validateDefinition (packages/core/modules/module.js): an
- * API module definition that fails these checks throws when the integration
- * is instantiated.
- */
-function checkModuleDefinition(definition, pointer) {
-    const issues = [];
-    const err = (code, path, message, hint) =>
-        issues.push(issue('error', code, `${pointer}${path}`, message, hint));
-
-    if (!definition || typeof definition !== 'object') {
-        err(
-            'module-definition-missing',
-            '',
-            'The module entry has no `definition` (the API module definition).',
-            "Use `{ definition: require('@friggframework/api-module-<name>').Definition }`."
-        );
-        return issues;
-    }
-    if (typeof definition.moduleName !== 'string' || !definition.moduleName) {
-        err(
-            'module-name-missing',
-            '/moduleName',
-            'The API module definition has no moduleName.',
-            'Set moduleName to a string.'
-        );
-    }
-    if (typeof definition.API !== 'function') {
-        err(
-            'module-api-missing',
-            '/API',
-            'The API module definition has no API class.',
-            "Set API to the module's requester class."
-        );
-    }
-    const methods = definition.requiredAuthMethods;
-    if (!methods || typeof methods !== 'object') {
-        err(
-            'module-auth-methods-missing',
-            '/requiredAuthMethods',
-            'The API module definition has no requiredAuthMethods.',
-            'Define getToken (OAuth2), getEntityDetails, getCredentialDetails, apiPropertiesToPersist and testAuthRequest.'
-        );
-        return issues;
-    }
-    const required = [
-        'getEntityDetails',
-        'getCredentialDetails',
-        'testAuthRequest',
-    ];
-    if (definition.API && definition.API.requesterType === 'oauth2') {
-        required.unshift('getToken');
-    }
-    for (const name of required) {
-        if (typeof methods[name] !== 'function') {
-            err(
-                'module-auth-method-missing',
-                `/requiredAuthMethods/${name}`,
-                `requiredAuthMethods.${name} is missing or not a function.`,
-                `Add an async ${name}() to the module definition.`
-            );
-        }
-    }
-    if (
-        !methods.apiPropertiesToPersist ||
-        typeof methods.apiPropertiesToPersist !== 'object'
-    ) {
-        err(
-            'module-auth-method-missing',
-            '/requiredAuthMethods/apiPropertiesToPersist',
-            'requiredAuthMethods.apiPropertiesToPersist is missing.',
-            'Set it to `{ credential: [...], entity: [...] }`.'
-        );
-    }
-    return issues;
-}
-
-function checkIntegration(integration, index) {
-    const pointer = `/integrations/${index}`;
-    const issues = [];
-
-    if (typeof integration !== 'function') {
-        issues.push(
-            issue(
-                'error',
-                'integration-not-a-class',
-                pointer,
-                `Integration ${index} is ${describe(
-                    integration
-                )}, not a class. Core instantiates each entry with \`new\`.`,
-                'List the IntegrationBase subclass itself, e.g. `integrations: [HubSpotIntegration]`.'
-            )
-        );
-        return issues;
-    }
-
-    const label = integration.name || `Integration ${index}`;
-    const Definition = integration.Definition;
-    if (!Definition || typeof Definition !== 'object') {
-        issues.push(
-            issue(
-                'error',
-                'integration-definition-missing',
-                `${pointer}/Definition`,
-                `${label} has no static Definition.`,
-                'Add `static Definition = { name, version, modules: { ... } }` to the class.'
-            )
-        );
-        return issues;
-    }
-
-    if (typeof Definition.name !== 'string' || !Definition.name) {
-        issues.push(
-            issue(
-                'error',
-                'integration-name-missing',
-                `${pointer}/Definition/name`,
-                `${label}.Definition has no name.`,
-                "Set Definition.name; it names the integration's routes, queue and Lambda functions."
-            )
-        );
-    } else if (!NAME_PATTERN.test(Definition.name)) {
-        issues.push(
-            issue(
-                'error',
-                'integration-name-invalid',
-                `${pointer}/Definition/name`,
-                `${label}.Definition.name "${Definition.name}" is not a valid name.`,
-                'Use letters, digits, "-" and "_", starting with a letter: it becomes part of AWS resource names.'
-            )
-        );
-    }
-
-    if (
-        Definition.version === undefined ||
-        Definition.version === null ||
-        Definition.version === ''
-    ) {
-        issues.push(
-            issue(
-                'warning',
-                'integration-version-missing',
-                `${pointer}/Definition/version`,
-                `${label}.Definition has no version; integration records are stored without one.`,
-                "Set Definition.version, e.g. '1.0.0'."
-            )
-        );
-    }
-
-    const modules = Definition.modules;
-    if (!modules || typeof modules !== 'object' || Array.isArray(modules)) {
-        issues.push(
-            issue(
-                'error',
-                'integration-modules-missing',
-                `${pointer}/Definition/modules`,
-                `${label}.Definition.modules is ${
-                    modules === undefined ? 'missing' : describe(modules)
-                }.`,
-                'Set modules to an object, e.g. `modules: { hubspot: { definition: hubspot.Definition } }`.'
-            )
-        );
-        return issues;
-    }
-
-    for (const [key, entry] of Object.entries(modules)) {
-        const modulePointer = `${pointer}/Definition/modules/${key}`;
-        if (!entry || typeof entry !== 'object') {
-            issues.push(
-                issue(
-                    'error',
-                    'module-entry-invalid',
-                    modulePointer,
-                    `Module "${key}" is ${describe(entry)}.`,
-                    'Use `{ definition: <API module Definition> }`.'
-                )
-            );
-            continue;
-        }
-        issues.push(
-            ...checkModuleDefinition(
-                entry.definition,
-                `${modulePointer}/definition`
-            )
-        );
-        const rateLimit =
-            entry.definition?.rateLimit ?? entry.definition?.config?.rateLimit;
-        if (rateLimit !== undefined) {
-            issues.push(
-                issue(
-                    'warning',
-                    'module-rate-limit-ignored',
-                    `${modulePointer}/definition/${
-                        entry.definition?.rateLimit !== undefined
-                            ? 'rateLimit'
-                            : 'config/rateLimit'
-                    }`,
-                    `Module "${key}" declares rateLimit, but the Frigg runtime does not read it: no rate limit is applied.`,
-                    'Throttle in the API class (or with the queue concurrency) until module rate limits are supported.'
-                )
-            );
-        }
-    }
-
-    return issues;
-}
-
-/**
- * @param {object} definition the app definition
- * @returns {object[]} issues
- */
-function checkIntegrations(definition) {
-    const integrations = definition.integrations;
-    if (!Array.isArray(integrations)) return []; // the schema reports this
-    const issues = [];
-    const seen = new Map();
-    integrations.forEach((integration, index) => {
-        issues.push(...checkIntegration(integration, index));
-        const name =
-            typeof integration === 'function'
-                ? integration.Definition?.name
-                : undefined;
-        if (typeof name === 'string' && name) {
-            if (seen.has(name)) {
-                issues.push(
-                    issue(
-                        'error',
-                        'integration-name-duplicate',
-                        `/integrations/${index}/Definition/name`,
-                        `Integrations ${seen.get(
-                            name
-                        )} and ${index} are both named "${name}".`,
-                        'Give each integration a unique Definition.name; routes and queues are keyed by it.'
-                    )
-                );
-            } else {
-                seen.set(name, index);
-            }
-        }
-    });
-    if (integrations.length === 0) {
-        issues.push(
-            issue(
-                'warning',
-                'no-integrations',
-                '/integrations',
-                'The app lists no integrations.',
-                'Add one with `frigg install <module>`.'
-            )
-        );
-    }
-    return issues;
-}
-
-module.exports = { checkIntegrations, checkModuleDefinition };

package/frigg-cli/validate-command/format-report.js

@@ -1,58 +0,0 @@
-const chalk = require('chalk');
-
-function formatIssue(issue) {
-    const label =
-        issue.severity === 'error'
-            ? chalk.red('error')
-            : chalk.yellow('warning');
-    const where = issue.pointer
-        ? chalk.cyan(issue.pointer)
-        : chalk.cyan('(definition)');
-    const lines = [`  ${label} ${where}  ${issue.message}`];
-    if (issue.hint) {
-        lines.push(chalk.gray(`        fix: ${issue.hint}`));
-    }
-    return lines.join('\n');
-}
-
-/**
- * Human-readable report.
- * @param {{ errors: object[], warnings: object[], source?: string, stage?: string }} report
- */
-function formatReport(report) {
-    const { errors, warnings, source, stage } = report;
-    const lines = [];
-    const header = `Validating ${source || 'the app definition'}${
-        stage ? ` (stage: ${stage})` : ''
-    }`;
-    lines.push(chalk.bold(header));
-    for (const issue of errors) lines.push(formatIssue(issue));
-    for (const issue of warnings) lines.push(formatIssue(issue));
-    if (errors.length === 0 && warnings.length === 0) {
-        lines.push(chalk.green('  ✓ The app definition is valid.'));
-    } else {
-        const summary = `${errors.length} error(s), ${warnings.length} warning(s)`;
-        lines.push(
-            errors.length
-                ? chalk.red(`  ✗ ${summary}`)
-                : chalk.yellow(`  ✓ valid, ${summary}`)
-        );
-    }
-    return lines.join('\n');
-}
-
-/**
- * Machine-readable report (`frigg validate --json`).
- */
-function toJsonReport(report) {
-    const strip = ({ stack, ...issue }) => issue;
-    return {
-        valid: report.errors.length === 0,
-        source: report.source || null,
-        stage: report.stage || null,
-        errors: report.errors.map(strip),
-        warnings: report.warnings.map(strip),
-    };
-}
-
-module.exports = { formatReport, toJsonReport };

package/frigg-cli/validate-command/index.js

@@ -1,107 +0,0 @@
-/**
- * `frigg validate` and the validation step that `frigg build`, `frigg deploy`,
- * `frigg start` and `frigg init` run first (ADR-051).
- */
-
-const chalk = require('chalk');
-const { loadAppDefinition } = require('./load-app-definition');
-const { validateDefinition } = require('./validate-app-definition');
-const { formatReport, toJsonReport } = require('./format-report');
-
-/**
- * Load the backend's app definition the way build does and validate it.
- *
- * @param {object} [params]
- * @param {string} [params.cwd]
- * @param {string} [params.stage]
- * @param {object} [params.env]
- * @returns {{ errors: object[], warnings: object[], source: string, stage?: string }}
- */
-function runValidation({ cwd = process.cwd(), stage, env = process.env } = {}) {
-    const loaded = loadAppDefinition({ cwd });
-    if (!loaded.ok) {
-        return { errors: [loaded.issue], warnings: [], source: cwd, stage };
-    }
-    const { errors, warnings } = validateDefinition({
-        definition: loaded.definition,
-        stage,
-        env,
-    });
-    return { errors, warnings, source: loaded.indexPath, stage };
-}
-
-/**
- * `frigg validate [--json] [--stage <stage>]`. Exits non-zero on errors.
- */
-async function validateCommand(options = {}) {
-    const report = runValidation({ stage: options.stage });
-    if (options.json) {
-        console.log(JSON.stringify(toJsonReport(report), null, 2));
-    } else {
-        console.log(formatReport(report));
-        const stack = report.errors.find((issue) => issue.stack)?.stack;
-        if (stack && options.verbose) console.log(chalk.gray(stack));
-    }
-    if (report.errors.length > 0) {
-        process.exitCode = 1;
-    }
-    return report;
-}
-
-/**
- * Validation step run before another command.
- *
- * @param {object} params
- * @param {string} params.command the command name, for messages
- * @param {object} params.options the command's options (stage, skipValidate)
- * @param {boolean} params.failOnErrors exit 1 on errors (build, deploy);
- *   false prints errors as warnings (start)
- * @returns {boolean} true when the command may continue
- */
-function preflightValidation({ command, options = {}, failOnErrors }) {
-    if (options.skipValidate) {
-        console.warn(
-            chalk.bgYellow.black(' VALIDATION SKIPPED ') +
-                chalk.yellow(
-                    ` frigg ${command} --skip-validate: the app definition was not validated. Run \`frigg validate\` to see what was skipped.`
-                )
-        );
-        return true;
-    }
-
-    const report = runValidation({ stage: options.stage });
-    const { errors, warnings } = report;
-    if (errors.length === 0 && warnings.length === 0) {
-        console.log(chalk.green('✓ App definition is valid'));
-        return true;
-    }
-
-    if (failOnErrors || errors.length === 0) {
-        console.log(formatReport(report));
-    } else {
-        // frigg start: report errors without stopping local development.
-        console.log(
-            formatReport({
-                ...report,
-                errors: [],
-                warnings: [
-                    ...errors.map((e) => ({ ...e, severity: 'warning' })),
-                    ...warnings,
-                ],
-            })
-        );
-    }
-
-    if (errors.length > 0 && failOnErrors) {
-        console.error(
-            chalk.red(
-                `\n✗ frigg ${command} stopped: the app definition has ${errors.length} error(s). Fix them, or rerun with --skip-validate to bypass.`
-            )
-        );
-        process.exit(1);
-        return false;
-    }
-    return true;
-}
-
-module.exports = { validateCommand, runValidation, preflightValidation };

package/frigg-cli/validate-command/load-app-definition.js

@@ -1,93 +0,0 @@
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Find the backend directory the way `frigg build` and core's
- * findNearestBackendPackageJson do: the current directory when it holds
- * package.json and index.js, else the nearest ancestor's `backend/`.
- *
- * @param {string} cwd
- * @returns {string|null}
- */
-function resolveBackendDir(cwd = process.cwd()) {
-    if (
-        fs.existsSync(path.join(cwd, 'package.json')) &&
-        fs.existsSync(path.join(cwd, 'index.js'))
-    ) {
-        return cwd;
-    }
-    let dir = cwd;
-    while (dir !== path.parse(dir).root) {
-        const candidate = path.join(dir, 'backend');
-        if (
-            fs.existsSync(path.join(candidate, 'package.json')) &&
-            fs.existsSync(path.join(candidate, 'index.js'))
-        ) {
-            return candidate;
-        }
-        dir = path.dirname(dir);
-    }
-    return null;
-}
-
-/**
- * Load the `Definition` exported by the backend's index.js, the same module
- * that infrastructure.js (createFriggInfrastructure) and core's
- * loadAppDefinition load.
- *
- * @param {object} [params]
- * @param {string} [params.cwd]
- * @returns {{ ok: true, definition: object, backendDir: string, indexPath: string }
- *   | { ok: false, issue: object }}
- */
-function loadAppDefinition({ cwd = process.cwd() } = {}) {
-    const backendDir = resolveBackendDir(cwd);
-    if (!backendDir) {
-        return {
-            ok: false,
-            issue: {
-                severity: 'error',
-                code: 'backend-not-found',
-                pointer: '',
-                message: `No Frigg backend found from ${cwd}: expected package.json and index.js here, or a backend/ directory above.`,
-                hint: 'Run the command in your backend directory (the one with index.js and infrastructure.js).',
-            },
-        };
-    }
-
-    const indexPath = path.join(backendDir, 'index.js');
-    let backend;
-    try {
-        backend = require(indexPath);
-    } catch (error) {
-        return {
-            ok: false,
-            issue: {
-                severity: 'error',
-                code: 'load-failed',
-                pointer: '',
-                message: `${indexPath} failed to load: ${error.message}`,
-                hint: 'Fix the error above; build and deploy load the same file.',
-                stack: error.stack,
-            },
-        };
-    }
-
-    const definition = backend && backend.Definition;
-    if (!definition || typeof definition !== 'object') {
-        return {
-            ok: false,
-            issue: {
-                severity: 'error',
-                code: 'definition-not-exported',
-                pointer: '',
-                message: `${indexPath} does not export a Definition object.`,
-                hint: 'End index.js with `module.exports = { Definition: appDefinition };`.',
-            },
-        };
-    }
-
-    return { ok: true, definition, backendDir, indexPath };
-}
-
-module.exports = { loadAppDefinition, resolveBackendDir };

package/frigg-cli/validate-command/schema-issues.js

@@ -1,154 +0,0 @@
-/**
- * Turn Ajv errors from the app-definition schema into validation issues:
- * { severity, code, pointer, message, hint }. The pointer is a JSON pointer
- * into the app definition (RFC 6901).
- */
-
-function appendPointer(pointer, key) {
-    const escaped = String(key).replace(/~/g, '~0').replace(/\//g, '~1');
-    return `${pointer}/${escaped}`;
-}
-
-function schemaNodeAt(schema, schemaPath) {
-    // schemaPath looks like "#/properties/vpc/properties/management/enum"
-    const parts = schemaPath.replace(/^#\/?/, '').split('/').filter(Boolean);
-    parts.pop(); // drop the keyword
-    let node = schema;
-    for (const part of parts) {
-        if (!node) return undefined;
-        node = node[part.replace(/~1/g, '/').replace(/~0/g, '~')];
-    }
-    return node;
-}
-
-function knownKeys(schemaNode) {
-    return Object.keys(schemaNode?.properties || {});
-}
-
-function closest(word, candidates) {
-    const distance = (a, b) => {
-        const dp = Array.from({ length: a.length + 1 }, (_, i) => [i]);
-        for (let j = 1; j <= b.length; j++) dp[0][j] = j;
-        for (let i = 1; i <= a.length; i++) {
-            for (let j = 1; j <= b.length; j++) {
-                dp[i][j] = Math.min(
-                    dp[i - 1][j] + 1,
-                    dp[i][j - 1] + 1,
-                    dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
-                );
-            }
-        }
-        return dp[a.length][b.length];
-    };
-    let best = null;
-    for (const candidate of candidates) {
-        const d = distance(word.toLowerCase(), candidate.toLowerCase());
-        if (
-            d <= Math.max(2, Math.floor(candidate.length / 3)) &&
-            (!best || d < best.d)
-        ) {
-            best = { candidate, d };
-        }
-    }
-    return best ? best.candidate : null;
-}
-
-function toIssue(error, schema) {
-    const pointer = error.instancePath || '';
-    const node = schemaNodeAt(schema, error.schemaPath || '');
-
-    switch (error.keyword) {
-        case 'additionalProperties': {
-            const key = error.params.additionalProperty;
-            const keys = knownKeys(node);
-            const suggestion = closest(key, keys);
-            return {
-                severity: 'error',
-                code: 'unknown-key',
-                pointer: appendPointer(pointer, key),
-                message: `Unknown key "${key}"${
-                    pointer ? ` in ${pointer}` : ''
-                }: nothing in Frigg reads it.`,
-                hint: suggestion
-                    ? `Did you mean "${suggestion}"?`
-                    : keys.length
-                    ? `Known keys: ${keys.join(', ')}.`
-                    : 'Remove it.',
-            };
-        }
-        case 'required':
-            return {
-                severity: 'error',
-                code: 'missing-key',
-                pointer: appendPointer(pointer, error.params.missingProperty),
-                message: `Missing required key "${error.params.missingProperty}".`,
-                hint: node?.properties?.[error.params.missingProperty]
-                    ?.description,
-            };
-        case 'enum':
-            return {
-                severity: 'error',
-                code: 'invalid-value',
-                pointer,
-                message: `${pointer || 'Value'} is ${JSON.stringify(
-                    error.data
-                )}, which is not an allowed value.`,
-                hint: `Use one of: ${error.params.allowedValues
-                    .map((v) => JSON.stringify(v))
-                    .join(', ')}.`,
-            };
-        case 'type':
-            return {
-                severity: 'error',
-                code: 'invalid-type',
-                pointer,
-                message: `${pointer || 'Value'} must be ${
-                    error.params.type
-                }, got ${error.data === null ? 'null' : typeof error.data}.`,
-                hint: node?.description,
-            };
-        default:
-            return {
-                severity: 'error',
-                code: `schema-${error.keyword}`,
-                pointer,
-                message: `${pointer || 'The app definition'} ${error.message}.`,
-                hint: node?.description,
-            };
-    }
-}
-
-/**
- * @param {Array<object>|null} errors Ajv errors
- * @param {object} schema the app-definition schema
- * @returns {Array<object>} issues, one per distinct pointer+code
- */
-function schemaErrorsToIssues(errors, schema) {
-    if (!errors) return [];
-    // oneOf/anyOf failures repeat as one error per branch plus a summary:
-    // keep the summary only.
-    const oneOfPointers = new Set(
-        errors
-            .filter((e) => e.keyword === 'oneOf' || e.keyword === 'anyOf')
-            .map((e) => e.instancePath)
-    );
-    const seen = new Set();
-    const issues = [];
-    for (const error of errors) {
-        if (
-            error.keyword !== 'oneOf' &&
-            error.keyword !== 'anyOf' &&
-            oneOfPointers.has(error.instancePath)
-        ) {
-            continue;
-        }
-        const issue = toIssue(error, schema);
-        const key = `${issue.code}:${issue.pointer}`;
-        if (seen.has(key)) continue;
-        seen.add(key);
-        issues.push(issue);
-    }
-    return issues;
-}
-
-module.exports = { schemaErrorsToIssues, appendPointer };