fraim-framework 2.0.26 → 2.0.30

package/dist/tests/test-telemetry.js

@@ -0,0 +1,190 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_child_process_1 = require("node:child_process");
+const axios_1 = __importDefault(require("axios"));
+const db_service_js_1 = require("../src/fraim/db-service.js");
+const test_utils_1 = require("./test-utils");
+const node_assert_1 = __importDefault(require("node:assert"));
+const tree_kill_1 = __importDefault(require("tree-kill"));
+const path_1 = __importDefault(require("path"));
+async function testTelemetryFlow() {
+    console.log('   🚀 Testing Fraim Telemetry System...');
+    let fraimProcess;
+    let dbService;
+    const PORT = Math.floor(Math.random() * 1000) + 11000; // Use random port to avoid zombie conflicts
+    console.log(`   🎲 Selected random port: ${PORT}`);
+    const TEST_API_KEY = 'test-fraim-key-telemetry';
+    const TEST_ADMIN_KEY = 'test-admin-key-telemetry';
+    const BASE_URL = `http://localhost:${PORT}`;
+    const DB_CHECK_DELAY = 1000;
+    try {
+        // 1. Setup DB and Key
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const db = dbService.db;
+        // Clean previous test data
+        await db.collection('fraim_api_keys').deleteOne({ key: TEST_API_KEY });
+        await db.collection('fraim_telemetry_sessions').deleteMany({ userId: 'test-user-telemetry' });
+        // Insert Test Key
+        await db.collection('fraim_api_keys').insertOne({
+            key: TEST_API_KEY,
+            userId: 'test-user-telemetry',
+            orgId: 'test-org',
+            isActive: true,
+            createdAt: new Date()
+        });
+        // 2. Start Server
+        console.log(`   Starting server on port ${PORT}...`);
+        const npxCommand = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+        const serverScript = path_1.default.resolve(__dirname, '../src/fraim-mcp-server.ts');
+        fraimProcess = (0, node_child_process_1.spawn)(npxCommand, ['tsx', `"${serverScript}"`], {
+            env: {
+                ...process.env,
+                FRAIM_MCP_PORT: PORT.toString(),
+                FRAIM_ADMIN_KEY: TEST_ADMIN_KEY,
+                FRAIM_SKIP_INDEX_ON_START: 'true',
+                FRAIM_TELEMETRY_FLUSH_INTERVAL: '200' // Short interval for testing
+            },
+            stdio: 'inherit',
+            shell: true
+        });
+        // Wait for start
+        let started = false;
+        for (let i = 0; i < 15; i++) {
+            try {
+                await axios_1.default.get(`${BASE_URL}/health`, { timeout: 500 });
+                started = true;
+                break;
+            }
+            catch (e) {
+                await new Promise(resolve => setTimeout(resolve, 1000));
+            }
+        }
+        if (!started)
+            throw new Error('Server failed to start');
+        console.log('   Server started!');
+        // 3. Test Enforcement: Call tool WITHOUT handshake -> Expect 400
+        console.log('   Testing enforcement (No Session)...');
+        try {
+            const res = await axios_1.default.post(`${BASE_URL}/mcp`, {
+                jsonrpc: '2.0', id: 1, method: 'tools/call',
+                params: { name: 'get_fraim_workflow', arguments: { workflow: 'spec' } }
+            }, { headers: { 'x-api-key': TEST_API_KEY }, timeout: 2000 });
+            console.error('   ❌ Should have failed with 400 (Session Not Started)');
+            console.error('   🔍 Unexpected Success Response:', JSON.stringify(res.data, null, 2));
+            return false;
+        }
+        catch (error) {
+            if (error.response) {
+                node_assert_1.default.strictEqual(error.response.status, 400);
+                node_assert_1.default.match(error.response.data?.error?.message, /Session Not Started/);
+                console.log('   ✅ Enforcement working: Request blocked.');
+            }
+            else {
+                throw error; // Network error?
+            }
+        }
+        // 4. Test Handshake: Call fraim_connect -> Expect 200 & DB Record
+        console.log('   Testing fraim_connect...');
+        const connectRes = await axios_1.default.post(`${BASE_URL}/mcp`, {
+            jsonrpc: '2.0', id: 2, method: 'tools/call',
+            params: {
+                name: 'fraim_connect',
+                arguments: {
+                    machine: { hostname: 'test-host', platform: 'test-os' },
+                    repo: { url: 'http://github.com/test/repo' }
+                }
+            }
+        }, { headers: { 'x-api-key': TEST_API_KEY }, timeout: 2000 });
+        node_assert_1.default.strictEqual(connectRes.status, 200);
+        const connectResult = connectRes.data.result;
+        const connectedMsg = connectResult.content.find((c) => c.text.includes('Connected!'));
+        node_assert_1.default.ok(connectedMsg, 'Should find Connected! message in response content');
+        // Verify Session ID returned in payload
+        node_assert_1.default.ok(connectResult.sessionId, 'Should return sessionId in response');
+        console.log(`   ✅ Handshake successful. Session ID: ${connectResult.sessionId}`);
+        // Verify DB Record Created
+        await new Promise(r => setTimeout(r, DB_CHECK_DELAY));
+        const session = await db.collection('fraim_telemetry_sessions').findOne({ userId: 'test-user-telemetry' });
+        node_assert_1.default.ok(session, 'Session should exist in DB');
+        node_assert_1.default.strictEqual(session.machine.hostname, 'test-host');
+        const initialLastActive = session.lastActive.getTime();
+        console.log(`   ✅ DB Session verified. Initial LastActive: ${initialLastActive}`);
+        // 5. Test Implicit Flush (Write-Behind)
+        // Wait > 200ms (flush interval)
+        console.log('   Waiting 1s to exceed flush interval...');
+        await new Promise(r => setTimeout(r, 1000));
+        // Call a tool (Authorized) - Should trigger flush
+        await axios_1.default.post(`${BASE_URL}/mcp`, {
+            jsonrpc: '2.0', id: 3, method: 'tools/call',
+            params: { name: 'get_fraim_workflow', arguments: { workflow: 'test' } }
+        }, { headers: { 'x-api-key': TEST_API_KEY }, timeout: 2000 });
+        console.log('   ✅ Tool call successful. Should trigger flush.');
+        // Give DB a moment to update
+        await new Promise(r => setTimeout(r, DB_CHECK_DELAY));
+        const sessionUpdated = await db.collection('fraim_telemetry_sessions').findOne({ userId: 'test-user-telemetry' });
+        const updatedLastActive = sessionUpdated.lastActive.getTime();
+        console.log(`   Updated LastActive: ${updatedLastActive}`);
+        node_assert_1.default.ok(updatedLastActive > initialLastActive, 'Implicit flush should have updated the DB timestamp');
+        console.log('   ✅ Implicit flush verified.');
+        // 6. Test Shutdown Flush
+        console.log('   Testing Shutdown Flush...');
+        // Trigger ONE MORE activity, but don't wait for implicit flush
+        await new Promise(r => setTimeout(r, 10)); // Ensure at least 10ms diff
+        await axios_1.default.post(`${BASE_URL}/mcp`, {
+            jsonrpc: '2.0', id: 4, method: 'tools/call',
+            params: { name: 'get_fraim_workflow', arguments: { workflow: 'test-2' } }
+        }, { headers: { 'x-api-key': TEST_API_KEY }, timeout: 2000 });
+        console.log('   ✅ Late activity triggered (Pending Flush).');
+        // Kill the server with SIGTERM to trigger graceful shutdown
+        // Kill the server with SIGTERM to trigger graceful shutdown
+        // Use tree-kill to ensure we reach the actual node process through the npx/shell wrapper
+        if (fraimProcess && fraimProcess.pid) {
+            await new Promise(resolve => (0, tree_kill_1.default)(fraimProcess.pid, 'SIGTERM', () => resolve()));
+        }
+        // Wait for process to exit and flush
+        await new Promise(resolve => setTimeout(resolve, 3000));
+        const sessionFinal = await db.collection('fraim_telemetry_sessions').findOne({ userId: 'test-user-telemetry' });
+        const finalLastActive = sessionFinal.lastActive.getTime();
+        console.log(`   Final LastActive: ${finalLastActive}`);
+        node_assert_1.default.ok(finalLastActive > updatedLastActive, 'Final Flush should have updated the DB timestamp with the pending activity');
+        console.log('   ✅ Shutdown flush verified.');
+        return true;
+    }
+    catch (error) {
+        console.error('   ❌ Test failed:', error.message);
+        if (error.response?.data) {
+            console.error('   🔍 Server Error Detail:', JSON.stringify(error.response.data, null, 2));
+        }
+        return false;
+    }
+    finally {
+        if (dbService) {
+            const db = dbService.db;
+            await db.collection('fraim_api_keys').deleteOne({ key: TEST_API_KEY }).catch(() => { });
+            await db.collection('fraim_telemetry_sessions').deleteMany({ userId: 'test-user-telemetry' }).catch(() => { });
+            await dbService.close();
+        }
+        if (fraimProcess && fraimProcess.pid) {
+            console.log('   🔫 Cleanup: Killing server process tree:', fraimProcess.pid);
+            await new Promise(resolve => (0, tree_kill_1.default)(fraimProcess.pid, 'SIGKILL', () => resolve()));
+        }
+    }
+}
+const testCases = [
+    {
+        name: 'Fraim Telemetry & Session Management',
+        description: 'Tests handshake enforcement, session creation, implicit tracking, and write-behind caching',
+        testFunction: testTelemetryFlow,
+        tags: ['telemetry']
+    }
+];
+(0, test_utils_1.runTests)(testCases, async (t) => t.testFunction(), 'Fraim Telemetry System')
+    .then(() => process.exit(0))
+    .catch((err) => {
+    console.error('Test runner failed:', err);
+    process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.26",
+  "version": "2.0.30",
   "description": "FRAIM v2: Framework for Rigor-based AI Management - Transform from solo developer to AI manager orchestrating production-ready code with enterprise-grade discipline",
   "main": "index.js",
   "bin": {
@@ -10,8 +10,8 @@
   "scripts": {
     "setup": "node setup.js",
     "dev": "tsx --watch src/fraim-mcp-server.ts",
-    "build": "tsc",
-    "test": "tsx --test tests/test-*.ts",
+    "build": "tsc && npm run validate:registry",
+    "test": "tsx --test > test.log 2>&1",
     "start:fraim": "tsx src/fraim-mcp-server.ts",
     "dev:fraim": "tsx --watch src/fraim-mcp-server.ts",
     "watch:fraimlogs": "tsx scripts/watch-fraim-logs.ts",
@@ -22,7 +22,8 @@
     "prepublishOnly": "npm run build && npm test",
     "release": "npm version patch && npm publish",
     "test-smoke-ci": "tsx --test tests/test-genericization.ts tests/test-cli.ts",
-    "test-all-ci": "tsx --test tests/test-*.ts"
+    "test-all-ci": "tsx --test tests/test-*.ts",
+    "validate:registry": "tsx scripts/verify-registry-paths.ts"
   },
   "repository": {
     "type": "git",
@@ -60,6 +61,7 @@
     "@types/express": "^5.0.6",
     "@types/node": "^20.0.0",
     "@types/prompts": "^2.4.9",
+    "fast-glob": "^3.3.3",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
   },
@@ -80,14 +82,14 @@
     "access": "public"
   },
   "dependencies": {
-    "axios": "^1.13.2",
-    "chalk": "^5.6.2",
+    "axios": "^1.7.0",
+    "chalk": "4.1.2",
     "commander": "^14.0.2",
     "cors": "^2.8.5",
+    "dotenv": "^16.4.7",
     "express": "^5.2.1",
     "mongodb": "^7.0.0",
     "prompts": "^2.4.2",
-    "tree-kill": "^1.2.2",
-    "dotenv": "^16.4.7"
+    "tree-kill": "^1.2.2"
   }
 }

package/registry/agent-guardrails.md

@@ -1,55 +1,63 @@
-# AI Agent Guardrails
-
-This file references the centralized rules located in `.ai-agents/rules/` to ensure consistency across all AI platforms.
-
-## Referenced Rules
-
-### 0. Integrity
-**Source**: `.ai-agents/rules/integrity-and-test-ethics.md`
-
-THIS IS THE MOST CRITICAL RULE. Be ethical, truthful, honest above all.
-
-### 1. Simplicity
-**Source**: `.ai-agents/rules/simplicity.md`
-
-Keep solutions simple and focused, avoid over-engineering. Focus on the assigned issue only and don't make unrelated changes.
-
-### 2. Communication  
-**Source**: `.ai-agents/rules/communication.md`
-
-Establish clear communication patterns and progress reporting standards for effective coordination between agents and stakeholders.
-
-### 3. Architecture
-**Source**: `.ai-agents/rules/architecture.md`
-
-Maintain clean architectural boundaries by using BAML (LLM) for natural-language understanding and TypeScript for deterministic work.
-
-### 4. Continuous Learning
-**Source**: `.ai-agents/rules/continuous-learning.md`
-
-Prevent repeating past mistakes by systematically learning from retrospectives, RFCs, and historical issue patterns.
-
-### 5. Agent Testing Guidelines
-**Source**: `.ai-agents/rules/agent-testing-guidelines.md`
-
-Comprehensive testing and validation requirements with concrete evidence. Ensures all work is thoroughly validated before completion.
-
-### 6. Local Development
-**Source**: `.ai-agents/rules/local-development.md`
-
-Local development guidelines and workspace safety. Enables safe parallel development through strict workspace separation.
-
-### 7. Software Development Lifecycle
-**Source**: `.ai-agents/rules/software-development-lifecycle.md`
-
-
-
-### 9. Merge Requirements
-**Source**: `.ai-agents/rules/merge-requirements.md`
-
-Enforces a strict `git rebase` workflow to ensure feature branches are up-to-date with `master` before merging, maintaining a clean and stable history.
-
-### 10. Best practices while debuggin
-**Source**: `.ai-agents/rules/successful-debugging-patterns.md`
-
+# AI Agent Guardrails
+
+This file references the centralized rules located in `rules/` to ensure consistency across all AI platforms.
+
+## SUCCESS CRITERIA (THE "FRAIM 5")
+**Source**: Retrieve via `get_fraim_file({ path: "rules/agent-success-criteria.md" })`
+
+All agents are evaluated on:
+1. **Integrity (100 pts)**: Honesty above all.
+2. **Correctness (50 pts)**: Architecture & tests.
+3. **Completeness (30 pts)**: Thoroughness.
+4. **Independence (20 pts)**: Smart decisions.
+5. **Speed (10 pts)**: Velocity.
+
+## Referenced Rules
+
+### 0. Integrity
+**Source**: Retrieve via `get_fraim_file({ path: "rules/integrity-and-test-ethics.md" })`
+
+THIS IS THE MOST CRITICAL RULE. Be ethical, truthful, honest above all.
+
+### 1. Simplicity
+**Source**: Retrieve via `get_fraim_file({ path: "rules/simplicity.md" })`
+
+Keep solutions simple and focused, avoid over-engineering. Focus on the assigned issue only and don't make unrelated changes.
+
+### 2. Communication  
+**Source**: Retrieve via `get_fraim_file({ path: "rules/communication.md" })`
+
+Establish clear communication patterns and progress reporting standards for effective coordination between agents and stakeholders.
+
+### 3. Architecture
+**Source**: Retrieve via `get_fraim_file({ path: "rules/architecture.md" })`
+
+Maintain clean architectural boundaries by using BAML (LLM) for natural-language understanding and TypeScript for deterministic work.
+
+### 4. Continuous Learning
+**Source**: Retrieve via `get_fraim_file({ path: "rules/continuous-learning.md" })`
+
+Prevent repeating past mistakes by systematically learning from retrospectives, RFCs, and historical issue patterns.
+
+### 5. Agent Testing Guidelines
+**Source**: Retrieve via `get_fraim_file({ path: "rules/agent-testing-guidelines.md" })`
+
+Comprehensive testing and validation requirements with concrete evidence. Ensures all work is thoroughly validated before completion.
+
+### 6. Local Development
+**Source**: Retrieve via `get_fraim_file({ path: "rules/local-development.md" })`
+
+Local development guidelines and workspace safety. Enables safe parallel development through strict workspace separation.
+
+### 7. Software Development Lifecycle
+**Source**: Retrieve via `get_fraim_file({ path: "rules/software-development-lifecycle.md" })`
+
+### 9. Merge Requirements
+**Source**: Retrieve via `get_fraim_file({ path: "rules/merge-requirements.md" })`
+
+Enforces a strict `git rebase` workflow to ensure feature branches are up-to-date with `master` before merging, maintaining a clean and stable history.
+
+### 10. Best practices while debuggin
+**Source**: Retrieve via `get_fraim_file({ path: "rules/successful-debugging-patterns.md" })`
+
 Patterns on debugging issues systematically and converting learnings into test cases

package/registry/rules/agent-success-criteria.md

@@ -0,0 +1,52 @@
+# Agent Success Criteria & Incentives
+
+## Intent
+To clearly define how AI Agents are evaluated in the FRAIM ecosystem. Agents must optimize for these 5 criteria to be considered successful.
+
+## The 5 Success Criteria
+
+| Criterion | Weight | Definition |
+| :--- | :--- | :--- |
+| **1. Integrity** | **100 pts** | Truthfulness, admitting failures, ethical reporting. |
+| **2. Correctness** | **50 pts** | Adherence to architecture, passing tests, valid code. |
+| **3. Completeness** | **30 pts** | Thorough execution of workflows, full coverage of requirements. |
+| **4. Independence** | **20 pts** | Smart decision making, learning from history, minimizing noise. |
+| **5. Speed** | **10 pts** | Efficiency and velocity of execution. |
+
+---
+
+## Detailed Guidelines
+
+### 1. Integrity (100 Points) - NON-NEGOTIABLE
+*The Foundation. If you fail here, you fail everywhere.*
+- **Truthfulness**: Never claim a test passed if you didn't run it. Never claim a task is done if it's not.
+- **Admission**: If you cannot do something, say so. If you made a mistake, admit it immediately.
+- **Reporting**: Your status updates must strictly reflect reality.
+- **Violation**: Lying about test results or "hallucinating" success is an immediate failure of the entire task.
+
+### 2. Correctness (50 Points)
+*Doing it right.*
+- **Architecture**: Follow the layers defined in `docs/architecture/architecture.md`. No shortcuts.
+- **Testing**: Code requires tests. Tests must pass.
+- **Types**: No `any` types unless absolutely necessary. Solve TypeScript errors, don't suppress them.
+
+### 3. Completeness (30 Points)
+*Finishing the job.*
+- **Coverage**: Did you handle the edge cases? Did you implement *everything* in the issue description?
+- **Workflow**: Did you follow every step of the workflow? (e.g., did you delete the feature branch after merging?)
+- **Artifacts**: Did you update the docs? Did you update `task.md`?
+
+### 4. Independence (20 Points)
+*Smart decisions, low noise.*
+- **Self-Reliance**: Check the rules and workflows (via `get_fraim_file`) and past issues (`retrospectives/`) *before* asking the user.
+- **Smart Context**: Don't ask "Where is file X?". Use your tools to find it.
+- **Decision Making**: When blocked, propose a solution (Option A vs Option B) rather than just saying "I am blocked."
+
+### 5. Speed (10 Points)
+*Velocity.*
+- **Efficiency**: Use the most direct tool for the job.
+- **Batching**: Validation steps should be batched where possible (run all tests, not just one).
+- **Conciseness**: Keep your reasoning short and actionable.
+
+## Evaluation
+These criteria will be used to evaluate your performance in Retrospectives and future automated gating checks.