fraim-framework 2.0.173 → 2.0.175

package/dist/src/cli/commands/cleanup-artifacts.js

@@ -21,6 +21,7 @@ function runCleanupArtifactsCommand(options) {
     process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
 }
 exports.cleanupArtifactsCommand = new commander_1.Command('cleanup-artifacts')
+    .alias('cleanup-artifact')
     .description('Evaluate and optionally apply artifact retention cleanup for the current FRAIM workspace')
     .option('--user <email>', 'Active user email used only for user-scoped cleanup categories')
     .option('--workspace-root <path>', 'Workspace root containing fraim/config.json')

package/dist/src/cli/setup/ide-detector.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.expandPath = exports.findIDEByName = exports.getAllSupportedIDEs = exports.detectInstalledIDEs = exports.IDE_CONFIGS = void 0;
+exports.expandPath = exports.findIDEByName = exports.getAllSupportedIDEs = exports.detectInstalledIDEs = exports.CLI_PROBE_CONFIGTYPES = exports.IDE_CONFIGS = void 0;
 exports.getAdapterConfigType = getAdapterConfigType;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -71,9 +71,9 @@ const detectGeminiCli = () => {
 };
 const detectGeminiSurface = () => {
     const paths = [
-        '~/.gemini',
-        '~/AppData/Roaming/gemini',
-        '~/.config/gemini'
+        '~/.gemini/settings.json',
+        '~/AppData/Roaming/gemini/settings.json',
+        '~/.config/gemini/settings.json'
     ];
     return checkMultiplePaths(paths);
 };
