fraim-framework 2.0.126 → 2.0.128

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

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Setup checklist surface — the row-keyed model that replaces the prior
+ * linear step machine for issue #352 v1.
+ *
+ * The same surface serves every user. What changes between a fresh-machine
+ * run and an experienced-engineer run is the distribution of row statuses,
+ * not the surface itself. Per R2.0 acceptance, the DOM and CSS chrome are
+ * byte-identical between cases — only `data-row-status`, the verb-text
+ * node, and the primary-button label differ.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIRST_RUN_AGENT_OPTIONS = exports.FIRST_RUN_RESOURCES_URL = exports.FIRST_RUN_PROMPT = exports.FIRST_RUN_ROW_IDS = void 0;
+exports.createInitialRows = createInitialRows;
+exports.derivePrimaryButtonLabel = derivePrimaryButtonLabel;
+exports.FIRST_RUN_ROW_IDS = [
+    'node',
+    'git',
+    'agent',
+    'agent-login',
+    'project',
+];
+exports.FIRST_RUN_PROMPT = 'Onboard this project';
+exports.FIRST_RUN_RESOURCES_URL = 'https://fraimworks.ai/resources.html';
+/**
+ * Recommended-agent priority order (R2.2).
+ * Tie-break: Claude Code first, then Codex, then Gemini.
+ */
+exports.FIRST_RUN_AGENT_OPTIONS = [
+    {
+        id: 'claude-code',
+        label: 'Claude Code',
+        detectAliases: ['claude-code', 'claude code', 'claude'],
+        loginCommand: 'claude',
+        launchCommand: 'claude',
+        installPackage: '@anthropic-ai/claude-code',
+    },
+    {
+        id: 'codex',
+        label: 'Codex',
+        detectAliases: ['codex'],
+        loginCommand: 'codex login',
+        launchCommand: 'codex',
+        installPackage: '@openai/codex',
+    },
+    {
+        id: 'gemini-cli',
+        label: 'Gemini CLI',
+        detectAliases: ['gemini-cli', 'gemini cli', 'gemini'],
+        loginCommand: 'gemini',
+        launchCommand: 'gemini',
+        installPackage: '@google/gemini-cli',
+    },
+];
+/**
+ * The canonical row set, in display order. Each row starts in `pending`;
+ * detection updates statuses on session load.
+ */
+function createInitialRows() {
+    return [
+        { id: 'node', label: 'Node.js', status: 'pending', verb: "we'll install" },
+        { id: 'git', label: 'git', status: 'pending', verb: "we'll install" },
+        { id: 'agent', label: 'AI agent', status: 'pending', verb: "we'll set up Claude Code (recommended)" },
+        { id: 'agent-login', label: 'Sign in', status: 'pending', verb: "you'll sign in after install" },
+        { id: 'project', label: 'Project folder', status: 'pending', verb: 'pick a folder where FRAIM should work' },
+    ];
+}
+/**
+ * State-derived primary-button label per R2.0. NEVER audience-derived.
+ *
+ * - "Open Hub": every row is ok, OR the project row is ok and every other
+ *   row is ok-or-manual-required (i.e. the user explicitly handed
+ *   themselves any remaining steps via Skip-and-continue, and there is no
+ *   forward action the wizard can take).
+ * - "Continue": at least one row is ok and there is still wizard work to do.
+ * - "Set up FRAIM": no rows ok yet.
+ *
+ * Manual-required is treated as "user-handled" for the Open-Hub gate so a
+ * Skip-and-continue path doesn't strand the user on a dead-end Continue
+ * button. It is treated as "in-progress / waiting on user" for the
+ * Continue gate so a fresh state with only the manual project row open
+ * still asks the user to continue picking a folder.
+ */
+function derivePrimaryButtonLabel(rows) {
+    const projectRow = rows.find((row) => row.id === 'project');
+    const projectOk = projectRow?.status === 'ok';
+    const allOk = rows.every((row) => row.status === 'ok');
+    if (allOk)
+        return 'Open Hub';
+    // User-skipped path: project ok and every other row ok-or-manual-required.
+    if (projectOk && rows.every((row) => row.status === 'ok' || row.status === 'manual-required')) {
+        return 'Open Hub';
+    }
+    if (rows.some((row) => row.status === 'ok'))
+        return 'Continue';
+    return 'Set up FRAIM';
+}

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.128",
   "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",

