fraim-framework 2.0.126 → 2.0.127

package/dist/src/first-run/session-service.js

@@ -0,0 +1,302 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FirstRunSessionService = void 0;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const child_process_1 = require("child_process");
+const ide_detector_1 = require("../cli/setup/ide-detector");
+const auto_mcp_setup_1 = require("../cli/setup/auto-mcp-setup");
+const setup_1 = require("../cli/commands/setup");
+const init_project_1 = require("../cli/commands/init-project");
+const script_sync_utils_1 = require("../cli/utils/script-sync-utils");
+const types_1 = require("./types");
+const install_state_1 = require("./install-state");
+function commandExists(command) {
+    const executable = process.platform === 'win32' ? 'cmd.exe' : command;
+    const args = process.platform === 'win32'
+        ? ['/d', '/s', '/c', `${command} --version`]
+        : ['--version'];
+    const result = (0, child_process_1.spawnSync)(executable, args, {
+        encoding: 'utf8',
+        stdio: ['ignore', 'ignore', 'ignore'],
+        shell: false,
+    });
+    return result.status === 0;
+}
+function ensureOutputDirs() {
+    fs_1.default.mkdirSync((0, script_sync_utils_1.getUserFraimDir)(), { recursive: true });
+    fs_1.default.mkdirSync(path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'last-install'), { recursive: true });
+}
+function getNextPromptPath() {
+    return path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'last-install', 'next-prompt.txt');
+}
+function getInstallLogPath() {
+    return path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'install-log.txt');
+}
+function appendInstallLog(line) {
+    ensureOutputDirs();
+    fs_1.default.appendFileSync(getInstallLogPath(), `[${new Date().toISOString()}] ${line}${os_1.default.EOL}`);
+}
+function getLaunchInstruction(agentId, projectRoot) {
+    const cwd = projectRoot || process.cwd();
+    switch (agentId) {
+        case 'claude-code':
+            return `cd "${cwd}" && claude`;
+        case 'codex':
+            return `cd "${cwd}" && codex`;
+        case 'gemini-cli':
+            return `cd "${cwd}" && gemini`;
+        default:
+            return `cd "${cwd}"`;
+    }
+}
+function maybeLaunchInteractiveShell(agentId, projectRoot) {
+    const commandLine = getLaunchInstruction(agentId, projectRoot);
+    try {
+        if (process.platform === 'win32') {
+            (0, child_process_1.spawn)('cmd.exe', ['/d', '/s', '/c', `start "" cmd /k ${commandLine}`], {
+                detached: true,
+                stdio: 'ignore',
+            }).unref();
+            return true;
+        }
+        if (process.platform === 'darwin') {
+            (0, child_process_1.spawn)('open', ['-a', 'Terminal', projectRoot], {
+                detached: true,
+                stdio: 'ignore',
+            }).unref();
+            return true;
+        }
+        (0, child_process_1.spawn)('x-terminal-emulator', ['-e', 'bash', '-lc', commandLine], {
+            detached: true,
+            stdio: 'ignore',
+        }).unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function probeCodex(projectRoot) {
+    const result = (0, child_process_1.spawnSync)('codex', ['exec', '--json', '--skip-git-repo-check', '--dangerously-bypass-approvals-and-sandbox'], {
+        cwd: projectRoot,
+        input: 'Reply exactly "FRAIM_READY" if FRAIM is available in this workspace. Otherwise reply exactly "NOT_READY".',
+        encoding: 'utf8',
+        timeout: 60000,
+    });
+    const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
+    return { ok: result.status === 0 && output.toUpperCase().includes('FRAIM'), output };
+}
+function probeClaude(projectRoot) {
+    const result = (0, child_process_1.spawnSync)('claude', ['-p', '--verbose', '--output-format', 'stream-json', '--dangerously-skip-permissions'], {
+        cwd: projectRoot,
+        input: 'Reply exactly "FRAIM_READY" if FRAIM is available in this workspace. Otherwise reply exactly "NOT_READY".',
+        encoding: 'utf8',
+        timeout: 60000,
+    });
+    const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
+    return { ok: result.status === 0 && output.toUpperCase().includes('FRAIM'), output };
+}
+function probeGemini(projectRoot) {
+    const result = (0, child_process_1.spawnSync)('gemini', ['--help'], {
+        cwd: projectRoot,
+        encoding: 'utf8',
+        timeout: 30000,
+    });
+    const output = `${result.stdout || ''}${result.stderr || ''}`.trim();
+    return {
+        ok: result.status === 0,
+        output: output || 'Gemini CLI responded to --help; runtime FRAIM probe still requires manual confirmation.',
+    };
+}
+class FirstRunSessionService {
+    constructor(options) {
+        this.key = options.key;
+        this.headless = options.headless === true;
+        this.fakeMode = process.env.FRAIM_FIRST_RUN_FAKE === '1';
+        this.requestToken = crypto_1.default.randomUUID();
+        this.state = options.resume ? (0, install_state_1.loadFirstRunState)() || (0, install_state_1.createInitialFirstRunState)(options.key) : (0, install_state_1.createInitialFirstRunState)(options.key);
+        if (options.projectRoot) {
+            this.state.workspacePath = path_1.default.resolve(options.projectRoot);
+            this.state.stepStates.project = 'running';
+            (0, install_state_1.saveFirstRunState)(this.state);
+        }
+    }
+    persist() {
+        (0, install_state_1.saveFirstRunState)(this.state);
+    }
+    markStep(step, status) {
+        this.state.stepStates[step] = status;
+        this.persist();
+    }
+    detectAgents() {
+        if (this.fakeMode) {
+            return types_1.FIRST_RUN_AGENT_OPTIONS.map((agent) => ({
+                id: agent.id,
+                label: agent.label,
+                detected: true,
+                detail: 'Fake test-mode agent available.',
+            }));
+        }
+        const detected = (0, ide_detector_1.detectInstalledIDEs)();
+        return types_1.FIRST_RUN_AGENT_OPTIONS.map((agent) => {
+            const ide = detected.find((entry) => entry.aliases?.some((alias) => agent.detectAliases.includes(alias)) ||
+                agent.detectAliases.some((alias) => entry.name.toLowerCase().includes(alias)));
+            return {
+                id: agent.id,
+                label: agent.label,
+                detected: Boolean(ide) || commandExists(agent.launchCommand),
+                detail: ide ? `Config path: ${ide.configPath}` : 'CLI/config not detected yet.',
+            };
+        });
+    }
+    getRequestToken() {
+        return this.requestToken;
+    }
+    getSession() {
+        const agents = this.detectAgents();
+        this.state.detectedAgents = agents.filter((agent) => agent.detected).map((agent) => agent.id);
+        this.persist();
+        return {
+            state: this.state,
+            agents,
+            prompt: types_1.FIRST_RUN_PROMPT,
+            headless: this.headless,
+            requestToken: this.requestToken,
+        };
+    }
+    runPrereqChecks() {
+        this.markStep('prereqs', 'running');
+        const checks = [
+            { label: 'node', ok: commandExists('node') },
+            { label: 'npx', ok: commandExists('npx') },
+            { label: 'git', ok: commandExists('git') },
+        ];
+        const failures = checks.filter((check) => !check.ok).map((check) => check.label);
+        const message = failures.length === 0
+            ? 'Node.js, npx, and git are available.'
+            : `Missing prerequisites: ${failures.join(', ')}.`;
+        appendInstallLog(`prereq-check ${message}`);
+        this.markStep('prereqs', failures.length === 0 ? 'complete' : 'failed');
+        if (failures.length === 0) {
+            this.markStep('agent', 'running');
+        }
+        return { ok: failures.length === 0, message, state: this.state };
+    }
+    selectAgent(agentId) {
+        this.state.selectedAgentId = agentId;
+        this.markStep('agent', 'complete');
+        this.markStep('configure', 'running');
+        appendInstallLog(`agent-selected ${agentId}`);
+        return {
+            ok: true,
+            message: `Selected ${types_1.FIRST_RUN_AGENT_OPTIONS.find((agent) => agent.id === agentId)?.label || agentId}.`,
+            state: this.state,
+            launchCommand: types_1.FIRST_RUN_AGENT_OPTIONS.find((agent) => agent.id === agentId)?.loginCommand,
+        };
+    }
+    async configureFraim() {
+        this.markStep('configure', 'running');
+        (0, setup_1.saveGlobalConfig)(this.key, 'conversational', {}, {});
+        if (!this.fakeMode) {
+            const selectedAgent = this.state.selectedAgentId ? (0, ide_detector_1.findIDEByName)(this.state.selectedAgentId) : undefined;
+            const targetNames = selectedAgent ? [selectedAgent.name] : undefined;
+            await (0, auto_mcp_setup_1.autoConfigureMCP)(this.key, {}, targetNames, {});
+            this.state.configuredAgents = this.detectAgents().filter((agent) => agent.detected).map((agent) => agent.id);
+        }
+        else {
+            this.state.configuredAgents = this.state.selectedAgentId ? [this.state.selectedAgentId] : [];
+        }
+        appendInstallLog(`configure configuredAgents=${this.state.configuredAgents.join(',')}`);
+        this.markStep('configure', 'complete');
+        this.markStep('project', 'running');
+        return {
+            ok: true,
+            message: 'Saved FRAIM global configuration and wrote agent config where available.',
+            state: this.state,
+        };
+    }
+    async initializeProject(projectPath, initializeGit = true) {
+        const resolvedPath = path_1.default.resolve(projectPath);
+        fs_1.default.mkdirSync(resolvedPath, { recursive: true });
+        this.markStep('project', 'running');
+        if (initializeGit && commandExists('git')) {
+            try {
+                (0, child_process_1.execSync)('git rev-parse --git-dir', { cwd: resolvedPath, stdio: 'ignore' });
+            }
+            catch {
+                (0, child_process_1.execSync)('git init', { cwd: resolvedPath, stdio: 'ignore' });
+            }
+        }
+        await (0, init_project_1.runInitProject)({ projectRoot: resolvedPath });
+        this.state.workspacePath = resolvedPath;
+        this.markStep('project', 'complete');
+        this.markStep('launch', 'running');
+        appendInstallLog(`project-initialized ${resolvedPath}`);
+        return {
+            ok: true,
+            message: `Initialized FRAIM in ${resolvedPath}.`,
+            state: this.state,
+        };
+    }
+    launchAndProbe() {
+        const agentId = this.state.selectedAgentId;
+        const projectRoot = this.state.workspacePath;
+        if (!agentId || !projectRoot) {
+            this.markStep('launch', 'failed');
+            return {
+                ok: false,
+                message: 'Select an agent and project folder before launch.',
+                state: this.state,
+            };
+        }
+        const launchCommand = getLaunchInstruction(agentId, projectRoot);
+        const opened = this.fakeMode ? true : maybeLaunchInteractiveShell(agentId, projectRoot);
+        let probeResult = { ok: true, output: 'Fake test-mode launch succeeded.' };
+        if (!this.fakeMode) {
+            if (agentId === 'codex') {
+                probeResult = probeCodex(projectRoot);
+            }
+            else if (agentId === 'claude-code') {
+                probeResult = probeClaude(projectRoot);
+            }
+            else {
+                probeResult = probeGemini(projectRoot);
+            }
+        }
+        this.state.lastLaunchCommand = launchCommand;
+        this.state.lastProbeMessage = probeResult.output;
+        this.markStep('launch', probeResult.ok ? 'complete' : 'failed');
+        if (probeResult.ok) {
+            this.markStep('finish', 'running');
+        }
+        appendInstallLog(`launch agent=${agentId} opened=${opened} probeOk=${probeResult.ok}`);
+        return {
+            ok: probeResult.ok,
+            message: opened
+                ? 'Agent launch was attempted and the probe completed.'
+                : 'Agent launch could not be opened automatically; use the provided command and review the probe output.',
+            state: this.state,
+            launchCommand,
+            output: probeResult.output,
+        };
+    }
+    finish() {
+        ensureOutputDirs();
+        fs_1.default.writeFileSync(getNextPromptPath(), `${types_1.FIRST_RUN_PROMPT}${os_1.default.EOL}`, 'utf8');
+        this.state.nextPrompt = types_1.FIRST_RUN_PROMPT;
+        this.markStep('finish', 'complete');
+        appendInstallLog('finish prompt-written');
+        return {
+            ok: true,
+            message: 'Wrote the next prompt artifact and completed first-run.',
+            state: this.state,
+        };
+    }
+}
+exports.FirstRunSessionService = FirstRunSessionService;

package/dist/src/first-run/types.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIRST_RUN_AGENT_OPTIONS = exports.FIRST_RUN_RESOURCES_URL = exports.FIRST_RUN_PROMPT = void 0;
+exports.createDefaultStepStates = createDefaultStepStates;
+exports.FIRST_RUN_PROMPT = 'Onboard this project';
+exports.FIRST_RUN_RESOURCES_URL = 'https://fraimworks.ai/resources.html';
+exports.FIRST_RUN_AGENT_OPTIONS = [
+    {
+        id: 'claude-code',
+        label: 'Claude Code',
+        detectAliases: ['claude-code', 'claude code', 'claude'],
+        loginCommand: 'claude',
+        launchCommand: 'claude',
+    },
+    {
+        id: 'codex',
+        label: 'Codex',
+        detectAliases: ['codex'],
+        loginCommand: 'codex login',
+        launchCommand: 'codex',
+    },
+    {
+        id: 'gemini-cli',
+        label: 'Gemini CLI',
+        detectAliases: ['gemini-cli', 'gemini cli', 'gemini'],
+        loginCommand: 'gemini',
+        launchCommand: 'gemini',
+    },
+];
+function createDefaultStepStates() {
+    return {
+        welcome: 'pending',
+        prereqs: 'pending',
+        agent: 'pending',
+        configure: 'pending',
+        project: 'pending',
+        launch: 'pending',
+        finish: 'pending',
+    };
+}

package/dist/src/local-mcp-server/otlp-metrics-receiver.js

@@ -257,6 +257,12 @@ function startOtlpReceiver(log) {
  * Stop the OTLP receiver and clear stored snapshots.
  */
 function stopOtlpReceiver(server) {
-    server.close();
+    try {
+        server.close();
+    }
+    catch {
+        // The receiver may have failed to bind because another FRAIM proxy owns
+        // the port. In that case there is no local listener to close.
+    }
     snapshots.clear();
 }

package/dist/src/local-mcp-server/stdio-server.js

@@ -402,6 +402,7 @@ class FraimLocalMCPServer {
         this.repoInfo = null;
         this.engine = null;
         this.otlpServer = null;
+        this.isShutdown = false;
         this.writer = writer || process.stdout.write.bind(process.stdout);
         this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
         this.apiKey = this.loadApiKey();
@@ -422,6 +423,16 @@ class FraimLocalMCPServer {
         // Start OTLP metrics receiver for Claude Code token telemetry
         this.otlpServer = (0, otlp_metrics_receiver_js_1.startOtlpReceiver)((msg) => this.log(`📊 ${msg}`));
     }
+    shutdown() {
+        if (this.isShutdown)
+            return;
+        this.isShutdown = true;
+        this.usageCollector.shutdown();
+        if (this.otlpServer?.server) {
+            (0, otlp_metrics_receiver_js_1.stopOtlpReceiver)(this.otlpServer.server);
+            this.otlpServer = null;
+        }
+    }
     /**
      * Load API key from environment variable or user config file
      * Priority: FRAIM_API_KEY env var > ~/.fraim/config.json
@@ -1436,6 +1447,33 @@ class FraimLocalMCPServer {
             projectPath: `${issueTracking.namespace}/${issueTracking.name}`
         };
     }
+    hasRemoteRepoLocator(value) {
+        if (typeof value !== 'string')
+            return false;
+        return /^[a-z]+:\/\//i.test(value) || /^[^@\s]+@[^:\s]+:/i.test(value);
+    }
+    mergeRepoContexts(agentRepo, detectedRepo) {
+        const normalizedAgent = this.normalizeRepoContext(agentRepo);
+        const normalizedDetected = this.normalizeRepoContext(detectedRepo);
+        if (!normalizedAgent)
+            return normalizedDetected;
+        if (!normalizedDetected)
+            return normalizedAgent;
+        const agentHasRemoteUrl = this.hasRemoteRepoLocator(normalizedAgent.url);
+        const detectedHasRemoteUrl = this.hasRemoteRepoLocator(normalizedDetected.url);
+        // Preserve an explicit agent-supplied remote repository when local auto-detection
+        // only found a workspace label or other non-remote fallback.
+        if (agentHasRemoteUrl && !detectedHasRemoteUrl) {
+            return this.normalizeRepoContext({
+                ...normalizedDetected,
+                ...normalizedAgent
+            });
+        }
+        return this.normalizeRepoContext({
+            ...normalizedAgent,
+            ...normalizedDetected
+        });
+    }
     /**
      * Internal method to perform the actual proxy request to the remote server.
      * This method does NOT inject raw: true, as it is used for both top-level
@@ -1457,11 +1495,7 @@ class FraimLocalMCPServer {
                 // REQUIRED: Auto-detect and inject repo info
                 const detectedRepo = this.detectRepoInfo();
                 if (detectedRepo) {
-                    args.repo = {
-                        ...args.repo, // Agent values as fallback
-                        ...detectedRepo // Detected values override (always win)
-                    };
-                    args.repo = this.normalizeRepoContext(args.repo);
+                    args.repo = this.mergeRepoContexts(args.repo, detectedRepo);
                     const repoLabel = args.repo.owner ? `${args.repo.owner}/${args.repo.name}` : args.repo.name;
                     this.log(`[req:${requestId}] Auto-detected and injected repo info: ${repoLabel}`);
                 }
@@ -1894,13 +1928,11 @@ class FraimLocalMCPServer {
                 this.log(`⚠️ Failed to upload usage data: ${error.message}`);
             });
         }, 60000); // Upload every minute
+        uploadInterval.unref?.();
         // Clean up interval on shutdown
         const cleanup = () => {
             clearInterval(uploadInterval);
-            this.usageCollector.shutdown();
-            if (this.otlpServer?.server) {
-                (0, otlp_metrics_receiver_js_1.stopOtlpReceiver)(this.otlpServer.server);
-            }
+            this.shutdown();
         };
         process.stdin.on('data', async (chunk) => {
             buffer += chunk;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.126",
+  "version": "2.0.127",
   "description": "FRAIM: AI Workforce Infrastructure — the organizational capability that turns AI agents into an accountable workforce, their operators into capable AI managers, and executives into leaders with clear optics on AI proficiency.",
   "main": "index.js",
   "bin": {
@@ -114,10 +114,12 @@
     "dist/src/local-mcp-server/",
     "dist/src/cli/",
     "dist/src/ai-hub/",
+    "dist/src/first-run/",
     "dist/src/core/",
     "bin/fraim.js",
     "bin/fraim-mcp.js",
     "public/ai-hub/",
+    "public/first-run/",
     "index.js",
     "README.md",
     "CHANGELOG.md",