fraim-framework 2.0.162 → 2.0.164

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

@@ -3,6 +3,7 @@
  * MCP connectivity checks for FRAIM doctor command
  * Tests FRAIM server connectivity and validates IDE MCP configurations
  * Issue #144: Enhanced doctor command
+ * Issue #532: Stdio MCP runtime connectivity check
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -43,6 +44,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getNpmMajorVersion = getNpmMajorVersion;
 exports.diagnoseFraimMcpLaunchPlan = diagnoseFraimMcpLaunchPlan;
+exports.spawnAndHandshake = spawnAndHandshake;
+exports.getStdioMCPRuntimeChecks = getStdioMCPRuntimeChecks;
 exports.getMCPConnectivityChecks = getMCPConnectivityChecks;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -52,7 +55,16 @@ const axios_1 = __importDefault(require("axios"));
 const toml = __importStar(require("toml"));
 const ide_detector_1 = require("../../setup/ide-detector");
 const fraim_mcp_latest_launcher_1 = require("../../mcp/fraim-mcp-latest-launcher");
+const command_resolution_1 = require("../../mcp/command-resolution");
+// 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.
+// With 8+ IDE checks running via Promise.all the blocking stacks sequentially.
+let _npmMajorVersionCache = undefined;
 function getNpmMajorVersion() {
+    if (_npmMajorVersionCache !== undefined) {
+        return _npmMajorVersionCache;
+    }
     try {
         const command = process.platform === 'win32' ? (process.env.ComSpec || 'cmd.exe') : 'npm';
         const args = process.platform === 'win32' ? ['/d', '/s', '/c', 'npm --version'] : ['--version'];
@@ -61,11 +73,12 @@ function getNpmMajorVersion() {
             stdio: ['ignore', 'pipe', 'ignore']
         });
         const major = Number.parseInt(output.trim().split('.')[0], 10);
-        return Number.isFinite(major) ? major : null;
+        _npmMajorVersionCache = Number.isFinite(major) ? major : null;
     }
     catch {
-        return null;
+        _npmMajorVersionCache = null;
     }
+    return _npmMajorVersionCache;
 }
 function diagnoseFraimMcpLaunchPlan(fraimServer, platform = process.platform, npmMajorVersion = getNpmMajorVersion()) {
     const command = String(fraimServer?.command || '');
@@ -419,6 +432,248 @@ async function validateIDEMCPConfig(ide) {
         };
     }
 }
