fraim-framework 2.0.27 → 2.0.30

package/dist/tests/test-node-compatibility.js

@@ -0,0 +1,71 @@
+"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 test_utils_1 = require("./test-utils");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+async function testInitOnNodeVersion(version) {
+    console.log(`   🧪 Testing Node v${version}...`);
+    // Create a temp directory for each version test
+    const tempDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), `fraim-node-${version}-`));
+    try {
+        const platform = process.platform;
+        const npx = platform === 'win32' ? 'npx.cmd' : 'npx';
+        const binPath = path_1.default.resolve(__dirname, '../bin/fraim.js');
+        // Run: npx -y -p node@<version> node bin/fraim.js init
+        // We use -y to skip prompt, and -p node@version to ensure that specific node binary is used
+        const execNode = (args) => {
+            return new Promise((resolve) => {
+                const ps = (0, node_child_process_1.spawn)(npx, ['-y', '-p', `node@${version}`, 'node', `"${binPath}"`, ...args], {
+                    cwd: tempDir,
+                    env: { ...process.env, TEST_MODE: 'true' },
+                    shell: true
+                });
+                let stdout = '';
+                let stderr = '';
+                ps.stdout.on('data', d => stdout += d.toString());
+                ps.stderr.on('data', d => stderr += d.toString());
+                ps.on('close', (code) => resolve({ stdout, stderr, code }));
+            });
+        };
+        console.log(`      Running "fraim init" on Node ${version}...`);
+        const result = await execNode(['init']);
+        if (result.code !== 0) {
+            console.error(`      ❌ Failed on Node ${version}`);
+            console.error(`      Error: ${result.stderr}`);
+            return false;
+        }
+        const configPath = path_1.default.join(tempDir, '.fraim', 'config.json');
+        if (fs_1.default.existsSync(configPath)) {
+            console.log(`      ✅ Success on Node ${version}`);
+            return true;
+        }
+        else {
+            console.error(`      ❌ Config not found on Node ${version}`);
+            return false;
+        }
+    }
+    catch (e) {
+        console.error(`      ❌ Test Logic Error on Node ${version}:`, e.message);
+        return false;
+    }
+    finally {
+        try {
+            fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch (e) { }
+    }
+}
+const nodeVersions = ['16', '18', '20', '22'];
+const testCases = nodeVersions.map(v => ({
+    name: `Node v${v} Compatibility`,
+    version: v,
+    tags: ['node', 'compatibility']
+}));
+(0, test_utils_1.runTests)(testCases, async (t) => await testInitOnNodeVersion(t.version), 'Node Compatibility Matrix')
+    .then(() => process.exit(0))
+    .catch(() => process.exit(1));

package/dist/tests/test-npm-install.js

@@ -0,0 +1,66 @@
+"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 test_utils_1 = require("./test-utils");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+async function testCleanNpmInstall(version) {
+    console.log(`   🧪 Testing NPM Install on Node v${version}...`);
+    // Create a temp directory for the install test
+    const tempDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), `fraim-npm-${version}-`));
+    try {
+        const platform = process.platform;
+        const npx = platform === 'win32' ? 'npx.cmd' : 'npx';
+        // Copy package.json to temp dir
+        const packageJsonPath = path_1.default.resolve(__dirname, '../package.json');
+        fs_1.default.copyFileSync(packageJsonPath, path_1.default.join(tempDir, 'package.json'));
+        // Run: npx -p node@<version> npm install --package-lock-only
+        // This uses the npm bundled with that specific Node version
+        const execNpm = () => {
+            return new Promise((resolve) => {
+                const ps = (0, node_child_process_1.spawn)(npx, ['-y', '-p', `node@${version}`, 'npm', 'install', '--package-lock-only', '--quiet', '--no-audit'], {
+                    cwd: tempDir,
+                    env: { ...process.env },
+                    shell: true
+                });
+                let stdout = '';
+                let stderr = '';
+                ps.stdout.on('data', d => stdout += d.toString());
+                ps.stderr.on('data', d => stderr += d.toString());
+                ps.on('close', (code) => resolve({ stdout, stderr, code }));
+            });
+        };
+        console.log(`      Running "npm install" with Node ${version}...`);
+        const result = await execNpm();
+        if (result.code !== 0) {
+            console.error(`      ❌ NPM Install Failed on Node ${version}`);
+            console.error(`      Stderr: ${result.stderr}`);
+            return false;
+        }
+        console.log(`      ✅ NPM Resolution Success on Node ${version}`);
+        return true;
+    }
+    catch (e) {
+        console.error(`      ❌ Test Logic Error on Node ${version}:`, e.message);
+        return false;
+    }
+    finally {
+        try {
+            fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch (e) { }
+    }
+}
+const nodeVersions = ['16', '18', '20', '22'];
+const testCases = nodeVersions.map(v => ({
+    name: `NPM Compatibility (Node v${v})`,
+    version: v,
+    tags: ['npm', 'compatibility']
+}));
+(0, test_utils_1.runTests)(testCases, async (t) => await testCleanNpmInstall(t.version), 'NPM Configuration Matrix')
+    .then(() => process.exit(0))
+    .catch(() => process.exit(1));

