Merge pull request #5956 from FlowFuse/add-api-o-generate-snapshot-diff-description

Steve-Mcl · web-flow · commit 0a50a04d9271 · 2025-08-27T17:26:27.000+01:00
Add api to generate snapshot diff description
diff --git a/forge/db/controllers/Assistant.js b/forge/db/controllers/Assistant.js
@@ -0,0 +1,92 @@
+const { default: axios } = require('axios')
+
+module.exports = {
+    /**
+     * Invokes a Language Learning Model (LLM) service with the specified method and payload.
+     *
+     * @async
+     * @function
+     * @param {Object} app @ignore - The application instance containing configuration details.
+     * @param {string} method - The API endpoint method to call on the LLM service.
+     * @param {Object} payload - The request payload to be sent to the LLM.
+     * @param {Object} options - An optional object containing configurations for the request.
+     * @param {string} options.teamHashId - The unique identifier for the team.
+     * @param {Object} [options.additionalHeaders={}] - Additional headers to be included in the request.
+     * @param {string} options.instanceType - The type of instance making the request.
+     * @param {string} options.instanceId - The unique identifier for the instance.
+     * @param {boolean} [options.isTeamOnTrial] - Indicator if the team is currently on trial.
+     * @returns {Promise<Object>} Resolves with the response data from the LLM service.
+     * @throws {Error} Throws an error if there is a transaction ID mismatch in the response.
+     */
+    invokeLLM: async (app, method, payload, {
+        teamHashId,
+        additionalHeaders = { },
+        instanceType,
+        instanceId,
+        isTeamOnTrial = undefined
+    }) => {
+        const timeout = app.config.assistant?.service?.requestTimeout || 60000
+        const serviceUrl = app.config.assistant?.service?.url
+        const url = `${serviceUrl.replace(/\/+$/, '')}/${method.replace(/^\/+/, '')}`
+
+        const headers = await module.exports.buildRequestHeaders(app, additionalHeaders, {
+            isTeamOnTrial,
+            instanceType,
+            instanceId,
+            teamHashId
+        })
+
+        const response = await axios.post(url, payload, { headers, timeout })
+
+        if (payload.transactionId !== response.data.transactionId) {
+            throw new Error('Transaction ID mismatch') // Ensure we are responding to the correct transaction
+        }
+        return response.data
+    },
+
+    /**
+     * Builds and returns the request headers for HTTP requests, combining application configuration, license information,
+     * and additional headers as needed.
+     *
+     * @param {Object} app - The application object containing configuration and license details.
+     * @param {Object} additionalHeaders - An object containing additional headers to include in the request.
+     * @param {Object} options - Options for customizing the headers.
+     * @param {string} options.instanceType - The type of owner for the request (e.g., user, team).
+     * @param {string} options.instanceId - The instance ID associated with the request.
+     * @param {string} options.teamHashId - The hashed team ID associated with the request.
+     * @param {boolean} [options.isTeamOnTrial] - Indicates if the team is currently in a trial period.
+     * @returns {Promise<Object>} A Promise */
+    buildRequestHeaders: async (app, additionalHeaders, { instanceType, instanceId, teamHashId, isTeamOnTrial }) => {
+        const config = app.config
+        const serviceToken = config.assistant?.service?.token
+
+        const requestHeaders = {
+            'ff-owner-type': instanceType,
+            'ff-owner-id': instanceId,
+            'ff-team-id': teamHashId
+        }
+        // include license information, team id and trial status so that we can make decisions in the assistant service
+        const isLicensed = app.license?.active() || false
+        const licenseType = isLicensed ? (app.license.get('dev') ? 'DEV' : 'EE') : 'CE'
+        const tier = isLicensed ? app.license.get('tier') : null
+
+        requestHeaders['ff-license-active'] = isLicensed
+        requestHeaders['ff-license-type'] = licenseType
+        requestHeaders['ff-license-tier'] = tier
+
+        if (isTeamOnTrial !== undefined) {
+            requestHeaders['ff-team-trial'] = isTeamOnTrial
+        }
+        if (serviceToken) {
+            requestHeaders.Authorization = `Bearer ${serviceToken}`
+        }
+        if (additionalHeaders.accept) {
+            requestHeaders.Accept = additionalHeaders.accept
+        }
+        if (additionalHeaders['user-agent']) {
+            requestHeaders['User-Agent'] = additionalHeaders['user-agent']
+        }
+
+        return requestHeaders
+    }
+}
diff --git a/forge/db/controllers/ProjectSnapshot.js b/forge/db/controllers/ProjectSnapshot.js
@@ -351,14 +351,7 @@ Object.freeze(deviceAutoSnapshotUtils)
 Object.freeze(instanceAutoSnapshotUtils)
 
 module.exports = {
-    /**
-     * Creates a snapshot of the current state of a project.
-     * Patches with flows, credentials, settings modules and env from request, if provided
-     *
-     * @param {*} app
-     * @param {*} project
-     */
-    createSnapshot: async function (app, project, user, options) {
+    async buildSnapshot (app, project, user, options) {
         const projectExport = await app.db.controllers.Project.exportProject(project)
 
         const credentialSecret = await project.getCredentialSecret()
@@ -399,6 +392,19 @@ module.exports = {
                 }, { })
             }
         }