+// ============================================================
+// Issue #532: Stdio MCP Runtime Connectivity Check
+// ============================================================
+const STDIO_HANDSHAKE_TIMEOUT_MS = 15000;
+/**
+ * Spawn a stdio MCP server, perform a two-phase JSON-RPC handshake
+ * (initialize then tools/list), and return a structured result.
+ *
+ * On Windows, wraps the command in cmd.exe /d /s /c so that .cmd wrappers
+ * resolve correctly. The same pattern is used by resolveManagedCommand and
+ * fraim-mcp-latest-launcher.
+ */
+async function spawnAndHandshake(command, args, timeoutMs = STDIO_HANDSHAKE_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        const startTime = Date.now();
+        let spawnCommand;
+        let spawnArgs;
+        // spawnOptions is typed loosely so we can set windowsVerbatimArguments below.
+        let spawnOptions = {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: process.env
+        };
+        if (process.platform === 'win32') {
+            // On Windows, wrap in cmd.exe so .cmd wrappers are resolved.
+            // cmd.exe /d /s /c requires special handling when the command path contains spaces:
+            //   cmd /c ""path with spaces" arg1 arg2"
+            // The outer pair of double-quotes is mandatory when the first token is quoted.
+            // We must also pass windowsVerbatimArguments: true so Node's CreateProcess call
+            // does not re-escape our already-quoted command string.
+            const comSpec = process.env.ComSpec || 'cmd.exe';
+            const quotedTokens = [command, ...args].map((a) => {
+                const v = String(a);
+                return /[\s"&|<>^]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
+            });
+            const innerCmd = quotedTokens.join(' ');
+            // Wrap in outer quotes only when the command contains spaces (i.e. was itself quoted).
+            const needsOuterQuote = /[\s"&|<>^]/.test(String(command));
+            const cmdString = needsOuterQuote ? `"${innerCmd}"` : innerCmd;
+            spawnCommand = comSpec;
+            spawnArgs = ['/d', '/s', '/c', cmdString];
+            spawnOptions = { ...spawnOptions, windowsVerbatimArguments: true };
+        }
+        else {
+            spawnCommand = command;
+            spawnArgs = args;
+        }
+        let child;
+        try {
+            child = (0, child_process_1.spawn)(spawnCommand, spawnArgs, spawnOptions);
+        }
+        catch (spawnErr) {
+            resolve({
+                status: 'error',
+                phase: 'spawn',
+                message: `Failed to spawn MCP server: ${spawnErr.message}`,
+                suggestion: 'Verify that npx is installed and accessible on PATH.',
+                details: { command, args, error: spawnErr.message }
+            });
+            return;
+        }
+        const timer = setTimeout(() => {
+            try {
+                child.kill('SIGKILL');
+            }
+            catch { /* best effort */ }
+            resolve({
+                status: 'error',
+                phase: 'initialize',
+                message: `MCP server did not respond within ${timeoutMs}ms`,
+                suggestion: 'The server may be slow to start. Check that the package is installed and npx cache is warm.',
+                details: { command, args, timeoutMs, elapsed: Date.now() - startTime }
+            });
+        }, timeoutMs);
+        let stderrBuffer = '';
+        let stdoutBuffer = '';
+        let spawnError = null;
+        child.stderr?.on('data', (d) => {
+            stderrBuffer += d.toString();
+        });
+        child.on('error', (err) => {
+            spawnError = err;
+        });
+        child.stdout?.on('data', (d) => {
+            stdoutBuffer += d.toString();
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (spawnError) {
+                const msg = spawnError.message || '';
+                const isEnoent = msg.includes('ENOENT') || msg.includes('not found');
+                resolve({
+                    status: 'error',
+                    phase: 'spawn',
+                    message: `Failed to start MCP server: ${msg}`,
+                    suggestion: isEnoent
+                        ? 'Verify that npx is installed. Run: npm install -g npm to update npm/npx.'
+                        : 'Check that the required package can be installed via npx.',
+                    details: { command, args, error: msg }
+                });
+                return;
+            }
+            if (code !== 0 && stdoutBuffer.trim() === '') {
+                resolve({
+                    status: 'error',
+                    phase: 'spawn',
+                    message: `MCP server exited with code ${code} before responding`,
+                    suggestion: 'Run: npx -y <package> manually to check for installation errors.',
+                    details: { command, args, exitCode: code, stderr: stderrBuffer.slice(0, 500) }
+                });
+                return;
+            }
+            // Parse all JSON-RPC messages received from stdout
+            const lines = stdoutBuffer.split('\n').map((l) => l.trim()).filter(Boolean);
+            let initializeResponse = null;
+            let toolsListResponse = null;
+            for (const line of lines) {
+                try {
+                    const msg = JSON.parse(line);
+                    if (msg?.id === 1 && msg?.result !== undefined) {
+                        initializeResponse = msg;
+                    }
+                    if (msg?.id === 2 && msg?.result !== undefined) {
+                        toolsListResponse = msg;
+                    }
+                }
+                catch {
+                    // Ignore non-JSON lines (e.g., startup log output)
+                }
+            }
+            if (!initializeResponse) {
+                resolve({
+                    status: 'error',
+                    phase: 'initialize',
+                    message: 'MCP server did not return a valid initialize response',
+                    suggestion: 'The server may have crashed during startup. Check stderr for error details.',
+                    details: { command, args, exitCode: code, stderr: stderrBuffer.slice(0, 500) }
+                });
+                return;
+            }
+            if (!toolsListResponse) {
+                resolve({
+                    status: 'error',
+                    phase: 'tools-list',
+                    message: 'MCP server did not respond to tools/list',
+                    suggestion: 'The server initialized but did not expose any tools. Check the package documentation.',
+                    details: { command, args, exitCode: code }
+                });
+                return;
+            }
+            const toolCount = Array.isArray(toolsListResponse.result?.tools)
+                ? toolsListResponse.result.tools.length
+                : 0;
+            const elapsed = Date.now() - startTime;
+            resolve({
+                status: 'passed',
+                message: `MCP server responded with ${toolCount} tool(s) in ${elapsed}ms`,
+                details: { command, args, toolCount, elapsed }
+            });
+        });
+        // Send two-phase JSON-RPC handshake
+        try {
+            const initMsg = JSON.stringify({
+                jsonrpc: '2.0',
+                id: 1,
+                method: 'initialize',
+                params: {
+                    protocolVersion: '2024-11-05',
+                    capabilities: {},
+                    clientInfo: { name: 'fraim-doctor', version: '1.0' }
+                }
+            }) + '\n';
+            child.stdin?.write(initMsg);
+            const toolsMsg = JSON.stringify({
+                jsonrpc: '2.0',
+                id: 2,
+                method: 'tools/list',
+                params: {}
+            }) + '\n';
+            child.stdin?.write(toolsMsg);
+            child.stdin?.end();
+        }
+        catch {
+            // stdin may not be writable if the process exited immediately
+        }
+    });
+}
+/**
+ * Run a connectivity check for a single named stdio MCP server.
+ */
+async function testStdioMCPServer(serverName, command, args) {
+    if (process.env.NODE_ENV === 'test') {
+        return {
+            status: 'warning',
+            message: `Stdio MCP runtime check for "${serverName}" skipped (test mode)`,
+            details: { testMode: true, skipped: true, serverName }
+        };
+    }
+    const result = await spawnAndHandshake(command, args, STDIO_HANDSHAKE_TIMEOUT_MS);
+    if (result.status === 'passed') {
+        return {
+            status: 'passed',
+            message: `${serverName} stdio MCP: ${result.message}`,
+            details: result.details
+        };
+    }
+    return {
+        status: 'error',
+        message: `${serverName} stdio MCP connectivity failed (phase: ${result.phase}): ${result.message}`,
+        suggestion: result.suggestion,
+        details: { ...result.details, phase: result.phase }
+    };
+}
+/**
+ * Build the 3 stdio MCP runtime checks (git, playwright, fraim).
+ * Exported separately so callers can obtain just the runtime checks if needed.
+ */
+function getStdioMCPRuntimeChecks() {
+    const npx = (0, command_resolution_1.resolveManagedCommand)('npx');
+    // For the fraim MCP server we use the latest launcher so the test
+    // exercises the same path that IDE configs use.
+    const fraimLauncherPath = (0, fraim_mcp_latest_launcher_1.getFraimMcpLatestLauncherPath)();
+    return [
+        {
+            name: 'git stdio runtime check',
+            category: 'mcpConnectivity',
+            critical: false,
+            run: () => testStdioMCPServer('git', npx, ['-y', '@cyanheads/git-mcp-server'])
+        },
+        {
+            name: 'playwright stdio runtime check',
+            category: 'mcpConnectivity',
+            critical: false,
+            run: () => testStdioMCPServer('playwright', npx, ['-y', '@playwright/mcp'])
+        },
+        {
+            name: 'fraim stdio runtime check',
+            category: 'mcpConnectivity',
+            critical: false,
+            run: () => testStdioMCPServer('fraim', process.execPath, [fraimLauncherPath])
+        }
+    ];
+}
 /**
  * Get all MCP connectivity checks
  */
