fraim-framework 2.0.128 → 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/sync.js

@@ -143,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}`;

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

@@ -22,31 +22,62 @@ 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);
@@ -125,9 +156,9 @@ class FirstRunServer {
                 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();
                 }
@@ -138,16 +169,30 @@ class FirstRunServer {
             }
         });
         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();
-            this.finishResolver?.();
             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.
+        // 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.openHub());
+                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 open Hub.' });

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

@@ -139,10 +139,33 @@ class FirstRunSessionService {
         delete row.errorFrame;
         delete row.streamOutput;
     }
-    setRowError(row, whatTried, whatHappened, actions) {
+    setRowError(row, whatTried, whatHappened, actions, hint) {
         row.status = 'error';
         row.verb = 'failed — see below';
-        row.errorFrame = { whatTried, whatHappened, actions };
+        row.errorFrame = { whatTried, whatHappened, actions, ...(hint ? { hint } : {}) };
+    }
+    /**
+     * Classify a thrown init/sync error into a non-tech-friendly hint.
+     * The verbatim stderr is preserved separately in `whatHappened` per
+     * R6.3 — the hint is additive context, not a replacement.
+     */
+    classifyInitError(detail) {
+        if (/status code 401|Unauthorized|401\b/i.test(detail)) {
+            return "Your FRAIM install key was rejected by the registry. If your key expired, get a new one from your account page and re-run setup with the new key. If you're testing locally, set `FRAIM_LOCAL_SYNC=1` so the project row syncs from your local FRAIM server instead of the production registry.";
+        }
+        if (/status code 403|Forbidden/i.test(detail)) {
+            return "The FRAIM registry refused this key for this project. Check that your install key has access to the registry you're syncing from.";
+        }
+        if (/status code 5\d\d/i.test(detail) || /5\d\d\b/.test(detail)) {
+            return 'The FRAIM registry returned a server error. This is usually transient — wait a minute and click Retry. If it keeps failing, the registry may be down.';
+        }
+        if (/ENOTFOUND|ECONNREFUSED|ECONNRESET|ETIMEDOUT|getaddrinfo|network/i.test(detail)) {
+            return "Couldn't reach the FRAIM registry. Check your internet connection (or if you're testing locally, that the local FRAIM server is running) and click Retry.";
+        }
+        if (/Global FRAIM setup not found/i.test(detail)) {
+            return 'FRAIM\'s global config is missing. This usually means the agent step didn\'t complete cleanly — go back and re-run the AI agent row.';
+        }
+        return undefined;
     }
     detectRowsOnLoad() {
         if (this.fakeMode) {
@@ -586,11 +609,11 @@ class FirstRunSessionService {
                 const detail = initError instanceof Error ? initError.message : 'Unknown init error';
                 // Skip is intentionally omitted on the project row — without a
                 // project there is no Hub to open, so deferring this row would
-                // leave the user wedged. Retry is always offered; if the failure
-                // is a 401 from remote sync, the verbatim message tells the user
-                // their API key is the problem and they need to re-run with a
-                // valid key.
-                this.setRowError(row, `Initializing FRAIM in ${resolvedPath}`, detail, [{ id: 'retry', label: 'Retry', variant: 'primary' }]);
+                // leave the user wedged. Retry is always offered; the hint
+                // translates the verbatim error (e.g. "Request failed with
+                // status code 401") into something a non-tech user can act on.
+                const hint = this.classifyInitError(detail);
+                this.setRowError(row, `Initializing FRAIM in ${resolvedPath}`, detail, [{ id: 'retry', label: 'Retry', variant: 'primary' }], hint);
                 appendInstallLog(`project-init-failed ${resolvedPath}: ${detail}`);
                 this.persist();
                 return this.respond(`Initialization failed: ${detail}`, false);
@@ -728,7 +751,11 @@ class FirstRunSessionService {
     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>"` mis-parses on some Windows hosts
+                // (cmd interprets the URL's `//` as a UNC path -> "Windows cannot
+                // find" popup). rundll32 + url.dll,FileProtocolHandler is the
+                // documented protocol-handler entry point and bypasses cmd entirely.
+                (0, child_process_1.spawn)('rundll32', ['url.dll,FileProtocolHandler', url], { detached: true, stdio: 'ignore' }).unref();
                 return;
             }
             if (process.platform === 'darwin') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.128",
+  "version": "2.0.129",
   "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": {

package/public/first-run/error-frame.js

@@ -43,6 +43,17 @@
     whatTried.textContent = escapeText(frame.whatTried || '');
     root.appendChild(whatTried);
 
+    // Optional plain-language hint rendered ABOVE the verbatim stderr so
+    // a non-tech user reads "your install key was rejected — get a new
+    // one" before they parse `Request failed with status code 401`.
+    if (frame.hint) {
+      const hint = document.createElement('div');
+      hint.className = 'error-hint';
+      hint.setAttribute('data-testid', 'error-hint');
+      hint.textContent = escapeText(frame.hint);
+      root.appendChild(hint);
+    }
+
     const { visible, hidden } = truncateToLastLines(frame.whatHappened || '', 12);
     const whatHappened = document.createElement('pre');
     whatHappened.className = 'what-happened';

package/public/first-run/script.js

@@ -350,11 +350,22 @@
 
     if (allOk || skipPathDone) {
       try {
-        const finishResp = await api('/api/first-run/finish', 'POST');
-        setStatus(finishResp.message);
+        // /open-hub starts the Hub server in-process AND writes the
+        // next-prompt artifact (the work /finish used to do). We do NOT
+        // call /finish separately — that would race against the Hub
+        // start (server.stop() would kill the just-spawned Hub).
+        PRIMARY_BUTTON.disabled = true;
+        setStatus('Opening Hub…');
         const openResp = await api('/api/first-run/open-hub', 'POST');
         if (openResp && openResp.message) setStatus(openResp.message);
+        if (openResp && openResp.hubUrl) {
+          // Redirect this tab to the Hub. The Hub server is in-process
+          // with the wizard server, so navigating away keeps the same
+          // Node process serving — no broken handoff.
+          window.location.replace(openResp.hubUrl);
+        }
       } catch (err) {
+        PRIMARY_BUTTON.disabled = false;
         setStatus(err.message, 'error');
       }
       return;

package/public/first-run/styles.css

@@ -316,6 +316,15 @@ body {
   color: var(--danger);
   font-weight: 600;
 }
+.error-frame .error-hint {
+  color: var(--text);
+  font-size: 14px;
+  line-height: 1.45;
+  background: var(--warn-soft);
+  border: 1px solid #f0d8b3;
+  border-radius: 8px;
+  padding: 10px 12px;
+}
 .error-frame .what-happened {
   background: #0d1410;
   color: #f1c0c0;