@friggframework/core 2.0.0-next.104 → 2.0.0-next.106

package/admin-scripts/repositories/admin-script-execution-repository-interface.js

@@ -34,7 +34,7 @@ class AdminScriptExecutionRepositoryInterface {
      * @param {string} [params.context.audit.apiKeyName] - Name of API key used
      * @param {string} [params.context.audit.apiKeyLast4] - Last 4 chars of API key
      * @param {string} [params.context.audit.ipAddress] - IP address of requester
-     * @param {string|number} [params.parentExecutionId] - ID of the execution that queued this one; persisted to the parentExecutionId column (self-FK) for the parent/child hierarchy
+     * @param {string|number} [params.parentExecutionId] - ID of the execution that queued this one, for the parent/child hierarchy
      * @returns {Promise<Object>} The created process record
      * @abstract
      */
@@ -65,6 +65,9 @@ class AdminScriptExecutionRepositoryInterface {
      * @param {string} [options.sortBy] - Field to sort by
      * @param {string} [options.sortOrder] - Sort order ('asc' or 'desc')
      * @param {string} [options.state] - Optional state filter ('PENDING', 'RUNNING', 'COMPLETED', 'FAILED')
+     * @param {string} [options.type] - Optional type filter ('ADMIN_SCRIPT', 'REPORT', 'DB_MIGRATION')
+     * @param {Date} [options.from] - Optional lower bound (inclusive) on createdAt
+     * @param {Date} [options.to] - Optional upper bound (inclusive) on createdAt
      * @returns {Promise<Array>} Array of process records
      * @abstract
      */
@@ -153,10 +156,12 @@ class AdminScriptExecutionRepositoryInterface {
      * Used for cleanup and retention policies
      *
      * @param {Date} date - Delete processes older than this date
+     * @param {Object} [options] - Deletion options
+     * @param {string} [options.type] - Optional type filter, so report vs script retention can diverge
      * @returns {Promise<Object>} Deletion result with count
      * @abstract
      */
-    async deleteExecutionsOlderThan(date) {
+    async deleteExecutionsOlderThan(date, options = {}) {
         throw new Error(
             'Method deleteExecutionsOlderThan must be implemented by subclass'
         );

package/admin-scripts/repositories/admin-script-execution-repository-mongo.js

@@ -75,10 +75,19 @@ class AdminScriptExecutionRepositoryMongo extends AdminScriptExecutionRepository
             sortBy = 'createdAt',
             sortOrder = 'desc',
             state,
+            type,
+            from,
+            to,
         } = options;
 
         const where = { name };
         if (state) where.state = state;
+        if (type) where.type = type;
+        if (from || to) {
+            where.createdAt = {};
+            if (from) where.createdAt.gte = from;
+            if (to) where.createdAt.lte = to;
+        }
 
         const processes = await this.prisma.adminScriptExecution.findMany({
             where,
@@ -207,15 +216,16 @@ class AdminScriptExecutionRepositoryMongo extends AdminScriptExecutionRepository
      * Used for cleanup and retention policies
      *
      * @param {Date} date - Delete processes older than this date
+     * @param {Object} [options] - Deletion options
+     * @param {string} [options.type] - Optional type filter
      * @returns {Promise<Object>} Deletion result with count
      */
-    async deleteExecutionsOlderThan(date) {
+    async deleteExecutionsOlderThan(date, { type } = {}) {
+        const where = { createdAt: { lt: date } };
+        if (type) where.type = type;
+
         const result = await this.prisma.adminScriptExecution.deleteMany({
-            where: {
-                createdAt: {
-                    lt: date,
-                },
-            },
+            where,
         });
 
         return {

package/admin-scripts/repositories/admin-script-execution-repository-postgres.js

@@ -110,10 +110,19 @@ class AdminScriptExecutionRepositoryPostgres extends AdminScriptExecutionReposit
             sortBy = 'createdAt',
             sortOrder = 'desc',
             state,
+            type,
+            from,
+            to,
         } = options;
 
         const where = { name };
         if (state) where.state = state;
+        if (type) where.type = type;
+        if (from || to) {
+            where.createdAt = {};
+            if (from) where.createdAt.gte = from;
+            if (to) where.createdAt.lte = to;
+        }
 
         const processes = await this.prisma.adminScriptExecution.findMany({
             where,
@@ -247,15 +256,16 @@ class AdminScriptExecutionRepositoryPostgres extends AdminScriptExecutionReposit
      * Used for cleanup and retention policies
      *
      * @param {Date} date - Delete processes older than this date
+     * @param {Object} [options] - Deletion options
+     * @param {string} [options.type] - Optional type filter
      * @returns {Promise<Object>} Deletion result with count
      */
-    async deleteExecutionsOlderThan(date) {
+    async deleteExecutionsOlderThan(date, { type } = {}) {
+        const where = { createdAt: { lt: date } };
+        if (type) where.type = type;
+
         const result = await this.prisma.adminScriptExecution.deleteMany({
-            where: {
-                createdAt: {
-                    lt: date,
-                },
-            },
+            where,
         });
 
         return {

package/application/commands/admin-script-commands.js

@@ -105,7 +105,8 @@ function createAdminScriptCommands() {
                 const process = await adminScriptExecutionRepository.findExecutionById(
                     processId
                 );
-                if (!process) {
+                // Scripts and reports share one store; exclude REPORT rows so the two never read each other's executions.
+                if (!process || process.type === 'REPORT') {
                     const error = new Error(`Execution ${processId} not found`);
                     error.code = 'EXECUTION_NOT_FOUND';
                     return mapErrorToResponse(error);

package/application/commands/credential-commands.js

@@ -216,6 +216,23 @@ function createCredentialCommands() {
             }
         },
 
+        /**
+         * Count credentials active (updatedAt >= since) grouped by integration
+         * type, derived from the related Entity.moduleName. Returns a non-secret
+         * projection only — never reads or decrypts credential secrets.
+         *
+         * @param {Object} params
+         * @param {Date} [params.since] - Lower bound on updatedAt
+         * @returns {Promise<Array<{ integrationType: string, count: number }>>}
+         */
+        async countActiveByType({ since } = {}) {
+            try {
+                return await credRepo.countActiveByType({ since });
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
         /**
          * Delete a credential by ID (alias for deleteCredential)
          * @param {string} credentialId - Credential ID to delete

package/application/commands/integration-commands.js

@@ -89,9 +89,21 @@ function createIntegrationCommands({ integrationClass } = {}) {
         }
     }
 
+    /**
+     * Report-shaped projection (derived counters + timestamps) — the
+     * cross-integration read that reports (ADR-010) consume via commands.
+     */
+    async function listForReport(filter = {}) {
+        try {
+            return await integrationRepository.findAllForReport(filter);
+        } catch (error) {
+            return mapErrorToResponse(error);
+        }
+    }
+
     // The remaining commands hydrate/modify integrations for a specific class.
     if (!integrationClass) {
-        return { findIntegrationById, listIntegrations };
+        return { findIntegrationById, listIntegrations, listForReport };
     }
 
     const moduleRepository = createModuleRepository();
@@ -154,6 +166,7 @@ function createIntegrationCommands({ integrationClass } = {}) {
     return {
         findIntegrationById,
         listIntegrations,
+        listForReport,
 
         /**
          * Find integration context by external entity ID and type

package/application/commands/integration-mapping-commands.js

@@ -0,0 +1,25 @@
+const {
+    createIntegrationMappingRepository,
+} = require('../../integrations/repositories/integration-mapping-repository-factory');
+
+function mapErrorToResponse(error) {
+    return { error: 500, reason: error?.message, code: error?.code };
+}
+
+// Kept separate from integration-commands so the mapping and integration domains stay decoupled.
+function createIntegrationMappingCommands() {
+    const mappingRepository = createIntegrationMappingRepository();
+
+    return {
+        // Returns a Map of integrationId → count, or an error object on failure.
+        async countByIntegrationIds(ids = []) {
+            try {
+                return await mappingRepository.countByIntegrationIds(ids);
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+    };
+}
+
+module.exports = { createIntegrationMappingCommands };

package/application/commands/report-commands.js

@@ -0,0 +1,188 @@
+const ERROR_CODE_MAP = {
+    EXECUTION_NOT_FOUND: 404,
+};
+
+function mapErrorToResponse(error) {
+    const status = ERROR_CODE_MAP[error?.code] || 500;
+    return { error: status, reason: error?.message, code: error?.code };
+}
+
+/**
+ * Report commands share the AdminScriptExecution store, discriminated by
+ * type:'REPORT'. That store has no user/integration FK, and findExecutionById
+ * rejects non-REPORT rows, so a report lookup can never return another
+ * operation type's record (ADR-010 Decision 3).
+ */
+function createReportCommands({ artifactRepository } = {}) {
+    const {
+        createAdminScriptExecutionRepository,
+    } = require('../../admin-scripts/repositories/admin-script-execution-repository-factory');
+
+    const executionRepository = createAdminScriptExecutionRepository();
+
+    let artifactRepo = artifactRepository || null;
+    function getArtifactRepository() {
+        if (!artifactRepo) {
+            const {
+                createArtifactRepository,
+            } = require('../../artifacts/repositories/artifact-repository-factory');
+            artifactRepo = createArtifactRepository();
+        }
+        return artifactRepo;
+    }
+
+    // Resolve to null rather than throw: a read must not fail because signing did.
+    async function signArtifact(ref) {
+        if (!ref) return null;
+        try {
+            return await getArtifactRepository().signedUrl(ref);
+        } catch (_error) {
+            return null;
+        }
+    }
+
+    return {
+        async createExecution({
+            reportName,
+            reportVersion,
+            trigger,
+            mode,
+            input,
+            audit,
+            seriesName,
+            parentExecutionId,
+        }) {
+            try {
+                return await executionRepository.createExecution({
+                    name: reportName,
+                    type: 'REPORT',
+                    parentExecutionId,
+                    context: {
+                        reportVersion,
+                        trigger,
+                        mode: mode || 'recorded',
+                        input,
+                        audit,
+                        ...(seriesName ? { seriesName } : {}),
+                    },
+                });
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        async findExecutionById(id) {
+            try {
+                const record = await executionRepository.findExecutionById(id);
+                if (!record || record.type !== 'REPORT') {
+                    const error = new Error(`Report execution ${id} not found`);
+                    error.code = 'EXECUTION_NOT_FOUND';
+                    return mapErrorToResponse(error);
+                }
+                // The stored artifact ref is not retrievable on its own; sign it on read.
+                if (record.results?.artifact) {
+                    record.results = {
+                        ...record.results,
+                        artifactUrl: await signArtifact(record.results.artifact),
+                    };
+                }
+                return record;
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        // Never-throws: returns [] on error (non-critical read).
+        async listExecutionsByName(reportName, { limit, offset, state } = {}) {
+            try {
+                return await executionRepository.findExecutionsByName(
+                    reportName,
+                    { type: 'REPORT', limit, offset, state }
+                );
+            } catch (error) {
+                return [];
+            }
+        },
+
+        // No mode index in the store, so fetch by name/window and filter snapshots
+        // in JS. Never-throws: returns [] on error.
+        async findSnapshotSeries(reportName, { from, to, limit } = {}) {
+            try {
+                const rows = await executionRepository.findExecutionsByName(
+                    reportName,
+                    {
+                        type: 'REPORT',
+                        from,
+                        to,
+                        sortBy: 'createdAt',
+                        sortOrder: 'asc',
+                        limit,
+                    }
+                );
+                const snapshots = rows.filter(
+                    (row) => row.context?.mode === 'snapshot'
+                );
+                return Promise.all(
+                    snapshots.map(async (row) => ({
+                        executionId: row.id,
+                        capturedAt: row.createdAt,
+                        summary:
+                            row.results?.output?.summary ??
+                            row.results?.summary ??
+                            null,
+                        artifactUrl: await signArtifact(row.results?.artifact),
+                    }))
+                );
+            } catch (error) {
+                return [];
+            }
+        },
+
+        async updateExecutionState(id, state) {
+            try {
+                return await executionRepository.updateExecutionState(id, state);
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        async appendExecutionLog(id, logEntry) {
+            try {
+                return await executionRepository.appendExecutionLog(id, logEntry);
+            } catch (error) {
+                return mapErrorToResponse(error);
+            }
+        },
+
+        // results.output is the inline JSON payload; results.summary + results.artifact
+        // are a large/binary payload's summary + object-store reference.
+        async completeExecution(
+            id,
+            { state, output, summary, artifact, error, metrics, logs } = {}
+        ) {
+            try {
+                if (state) {
+                    await executionRepository.updateExecutionState(id, state);
+                }
+                const resultsUpdate = {};
+                if (output !== undefined) resultsUpdate.output = output;
+                if (summary !== undefined) resultsUpdate.summary = summary;
+                if (artifact !== undefined) resultsUpdate.artifact = artifact;
+                if (error) resultsUpdate.error = error;
+                if (metrics) resultsUpdate.metrics = metrics;
+                if (logs) resultsUpdate.logs = logs;
+                if (Object.keys(resultsUpdate).length > 0) {
+                    await executionRepository.updateExecutionResults(
+                        id,
+                        resultsUpdate
+                    );
+                }
+                return { success: true };
+            } catch (err) {
+                return mapErrorToResponse(err);
+            }
+        },
+    };
+}
+
+module.exports = { createReportCommands };

package/artifacts/repositories/artifact-repository-factory.js

@@ -0,0 +1,19 @@
+// A configured bucket always wins, even in dev (unlike the encryption stage-bypass):
+// a deployed Lambda writes artifacts and the router reads them in different containers,
+// so routing dev to ephemeral /tmp would silently lose them.
+const { ArtifactRepositoryS3 } = require('./artifact-repository-s3');
+const { ArtifactRepositoryLocal } = require('./artifact-repository-local');
+
+function createArtifactRepository() {
+    const bucket = process.env.REPORT_ARTIFACT_BUCKET;
+    if (bucket) {
+        return new ArtifactRepositoryS3({ bucket });
+    }
+    return new ArtifactRepositoryLocal();
+}
+
+module.exports = {
+    createArtifactRepository,
+    ArtifactRepositoryS3,
+    ArtifactRepositoryLocal,
+};

package/artifacts/repositories/artifact-repository-interface.js

@@ -0,0 +1,27 @@
+/**
+ * Port for report artifacts (non-JSON output like CSV, PDF). Implementations
+ * write bytes to a durable store and return a location reference the caller
+ * persists; signed URLs are minted on read.
+ */
+class ArtifactRepositoryInterface {
+    /**
+     * @param {string} key - Caller-supplied, e.g. `reports/{executionId}/{name}-{stamp}.{ext}`.
+     * @returns {Promise<{bucket: string, key: string}>} Location reference.
+     */
+    async put(key, body, contentType) {
+        throw new Error('ArtifactRepositoryInterface.put not implemented');
+    }
+
+    /**
+     * @param {{bucket: string, key: string}|string} ref - Reference from put(), or a bare key.
+     */
+    async signedUrl(ref, { expiresIn } = {}) {
+        throw new Error('ArtifactRepositoryInterface.signedUrl not implemented');
+    }
+
+    async get(key) {
+        throw new Error('ArtifactRepositoryInterface.get not implemented');
+    }
+}
+
+module.exports = { ArtifactRepositoryInterface };

package/artifacts/repositories/artifact-repository-local.js

@@ -0,0 +1,42 @@
+/**
+ * Dev/test artifact adapter: writes to a local directory and returns file:// URLs.
+ * Selected by the factory only when no object store is configured (no REPORT_ARTIFACT_BUCKET).
+ */
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const {
+    ArtifactRepositoryInterface,
+} = require('./artifact-repository-interface');
+
+class ArtifactRepositoryLocal extends ArtifactRepositoryInterface {
+    constructor({ baseDir } = {}) {
+        super();
+        this.baseDir =
+            baseDir ||
+            process.env.REPORT_ARTIFACT_DIR ||
+            path.join(os.tmpdir(), 'frigg-report-artifacts');
+    }
+
+    _pathFor(key) {
+        return path.join(this.baseDir, key);
+    }
+
+    async put(key, body, _contentType) {
+        const filePath = this._pathFor(key);
+        await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.promises.writeFile(filePath, body);
+        return { bucket: this.baseDir, key };
+    }
+
+    async signedUrl(ref, _options = {}) {
+        const key = ref?.key || ref;
+        return `file://${this._pathFor(key)}`;
+    }
+
+    async get(key) {
+        return fs.promises.readFile(this._pathFor(key), 'utf8');
+    }
+}
+
+module.exports = { ArtifactRepositoryLocal };

package/artifacts/repositories/artifact-repository-s3.js

@@ -0,0 +1,61 @@
+// aws-sdk modules are lazy-required so importing this file (and the factory that
+// references it) never forces the SDK to load for contexts that only need the local adapter.
+const {
+    ArtifactRepositoryInterface,
+} = require('./artifact-repository-interface');
+
+class ArtifactRepositoryS3 extends ArtifactRepositoryInterface {
+    constructor({ bucket, region, s3Client } = {}) {
+        super();
+        this.bucket = bucket || process.env.REPORT_ARTIFACT_BUCKET;
+        this.region = region || process.env.AWS_REGION || 'us-east-1';
+        this._s3Client = s3Client || null;
+    }
+
+    _getClient() {
+        if (!this._s3Client) {
+            const { S3Client } = require('@aws-sdk/client-s3');
+            this._s3Client = new S3Client({ region: this.region });
+        }
+        return this._s3Client;
+    }
+
+    async put(key, body, contentType) {
+        if (!this.bucket) {
+            throw new Error(
+                'REPORT_ARTIFACT_BUCKET is not configured; cannot store report artifact'
+            );
+        }
+        const { PutObjectCommand } = require('@aws-sdk/client-s3');
+        // No ACL set: the bucket blocks public access, so objects stay private.
+        await this._getClient().send(
+            new PutObjectCommand({
+                Bucket: this.bucket,
+                Key: key,
+                Body: body,
+                ContentType: contentType,
+                ServerSideEncryption: 'AES256',
+            })
+        );
+        return { bucket: this.bucket, key };
+    }
+
+    async signedUrl(ref, { expiresIn = 3600 } = {}) {
+        const { GetObjectCommand } = require('@aws-sdk/client-s3');
+        const { getSignedUrl } = require('@aws-sdk/s3-request-presigner');
+        const bucket = ref?.bucket || this.bucket;
+        const key = ref?.key || ref;
+        const command = new GetObjectCommand({ Bucket: bucket, Key: key });
+        return getSignedUrl(this._getClient(), command, { expiresIn });
+    }
+
+    async get(key) {
+        const { GetObjectCommand } = require('@aws-sdk/client-s3');
+        const response = await this._getClient().send(
+            new GetObjectCommand({ Bucket: this.bucket, Key: key })
+        );
+        return response.Body.transformToString();
+    }
+}
+
+module.exports = { ArtifactRepositoryS3 };

package/credential/repositories/credential-active-type.js

@@ -0,0 +1,32 @@
+const UNKNOWN_TYPE = 'unknown';
+
+/**
+ * Type is derived from the related Entity.moduleName since Credential carries
+ * no type column. Counted once per distinct linked moduleName; none → `unknown`.
+ * Reads only the non-encrypted projection — never `data`/secrets.
+ */
+function tallyActiveCredentialsByType(credentials = []) {
+    const counts = new Map();
+
+    for (const credential of credentials) {
+        const modules = new Set(
+            (credential?.entities || [])
+                .map((entity) => entity?.moduleName)
+                .filter(
+                    (moduleName) => moduleName != null && moduleName !== ''
+                )
+        );
+        const types = modules.size > 0 ? [...modules] : [UNKNOWN_TYPE];
+
+        for (const type of types) {
+            counts.set(type, (counts.get(type) || 0) + 1);
+        }
+    }
+
+    return [...counts].map(([integrationType, count]) => ({
+        integrationType,
+        count,
+    }));
+}
+
+module.exports = { tallyActiveCredentialsByType, UNKNOWN_TYPE };

package/credential/repositories/credential-repository-documentdb.js

@@ -2,6 +2,7 @@ const { prisma } = require('../../database/prisma');
 const {
     toObjectId,
     fromObjectId,
+    findManyDrained,
     findOne,
     insertOne,
     updateOne,
@@ -10,6 +11,7 @@ const {
 const {
     CredentialRepositoryInterface,
 } = require('./credential-repository-interface');
+const { tallyActiveCredentialsByType } = require('./credential-active-type');
 const {
     DocumentDBEncryptionService,
 } = require('../../database/documentdb-encryption-service');
@@ -238,6 +240,55 @@ class CredentialRepositoryDocumentDB extends CredentialRepositoryInterface {
         return this._mapCredential(decryptedCredential);
     }
 
+    /**
+     * Count credentials active since a timestamp, grouped by integration type.
+     * Projected raw reads only; the encrypted `data` is never fetched, so secrets are never decrypted for this read.
+     * @returns {Promise<Array<{ integrationType: string, count: number }>>}
+     */
+    async countActiveByType({ since } = {}) {
+        const filter = {};
+        // Coerce to Date: a raw string never matches the BSON date $gte (type bracketing).
+        if (since) filter.updatedAt = { $gte: new Date(since) };
+
+        // Drained: a deployment-wide scan must not truncate at DocumentDB's ~101-doc first batch.
+        const activeCredentials = await findManyDrained(
+            this.prisma,
+            'Credential',
+            filter,
+            { projection: { _id: 1 } }
+        );
+
+        const credentialIds = activeCredentials
+            .map((doc) => toObjectId(doc._id))
+            .filter(Boolean);
+
+        const entities = credentialIds.length
+            ? await findManyDrained(
+                  this.prisma,
+                  'Entity',
+                  { credentialId: { $in: credentialIds } },
+                  { projection: { credentialId: 1, moduleName: 1 } }
+              )
+            : [];
+
+        const entitiesByCredential = new Map();
+        for (const entity of entities) {
+            const key = fromObjectId(entity.credentialId);
+            if (!entitiesByCredential.has(key)) {
+                entitiesByCredential.set(key, []);
+            }
+            entitiesByCredential
+                .get(key)
+                .push({ moduleName: entity.moduleName });
+        }
+
+        const credentials = activeCredentials.map((doc) => ({
+            entities: entitiesByCredential.get(fromObjectId(doc._id)) || [],
+        }));
+
+        return tallyActiveCredentialsByType(credentials);
+    }
+
     _buildIdentifierFilter(identifiers) {
         const filter = {};
         if (identifiers._id || identifiers.id) {

package/credential/repositories/credential-repository-interface.js

@@ -93,6 +93,21 @@ class CredentialRepositoryInterface {
             'Method updateCredential must be implemented by subclass'
         );
     }
+
+    /**
+     * Count credentials active (updatedAt >= since) grouped by integration type.
+     * Reads ONLY non-encrypted fields — never the encrypted `data` JSON.
+     *
+     * @param {Object} params
+     * @param {Date} [params.since] - Lower bound on updatedAt
+     * @returns {Promise<Array<{ integrationType: string, count: number }>>}
+     * @abstract
+     */
+    async countActiveByType(/* { since } */) {
+        throw new Error(
+            'Method countActiveByType must be implemented by subclass'
+        );
+    }
 }
 
 module.exports = { CredentialRepositoryInterface };