@@ -441,5 +696,9 @@ function getMCPConnectivityChecks() {
             run: async () => validateIDEMCPConfig(ide)
         });
     }
+    // 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());
     return checks;
 }

package/dist/src/cli/utils/git-org-sync.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchOrgRepoSnapshot = fetchOrgRepoSnapshot;
+/**
+ * Shallow snapshot of a customer-owned org repo (issue #563, git backend).
+ *
+ * Uses execSync git like the rest of the CLI (see core/utils/git-utils.ts);
+ * no new git dependency. The snapshot is a depth-1 clone of the default
+ * branch into a temp directory the caller copies from and then cleans up.
+ */
+const child_process_1 = require("child_process");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Org repo URLs are restricted to real transport schemes plus scp-style
+ * SSH shorthand. This blocks git's command-executing transports
+ * (`ext::`, `fd::`) and option injection via URLs starting with `-`.
+ */
+const ALLOWED_GIT_URL = /^(https?:\/\/|ssh:\/\/|git:\/\/|file:\/\/|[\w.-]+@[\w.-]+:)/;
+/**
+ * Shallow-clone the org repo's default branch (R7.4). Throws on any git
+ * failure; callers translate failures into stale/absent outcomes.
+ */
+function fetchOrgRepoSnapshot(gitUrl) {
+    if (!ALLOWED_GIT_URL.test(gitUrl)) {
+        throw new Error(`Org repo URL has an unsupported scheme: ${gitUrl}`);
+    }
+    const dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'fraim-org-snap-'));
+    try {
+        // Arg-array exec (no shell) and `--` so the URL can never be parsed
+        // as a git option or shell metacharacters.
+        (0, child_process_1.execFileSync)('git', ['clone', '--depth=1', '--quiet', '--', gitUrl, '.'], {
+            cwd: dir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 60_000
+        });
+        const sha = (0, child_process_1.execFileSync)('git', ['rev-parse', 'HEAD'], {
+            cwd: dir,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe']
+        }).trim();
+        return {
+            dir,
+            sha,
+            cleanup: () => fs_1.default.rmSync(dir, { recursive: true, force: true })
+        };
+    }
+    catch (error) {
+        fs_1.default.rmSync(dir, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/src/cli/utils/org-migration.js

@@ -0,0 +1,50 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectLegacyOrgArtifacts = detectLegacyOrgArtifacts;
+exports.archiveLegacyOrgArtifacts = archiveLegacyOrgArtifacts;
+/**
+ * Legacy org artifact migration (issue #563, R8).
+ *
+ * Before #563, organization-onboarding wrote org_context.md and org_rules.md
+ * machine-locally under ~/.fraim/personalized-employee/. These helpers detect
+ * those files for a one-time publish offer and archive them (never delete)
+ * once the user accepts. Declining is safe: detection is read-only and the
+ * legacy resolution tier keeps working (AC8).
+ *
+ * Manager files are personal by design and are never migrated (R3.3).
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
+const LEGACY_ORG_RELATIVE_PATHS = [
+    'context/org_context.md',
+    'rules/org_rules.md'
+];
+function detectLegacyOrgArtifacts() {
+    const root = path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'personalized-employee');
+    const detected = [];
+    for (const relativePath of LEGACY_ORG_RELATIVE_PATHS) {
+        const absolutePath = path_1.default.join(root, relativePath);
+        if (fs_1.default.existsSync(absolutePath)) {
+            detected.push({ absolutePath, relativePath });
+        }
+    }
+    return detected;
+}
+/**
+ * Move legacy org artifacts into a timestamped directory under
+ * ~/.fraim/backups/ (R8.1). Returns the backup directory path.
+ */
+function archiveLegacyOrgArtifacts(artifacts) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupDir = path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'backups', `org-migration-${stamp}`);
+    for (const artifact of artifacts) {
+        const destination = path_1.default.join(backupDir, artifact.relativePath);
+        fs_1.default.mkdirSync(path_1.default.dirname(destination), { recursive: true });
+        fs_1.default.renameSync(artifact.absolutePath, destination);
+    }
+    return backupDir;
+}

