@equilateral_ai/mindmeld 3.2.0 → 3.3.0

package/src/core/StandardLifecycle.js

@@ -0,0 +1,244 @@
+/**
+ * StandardLifecycle.js - State Machine for Standard Lifecycle
+ *
+ * Manages the full lifecycle of standards from discovery through deletion.
+ *
+ * States: discovery -> proposed -> active -> disabled -> deprecated -> deleted
+ *
+ * Valid transitions:
+ *   discovery -> proposed  (when confidence > threshold)
+ *   proposed  -> active    (user approves)
+ *   proposed  -> deleted   (user rejects)
+ *   active    -> disabled  (user disables temporarily)
+ *   active    -> deprecated (scheduled for removal)
+ *   disabled  -> active    (user re-enables)
+ *   deprecated -> deleted  (after grace period)
+ *   deprecated -> active   (user cancels deprecation)
+ *
+ * Records every transition in standards_audit_trail table.
+ */
+
+const { executeQuery } = require('../handlers/helpers/dbOperations');
+
+/**
+ * All valid lifecycle states
+ */
+const STATES = {
+    DISCOVERY: 'discovery',
+    PROPOSED: 'proposed',
+    ACTIVE: 'active',
+    DISABLED: 'disabled',
+    DEPRECATED: 'deprecated',
+    DELETED: 'deleted'
+};
+
+/**
+ * All valid transition actions and their from -> to mappings
+ */
+const TRANSITIONS = {
+    propose: { from: STATES.DISCOVERY, to: STATES.PROPOSED },
+    approve: { from: STATES.PROPOSED, to: STATES.ACTIVE },
+    reject: { from: STATES.PROPOSED, to: STATES.DELETED },
+    disable: { from: STATES.ACTIVE, to: STATES.DISABLED },
+    deprecate: { from: STATES.ACTIVE, to: STATES.DEPRECATED },
+    enable: { from: STATES.DISABLED, to: STATES.ACTIVE },
+    delete: { from: STATES.DEPRECATED, to: STATES.DELETED },
+    cancel_deprecation: { from: STATES.DEPRECATED, to: STATES.ACTIVE }
+};
+
+class StandardLifecycle {
+    constructor(config = {}) {
+        this.config = {
+            confidenceThreshold: config.confidenceThreshold || 0.80,
+            ...config
+        };
+    }
+
+    /**
+     * Execute a state transition for a standard
+     *
+     * @param {string} standardId - The standard identifier
+     * @param {string} action - The transition action to perform
+     * @param {string} userId - Email of the user performing the action
+     * @param {string} reason - Optional reason for the transition
+     * @returns {Promise<Object>} The transition result with new state and audit entry
+     */
+    async transition(standardId, action, userId, reason) {
+        // Validate action exists
+        const transitionDef = TRANSITIONS[action];
+        if (!transitionDef) {
+            const validActions = Object.keys(TRANSITIONS);
+            throw new Error(`Invalid action '${action}'. Valid actions: ${validActions.join(', ')}`);
+        }
+
+        // Get current state of the standard
+        const currentState = await this.getCurrentState(standardId);
+
+        if (!currentState) {
+            throw new Error(`Standard '${standardId}' not found`);
+        }
+
+        // Validate the transition is allowed from the current state
+        if (currentState !== transitionDef.from) {
+            throw new Error(
+                `Cannot perform '${action}' on standard in '${currentState}' state. ` +
+                `Action '${action}' requires state '${transitionDef.from}'.`
+            );
+        }
+
+        const oldState = currentState;
+        const newState = transitionDef.to;
+
+        // Update the standard's lifecycle state
+        await executeQuery(`
+            UPDATE rapport.patterns
+            SET lifecycle_state = $2
+            WHERE pattern_id = $1
+        `, [standardId, newState]);
+
+        // Record the transition in the audit trail
+        const auditResult = await executeQuery(`
+            INSERT INTO rapport.standards_audit_trail (
+                standard_id,
+                project_id,
+                action,
+                old_state,
+                new_state,
+                user_email,
+                reason,
+                metadata,
+                created_at
+            ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, NOW())
+            RETURNING id, standard_id, action, old_state, new_state, user_email, reason, created_at
+        `, [
+            standardId,
+            null,
+            action,
+            oldState,
+            newState,
+            userId,
+            reason || null,
+            JSON.stringify({})
+        ]);
+
+        const auditEntry = auditResult.rows[0];
+
+        console.log(`[StandardLifecycle] ${standardId}: ${oldState} -> ${newState} (${action}) by ${userId}`);
+
+        return {
+            standard_id: standardId,
+            old_state: oldState,
+            new_state: newState,
+            action: action,
+            audit_entry: auditEntry
+        };
+    }
+
+    /**
+     * Get valid transitions available from the current state
+     *
+     * @param {string} currentState - The current lifecycle state
+     * @returns {Array<Object>} Available actions with their target states
+     */
+    getValidTransitions(currentState) {
+        const valid = [];
+
+        for (const [action, def] of Object.entries(TRANSITIONS)) {
+            if (def.from === currentState) {
+                valid.push({
+                    action: action,
+                    from: def.from,
+                    to: def.to
+                });
+            }
+        }
+
+        return valid;
+    }
+
+    /**
+     * Get the full audit trail for a standard
+     *
+     * @param {string} standardId - The standard identifier
+     * @param {Object} options - Pagination options
+     * @param {string} options.cursor - Cursor for pagination (audit trail id)
+     * @param {number} options.limit - Number of records to return (default 50)
+     * @returns {Promise<Object>} Audit trail with entries and pagination info
+     */
+    async getHistory(standardId, options = {}) {
+        const limit = Math.min(parseInt(options.limit) || 50, 200);
+        const cursor = options.cursor ? parseInt(options.cursor) : null;
+
+        let query = `
+            SELECT
+                id,
+                standard_id,
+                project_id,
+                action,
+                old_state,
+                new_state,
+                user_email,
+                reason,
+                metadata,
+                created_at
+            FROM rapport.standards_audit_trail
+            WHERE standard_id = $1
+        `;
+
+        const params = [standardId];
+        let paramIndex = 2;
+
+        if (cursor) {
+            query += ` AND id < $${paramIndex}`;
+            params.push(cursor);
+            paramIndex++;
+        }
+
+        query += ` ORDER BY created_at DESC, id DESC LIMIT $${paramIndex}`;
+        params.push(limit + 1); // Fetch one extra to determine if there are more
+
+        const result = await executeQuery(query, params);
+
+        const hasMore = result.rows.length > limit;
+        const entries = hasMore ? result.rows.slice(0, limit) : result.rows;
+        const nextCursor = hasMore ? entries[entries.length - 1].id : null;
+
+        // Get total count
+        const countResult = await executeQuery(`
+            SELECT COUNT(*) as total
+            FROM rapport.standards_audit_trail
+            WHERE standard_id = $1
+        `, [standardId]);
+
+        const totalTransitions = parseInt(countResult.rows[0].total);
+
+        return {
+            entries: entries,
+            total_transitions: totalTransitions,
+            has_more: hasMore,
+            next_cursor: nextCursor ? String(nextCursor) : null
+        };
+    }
+
+    /**
+     * Get the current lifecycle state of a standard
+     *
+     * @param {string} standardId - The standard identifier
+     * @returns {Promise<string|null>} Current state or null if not found
+     */
+    async getCurrentState(standardId) {
+        const result = await executeQuery(`
+            SELECT lifecycle_state
+            FROM rapport.patterns
+            WHERE pattern_id = $1
+        `, [standardId]);
+
+        if (result.rowCount === 0) {
+            return null;
+        }
+
+        return result.rows[0].lifecycle_state || STATES.ACTIVE;
+    }
+}
+
+module.exports = { StandardLifecycle, STATES, TRANSITIONS };