package/dist/tests/test-npm-resolution-diagnostic.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Diagnostic test to understand npm's chalk resolution behavior
+ *
+ * This test will show us exactly what npm does when there's a version conflict
+ */
+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 fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+async function main() {
+    console.log('🔍 NPM Chalk Resolution Diagnostic\n');
+    const tempDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'npm-diagnostic-'));
+    console.log(`📂 Temp dir: ${tempDir}\n`);
+    try {
+        // 1. Pack fraim-framework
+        console.log('📦 Packing fraim-framework...');
+        const projectRoot = process.cwd();
+        const packResult = (0, node_child_process_1.execSync)('npm pack', {
+            cwd: projectRoot,
+            encoding: 'utf-8'
+        });
+        const tarballName = packResult.trim().split('\n').pop()?.trim();
+        if (!tarballName) {
+            console.log('❌ Failed to pack');
+            return;
+        }
+        const tarballPath = path_1.default.join(projectRoot, tarballName);
+        console.log(`✅ Created: ${tarballName}\n`);
+        // 2. Create test project with chalk v5
+        console.log('📝 Creating test project with chalk v5 dependency...');
+        const packageJson = {
+            name: 'diagnostic-test',
+            version: '1.0.0',
+            dependencies: {
+                'chalk': '^5.0.0',
+                'fraim-framework': `file:${tarballPath}`
+            }
+        };
+        fs_1.default.writeFileSync(path_1.default.join(tempDir, 'package.json'), JSON.stringify(packageJson, null, 2));
+        // 3. Install
+        console.log('📥 Running npm install...\n');
+        try {
+            const installOutput = (0, node_child_process_1.execSync)('npm install', {
+                cwd: tempDir,
+                encoding: 'utf-8',
+                stdio: 'pipe'
+            });
+            console.log('✅ Install completed\n');
+        }
+        catch (error) {
+            console.log('⚠️  Install had issues:\n', error.stdout || error.message);
+        }
+        // 4. Check what was installed
+        console.log('📋 Checking installed chalk versions...\n');
+        // Root chalk
+        const rootChalkPath = path_1.default.join(tempDir, 'node_modules', 'chalk', 'package.json');
+        if (fs_1.default.existsSync(rootChalkPath)) {
+            const pkg = JSON.parse(fs_1.default.readFileSync(rootChalkPath, 'utf-8'));
+            console.log(`  Root chalk: ${pkg.version}`);
+            console.log(`  Type: ${pkg.type || 'commonjs'}`);
+            console.log(`  Main: ${pkg.main || 'N/A'}`);
+            console.log(`  Exports: ${pkg.exports ? 'Yes' : 'No'}\n`);
+        }
+        else {
+            console.log('  ❌ No root chalk found\n');
+        }
+        // Fraim's chalk
+        const fraimChalkPath = path_1.default.join(tempDir, 'node_modules', 'fraim-framework', 'node_modules', 'chalk', 'package.json');
+        if (fs_1.default.existsSync(fraimChalkPath)) {
+            const pkg = JSON.parse(fs_1.default.readFileSync(fraimChalkPath, 'utf-8'));
+            console.log(`  fraim-framework's chalk: ${pkg.version}`);
+            console.log(`  Type: ${pkg.type || 'commonjs'}`);
+            console.log(`  Main: ${pkg.main || 'N/A'}\n`);
+        }
+        else {
+            console.log('  ℹ️  fraim-framework has no separate chalk (using root)\n');
+        }
+        // 5. Run npm ls to see the dependency tree
+        console.log('🌳 Dependency tree (npm ls chalk):\n');
+        try {
+            const lsOutput = (0, node_child_process_1.execSync)('npm ls chalk', {
+                cwd: tempDir,
+                encoding: 'utf-8'
+            });
+            console.log(lsOutput);
+        }
+        catch (error) {
+            console.log(error.stdout || error.message);
+        }
+        // 6. Check fraim-framework's package.json in node_modules
+        console.log('\n📋 fraim-framework\'s chalk dependency in node_modules:\n');
+        const fraimPkgPath = path_1.default.join(tempDir, 'node_modules', 'fraim-framework', 'package.json');
+        if (fs_1.default.existsSync(fraimPkgPath)) {
+            const fraimPkg = JSON.parse(fs_1.default.readFileSync(fraimPkgPath, 'utf-8'));
+            console.log(`  Chalk version in package.json: ${fraimPkg.dependencies?.chalk || 'N/A'}\n`);
+        }
+        // 7. Try to load fraim CLI
+        console.log('🚀 Testing fraim CLI load...\n');
+        const testScript = `
+try {
+    const fraimCli = require('./node_modules/fraim-framework/dist/src/cli/fraim.js');
+    console.log('✅ SUCCESS: fraim CLI loaded');
+} catch (error) {
+    console.log('❌ ERROR:', error.code || 'Unknown');
+    console.log('Message:', error.message.substring(0, 200));
+}
+`;
+        fs_1.default.writeFileSync(path_1.default.join(tempDir, 'test.js'), testScript);
+        try {
+            const testOutput = (0, node_child_process_1.execSync)('node test.js', {
+                cwd: tempDir,
+                encoding: 'utf-8'
+            });
+            console.log(testOutput);
+        }
+        catch (error) {
+            console.log(error.stdout || error.message);
+        }
+        // Cleanup
+        fs_1.default.unlinkSync(tarballPath);
+        console.log('\n✅ Diagnostic complete');
+    }
+    catch (error) {
+        console.error('\n❌ Diagnostic failed:', error);
+    }
+    finally {
+        try {
+            fs_1.default.rmSync(tempDir, { recursive: true, force: true });
+        }
+        catch (e) {
+            console.log('\n⚠️  Could not clean up temp directory');
+        }
+    }
+}
+main();