package/dist/src/cli/utils/org-pack-sync.js

@@ -0,0 +1,208 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORG_CACHE_MANAGED_HEADER = exports.ORG_SYNC_METADATA_FILE = exports.ORG_CACHE_DIRNAME = void 0;
+exports.getOrgCacheDir = getOrgCacheDir;
+exports.readOrgCacheMetadata = readOrgCacheMetadata;
+exports.getOrgCacheAgeHours = getOrgCacheAgeHours;
+exports.syncOrgCache = syncOrgCache;
+/**
+ * Org cache sync (issue #563).
+ *
+ * Materializes the organization's shared context/rules/learnings into the
+ * managed read-only cache at ~/.fraim/org/, from either backend:
+ *   - git: shallow snapshot of the customer-owned org repo (R7)
+ *   - fraim-cloud: GET /api/org/pack from the FRAIM server (R6)
+ *
+ * Cache files are managed content: marked, overwritten on every sync, and
+ * never a write target for agents (R2.2). A failed refresh never throws:
+ * an existing cache is served stale with its age (R2.3, R4.3).
+ */
+const axios_1 = __importDefault(require("axios"));
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
+const user_config_1 = require("./user-config");
+const git_org_sync_1 = require("./git-org-sync");
+exports.ORG_CACHE_DIRNAME = 'org';
+exports.ORG_SYNC_METADATA_FILE = '.org-sync-metadata.json';
+exports.ORG_CACHE_MANAGED_HEADER = '<!-- FRAIM_ORG_SYNC_MANAGED_CONTENT -->';
+/** Subdirectories of the org pack that sync into the cache (spec R7.1). */
+const ORG_PACK_DIRS = ['context', 'rules', 'learnings'];
+/**
+ * Pack files must stay inside the three org pack directories. Applied to
+ * every relativePath before it touches the filesystem, so a compromised
+ * backend response can never write outside the cache directory.
+ */
+const SAFE_PACK_RELATIVE_PATH = /^(context|rules|learnings)\/[\w.-]+\.md$/;
+function getOrgCacheDir() {
+    return path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), exports.ORG_CACHE_DIRNAME);
+}
+function readOrgCacheMetadata() {
+    try {
+        const metadataPath = path_1.default.join(getOrgCacheDir(), exports.ORG_SYNC_METADATA_FILE);
+        if (!fs_1.default.existsSync(metadataPath))
+            return null;
+        return JSON.parse(fs_1.default.readFileSync(metadataPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function getOrgCacheAgeHours() {
+    const metadata = readOrgCacheMetadata();
+    if (!metadata?.syncedAt)
+        return null;
+    const syncedAt = Date.parse(metadata.syncedAt);
+    if (Number.isNaN(syncedAt))
+        return null;
+    return Math.max(0, (Date.now() - syncedAt) / 3_600_000);
+}
+function decorateManagedOrgFile(content, backend) {
+    const normalized = content.replace(/^/, '');
+    if (normalized.startsWith(exports.ORG_CACHE_MANAGED_HEADER))
+        return normalized;
+    const writePath = backend === 'git'
+        ? 'open a pull request against your organization repo'
+        : 'update it through the organization-onboarding flow';
+    const marker = [
+        exports.ORG_CACHE_MANAGED_HEADER,
+        '> [!IMPORTANT]',
+        '> Synced from your organization\'s shared context. Local edits are overwritten on the next sync.',
+        `> To change this content, ${writePath}.`,
+        ''
+    ].join('\n');
+    return `${marker}\n${normalized}`;
+}
+function collectGitPackFiles(snapshotDir) {
+    const files = [];
+    for (const dirName of ORG_PACK_DIRS) {
+        const dirPath = path_1.default.join(snapshotDir, dirName);
+        if (!fs_1.default.existsSync(dirPath))
+            continue;
+        for (const entry of fs_1.default.readdirSync(dirPath, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith('.md'))
+                continue;
+            files.push({
+                relativePath: `${dirName}/${entry.name}`,
+                content: fs_1.default.readFileSync(path_1.default.join(dirPath, entry.name), 'utf8')
+            });
+        }
+    }
+    return files;
+}
+async function fetchCloudPack(remoteUrl, apiKey) {
+    const response = await axios_1.default.get(`${remoteUrl.replace(/\/$/, '')}/api/org/pack`, {
+        headers: { 'x-api-key': apiKey },
+        timeout: 30_000
+    });
+    const files = Array.isArray(response.data?.files) ? response.data.files : [];
+    return {
+        files: files.filter((f) => typeof f?.relativePath === 'string' &&
+            SAFE_PACK_RELATIVE_PATH.test(f.relativePath) &&
+            typeof f?.content === 'string'),
+        version: String(response.data?.version ?? '0')
+    };
+}
+/** Replace the cache contents atomically: stage fully, then swap. */
+function materializeCache(files, metadata) {
+    const cacheDir = getOrgCacheDir();
+    const stagingDir = `${cacheDir}.staging-${process.pid}`;
+    fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
+    fs_1.default.mkdirSync(stagingDir, { recursive: true });
+    for (const file of files) {
+        if (!SAFE_PACK_RELATIVE_PATH.test(file.relativePath))
+            continue;
+        const destination = path_1.default.join(stagingDir, file.relativePath);
+        fs_1.default.mkdirSync(path_1.default.dirname(destination), { recursive: true });
+        fs_1.default.writeFileSync(destination, decorateManagedOrgFile(file.content, metadata.backend));
+    }
+    fs_1.default.writeFileSync(path_1.default.join(stagingDir, exports.ORG_SYNC_METADATA_FILE), JSON.stringify(metadata, null, 2));
+    fs_1.default.rmSync(cacheDir, { recursive: true, force: true });
+    fs_1.default.renameSync(stagingDir, cacheDir);
+}
+/**
+ * New-machine onboarding (R1.3, AC1): when this machine has an API key but no
+ * organization block yet, probe the FRAIM server. If the account owns org
+ * artifacts, persist the fraim-cloud organization block so `fraim setup` +
+ * `fraim sync` is the complete second-machine flow. Quietly resolves null on
+ * any failure or when the account has no org.
+ */
+async function discoverCloudOrganization(options) {
+    try {
+        const apiKey = options?.apiKey || (0, user_config_1.readUserFraimConfig)().apiKey;
+        if (!apiKey || apiKey === 'local-dev' || apiKey === 'test-mode-key')
+            return null;
+        const remoteUrl = options?.remoteUrl || process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
+        const pack = await fetchCloudPack(remoteUrl, apiKey);
+        if (pack.files.length === 0)
+            return null;
+        (0, user_config_1.writeUserFraimConfig)({ organization: { backend: 'fraim-cloud' } });
+        return (0, user_config_1.getOrganizationConfig)();
+    }
+    catch {
+        return null;
+    }
+}
+function failureOutcome(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const existing = readOrgCacheMetadata();
+    if (existing) {
+        return {
+            status: 'stale',
+            metadata: existing,
+            ageHours: getOrgCacheAgeHours() ?? 0,
+            error: message
+        };
+    }
+    return { status: 'absent', error: message };
+}
+/**
+ * Refresh the org cache from the configured backend (R4.1). Never throws:
+ * returns 'disabled' (no org configured), 'synced', 'stale' (refresh failed,
+ * existing cache served with age), or 'absent' (refresh failed, no cache).
+ */
+async function syncOrgCache(options) {
+    let organization = (0, user_config_1.getOrganizationConfig)();
+    if (!organization) {
+        organization = await discoverCloudOrganization(options);
+        if (!organization)
+            return { status: 'disabled' };
+    }
+    try {
+        if (organization.backend === 'git') {
+            const snapshot = (0, git_org_sync_1.fetchOrgRepoSnapshot)(organization.gitUrl);
+            try {
+                const metadata = {
+                    version: snapshot.sha,
+                    backend: 'git',
+                    source: organization.gitUrl,
+                    syncedAt: new Date().toISOString()
+                };
+                materializeCache(collectGitPackFiles(snapshot.dir), metadata);
+                return { status: 'synced', metadata };
+            }
+            finally {
+                snapshot.cleanup();
+            }
+        }
+        const remoteUrl = options?.remoteUrl || process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
+        const apiKey = options?.apiKey || (0, user_config_1.readUserFraimConfig)().apiKey;
+        if (!apiKey)
+            throw new Error('No FRAIM API key available for the fraim-cloud org backend.');
+        const pack = await fetchCloudPack(remoteUrl, apiKey);
+        const metadata = {
+            version: pack.version,
+            backend: 'fraim-cloud',
+            source: remoteUrl,
+            syncedAt: new Date().toISOString()
+        };
+        materializeCache(pack.files, metadata);
+        return { status: 'synced', metadata };
+    }
+    catch (error) {
+        return failureOutcome(error);
+    }
+}