fraim-framework 2.0.127 → 2.0.129

package/dist/src/cli/commands/first-run.js

@@ -13,7 +13,13 @@ const server_2 = require("../../ai-hub/server");
 function openBrowser(url) {
     try {
         if (process.platform === 'win32') {
-            (0, child_process_1.spawn)('cmd.exe', ['/d', '/s', '/c', `start "" "${url}"`], { detached: true, stdio: 'ignore' }).unref();
+            // `cmd.exe /c start "" "<url>"` works in most cases but mis-parses on
+            // some Windows configurations (cmd treats the URL's `//` as a UNC
+            // path and the user sees a "Windows cannot find" dialog). The
+            // `rundll32 url.dll,FileProtocolHandler <url>` pattern is the
+            // documented protocol-handler entry point and bypasses cmd.exe
+            // entirely.
+            (0, child_process_1.spawn)('rundll32', ['url.dll,FileProtocolHandler', url], { detached: true, stdio: 'ignore' }).unref();
             return;
         }
         if (process.platform === 'darwin') {
@@ -47,6 +53,13 @@ const runFirstRun = async (options) => {
     if (!options.headless) {
         openBrowser(url);
     }
+    // Block forever — the wizard's /open-hub endpoint starts the Hub
+    // server in-process. Stopping the server here would kill the Hub.
+    // The user closes the terminal (Ctrl+C) when they're done. v2 (#355)
+    // replaces this in-process model with a detached launcher binary so
+    // the wizard CLI can exit cleanly while the Hub keeps running.
+    console.log(chalk_1.default.gray('When you finish the wizard, the Hub will be served from this terminal.'));
+    console.log(chalk_1.default.gray('Press Ctrl+C to stop everything when you are done.'));
     await server.waitForFinish();
     await server.stop();
     console.log(chalk_1.default.green('FRAIM first-run completed.'));

package/dist/src/cli/commands/init-project.js

@@ -160,11 +160,15 @@ const createGitHubLabels = (projectRoot) => {
 };
 const runInitProject = async (options = {}) => {
     console.log(chalk_1.default.blue('Initializing FRAIM project...'));
+    const failHard = options.failHard ?? 'exit';
     const globalSetup = checkGlobalSetup();
     if (!globalSetup.exists) {
         console.log(chalk_1.default.red('Global FRAIM setup not found.'));
         console.log(chalk_1.default.yellow('Please run global setup first:'));
         console.log(chalk_1.default.cyan('   fraim setup'));
+        if (failHard === 'throw') {
+            throw new Error('Global FRAIM setup not found.');
+        }
         process.exit(1);
     }
     const projectRoot = options.projectRoot || process.cwd();
@@ -312,7 +316,7 @@ const runInitProject = async (options = {}) => {
         result.repositoryDetected = true;
     }
     if (!process.env.FRAIM_SKIP_SYNC) {
-        await (0, sync_1.runSync)({ projectRoot });
+        await (0, sync_1.runSync)({ projectRoot, failHard });
         result.syncPerformed = true;
     }
     else {

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

@@ -101,7 +101,14 @@ function updateVersionInConfig(fraimDir) {
         console.warn(chalk_1.default.yellow('Could not update version in config.json.'));
     }
 }
+function failSync(mode, message) {
+    if (mode === 'throw') {
+        throw new Error(message);
+    }
+    process.exit(1);
+}
 const runSync = async (options) => {
+    const failHard = options.failHard ?? 'exit';
     // Handle --global flag: sync to user-level ~/.fraim/ instead of project
     if (options.global) {
         console.log(chalk_1.default.blue('Syncing FRAIM content to user-level directory (~/.fraim/)...'));
@@ -112,7 +119,7 @@ const runSync = async (options) => {
         }
         catch (error) {
             console.error(chalk_1.default.red(`User-level sync failed: ${error.message}`));
-            process.exit(1);
+            failSync(failHard, `User-level sync failed: ${error.message}`);
         }
         return;
     }
@@ -136,7 +143,14 @@ const runSync = async (options) => {
         console.log(chalk_1.default.cyan('Recommended: Use "npx fraim-framework@latest sync" instead.\n'));
     }
     const { syncFromRemote } = await Promise.resolve().then(() => __importStar(require('../utils/remote-sync')));
-    if (options.local) {
+    // Allow `FRAIM_LOCAL_SYNC=1` to flip into local-mode without needing
+    // the --local CLI flag. The FRE's runProjectRow path doesn't surface
+    // a --local flag, but devs validating the FRE locally need a way to
+    // point sync at their localhost MCP server. With this env var set,
+    // any caller (including the FRE) routes through the local sync path
+    // exactly as if the user had passed --local.
+    const useLocal = options.local || process.env.FRAIM_LOCAL_SYNC === '1';
+    if (useLocal) {
         console.log(chalk_1.default.blue('Syncing FRAIM jobs from local server...'));
         const localPort = process.env.FRAIM_MCP_PORT ? parseInt(process.env.FRAIM_MCP_PORT) : (0, git_utils_1.getPort)();
         const localUrl = resolveExplicitLocalSyncUrl() || `http://localhost:${localPort}`;
@@ -158,7 +172,7 @@ const runSync = async (options) => {
         }
         console.error(chalk_1.default.red(`Local sync failed: ${result.error}`));
         console.error(chalk_1.default.yellow('Make sure the FRAIM MCP server is running locally (npm run dev).'));
-        process.exit(1);
+        failSync(failHard, `Local sync failed: ${result.error}`);
     }
     let apiKey = loadUserApiKey() || config.apiKey || process.env.FRAIM_API_KEY;
     if (!apiKey) {
@@ -170,7 +184,7 @@ const runSync = async (options) => {
             console.error(chalk_1.default.red('No API key configured. Cannot sync.'));
             console.error(chalk_1.default.yellow(`Set FRAIM_API_KEY in your environment, or add apiKey to ~/.fraim/config.json or ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('config.json')}`));
             console.error(chalk_1.default.yellow('Or use --local to sync from a locally running FRAIM server.'));
-            process.exit(1);
+            failSync(failHard, 'No API key configured.');
         }
     }
     console.log(chalk_1.default.blue('Syncing FRAIM jobs from remote server...'));
@@ -188,7 +202,7 @@ const runSync = async (options) => {
             updateVersionInConfig(fraimDir);
             return;
         }
-        process.exit(1);
+        failSync(failHard, `Remote sync failed: ${result.error}`);
     }
     console.log(chalk_1.default.green(`Successfully synced ${result.employeeJobsSynced} ai-employee jobs, ${result.managerJobsSynced} ai-manager jobs, ${result.skillsSynced} skills, ${result.rulesSynced} rules, ${result.scriptsSynced} scripts, and ${result.docsSynced} docs from remote`));
     updateVersionInConfig(fraimDir);

package/dist/src/first-run/install-state.js

@@ -27,14 +27,12 @@ function maskInstallKey(key) {
 function createInitialFirstRunState(key) {
     const now = new Date().toISOString();
     return {
-        version: 1,
+        version: 2,
         installKeyRef: maskInstallKey(key),
         platform: process.platform,
-        detectedAgents: [],
-        configuredAgents: [],
-        restartDeferredAgents: [],
+        agentId: 'claude-code',
+        rows: (0, types_1.createInitialRows)(),
         resourcesUrl: types_1.FIRST_RUN_RESOURCES_URL,
-        stepStates: (0, types_1.createDefaultStepStates)(),
         createdAt: now,
         updatedAt: now,
     };
@@ -46,6 +44,10 @@ function loadFirstRunState() {
     }
     try {
         const state = JSON.parse(fs_1.default.readFileSync(statePath, 'utf8'));
+        // Reject persisted v1 state — schema changed materially in #352 v1.
+        if (state.version !== 2) {
+            return null;
+        }
         if (typeof state.installKeyRef === 'string' && !state.installKeyRef.includes('...')) {
             state.installKeyRef = maskInstallKey(state.installKeyRef);
         }

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

@@ -8,6 +8,7 @@ const express_1 = __importDefault(require("express"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
+const session_service_1 = require("./session-service");
 function resolveFirstRunPublicDir() {
     const candidates = [
         path_1.default.resolve(process.cwd(), 'public/first-run'),
@@ -21,31 +22,65 @@ function resolveFirstRunPublicDir() {
     }
     throw new Error('Could not locate public/first-run assets.');
 }
+/**
+ * Open the platform's native folder picker and return the chosen path
+ * (or `null` if the user cancelled).
+ *
+ * Implementation notes:
+ * - Async (`spawn`, not `spawnSync`). The folder dialog blocks until the
+ *   user dismisses it, which can be many seconds. With `spawnSync` the
+ *   entire Node event loop freezes during that time — every other HTTP
+ *   request to the FRE server gets `ERR_ABORTED`, and the FRE looks dead.
+ * - Windows: PowerShell needs `-STA` (Single-Threaded Apartment) for
+ *   `System.Windows.Forms.FolderBrowserDialog` to work. We also create a
+ *   hidden `$owner` form with `TopMost = $true` and pass it as the
+ *   dialog's owner so the picker comes to the foreground instead of
+ *   appearing behind the browser (which made the Browse button look
+ *   broken).
+ */
 function pickProjectPath() {
     if (process.platform === 'win32') {
         const script = [
             'Add-Type -AssemblyName System.Windows.Forms',
             '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
+            '$dialog.Description = "Select a FRAIM project folder"',
             '$dialog.ShowNewFolderButton = $true',
-            'if ($dialog.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) {',
+            // Hidden owner form forces the dialog above the user's browser. Without
+            // this the dialog often appears behind the browser tab and the user
+            // sees nothing happen when they click Browse.
+            '$owner = New-Object System.Windows.Forms.Form',
+            '$owner.TopMost = $true',
+            '$owner.ShowInTaskbar = $false',
+            'if ($dialog.ShowDialog($owner) -eq [System.Windows.Forms.DialogResult]::OK) {',
             '  Write-Output $dialog.SelectedPath',
             '}',
+            '$owner.Dispose()',
         ].join('; ');
-        const result = (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-Command', script], {
-            encoding: 'utf8',
-        });
-        return result.status === 0 ? result.stdout.trim() || null : null;
+        return runPickerProcess('powershell', ['-NoProfile', '-STA', '-Command', script]);
     }
     if (process.platform === 'darwin') {
-        const result = (0, child_process_1.spawnSync)('osascript', ['-e', 'POSIX path of (choose folder with prompt "Select a FRAIM project folder")'], {
-            encoding: 'utf8',
-        });
-        return result.status === 0 ? result.stdout.trim() || null : null;
+        return runPickerProcess('osascript', ['-e', 'POSIX path of (choose folder with prompt "Select a FRAIM project folder")']);
     }
-    const result = (0, child_process_1.spawnSync)('bash', ['-lc', 'zenity --file-selection --directory 2>/dev/null || kdialog --getexistingdirectory 2>/dev/null'], {
-        encoding: 'utf8',
+    return runPickerProcess('bash', ['-lc', 'zenity --file-selection --directory 2>/dev/null || kdialog --getexistingdirectory 2>/dev/null']);
+}
+function runPickerProcess(command, args) {
+    return new Promise((resolve) => {
+        const proc = (0, child_process_1.spawn)(command, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        proc.stdout?.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+        proc.stderr?.on('data', () => { });
+        proc.on('close', () => {
+            const trimmed = stdout.trim();
+            resolve(trimmed || null);
+        });
+        proc.on('error', () => resolve(null));
     });
-    return result.status === 0 ? result.stdout.trim() || null : null;
+}
+function isCanonicalRowId(value) {
+    return typeof value === 'string' && session_service_1.FIRST_RUN_ROW_IDS.includes(value);
 }
 class FirstRunServer {
     constructor(options) {
@@ -100,26 +135,30 @@ class FirstRunServer {
         this.app.get('/api/first-run/session', (_req, res) => {
             res.json(this.sessionService.getSession());
         });
-        this.app.post('/api/first-run/prereqs', (_req, res) => {
-            res.json(this.sessionService.runPrereqChecks());
-        });
-        this.app.post('/api/first-run/agents/select', (req, res) => {
-            if (!req.body.agentId) {
-                return res.status(400).json({ error: 'agentId is required.' });
+        this.app.post('/api/first-run/rows/:rowId/run', async (req, res) => {
+            const { rowId } = req.params;
+            if (!isCanonicalRowId(rowId)) {
+                return res.status(400).json({ error: `Unknown row id: ${rowId}` });
+            }
+            try {
+                const result = await this.sessionService.runRow(rowId, req.body || {});
+                return res.json(result);
+            }
+            catch (error) {
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not run row.' });
             }
-            return res.json(this.sessionService.selectAgent(req.body.agentId));
         });
-        this.app.post('/api/first-run/configure', async (_req, res) => {
+        this.app.post('/api/first-run/agent/change', (req, res) => {
             try {
-                return res.json(await this.sessionService.configureFraim());
+                return res.json(this.sessionService.changeAgent(req.body || {}));
             }
             catch (error) {
-                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not configure FRAIM.' });
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not change agent.' });
             }
         });
-        this.app.post('/api/first-run/project-path/pick', (_req, res) => {
+        this.app.post('/api/first-run/project-path/pick', async (_req, res) => {
             try {
-                const selectedPath = pickProjectPath();
+                const selectedPath = await pickProjectPath();
                 if (!selectedPath) {
                     return res.status(204).end();
                 }
@@ -129,25 +168,36 @@ class FirstRunServer {
                 return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not open the folder picker.' });
             }
         });
-        this.app.post('/api/first-run/project', async (req, res) => {
-            if (!req.body.projectPath) {
-                return res.status(400).json({ error: 'projectPath is required.' });
-            }
+        this.app.post('/api/first-run/finish', (_req, res) => {
+            // Note: /finish writes the next-prompt artifact but does NOT trigger
+            // process shutdown. In v1 the Hub server is started in-process by
+            // /open-hub — if we resolved the finishPromise here, runFirstRun
+            // would call server.stop() and the parent process would exit,
+            // taking the just-started Hub down with it. The Hub handoff has
+            // to keep the parent alive. The CLI exits when the user Ctrl+Cs
+            // the terminal. v2 (#355) replaces this with a detached launcher.
+            const result = this.sessionService.finish();
+            return res.json(result);
+        });
+        // Hub-launch helper — starts an AiHubServer for the chosen project and
+        // opens the user's browser. v2 (#355) replaces the in-process spawn with
+        // a durable launcher binary that survives independently.
+        this.app.post('/api/first-run/open-hub', async (_req, res) => {
             try {
-                return res.json(await this.sessionService.initializeProject(req.body.projectPath, req.body.initializeGit !== false));
+                const result = await this.sessionService.openHub();
+                // Write the next-prompt artifact as a side effect of opening the
+                // Hub so the client doesn't need a separate /finish call. We
+                // intentionally do NOT resolve the finishPromise — see /finish
+                // handler comment above.
+                if (result.ok) {
+                    this.sessionService.finish();
+                }
+                return res.json(result);
             }
             catch (error) {
-                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not initialize the project.' });
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not open Hub.' });
             }
         });
-        this.app.post('/api/first-run/launch', (_req, res) => {
-            return res.json(this.sessionService.launchAndProbe());
-        });
-        this.app.post('/api/first-run/finish', (_req, res) => {
-            const result = this.sessionService.finish();
-            this.finishResolver?.();
-            return res.json(result);
-        });
     }
 }
 exports.FirstRunServer = FirstRunServer;