package/dist/tests/test-session-rehydration.js

@@ -0,0 +1,145 @@
+"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 testRehydrationAndExemptions() {
+    console.log('   🚀 Testing Session Re-hydration and Initialization Exemptions...');
+    let fraimProcess;
+    let dbService;
+    const PORT = Math.floor(Math.random() * 1000) + 12000;
+    const TEST_API_KEY = 'test-rehydration-key';
+    const TEST_ADMIN_KEY = 'test-admin-key';
+    const BASE_URL = `http://localhost:${PORT}`;
+    const startServer = async () => {
+        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');
+        const proc = (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'
+            },
+            stdio: 'inherit',
+            shell: true
+        });
+        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');
+        return proc;
+    };
+    const stopServer = async (proc) => {
+        if (proc && proc.pid) {
+            await new Promise(resolve => (0, tree_kill_1.default)(proc.pid, 'SIGKILL', () => resolve()));
+        }
+    };
+    try {
+        // 1. Setup DB and Key
+        dbService = new db_service_js_1.FraimDbService();
+        await dbService.connect();
+        const db = dbService.db;
+        await db.collection('fraim_api_keys').deleteOne({ key: TEST_API_KEY });
+        await db.collection('fraim_telemetry_sessions').deleteMany({ userId: 'test-user-recalc' });
+        await db.collection('fraim_api_keys').insertOne({
+            key: TEST_API_KEY,
+            userId: 'test-user-recalc',
+            orgId: 'test-org',
+            isActive: true,
+            createdAt: new Date()
+        });
+        // 2. Start Server (Instance 1)
+        fraimProcess = await startServer();
+        // 3. Verify Initialization Exemptions
+        console.log('   Testing standard MCP exemptions (initialize, tools/list)...');
+        const initRes = await axios_1.default.post(`${BASE_URL}/mcp`, {
+            jsonrpc: '2.0', id: 1, method: 'initialize', params: {}
+        }, { headers: { 'x-api-key': TEST_API_KEY } });
+        node_assert_1.default.strictEqual(initRes.status, 200, 'initialize should be exempt');
+        const listRes = await axios_1.default.post(`${BASE_URL}/mcp`, {
+            jsonrpc: '2.0', id: 2, method: 'tools/list', params: {}
+        }, { headers: { 'x-api-key': TEST_API_KEY } });
+        node_assert_1.default.strictEqual(listRes.status, 200, 'tools/list should be exempt');
+        console.log('   Testing discovery tools exemptions (get_fraim_init)...');
+        const discoveryRes = await axios_1.default.post(`${BASE_URL}/mcp`, {
+            jsonrpc: '2.0', id: 3, method: 'tools/call',
+            params: { name: 'get_fraim_init', arguments: {} }
+        }, { headers: { 'x-api-key': TEST_API_KEY } });
+        node_assert_1.default.strictEqual(discoveryRes.status, 200, 'get_fraim_init should be exempt');
+        console.log('   ✅ Exemptions verified.');
+        // 4. Start Session
+        console.log('   Starting session...');
+        await axios_1.default.post(`${BASE_URL}/mcp`, {
+            jsonrpc: '2.0', id: 4, method: 'tools/call',
+            params: {
+                name: 'fraim_connect',
+                arguments: {
+                    machine: { hostname: 'repro-host' },
+                    repo: { url: 'http://github.com/repro' }
+                }
+            }
+        }, { headers: { 'x-api-key': TEST_API_KEY } });
+        // 5. Restart Server (Instance 2)
+        console.log('   ♻️ Swapping server instances (Simulating restart)...');
+        await stopServer(fraimProcess);
+        fraimProcess = await startServer();
+        // 6. Verify Re-hydration
+        console.log('   Checking if session re-hydrated from DB...');
+        const secureRes = await axios_1.default.post(`${BASE_URL}/mcp`, {
+            jsonrpc: '2.0', id: 5, method: 'tools/call',
+            params: { name: 'get_fraim_workflow', arguments: { workflow: 'test' } }
+        }, { headers: { 'x-api-key': TEST_API_KEY } });
+        node_assert_1.default.strictEqual(secureRes.status, 200, 'Request should be authorized via re-hydrated session');
+        console.log('   ✅ Re-hydration successful!');
+        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-recalc' }).catch(() => { });
+            await dbService.close();
+        }
+        if (fraimProcess)
+            await stopServer(fraimProcess);
+    }
+}
+const testCases = [
+    {
+        name: 'MCP Session Re-hydration and Initialization',
+        description: 'Verifies re-hydration from DB after restart and initialization exemptions',
+        testFunction: testRehydrationAndExemptions,
+        tags: ['session', 'rehydration']
+    }
+];
+(0, test_utils_1.runTests)(testCases, async (t) => t.testFunction(), 'Fraim Session System')
+    .then(() => process.exit(0))
+    .catch((err) => {
+    console.error('Test runner failed:', err);
+    process.exit(1);
+});

