fraim-framework 2.0.127 → 2.0.128

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

@@ -1,9 +1,31 @@
 "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 = void 0;
-exports.createDefaultStepStates = createDefaultStepStates;
+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',
@@ -11,6 +33,7 @@ exports.FIRST_RUN_AGENT_OPTIONS = [
         detectAliases: ['claude-code', 'claude code', 'claude'],
         loginCommand: 'claude',
         launchCommand: 'claude',
+        installPackage: '@anthropic-ai/claude-code',
     },
     {
         id: 'codex',
@@ -18,6 +41,7 @@ exports.FIRST_RUN_AGENT_OPTIONS = [
         detectAliases: ['codex'],
         loginCommand: 'codex login',
         launchCommand: 'codex',
+        installPackage: '@openai/codex',
     },
     {
         id: 'gemini-cli',
@@ -25,16 +49,49 @@ exports.FIRST_RUN_AGENT_OPTIONS = [
         detectAliases: ['gemini-cli', 'gemini cli', 'gemini'],
         loginCommand: 'gemini',
         launchCommand: 'gemini',
+        installPackage: '@google/gemini-cli',
     },
 ];
-function createDefaultStepStates() {
-    return {
-        welcome: 'pending',
-        prereqs: 'pending',
-        agent: 'pending',
-        configure: 'pending',
-        project: 'pending',
-        launch: 'pending',
-        finish: 'pending',
-    };
+/**
+ * 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/package.json

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

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

@@ -0,0 +1,89 @@
+/**
+ * R6.1 — unified error-frame renderer.
+ *
+ * Exposes a single function `renderErrorFrame(frame, onAction)` which returns
+ * a DOM Node containing exactly:
+ *   - "What we tried" sentence
+ *   - "What happened" verbatim stderr (last 12 lines, with a Show-full toggle
+ *     that surfaces the rest on demand)
+ *   - Up to three actions in fixed order (Retry / Try alternative / Skip and continue)
+ *
+ * The same renderer must be lifted into public/ai-hub/ in the v2 follow-up
+ * (issue #355, "Hub-side error-frame adoption") so bootstrap and Hub share
+ * one frame across surfaces.
+ */
+(function () {
+  'use strict';
+
+  function escapeText(text) {
+    if (typeof text !== 'string') return '';
+    return text;
+  }
+
+  function truncateToLastLines(text, lineCount) {
+    if (typeof text !== 'string') return { visible: '', hidden: '' };
+    const lines = text.split(/\r?\n/);
+    if (lines.length <= lineCount) {
+      return { visible: text, hidden: '' };
+    }
+    const visible = lines.slice(-lineCount).join('\n');
+    const hidden = lines.slice(0, -lineCount).join('\n');
+    return { visible, hidden };
+  }
+
+  function renderErrorFrame(frame, onAction) {
+    const root = document.createElement('div');
+    root.className = 'error-frame';
+    root.setAttribute('data-testid', 'error-frame');
+    root.setAttribute('role', 'alert');
+
+    const whatTried = document.createElement('div');
+    whatTried.className = 'what-tried';
+    whatTried.setAttribute('data-testid', 'error-what-tried');
+    whatTried.textContent = escapeText(frame.whatTried || '');
+    root.appendChild(whatTried);
+
+    const { visible, hidden } = truncateToLastLines(frame.whatHappened || '', 12);
+    const whatHappened = document.createElement('pre');
+    whatHappened.className = 'what-happened';
+    whatHappened.setAttribute('data-testid', 'error-what-happened');
+    whatHappened.textContent = visible;
+    root.appendChild(whatHappened);
+
+    if (hidden) {
+      const showFull = document.createElement('button');
+      showFull.type = 'button';
+      showFull.className = 'show-full';
+      showFull.setAttribute('data-testid', 'error-show-full');
+      showFull.textContent = 'Show full output';
+      showFull.addEventListener('click', () => {
+        whatHappened.textContent = (hidden + '\n' + visible).trimEnd();
+        showFull.remove();
+      });
+      root.appendChild(showFull);
+    }
+
+    const actions = Array.isArray(frame.actions) ? frame.actions.slice(0, 3) : [];
+    const actionRow = document.createElement('div');
+    actionRow.className = 'actions';
+    for (const action of actions) {
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.className = 'action';
+      btn.setAttribute('data-testid', 'error-action');
+      btn.setAttribute('data-action-id', action.id);
+      btn.setAttribute('data-variant', action.variant || 'secondary');
+      btn.textContent = action.label || action.id;
+      btn.addEventListener('click', () => {
+        if (typeof onAction === 'function') {
+          onAction(action);
+        }
+      });
+      actionRow.appendChild(btn);
+    }
+    root.appendChild(actionRow);
+    return root;
+  }
+
+  window.FraimErrorFrame = { render: renderErrorFrame };
+})();

package/public/first-run/index.html

@@ -1,221 +1,35 @@
-<!doctype html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>FRAIM First Run</title>
-  <style>
-    :root {
-      --bg: #f4efe5;
-      --panel: #fffdf8;
-      --ink: #1f2a1f;
-      --muted: #68736a;
-      --line: #d8d0c1;
-      --accent: #0f6b4d;
-      --accent-2: #d6efe4;
-      --error: #9f2d2d;
-    }
-    * { box-sizing: border-box; }
-    body {
-      margin: 0;
-      font-family: "Segoe UI", "Helvetica Neue", sans-serif;
-      color: var(--ink);
-      background:
-        radial-gradient(circle at top right, #efe7d7 0, transparent 32%),
-        linear-gradient(180deg, #f7f1e7 0%, var(--bg) 100%);
-    }
-    .shell {
-      min-height: 100vh;
-      display: grid;
-      grid-template-columns: 280px 1fr;
-    }
-    aside {
-      padding: 32px 24px;
-      border-right: 1px solid var(--line);
-      background: rgba(255, 253, 248, 0.72);
-      backdrop-filter: blur(8px);
-    }
-    main {
-      padding: 32px;
-    }
-    h1 {
-      margin: 0 0 8px;
-      font-size: 28px;
-    }
-    .lede {
-      margin: 0 0 20px;
-      color: var(--muted);
-      line-height: 1.5;
-    }
-    .steps {
-      list-style: none;
-      padding: 0;
-      margin: 24px 0 0;
-      display: grid;
-      gap: 10px;
-    }
-    .step {
-      border: 1px solid var(--line);
-      border-radius: 16px;
-      padding: 12px 14px;
-      background: #fff;
-    }
-    .step strong {
-      display: block;
-      margin-bottom: 4px;
-      font-size: 14px;
-    }
-    .step span {
-      color: var(--muted);
-      font-size: 13px;
-      text-transform: capitalize;
-    }
-    .step.active {
-      border-color: var(--accent);
-      background: var(--accent-2);
-    }
-    .card {
-      max-width: 860px;
-      background: var(--panel);
-      border: 1px solid var(--line);
-      border-radius: 24px;
-      padding: 28px;
-      box-shadow: 0 24px 64px rgba(49, 45, 32, 0.08);
-    }
-    .grid {
-      display: grid;
-      gap: 14px;
-      grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-      margin: 20px 0;
-    }
-    .agent-card, .stat {
-      border: 1px solid var(--line);
-      border-radius: 18px;
-      padding: 16px;
-      background: #fff;
-    }
-    .agent-card h3, .stat h3 {
-      margin: 0 0 8px;
-      font-size: 18px;
-    }
-    .agent-card p, .stat p {
-      margin: 0;
-      color: var(--muted);
-      line-height: 1.45;
-    }
-    .actions {
-      display: flex;
-      gap: 12px;
-      flex-wrap: wrap;
-      margin-top: 20px;
-    }
-    button, input[type="text"] {
-      font: inherit;
-    }
-    button {
-      border: 0;
-      border-radius: 999px;
-      padding: 12px 18px;
-      background: var(--accent);
-      color: #fff;
-      cursor: pointer;
-    }
-    button.secondary {
-      background: #fff;
-      color: var(--ink);
-      border: 1px solid var(--line);
-    }
-    button:disabled {
-      opacity: 0.6;
-      cursor: default;
-    }
-    label {
-      display: block;
-      margin: 18px 0 8px;
-      font-weight: 600;
-    }
-    .path-row {
-      display: flex;
-      gap: 12px;
-      flex-wrap: wrap;
-      margin-top: 12px;
-    }
-    #project-path {
-      flex: 1 1 440px;
-      min-width: 260px;
-      border: 1px solid var(--line);
-      border-radius: 14px;
-      padding: 12px 14px;
-      background: #fff;
-    }
-    pre {
-      margin: 18px 0 0;
-      padding: 16px;
-      border-radius: 18px;
-      background: #12201a;
-      color: #d8fbe8;
-      overflow: auto;
-      white-space: pre-wrap;
-      min-height: 88px;
-    }
-    .status {
-      margin-top: 18px;
-      padding: 14px 16px;
-      border-radius: 16px;
-      background: #fff;
-      border: 1px solid var(--line);
-      color: var(--muted);
-      line-height: 1.5;
-    }
-    .error {
-      border-color: #e7b8b8;
-      color: var(--error);
-      background: #fff5f5;
-    }
-    .prompt {
-      border: 1px dashed var(--accent);
-      border-radius: 20px;
-      padding: 18px;
-      margin-top: 18px;
-      background: #fcfffd;
-      font-size: 22px;
-      font-weight: 700;
-    }
-    a {
-      color: var(--accent);
-    }
-    @media (max-width: 860px) {
-      .shell {
-        grid-template-columns: 1fr;
-      }
-      aside {
-        border-right: 0;
-        border-bottom: 1px solid var(--line);
-      }
-      main {
-        padding: 20px;
-      }
-      .card {
-        padding: 22px;
-      }
-    }
-  </style>
-</head>
-<body>
-  <div class="shell">
-    <aside>
-      <h1>FRAIM First Run</h1>
-      <p class="lede">We’ll verify your machine, connect FRAIM to an AI agent, initialize your folder, and leave you with the exact next prompt.</p>
-      <ul id="steps" class="steps"></ul>
-    </aside>
-    <main>
-      <section class="card">
-        <div id="content"></div>
-        <div id="status" class="status">Loading first-run session…</div>
-        <pre id="details" hidden></pre>
-      </section>
-    </main>
-  </div>
-  <script src="/first-run/script.js"></script>
-</body>
-</html>
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>FRAIM Setup</title>
+  <link rel="stylesheet" href="/first-run/styles.css">
+</head>
+<body>
+  <main class="page">
+    <header class="page-header">
+      <h1>Set up FRAIM</h1>
+      <p class="lede" id="lede">We're getting your machine ready. Sit tight — we'll only need you for one step.</p>
+    </header>
+
+    <section class="card">
+      <ul class="checklist" id="checklist" data-testid="setup-checklist" aria-label="FRAIM setup checklist">
+        <!-- Skeleton rows shown until the async session-load completes.
+             Replaced wholesale by script.js once /api/first-run/session returns. -->
+        <li class="row skeleton-row" data-row-id="node" data-row-status="pending"><span class="icon" aria-hidden="true">·</span><span class="label">Node.js</span><span class="verb" data-testid="row-verb">checking…</span></li>
+        <li class="row skeleton-row" data-row-id="git" data-row-status="pending"><span class="icon" aria-hidden="true">·</span><span class="label">git</span><span class="verb" data-testid="row-verb">checking…</span></li>
+        <li class="row skeleton-row" data-row-id="agent" data-row-status="pending"><span class="icon" aria-hidden="true">·</span><span class="label">AI agent</span><span class="verb" data-testid="row-verb">checking…</span></li>
+        <li class="row skeleton-row" data-row-id="agent-login" data-row-status="pending"><span class="icon" aria-hidden="true">·</span><span class="label">Sign in</span><span class="verb" data-testid="row-verb">checking…</span></li>
+        <li class="row skeleton-row" data-row-id="project" data-row-status="pending"><span class="icon" aria-hidden="true">·</span><span class="label">Project folder</span><span class="verb" data-testid="row-verb">checking…</span></li>
+      </ul>
+      <div class="actions">
+        <button id="primary-button" class="primary-button" data-testid="primary-button">Set up FRAIM</button>
+      </div>
+      <p class="status" id="status" role="status" aria-live="polite"></p>
+    </section>
+  </main>
+  <script src="/first-run/error-frame.js"></script>
+  <script src="/first-run/script.js"></script>
+</body>
+</html>