@@ -103,7 +103,8 @@ exports.IDE_CONFIGS = [
         alternativePaths: [
             '~/.claude/settings.json'
         ],
-        description: 'Anthropic Claude Code local surfaces (CLI and Desktop Code tab)'
+        description: 'Anthropic Claude Code local surfaces (CLI and Desktop Code tab)',
+        downloadUrl: 'https://claude.ai/code',
     },
     {
         name: 'Claude Desktop / Cowork',
@@ -116,7 +117,8 @@ exports.IDE_CONFIGS = [
         alternativePaths: [
             '~/Library/Application Support/Claude/claude_desktop_config.json'
         ],
-        description: 'Anthropic Claude Desktop chat and Cowork surfaces'
+        description: 'Anthropic Claude Desktop chat and Cowork surfaces',
+        downloadUrl: 'https://claude.ai/download',
     },
     {
         name: 'Antigravity',
@@ -125,7 +127,8 @@ exports.IDE_CONFIGS = [
         configType: 'standard',
         invocationProfile: 'cursor-mention',
         detectMethod: () => fs_1.default.existsSync(expandPath('~/.gemini/antigravity')),
-        description: 'Google Gemini Antigravity IDE'
+        description: 'Google Gemini Antigravity IDE',
+        downloadUrl: 'https://deepmind.google/technologies/gemini/',
     },
     {
         name: 'Gemini CLI',
@@ -140,7 +143,8 @@ exports.IDE_CONFIGS = [
             '~/AppData/Roaming/gemini/settings.json',
             '~/.config/gemini/settings.json'
         ],
-        description: 'Google Gemini CLI local settings'
+        description: 'Google Gemini CLI local settings',
+        downloadUrl: 'https://github.com/google-gemini/gemini-cli',
     },
     {
         name: 'Kiro',
@@ -149,7 +153,8 @@ exports.IDE_CONFIGS = [
         configType: 'kiro',
         invocationProfile: 'kiro-hashtag',
         detectMethod: () => fs_1.default.existsSync(expandPath('~/.kiro')),
-        description: 'Kiro AI-powered IDE'
+        description: 'Kiro AI-powered IDE',
+        downloadUrl: 'https://kiro.dev/',
     },
     {
         name: 'Cursor',
@@ -164,7 +169,8 @@ exports.IDE_CONFIGS = [
             '~/AppData/Roaming/Cursor/mcp.json',
             '~/.config/Cursor/mcp.json'
         ],
-        description: 'Cursor AI code editor'
+        description: 'Cursor AI code editor',
+        downloadUrl: 'https://cursor.com/',
     },
     {
         name: 'VSCode',
@@ -182,7 +188,8 @@ exports.IDE_CONFIGS = [
             '~/AppData/Roaming/Code/User/mcp.json',
             '~/.config/Code/User/mcp.json'
         ],
-        description: 'Visual Studio Code'
+        description: 'Visual Studio Code',
+        downloadUrl: 'https://code.visualstudio.com/',
     },
     {
         name: 'Codex',
@@ -191,7 +198,8 @@ exports.IDE_CONFIGS = [
         configType: 'codex',
         invocationProfile: 'codex-skill',
         detectMethod: detectCodexSurface,
-        description: 'Codex AI development environment'
+        description: 'Codex AI development environment',
+        downloadUrl: 'https://github.com/openai/codex',
     },
     {
         name: 'Grok',
@@ -202,7 +210,8 @@ exports.IDE_CONFIGS = [
         detectMethod: detectGrokSurface,
         supportsConfigBootstrap: true,
         aliases: ['grok', 'grok-cli', 'grok cli', 'grok build'],
-        description: 'xAI Grok Build CLI local settings'
+        description: 'xAI Grok Build CLI local settings',
+        downloadUrl: 'https://x.ai/grok',
     },
     {
         name: 'Windsurf',
@@ -216,7 +225,8 @@ exports.IDE_CONFIGS = [
             '~/AppData/Roaming/Windsurf/mcp_config.json',
             '~/.config/windsurf/mcp_config.json'
         ],
-        description: 'Codeium Windsurf IDE'
+        description: 'Codeium Windsurf IDE',
+        downloadUrl: 'https://windsurf.com/',
     }
 ];
 const findBestConfigPath = (ide) => {
@@ -236,6 +246,8 @@ const _cachedIDEs = new Map();
 const _cacheTimestamps = new Map();
 const _cacheHomeDirs = new Map();
 const DETECT_CACHE_TTL_MS = 5000;
+/** configTypes that require a binary probe in cli-runnable mode; config folder alone is insufficient. */
+exports.CLI_PROBE_CONFIGTYPES = new Set(['claude-code', 'codex', 'grok', 'gemini-cli']);
 const isDetectedForMode = (ide, mode) => {
     if (mode === 'cli-runnable') {
         switch (ide.configType) {

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

@@ -175,7 +175,13 @@ function normalizeRows(rows) {
     }));
 }
 function buildRunnableAgentSurfaces() {
-    const ides = (0, ide_detector_1.detectInstalledIDEs)('cli-runnable');
+    // GUI agents (Claude Desktop, VSCode, Cursor, Windsurf, Kiro) are detected by config-surface:
+    // their config folder is sufficient evidence of installation.
+    // CLI agents require a binary on PATH; a config folder alone does not mean the agent is
+    // runnable, so they are gated through cli-runnable as well.
+    const configSurface = (0, ide_detector_1.detectInstalledIDEs)('config-surface');
+    const cliRunnableTypes = new Set((0, ide_detector_1.detectInstalledIDEs)('cli-runnable').map((ide) => ide.configType));
+    const ides = configSurface.filter((ide) => !ide_detector_1.CLI_PROBE_CONFIGTYPES.has(ide.configType) || cliRunnableTypes.has(ide.configType));
     const hints = (0, ide_global_integration_1.describeOnboardingInvocationSurfaces)(ides);
     return ides.map((ide, index) => ({
         id: ide.configType,
@@ -426,6 +432,13 @@ class FirstRunSessionService {
     getSession() {
         this.detectRowsOnLoad();
         this.persist();
+        const detectedNames = new Set((this.state.setupResult?.configuredSurfaces ?? []).map((s) => s.name));
+        const supportedAgents = ide_detector_1.IDE_CONFIGS
+            .map((ide) => ({
+            name: ide.name,
+            detected: detectedNames.has(ide.name),
+            downloadUrl: ide.downloadUrl ?? null,
+        }));
         return {
             state: this.state,
             rows: this.state.rows,
@@ -435,6 +448,7 @@ class FirstRunSessionService {
             requestToken: this.requestToken,
             agentOptions: types_1.FIRST_RUN_AGENT_OPTIONS,
             currentAgentId: this.state.agentId,
+            supportedAgents,
         };
     }
     respond(message, ok) {

package/dist/src/local-mcp-server/artifact-retention-cleanup.js

@@ -8,6 +8,7 @@ exports.resolveArtifactRetentionConfig = resolveArtifactRetentionConfig;
 exports.runArtifactCleanup = runArtifactCleanup;
 exports.planArtifactCleanup = planArtifactCleanup;
 const node_fs_1 = __importDefault(require("node:fs"));
+const node_child_process_1 = require("node:child_process");
 const node_path_1 = __importDefault(require("node:path"));
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 exports.ARTIFACT_RETENTION_CATEGORIES = [
@@ -96,6 +97,41 @@ function fileMtime(absolutePath) {
         return undefined;
     }
 }
+function parseDate(value) {
+    if (!value)
+        return undefined;
+    const parsed = new Date(value);
+    return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+}
+function loadGitLastChangeDates(workspaceRoot, relativeDir) {
+    const dates = new Map();
+    try {
+        const output = (0, node_child_process_1.execFileSync)('git', ['log', '--format=__FRAIM_CLEANUP_DATE__%cI', '--name-only', '--', relativeDir], {
+            cwd: workspaceRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 10_000,
+            maxBuffer: 80 * 1024 * 1024,
+        });
+        let currentDate;
+        for (const rawLine of output.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (!line)
+                continue;
+            if (line.startsWith('__FRAIM_CLEANUP_DATE__')) {
+                currentDate = parseDate(line.slice('__FRAIM_CLEANUP_DATE__'.length));
+                continue;
+            }
+            const relativePath = line.replace(/\\/g, '/');
+            if (currentDate && !dates.has(relativePath))
+                dates.set(relativePath, currentDate);
+        }
+    }
+    catch {
+        return new Map();
+    }
+    return dates;
+}
 function readFrontmatter(content) {
     const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
     if (!match)
@@ -124,6 +160,10 @@ function synthesizedDate(absolutePath) {
 function userScoped(fileName, activeUserEmail) {
     return fileName.startsWith(`${activeUserEmail}-`);
 }
+function evidenceEligibilityDate(workspaceRoot, absolutePath, gitDates) {
+    const relativePath = normalizeRelative(workspaceRoot, absolutePath);
+    return gitDates.get(relativePath) ?? fileMtime(absolutePath);
+}
 function collectCandidates(workspaceRoot, activeUserEmail) {
     const candidates = [];
     const add = (category, absolutePath, eligible, reason, eligibilityDate) => {
@@ -155,23 +195,26 @@ function collectCandidates(workspaceRoot, activeUserEmail) {
             add('retrospectives', filePath, false, 'Retrospective has no synthesized frontmatter.');
     }
     const evidenceDir = node_path_1.default.join(workspaceRoot, 'docs', 'evidence');
+    const evidenceGitDates = loadGitLastChangeDates(workspaceRoot, 'docs/evidence');
     for (const filePath of listFiles(evidenceDir)) {
         const fileName = node_path_1.default.basename(filePath);
         const isMarkdown = fileName.endsWith('.md');
         const isJson = fileName.endsWith('.json');
+        const eligibilityDate = evidenceEligibilityDate(workspaceRoot, filePath, evidenceGitDates);
         if (fileName.includes('cleanup-manifest') || fileName.includes('cleanup_manifest')) {
-            if (!isMarkdown && !isJson)
-                continue;
-            add('cleanup_manifests', filePath, true, 'Cleanup manifest file.', fileMtime(filePath));
+            if (isMarkdown || isJson) {
+                add('cleanup_manifests', filePath, true, 'Cleanup manifest file.', eligibilityDate);
+            }
+            else {
+                add('evidence', filePath, true, 'Evidence file.', eligibilityDate);
+            }
             continue;
         }
-        if (!isMarkdown)
-            continue;
         if (fileName.endsWith('-feedback.md')) {
-            add('feedback', filePath, true, 'Feedback evidence file.', fileMtime(filePath));
+            add('feedback', filePath, true, 'Feedback evidence file.', eligibilityDate);
             continue;
         }
-        add('evidence', filePath, true, 'Evidence file.', fileMtime(filePath));
+        add('evidence', filePath, true, 'Evidence file.', eligibilityDate);
     }
     return candidates;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.173",
+  "version": "2.0.175",
   "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/script.js

@@ -13,6 +13,7 @@
     configureError: null,
   };
 
+
   const STEP_LABELS = {
     prereqs: 'Prerequisites',
     agents: 'Local Agents',
@@ -86,15 +87,6 @@
     return configuredSurfaces().some((surface) => surface && (surface.id === opt.id || surface.name === opt.label));
   }
 
-  function readyAgentLabels() {
-    const labels = new Set();
-    for (const agent of readyAgents()) labels.add(agent.label);
-    for (const surface of configuredSurfaces()) {
-      if (surface && surface.name) labels.add(surface.name);
-    }
-    return Array.from(labels);
-  }
-
   function detectedAgentCount() {
     const setupResult = state.session && state.session.state ? state.session.state.setupResult : null;
     return (setupResult && setupResult.detectedSurfaceCount) || readyAgents().length;
@@ -216,60 +208,74 @@
     h.textContent = 'Locally installed AI agents';
     pane.appendChild(h);
 
+    const anyDetected = detectedAgentCount() > 0;
     const p = document.createElement('p');
     p.className = 'pane-copy';
-    p.textContent = detectedAgentCount() > 0
-      ? 'At least one local AI agent is ready. You can add more agents or continue to configure FRAIM.'
-      : 'No problem, we will install AI agents next.';
+    p.textContent = anyDetected
+      ? 'An AI tool is ready. You can add more or continue to configure FRAIM.'
+      : 'Install any of the AI tools below, then click Rescan once it is running.';
     pane.appendChild(p);
 
-    const readyLabels = readyAgentLabels();
-    if (readyLabels.length > 0) {
-      const readyList = document.createElement('div');
-      readyList.className = 'ready-strip';
-      readyList.setAttribute('data-testid', 'ready-agents');
-      readyList.textContent = `Already installed: ${readyLabels.join(', ')}`;
-      pane.appendChild(readyList);
-    } else {
-      const readyList = document.createElement('div');
-      readyList.className = 'ready-strip ready-strip--muted';
-      readyList.setAttribute('data-testid', 'ready-agents');
-      readyList.textContent = 'Already installed: none detected yet';
-      pane.appendChild(readyList);
-    }
+    // Server-driven list: session.supportedAgents contains every GUI-detectable IDE
+    // with detection status and download URL already resolved.
+    const agents = (state.session && state.session.supportedAgents) || [];
 
-    const grid = document.createElement('div');
-    grid.className = 'agent-grid';
-    const agentOptions = state.session.agentOptions || [];
-    for (const opt of agentOptions) {
-      const card = document.createElement('div');
-      card.className = 'user-type-card recruit-card';
-      card.setAttribute('data-agent-id', opt.id);
-      card.setAttribute('data-testid', `agent-card-${opt.id}`);
-      const agentReady = isAgentReady(opt);
-      const title = document.createElement('strong');
-      title.className = 'card-title';
-      title.textContent = opt.label;
-      const desc = document.createElement('p');
-      desc.className = 'card-desc';
-      desc.textContent = agentReady
-        ? 'Already installed and ready for FRAIM.'
-        : `Available to set up: install, sign in, and verify ${opt.label}.`;
-      const action = button(agentReady ? 'Ready' : 'Set up', 'secondary');
-      action.disabled = agentReady;
-      action.setAttribute('data-testid', `install-${opt.id}`);
-      action.addEventListener('click', () => openAgentModal(opt));
-      card.appendChild(title);
-      card.appendChild(desc);
-      card.appendChild(action);
-      grid.appendChild(card);
+    const list = document.createElement('ul');
+    list.className = 'agent-list';
+    list.setAttribute('data-testid', 'agent-list');
+
+    for (const agent of agents) {
+      const li = document.createElement('li');
+      li.className = 'agent-row' + (agent.detected ? ' agent-row--detected' : '');
+      li.setAttribute('data-testid', `agent-row-${agent.name.toLowerCase().replace(/\s+/g, '-')}`);
+
+      const nameSpan = document.createElement('span');
+      nameSpan.className = 'agent-row__name';
+      nameSpan.textContent = agent.name;
+
+      const actionSpan = document.createElement('span');
+      actionSpan.className = 'agent-row__action';
+
+      if (agent.detected) {
+        const badge = document.createElement('span');
+        badge.className = 'agent-badge agent-badge--installed';
+        badge.setAttribute('data-testid', `agent-installed-${agent.name.toLowerCase().replace(/\s+/g, '-')}`);
+        badge.textContent = 'Installed';
+        actionSpan.appendChild(badge);
+      } else if (agent.downloadUrl) {
+        const link = document.createElement('a');
+        link.className = 'agent-download-link';
+        link.href = agent.downloadUrl;
+        link.target = '_blank';
+        link.rel = 'noopener noreferrer';
+        link.textContent = 'Download';
+        link.setAttribute('data-testid', `agent-download-${agent.name.toLowerCase().replace(/\s+/g, '-')}`);
+        actionSpan.appendChild(link);
+      }
+
+      li.appendChild(nameSpan);
+      li.appendChild(actionSpan);
+      list.appendChild(li);
     }
 
-    const byoa = document.createElement('div');
-    byoa.className = 'user-type-card recruit-card byoa-card';
-    byoa.innerHTML = '<strong class="card-title">Bring Your Own Agent</strong><p class="card-desc">Use Cursor, Windsurf, Kiro, VS Code, or another supported local AI tool. If you install a new agent later and want FRAIM to use it, run this command from your project.</p><div class="cmd-block">npx fraim add-ide</div>';
-    grid.appendChild(byoa);
-    pane.appendChild(grid);
+    pane.appendChild(list);
+
+    const otherNote = document.createElement('p');
+    otherNote.className = 'pane-copy';
+    otherNote.innerHTML = 'Using a different tool? Run <code>npx fraim add-ide</code> from your project directory after setup.';
+    pane.appendChild(otherNote);
+
+    const rescanBtn = button('Rescan installed tools', 'ghost');
+    rescanBtn.setAttribute('data-testid', 'rescan-agents');
+    rescanBtn.addEventListener('click', async () => {
+      rescanBtn.disabled = true;
+      rescanBtn.textContent = 'Scanning...';
+      try { await loadSession(false); } finally {
+        state.activeStep = 'agents';
+        render();
+      }
+    });
+    pane.appendChild(rescanBtn);
 
     const done = button('Next', 'primary');
     done.setAttribute('data-testid', 'done-installing-agents');

package/public/first-run/styles.css

@@ -516,6 +516,53 @@ body {
   grid-template-columns: repeat(2, minmax(0, 1fr));
   gap: 12px;
 }
+
+/* Compact server-driven agent list */
+.agent-list {
+  list-style: none;
+  margin: 0 0 12px;
+  padding: 0;
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  overflow: hidden;
+}
+.agent-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--line);
+  background: var(--surface);
+  gap: 12px;
+}
+.agent-row:last-child { border-bottom: 0; }
+.agent-row--detected { background: var(--accent-soft); }
+.agent-row__name {
+  font-size: 14px;
+  font-weight: 500;
+  color: var(--text);
+  flex: 1;
+}
+.agent-row--detected .agent-row__name { color: var(--accent-strong); }
+.agent-row__action { flex-shrink: 0; }
+.agent-badge {
+  font-size: 12px;
+  font-weight: 600;
+  padding: 3px 10px;
+  border-radius: 20px;
+}
+.agent-badge--installed {
+  background: var(--accent);
+  color: #fff;
+}
+.agent-download-link {
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--accent-strong);
+  text-decoration: none;
+}
+.agent-download-link:hover { text-decoration: underline; }
+
 .ready-strip {
   background: var(--accent-soft);
   border: 1px solid var(--accent);