package/public/ai-hub/index.html

@@ -3,127 +3,174 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Visa AI Hub</title>
-  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 48 48'%3E%3Crect width='48' height='48' rx='10' fill='%230d3f8a'/%3E%3Cpath d='M13 31h6l3-14h-6zm10 0h6l3-14h-6zm11-14h-6l-3 14h6z' fill='%23f7b600'/%3E%3C/svg%3E">
+  <title>AI Hub</title>
+  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 48 48'%3E%3Crect width='48' height='48' rx='10' fill='%233d8a6e'/%3E%3Ctext x='24' y='32' text-anchor='middle' font-family='Helvetica,Arial,sans-serif' font-size='22' font-weight='700' fill='white'%3EH%3C/text%3E%3C/svg%3E">
   <link rel="stylesheet" href="./styles.css">
 </head>
 <body>
-  <div class="app-shell">
-    <header class="app-header">
-      <div class="brand-lockup">
-        <p class="brand-title">Visa AI Hub</p>
-        <p class="brand-subtitle">Powered by <a href="https://fraimworks.ai" target="_blank" rel="noreferrer">FRAIM</a></p>
-      </div>
-      <div class="topbar-card workspace-card">
-        <div class="workspace-section workspace-section-inline">
-          <span class="section-label">Employee</span>
-          <div class="employee-picker" id="employee-picker"></div>
-        </div>
-        <details class="project-path workspace-project">
-          <summary>
-            <span>Project Path</span>
-            <span class="project-path-preview" id="project-path-preview"></span>
-          </summary>
-          <div class="project-path-body">
-            <input id="project-path-input" class="text-input" type="text" />
-            <div class="project-actions">
-              <button id="browse-project" class="secondary-button" type="button">Choose Folder</button>
-              <button id="reload-project" class="secondary-button" type="button">Reload</button>
-            </div>
-            <p class="helper-text" id="project-status"></p>
-          </div>
-        </details>
-      </div>
+
+  <div class="page">
+
+    <header class="header">
+      <h1>AI Hub</h1>
+      <button class="project-button" type="button" id="project-button">
+        <span class="folder">Project</span>
+        <strong id="project-name">Choose a folder</strong>
+      </button>
     </header>
 