package/dist/tests/test-standalone.js

@@ -98,13 +98,7 @@ async function testServerStartsAndResponds() {
         });
         node_assert_1.default.strictEqual(mcpResponse.status, 200);
         node_assert_1.default.ok(mcpResponse.data.result.tools.length > 0);
-        // 7. Verify usage logging
-        console.log('   Verifying usage logging...');
-        await new Promise(resolve => setTimeout(resolve, 1500));
-        const log = await db.collection('fraim_usage_logs').findOne({ keyId: TEST_API_KEY });
-        node_assert_1.default.ok(log, 'Usage log should have been created');
-        node_assert_1.default.strictEqual(log.userId, 'test-user@ashley.ai');
-        // 8. Test Admin API - List Keys
+        // 7. Test Admin API - List Keys
         console.log('   Testing Admin API - List Keys...');
         const listKeysRes = await axios_1.default.get(`${BASE_URL}/admin/keys`, {
             headers: TEST_ADMIN_HEADER,
@@ -141,7 +135,7 @@ async function runFraimTest(testCase) {
 const testCases = [
     {
         name: 'Fraim Standalone Server Integration',
-        description: 'Tests server startup, public health check, authenticated MCP access, usage logging, and admin API',
+        description: 'Tests server startup, public health check, authenticated MCP access, and admin API',
         testFunction: testServerStartsAndResponds,
         tags: ['smoke', 'fraim']
     }

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);
+});