+
+        return snapshotOptions
+    },
+    /**
+     * Creates a snapshot of the current state of a project.
+     * Patches with flows, credentials, settings modules and env from request, if provided
+     *
+     * @param {*} app
+     * @param {*} project
+     */
+    createSnapshot: async function (app, project, user, options) {
+        const snapshotOptions = await module.exports.buildSnapshot(app, project, user, options)
+
         const snapshot = await app.db.models.ProjectSnapshot.create(snapshotOptions)
         await snapshot.save()
         return snapshot
diff --git a/forge/db/controllers/index.js b/forge/db/controllers/index.js
@@ -30,7 +30,8 @@ const modelTypes = [
     'StorageFlows',
     'StorageSettings',
     'StorageSession',
-    'TeamBrokerClient'
+    'TeamBrokerClient',
+    'Assistant'
 ]
 
 async function init (app) {
diff --git a/forge/db/models/Project.js b/forge/db/models/Project.js
@@ -378,8 +378,15 @@ module.exports = {
                     return result
                 },
 
-                async getLatestSnapshot () {
+                async getLatestSnapshot (excludeAutoGenerated = false) {
                     const snapshots = await this.getProjectSnapshots({
+                        where: excludeAutoGenerated
+                            ? {
+                                name: {
+                                    [Op.notLike]: 'Auto Snapshot - %'
+                                }
+                            }
+                            : {},
                         order: [['createdAt', 'DESC']],
                         limit: 1
                     })
diff --git a/forge/ee/lib/index.js b/forge/ee/lib/index.js
@@ -50,4 +50,7 @@ module.exports = fp(async function (app, opts) {
 
     // Set the Editor Limits Feature Flag
     app.config.features.register('editorLimits', true, true)
+
+    // Set the Editor Limits Feature Flag
+    app.config.features.register('generatedSnapshotDescription', true, true)
 }, { name: 'app.ee.lib' })
diff --git a/forge/lib/objectHelpers.js b/forge/lib/objectHelpers.js
@@ -0,0 +1,92 @@
+module.exports = {
+    /**
+     * Computes the deep difference between two objects. The result represents
+     * the changes between `currentState` and `previousState`, identifying additions,
+     * removals, and modifications in nested structures such as objects and arrays.
+     *
+     * @param {Object|Array|null} currentState - The current state object or array to compare.
+     * @param {Object|Array|null} previousState - The previous state object or array to compare.
+     * @returns {Object} An object containing two properties:
+     *                   - `currentStateDiff`: The differences from the current state, highlighting added or modified values.
+     *                   - `previousStateDiff`: The differences from the previous state, highlighting removed or modified values.
+     */
+    deepDiff: (currentState, previousState) => {
+        const isMergeable = v =>
+            v !== null &&
+            typeof v === 'object' &&
+            (v.constructor === Object || Array.isArray(v))
+
+        const sameMergeableType = (a, b) =>
+            isMergeable(a) && isMergeable(b) &&
+            (Array.isArray(a) === Array.isArray(b))
+
+        function diffNode (a, b) {
+            if (Object.is(a, b)) return [undefined, undefined]
+
+            if (sameMergeableType(a, b)) {
+                const aKeys = a ? Object.keys(a) : []
+                const bKeys = b ? Object.keys(b) : []
+                const keys = new Set([...aKeys, ...bKeys])
+
+                const cOut = Array.isArray(a) ? [] : {}
+                const pOut = Array.isArray(b) ? [] : {}
+
+                let touched = false
+
+                for (const k of keys) {
+                    const aHas = a != null && Object.prototype.hasOwnProperty.call(a, k)
+                    const bHas = b != null && Object.prototype.hasOwnProperty.call(b, k)
+
+                    const aVal = aHas ? a[k] : undefined
+                    const bVal = bHas ? b[k] : undefined
+
+                    // addition -> only record on current side
+                    if (aHas && !bHas) {
+                        cOut[k] = cloneShallow(aVal)
+                        touched = true
+                        continue
+                    }
+                    // removal -> only record on previous side
+                    if (!aHas && bHas) {
+                        pOut[k] = cloneShallow(bVal)
+                        touched = true
+                        continue
+                    }
+
+                    // both present
+                    const [cChild, pChild] = diffNode(aVal, bVal)
+                    if (cChild !== undefined) {
+                        cOut[k] = cChild
+                        touched = true
+                    }
+                    if (pChild !== undefined) {
+                        pOut[k] = pChild
+                        touched = true
+                    }
+                }
+
+                if (!touched) return [undefined, undefined]
+                return [isEmpty(cOut) ? undefined : cOut, isEmpty(pOut) ? undefined : pOut]
+            }
+
+            // value changed (present in both)
+            return [cloneShallow(a), cloneShallow(b)]
+        }
+
+        function isEmpty (x) {
+            return x && typeof x === 'object' && Object.keys(x).length === 0
+        }
+
+        function cloneShallow (v) {
+            if (Array.isArray(v)) return v.slice()
+            if (v && v.constructor === Object) return { ...v }
+            return v
+        }
+
+        const [c, p] = diffNode(currentState, previousState)
+        return {
+            currentStateDiff: c || {},
+            previousStateDiff: p || {}
+        }
+    }
+}
diff --git a/forge/routes/api/assistant.js b/forge/routes/api/assistant.js
@@ -173,8 +173,6 @@ module.exports = async function (app) {
             return reply.code(400).send({ code: 'invalid_method', error: 'Invalid method name' })
         }
 
-        const url = `${serviceUrl.replace(/\/+$/, '')}/${method.replace(/^\/+/, '')}`
-
         // if this is a `flowfuse-tables-query` lets see if tables are enabled and try to get the schema hints
         const tablesFeatureEnabled = app.config.features.enabled('tables') && request.team.TeamType.getFeatureProperty('tables', false)
         const isTablesQuery = tablesFeatureEnabled && method === 'flowfuse-tables-query'
@@ -198,19 +196,30 @@ module.exports = async function (app) {
 
         // post to the assistant service
         try {
-            const headers = await buildRequestHeaders(request)
+            let isTeamOnTrial
+            if (app.billing && request.team.getSubscription) {
+                const subscription = await request.team.getSubscription()
+                isTeamOnTrial = subscription ? subscription.isTrial() : null
+            }
             const data = { ...request.body }
             if (isTablesQuery) {
                 data.context = data.context || {}
                 data.context.tablesSchema = tablesSchemaCache.get(tablesCacheKey)
             }
-            const response = await axios.post(url, data, {
-                headers,
-                timeout: requestTimeout
-            })
-            if (request.body.transactionId !== response.data.transactionId) {
+
+            const response = await app.db.controllers.Assistant.invokeLLM(
+                method, data, {
+                    teamHashId: request.team.hashid,
+                    instanceType: request.ownerType,
+                    instanceId: request.ownerId,
+                    additionalHeaders: request.headers,
+                    isTeamOnTrial
+                })
+
+            if (request.body.transactionId !== response.transactionId) {
                 throw new Error('Transaction ID mismatch') // Ensure we are responding to the correct transaction
             }
+
             reply.send(response.data)
         } catch (error) {
             reply.code(error.response?.status || 500).send({ code: error.response?.data?.code || 'unexpected_error', error: error.response?.data?.error || error.message })
diff --git a/forge/routes/api/project.js b/forge/routes/api/project.js
diff --git a/frontend/src/pages/admin/TeamTypes/dialogs/TeamTypeEditDialog.vue b/frontend/src/pages/admin/TeamTypes/dialogs/TeamTypeEditDialog.vue
diff --git a/test/unit/forge/routes/api/project_spec.js b/test/unit/forge/routes/api/project_spec.js

Original file line number	Diff line number	Diff line change
`@@ -30,7 +30,8 @@ const modelTypes = [`
`30`	`30`	`'StorageFlows',`
`31`	`31`	`'StorageSettings',`
`32`	`32`	`'StorageSession',`
`33`		`- 'TeamBrokerClient'`
	`33`	`+ 'TeamBrokerClient',`
	`34`	`+ 'Assistant'`
`34`	`35`	`]`
`35`	`36`
`36`	`37`	`async function init (app) {`