-    <main class="workspace">
-      <section class="workspace-intro card">
-        <div class="workspace-intro-copy">
-          <p class="section-label">Pick A Job</p>
-          <p class="panel-intro">Manage your AI employees just like you manage your teams. Tell them what jobs they need to complete, review their results, coach them, expect them to learn from you, and expect to learn from your employees.</p>
-        </div>
-        <div class="workspace-intro-actions">
-          <p class="section-label">Job Category</p>
-          <div class="category-picker" id="category-picker"></div>
-        </div>
-      </section>
-
-      <section class="job-panel">
-        <div class="panel-head card">
-          <div class="panel-copy">
-            <p class="section-label">Job Category</p>
-            <h2 class="panel-title">Pick a job</h2>
-            <p class="muted">Choose the next assignment for your employee.</p>
-          </div>
-        </div>
+    <section class="welcome">
+      Hi <strong class="you">there</strong>, remember, you are the
+      <span class="concept">AI Manager<button class="info" data-concept="manager" aria-label="What is AI Manager?">i</button>
+        <span class="popover" id="pop-manager">
+          <span class="pop-title">AI Manager</span>
+          That's you. You decide what outcome matters, pick the right job, and hold the bar on quality. You're not writing the work — you're directing it.
+          <a class="pop-link" href="#" data-target="jobs-manager">See manager jobs →</a>
+          <span class="pop-jobs" id="jobs-manager"></span>
+        </span></span>.
+      Delegate jobs to your
+      <span class="concept">AI Employees<button class="info" data-concept="employee" aria-label="What is AI Employee?">i</button>
+        <span class="popover" id="pop-employee">
+          <span class="pop-title">AI Employee</span>
+          The coding agent — Codex, Claude, or another — that actually does the work you assign. AI Hub is where you direct them; the agent itself is the employee.
+          <a class="pop-link" href="#" data-target="jobs-employee">See employee jobs →</a>
+          <span class="pop-jobs" id="jobs-employee"></span>
+        </span></span>,
+      <span class="concept">Coach<button class="info" data-concept="coach" aria-label="What is Coach?">i</button>
+        <span class="popover" id="pop-coach">
+          <span class="pop-title">Coach</span>
+          Add context, raise the bar, or correct course mid-flight without abandoning the conversation. Same job, sharper guidance.
+          <a class="pop-link" href="#" data-target="jobs-coach">See coaching jobs →</a>
+          <span class="pop-jobs" id="jobs-coach"></span>
+        </span></span>
+      them,
+      <span class="concept">Verify<button class="info" data-concept="verify" aria-label="What is Verify?">i</button>
+        <span class="popover" id="pop-verify">
+          <span class="pop-title">Verify</span>
+          Check that the artifact actually solved the problem before you trust completion. Read the result, not just the logs.
+          <a class="pop-link" href="#" data-target="jobs-verify">See verification jobs →</a>
+          <span class="pop-jobs" id="jobs-verify"></span>
+        </span></span>
+      their work, and expect them to
+      <span class="concept">Learn<button class="info" data-concept="learn" aria-label="What is Learn?">i</button>
+        <span class="popover" id="pop-learn">
+          <span class="pop-title">Learn</span>
+          Each run should make the next one better. Your coaching becomes their lasting habit.
+          <a class="pop-link" href="#" data-target="jobs-learn">See learning jobs →</a>
+          <span class="pop-jobs" id="jobs-learn"></span>
+        </span></span>
+      and get better. Let your employees make you shine.
+    </section>
 
-        <div class="job-list-card card">
-          <div class="job-list" id="job-list"></div>
+    <div class="layout">
+      <aside class="rail">
+        <button class="new-conv" type="button" id="new-conv-btn">+ New job</button>
+        <div class="conv-list" id="conv-list"></div>
+      </aside>
+
+      <main class="conversation" id="conversation">
+        <div class="empty-state" id="empty">
+          <h3>No job selected</h3>
+          <p>Pick an existing job from the left, or click <strong>+ New job</strong> to give your employee something to work on.</p>
         </div>
-      </section>
-
-      <section class="interaction-panel">
-        <div class="card interaction-card">
-          <div class="run-toolbar">
-            <div class="selected-job-summary">
-              <div>
-                <p class="section-label">Selected Job</p>
-                <h2 id="selected-job-title">Select a job</h2>
-                <p id="selected-job-intent" class="muted"></p>
-              </div>
-              <ul class="job-outcomes" id="selected-job-outcomes"></ul>
-            </div>
-            <div class="run-toolbar-actions">
-              <button id="start-job" class="primary-button" type="button" disabled>Start Job</button>
-            </div>
+
+        <div id="active-conv" hidden>
+          <div class="conv-header">
+            <h2 id="active-title"></h2>
+            <div class="conv-job" id="active-job"></div>
+            <div id="artifact-slot"></div>
           </div>
 
-          <div class="interaction-body">
-            <div class="conversation-column">
-              <div class="interaction-head">
-                <div>
-                  <p class="section-label">Manager / Employee Interactions</p>
-                  <h2 id="conversation-title">No active job</h2>
-                </div>
-                <p class="muted" id="conversation-state">Select a job and coach your employee toward your desired outcome.</p>
-              </div>
-
-              <div class="timeline" id="timeline"></div>
-            </div>
+          <!-- Issue #347 R1: pizza tracker. Hidden when the active job
+               declares no phases. Populated by renderTracker() in script.js. -->
+          <div class="tracker" id="tracker" aria-label="Job progress" hidden>
+            <div class="tracker-rows" id="tracker-rows"></div>
+            <div class="tracker-note" id="tracker-note" hidden></div>
+          </div>
 
-            <div class="manager-tools">
-              <div class="template-row">
-                <span class="section-label">Manager Templates</span>
-                <div class="template-chips" id="manager-templates"></div>
-              </div>
+          <div class="progress" id="progress">
+            <span class="stage" id="stage">Getting started…</span>
+            <span class="latest" id="latest"></span>
+          </div>
 
-              <label class="composer-label" for="manager-message">Coach your employee toward your desired outcome.</label>
-              <textarea id="manager-message" class="composer" placeholder='Use FRAIM job "marketing-content-creation" and include the audience, desired outcome, and any constraints.'></textarea>
+          <div class="messages" id="messages"></div>
 
-              <div class="composer-actions">
-                <button id="send-coaching" class="secondary-button" type="button" disabled>Send Coaching</button>
-              </div>
+          <div class="coach">
+            <div class="section-title">Coach the employee</div>
+            <textarea id="coach-text" placeholder="Tell the employee what to do next…"></textarea>
+            <div class="coach-actions">
+              <!-- Issue #347 R2: template picker. Hidden when the project
+                   has no manager-job templates. -->
+              <button class="ghost" type="button" id="template-picker-btn" aria-haspopup="menu" aria-expanded="false" hidden>Use a template ▾</button>
+              <button class="send-button" type="button" id="send" disabled>Send</button>
+              <div class="template-popover" id="template-popover" role="menu" hidden></div>
             </div>
+            <!-- Issue #347 R4: run-level totals. Discoverable, not dominating.
+                 Populated by renderTotals() each poll tick. -->
+            <div class="totals" id="totals" aria-label="Run totals" hidden></div>
           </div>
+
+          <details class="micro" id="micro-manage">
+            <summary>Micro-manage — raw host details</summary>
+            <pre class="micro-log" id="micro-log"></pre>
+          </details>
         </div>
+      </main>
+    </div>
 
-        <details class="card micro-manage" id="micro-manage">
-          <summary>Micro-manage</summary>
-          <div class="micro-manage-body" id="raw-history"></div>
-        </details>
-      </section>
-    </main>
+    <p class="status-line" id="status-line" role="status" aria-live="polite"></p>
   </div>
 
-  <template id="timeline-message-template">
-    <article class="message">
-      <div class="message-meta">
-        <span class="message-role"></span>
-        <time class="message-time"></time>
+  <!-- Modal: New Job -->
+  <div class="modal-backdrop" id="modal" role="dialog" aria-modal="true" hidden>
+    <div class="modal">
+
+      <div id="step1">
+        <div class="modal-header">
+          <h2>What should the employee work on?</h2>
+          <p>Pick one job. You can always start a new job for different work.</p>
+        </div>
+        <div class="modal-body">
+          <input class="search" type="text" placeholder="Search jobs…" id="job-search">
+          <div id="job-catalog"></div>
+        </div>
+        <div class="modal-footer">
+          <span class="left" id="job-pick-status">Choose a job to continue</span>
+          <div class="right">
+            <button class="ghost" type="button" id="cancel1">Cancel</button>
+            <button class="send-button" type="button" id="next1" disabled>Next →</button>
+          </div>
+        </div>
       </div>
-      <p class="message-text"></p>
-    </article>
-  </template>
+
+      <div id="step2" class="step2" hidden>
+        <div class="modal-header">
+          <h2>Tell the employee what you need</h2>
+          <p>A few sentences is enough. The employee will ask if anything is unclear.</p>
+        </div>
+        <div class="modal-body">
+          <div class="assigned-job">
+            <div class="label">Assigned job</div>
+            <div class="name" id="picked-name"></div>
+            <div class="desc" id="picked-desc"></div>
+          </div>
+          <textarea id="instructions" placeholder="What outcome do you want? Any context the employee should know?"></textarea>
+          <div class="employee-line">
+            <span class="employee-label">Employee:</span>
+            <select id="employee-select" class="employee-select"></select>
+          </div>
+        </div>
+        <div class="modal-footer">
+          <span class="left">You can coach the employee with more detail after they start.</span>
+          <div class="right">
+            <button class="ghost" type="button" id="back2">← Back</button>
+            <button class="send-button" type="button" id="start" disabled>Start</button>
+          </div>
+        </div>
+      </div>
+
+    </div>
+  </div>
 
   <script src="./script.js"></script>
 </body>