fraim 2.0.333 → 2.0.337

package/dist/src/cli/commands/doctor.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.doctorCommand = void 0;
 exports.getAllChecks = getAllChecks;
 exports.runFixMcpRepair = runFixMcpRepair;
+exports.runRepairMcpCache = runRepairMcpCache;
 const commander_1 = require("commander");
 const fs_1 = require("fs");
 const path_1 = require("path");
@@ -17,6 +18,8 @@ const mcp_connectivity_checks_1 = require("../doctor/checks/mcp-connectivity-che
 const scripts_checks_1 = require("../doctor/checks/scripts-checks");
 const agent_cli_health_checks_1 = require("../doctor/checks/agent-cli-health-checks");
 const llm_auth_route_checks_1 = require("../doctor/checks/llm-auth-route-checks");
+const fraim_mcp_cache_repair_1 = require("../doctor/checks/fraim-mcp-cache-repair");
+const fraim_mcp_latest_launcher_1 = require("../mcp/fraim-mcp-latest-launcher");
 const add_ide_1 = require("./add-ide");
 // Read version from package.json
 const getFramVersion = () => {
@@ -85,18 +88,34 @@ async function runFixMcpRepair(options, repair = add_ide_1.runAddIDE) {
         console.log = originalLog;
     }
 }
+async function runRepairMcpCache(options, dependencies = {}) {
+    if (!options.repairMcpCache) {
+        return;
+    }
+    const ensureShims = dependencies.ensureShims ?? fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher;
+    const repairCache = dependencies.repairCache ?? fraim_mcp_cache_repair_1.repairFraimMcpPackageCache;
+    const warmPackage = dependencies.warmPackage ?? fraim_mcp_cache_repair_1.warmFraimPackage;
+    ensureShims();
+    const result = repairCache({});
+    if (!options.json) {
+        console.log(`FRAIM MCP package cache repair removed ${result.removedBrokenNpxEntries.length} broken _npx entr${result.removedBrokenNpxEntries.length === 1 ? 'y' : 'ies'} and ${result.removedStaleRetryCaches.length} stale retry cache${result.removedStaleRetryCaches.length === 1 ? '' : 's'}.`);
+    }
+    await warmPackage(FRAIM_VERSION === 'unknown' ? 'latest' : FRAIM_VERSION);
+}
 exports.doctorCommand = new commander_1.Command('doctor')
     .description('Validate FRAIM installation and configuration')
     .option('--test-mcp', 'Test only MCP server connectivity')
     .option('--test-config', 'Validate only configuration files')
     .option('--test-jobs', 'Check only job status')
     .option('--fix-mcp', 'Repair FRAIM-owned MCP server entries in detected IDE configs, then validate MCP connectivity')
+    .option('--repair-mcp-cache', 'Repair corrupted FRAIM MCP package cache entries, then validate MCP connectivity')
     .option('--verbose', 'Show detailed output including successful checks')
     .option('--json', 'Output results as JSON')
     .action(async (cmdOptions) => {
     const startTime = Date.now();
     const options = {
-        testMcp: cmdOptions.testMcp || cmdOptions.fixMcp,
+        testMcp: cmdOptions.testMcp || cmdOptions.fixMcp || cmdOptions.repairMcpCache,
+        repairMcpCache: cmdOptions.repairMcpCache,
         testConfig: cmdOptions.testConfig,
         testJobs: cmdOptions.testJobs,
         fixMcp: cmdOptions.fixMcp,
@@ -110,6 +129,7 @@ exports.doctorCommand = new commander_1.Command('doctor')
             testConfig: options.testConfig || false,
             testJobs: options.testJobs || false,
             fixMcp: options.fixMcp || false,
+            repairMcpCache: options.repairMcpCache || false,
             verbose: options.verbose || false,
             json: options.json || false
         }
@@ -125,12 +145,15 @@ exports.doctorCommand = new commander_1.Command('doctor')
         trackMetric('doctor.flags.test_jobs', 1);
     if (options.fixMcp)
         trackMetric('doctor.flags.fix_mcp', 1);
+    if (options.repairMcpCache)
+        trackMetric('doctor.flags.repair_mcp_cache', 1);
     if (options.verbose)
         trackMetric('doctor.flags.verbose', 1);
     if (options.json)
         trackMetric('doctor.flags.json', 1);
     try {
         await runFixMcpRepair(options);
+        await runRepairMcpCache(options);
         // Collect all checks
         const checks = getAllChecks();
         // Run checks

package/dist/src/cli/commands/sync.js

@@ -311,13 +311,11 @@ const runSync = async (options) => {
             if (ignoreUpdate.gitignoreUpdated) {
                 console.log(chalk_1.default.green('Removed legacy FRAIM sync block from .gitignore'));
             }
-            if (options.projectAdapters) {
-                const allowedTypes = resolveAllowedConfigTypes();
-                await cleanupStaleAdapterFiles(projectRoot, allowedTypes);
-                const adapterUpdates = (0, agent_adapters_1.ensureAgentAdapterFiles)(projectRoot, allowedTypes);
-                if (adapterUpdates.length > 0) {
-                    console.log(chalk_1.default.green(`Updated FRAIM agent adapter files: ${adapterUpdates.join(', ')}`));
-                }
+            const allowedLocalTypes = resolveAllowedConfigTypes();
+            await cleanupStaleAdapterFiles(projectRoot, allowedLocalTypes);
+            const localAdapterUpdates = (0, agent_adapters_1.ensureAgentAdapterFiles)(projectRoot, allowedLocalTypes);
+            if (localAdapterUpdates.length > 0) {
+                console.log(chalk_1.default.green(`Updated FRAIM agent adapter files: ${localAdapterUpdates.join(', ')}`));
             }
             await refreshOrgCache(localUrl, 'local-dev');
             await refreshManagerCache(localUrl, 'local-dev');
@@ -437,13 +435,11 @@ const runSync = async (options) => {
     if (ignoreUpdate.gitignoreUpdated) {
         console.log(chalk_1.default.green('Removed legacy FRAIM sync block from .gitignore'));
     }
-    if (options.projectAdapters) {
-        const allowedTypes = resolveAllowedConfigTypes();
-        await cleanupStaleAdapterFiles(projectRoot, allowedTypes);
-        const adapterUpdates = (0, agent_adapters_1.ensureAgentAdapterFiles)(projectRoot, allowedTypes);
-        if (adapterUpdates.length > 0) {
-            console.log(chalk_1.default.green(`Updated FRAIM agent adapter files: ${adapterUpdates.join(', ')}`));
-        }
+    const allowedTypes = resolveAllowedConfigTypes();
+    await cleanupStaleAdapterFiles(projectRoot, allowedTypes);
+    const adapterUpdates = (0, agent_adapters_1.ensureAgentAdapterFiles)(projectRoot, allowedTypes);
+    if (adapterUpdates.length > 0) {
+        console.log(chalk_1.default.green(`Updated FRAIM agent adapter files: ${adapterUpdates.join(', ')}`));
     }
     console.log(chalk_1.default.green('✅ Project-level sync complete.'));
 };

package/dist/src/cli/doctor/checks/fraim-mcp-cache-repair.js

@@ -0,0 +1,188 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RETRY_CACHE_AGE_FLOOR_MS = exports.CORRUPTED_NPX_PACKAGE_CACHE_CLASSIFICATION = exports.FRAIM_MCP_CACHE_REPAIR_DIAGNOSTIC_VERSION = void 0;
+exports.getFraimMcpCacheRoot = getFraimMcpCacheRoot;
+exports.inspectFraimMcpPackageCache = inspectFraimMcpPackageCache;
+exports.repairFraimMcpPackageCache = repairFraimMcpPackageCache;
+exports.buildFraimMcpCacheDiagnostic = buildFraimMcpCacheDiagnostic;
+exports.warmFraimPackage = warmFraimPackage;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const fraim_mcp_latest_launcher_1 = require("../../mcp/fraim-mcp-latest-launcher");
+exports.FRAIM_MCP_CACHE_REPAIR_DIAGNOSTIC_VERSION = 'fraim-mcp-cache-repair-v1';
+exports.CORRUPTED_NPX_PACKAGE_CACHE_CLASSIFICATION = 'corrupted-npx-package-cache';
+exports.DEFAULT_RETRY_CACHE_AGE_FLOOR_MS = 7 * 24 * 60 * 60 * 1000;
+const FRAIM_MCP_CACHE_REPAIR_COMMAND = 'npx --yes fraim@latest doctor --repair-mcp-cache';
+const VALID_VERSION_PATTERN = /^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/;
+function userDir() {
+    return process.env.FRAIM_USER_DIR || path_1.default.join(os_1.default.homedir(), '.fraim');
+}
+function getFraimMcpCacheRoot() {
+    return path_1.default.join(userDir(), 'npm-cache', 'mcp');
+}
+function versionFromCacheDir(versionCacheDir) {
+    const base = path_1.default.basename(versionCacheDir);
+    if (!base.startsWith('fraim-'))
+        return null;
+    const version = base.slice('fraim-'.length);
+    return VALID_VERSION_PATTERN.test(version) ? version : null;
+}
+function safeChild(parent, child) {
+    const parentResolved = path_1.default.resolve(parent);
+    const childResolved = path_1.default.resolve(child);
+    return childResolved === parentResolved || childResolved.startsWith(parentResolved + path_1.default.sep);
+}
+function directoryExists(dir) {
+    try {
+        return fs_1.default.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function findBrokenNpxEntries(versionCacheDir) {
+    const version = versionFromCacheDir(versionCacheDir);
+    if (!version)
+        return [];
+    const npxRoot = path_1.default.join(versionCacheDir, '_npx');
+    if (!directoryExists(npxRoot))
+        return [];
+    return fs_1.default.readdirSync(npxRoot, { withFileTypes: true })
+        .filter(entry => entry.isDirectory())
+        .map(entry => path_1.default.join(npxRoot, entry.name))
+        .filter(entryPath => safeChild(npxRoot, entryPath))
+        .filter(entryPath => (directoryExists(path_1.default.join(entryPath, 'node_modules')) &&
+        !fs_1.default.existsSync(path_1.default.join(entryPath, 'package.json'))))
+        .map(entryPath => ({ version, path: entryPath }));
+}
+function findStaleRetryCaches(cacheRoot, options = {}) {
+    if (!directoryExists(cacheRoot))
+        return [];
+    const nowMs = options.nowMs ?? Date.now();
+    const ageFloorMs = options.ageFloorMs ?? exports.DEFAULT_RETRY_CACHE_AGE_FLOOR_MS;
+    return fs_1.default.readdirSync(cacheRoot, { withFileTypes: true })
+        .filter(entry => entry.isDirectory() && /^retry-\d+-\d+$/.test(entry.name))
+        .map(entry => {
+        const entryPath = path_1.default.join(cacheRoot, entry.name);
+        const stat = fs_1.default.statSync(entryPath);
+        return { path: entryPath, mtimeMs: stat.mtimeMs, ageMs: nowMs - stat.mtimeMs };
+    })
+        .filter(entry => entry.ageMs >= ageFloorMs && safeChild(cacheRoot, entry.path));
+}
+function inspectFraimMcpPackageCache(options = {}) {
+    const cacheRoot = options.cacheRoot ?? getFraimMcpCacheRoot();
+    const brokenNpxEntries = [];
+    if (directoryExists(cacheRoot)) {
+        for (const entry of fs_1.default.readdirSync(cacheRoot, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const versionCacheDir = path_1.default.join(cacheRoot, entry.name);
+            brokenNpxEntries.push(...findBrokenNpxEntries(versionCacheDir));
+        }
+    }
+    const counts = new Map();
+    for (const entry of brokenNpxEntries) {
+        counts.set(entry.version, (counts.get(entry.version) ?? 0) + 1);
+    }
+    return {
+        cacheRoot,
+        brokenNpxEntries,
+        staleRetryCaches: findStaleRetryCaches(cacheRoot, {
+            nowMs: options.nowMs,
+            ageFloorMs: options.retryAgeFloorMs,
+        }),
+        affectedVersions: [...counts.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([version, brokenNpxEntryCount]) => ({ version, brokenNpxEntryCount })),
+    };
+}
+function repairFraimMcpPackageCache(options = {}) {
+    const inspection = inspectFraimMcpPackageCache(options);
+    const removedBrokenNpxEntries = [];
+    const removedStaleRetryCaches = [];
+    if (!options.dryRun) {
+        for (const entry of inspection.brokenNpxEntries) {
+            if (!safeChild(inspection.cacheRoot, entry.path))
+                continue;
+            fs_1.default.rmSync(entry.path, { recursive: true, force: true });
+            removedBrokenNpxEntries.push(entry);
+        }
+        for (const entry of inspection.staleRetryCaches) {
+            if (!safeChild(inspection.cacheRoot, entry.path))
+                continue;
+            fs_1.default.rmSync(entry.path, { recursive: true, force: true });
+            removedStaleRetryCaches.push(entry);
+        }
+    }
+    return {
+        ...inspection,
+        removedBrokenNpxEntries,
+        removedStaleRetryCaches,
+    };
+}
+function buildFraimMcpCacheDiagnostic(options = {}) {
+    const inspection = inspectFraimMcpPackageCache({
+        cacheRoot: options.cacheRoot,
+        nowMs: options.nowMs,
+    });
+    if (inspection.brokenNpxEntries.length === 0) {
+        return {
+            status: 'passed',
+            message: 'FRAIM MCP package cache has no corrupted _npx entries',
+            details: {
+                diagnosticVersion: exports.FRAIM_MCP_CACHE_REPAIR_DIAGNOSTIC_VERSION,
+                cacheRoot: inspection.cacheRoot,
+                affectedVersions: [],
+                staleRetryCacheCount: inspection.staleRetryCaches.length,
+            },
+        };
+    }
+    const status = options.mcpRuntimeStatus === 'error' ? 'error' : 'warning';
+    return {
+        status,
+        message: 'FRAIM MCP package cache is corrupted',
+        suggestion: `Run: ${FRAIM_MCP_CACHE_REPAIR_COMMAND}`,
+        details: {
+            diagnosticVersion: exports.FRAIM_MCP_CACHE_REPAIR_DIAGNOSTIC_VERSION,
+            classification: exports.CORRUPTED_NPX_PACKAGE_CACHE_CLASSIFICATION,
+            cacheRoot: inspection.cacheRoot,
+            affectedVersions: inspection.affectedVersions,
+            brokenNpxEntryCount: inspection.brokenNpxEntries.length,
+            staleRetryCacheCount: inspection.staleRetryCaches.length,
+            repairCommand: FRAIM_MCP_CACHE_REPAIR_COMMAND,
+        },
+    };
+}
+function readRecordedLauncherVersion() {
+    try {
+        const state = JSON.parse(fs_1.default.readFileSync((0, fraim_mcp_latest_launcher_1.getFraimMcpLauncherStatePath)(), 'utf8'));
+        const version = typeof state?.version === 'string' ? state.version : '';
+        return VALID_VERSION_PATTERN.test(version) ? version : null;
+    }
+    catch {
+        return null;
+    }
+}
+function versionCacheDirName(version) {
+    return `fraim-${version.replace(/[^a-zA-Z0-9._-]/g, '_')}`;
+}
+async function warmFraimPackage(versionFallback) {
+    const version = readRecordedLauncherVersion() || versionFallback;
+    const cacheDir = path_1.default.join(getFraimMcpCacheRoot(), versionCacheDirName(version));
+    const command = process.platform === 'win32' ? (process.env.ComSpec || 'cmd.exe') : 'npx';
+    const args = process.platform === 'win32'
+        ? ['/d', '/s', '/c', `npx --yes --package fraim@${version} fraim --version`]
+        : ['--yes', '--package', `fraim@${version}`, 'fraim', '--version'];
+    fs_1.default.mkdirSync(cacheDir, { recursive: true });
+    (0, child_process_1.execFileSync)(command, args, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        env: { ...process.env, npm_config_cache: cacheDir },
+        timeout: 120000,
+    });
+}

package/dist/src/cli/doctor/checks/mcp-connectivity-checks.js

@@ -59,6 +59,7 @@ const redact_secrets_1 = require("../../../core/utils/redact-secrets");
 const ide_detector_1 = require("../../setup/ide-detector");
 const fraim_mcp_latest_launcher_1 = require("../../mcp/fraim-mcp-latest-launcher");
 const fraim_mcp_diagnostics_1 = require("./fraim-mcp-diagnostics");
+const fraim_mcp_cache_repair_1 = require("./fraim-mcp-cache-repair");
 // Cache the npm major version so execFileSync is called at most once per process.
 // Without caching, each IDE config check calls diagnoseFraimMcpLaunchPlan which calls
 // getNpmMajorVersion, and execFileSync blocks the event loop for ~2s on Windows.
@@ -1001,8 +1002,18 @@ function getStdioMCPRuntimeChecks() {
 /**
  * Get all MCP connectivity checks
  */
-function getMCPConnectivityChecks() {
+function getMCPConnectivityChecks(dependencies = {}) {
     const checks = [];
+    const ensureLauncher = dependencies.ensureLauncher ?? fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher;
+    const runStdioServer = dependencies.testStdioServer ?? testStdioMCPServer;
+    ensureLauncher();
+    const npx = dependencies.npxPath ?? (0, fraim_mcp_latest_launcher_1.getFraimNpxShimPath)();
+    const fraimMcp = dependencies.fraimMcpPath ?? (0, fraim_mcp_latest_launcher_1.getFraimMcpShimPath)();
+    let fraimRuntimeCheck = null;
+    const runFraimRuntimeCheck = () => {
+        fraimRuntimeCheck ??= runStdioServer('fraim', fraimMcp, []);
+        return fraimRuntimeCheck;
+    };
     // Check 1: Test FRAIM server connectivity with actual API key
     checks.push({
         name: 'FRAIM server connectivity',
@@ -1016,6 +1027,14 @@ function getMCPConnectivityChecks() {
         critical: false,
         run: testFraimLocalProxyTroubleshooting
     });
+    checks.push({
+        name: 'FRAIM MCP package cache health',
+        category: 'mcpConnectivity',
+        critical: false,
+        run: async () => (0, fraim_mcp_cache_repair_1.buildFraimMcpCacheDiagnostic)({
+            mcpRuntimeStatus: (await runFraimRuntimeCheck()).status
+        })
+    });
     // Check 2: Validate each installed IDE's MCP config
     const installedIDEs = (0, ide_detector_1.detectInstalledIDEs)();
     for (const ide of installedIDEs) {
@@ -1029,6 +1048,23 @@ function getMCPConnectivityChecks() {
     // Check 3 (Issue #532): Confirm stdio MCP servers respond at runtime.
     // "Disconnected" in mcp list is expected on-demand-spawn behavior. These checks
     // verify that each server can actually start and complete a JSON-RPC handshake.
-    checks.push(...getStdioMCPRuntimeChecks());
+    checks.push({
+        name: 'git stdio runtime check',
+        category: 'mcpConnectivity',
+        critical: false,
+        run: () => runStdioServer('git', npx, ['-y', '@cyanheads/git-mcp-server'])
+    });
+    checks.push({
+        name: 'playwright stdio runtime check',
+        category: 'mcpConnectivity',
+        critical: false,
+        run: () => runStdioServer('playwright', npx, ['-y', '@playwright/mcp'])
+    });
+    checks.push({
+        name: 'fraim stdio runtime check',
+        category: 'mcpConnectivity',
+        critical: false,
+        run: runFraimRuntimeCheck
+    });
     return checks;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.333",
+  "version": "2.0.337",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {