specsmd 0.1.22 → 0.1.24

package/lib/dashboard/tui/app.js

@@ -0,0 +1,175 @@
+const { createWatchRuntime } = require('../runtime/watch-runtime');
+const { createInitialUIState, cycleView, cycleRunFilter } = require('./store');
+const { formatDashboardText } = require('./renderer');
+
+function toDashboardError(error, defaultCode = 'DASHBOARD_ERROR') {
+  if (!error) {
+    return {
+      code: defaultCode,
+      message: 'Unknown dashboard error.'
+    };
+  }
+
+  if (typeof error === 'string') {
+    return {
+      code: defaultCode,
+      message: error
+    };
+  }
+
+  if (typeof error === 'object') {
+    return {
+      code: error.code || defaultCode,
+      message: error.message || 'Unknown dashboard error.',
+      details: error.details,
+      path: error.path,
+      hint: error.hint
+    };
+  }
+
+  return {
+    code: defaultCode,
+    message: String(error)
+  };
+}
+
+function createDashboardApp(deps) {
+  const {
+    React,
+    ink,
+    parseSnapshot,
+    workspacePath,
+    rootPath,
+    flow,
+    refreshMs,
+    watchEnabled,
+    initialSnapshot,
+    initialError
+  } = deps;
+
+  const { Box, Text, useApp, useInput } = ink;
+  const { useState, useEffect, useCallback } = React;
+
+  function DashboardApp() {
+    const { exit } = useApp();
+
+    const [snapshot, setSnapshot] = useState(initialSnapshot || null);
+    const [error, setError] = useState(initialError ? toDashboardError(initialError) : null);
+    const [ui, setUi] = useState(createInitialUIState());
+    const [lastRefreshAt, setLastRefreshAt] = useState(new Date().toISOString());
+    const [watchStatus, setWatchStatus] = useState(watchEnabled ? 'watching' : 'off');
+
+    const refresh = useCallback(async () => {
+      try {
+        const result = await parseSnapshot();
+
+        if (result?.ok) {
+          setSnapshot(result.snapshot || null);
+          setError(null);
+          setWatchStatus(watchEnabled ? 'watching' : 'off');
+        } else {
+          setError(toDashboardError(result?.error, 'PARSE_ERROR'));
+        }
+      } catch (refreshError) {
+        setError(toDashboardError(refreshError, 'REFRESH_FAILED'));
+      } finally {
+        setLastRefreshAt(new Date().toISOString());
+      }
+    }, [parseSnapshot, watchEnabled]);
+
+    useInput((input, key) => {
+      if ((key.ctrl && input === 'c') || input === 'q') {
+        exit();
+        return;
+      }
+
+      if (input === 'r') {
+        void refresh();
+        return;
+      }
+
+      if (input === 'h' || input === '?') {
+        setUi((previous) => ({ ...previous, showHelp: !previous.showHelp }));
+        return;
+      }
+
+      if (input === '1') {
+        setUi((previous) => ({ ...previous, view: 'runs' }));
+        return;
+      }
+
+      if (input === '2') {
+        setUi((previous) => ({ ...previous, view: 'overview' }));
+        return;
+      }
+
+      if (key.tab) {
+        setUi((previous) => ({ ...previous, view: cycleView(previous.view) }));
+        return;
+      }
+
+      if (input === 'f') {
+        setUi((previous) => ({ ...previous, runFilter: cycleRunFilter(previous.runFilter) }));
+      }
+    });
+
+    useEffect(() => {
+      void refresh();
+    }, [refresh]);
+
+    useEffect(() => {
+      if (!watchEnabled) {
+        return undefined;
+      }
+
+      const runtime = createWatchRuntime({
+        rootPath: rootPath || `${workspacePath}/.specs-fire`,
+        debounceMs: 250,
+        onRefresh: () => {
+          void refresh();
+        },
+        onError: (watchError) => {
+          setWatchStatus('reconnecting');
+          setError(toDashboardError(watchError, 'WATCH_ERROR'));
+        }
+      });
+
+      runtime.start();
+      const interval = setInterval(() => {
+        void refresh();
+      }, refreshMs);
+
+      return () => {
+        clearInterval(interval);
+        void runtime.close();
+      };
+    }, [watchEnabled, refreshMs, refresh, rootPath, workspacePath]);
+
+    const dashboardOutput = formatDashboardText({
+      snapshot,
+      error,
+      flow,
+      workspacePath,
+      view: ui.view,
+      runFilter: ui.runFilter,
+      watchEnabled,
+      watchStatus,
+      showHelp: ui.showHelp,
+      lastRefreshAt,
+      width: process.stdout.columns || 120
+    });
+
+    return React.createElement(
+      Box,
+      { flexDirection: 'column' },
+      React.createElement(Text, null, dashboardOutput)
+    );
+  }
+
+  return DashboardApp;
+}
+
+module.exports = {
+  createDashboardApp,
+  toDashboardError
+};

package/lib/dashboard/tui/components/error-banner.js

@@ -0,0 +1,35 @@
+const { truncate } = require('./header');
+
+function renderErrorLines(error, width, watchEnabled = true) {
+  if (!error) {
+    return [];
+  }
+
+  const lines = [
+    `[error:${error.code || 'UNKNOWN'}] ${error.message || 'Unknown error'}`
+  ];
+
+  if (error.details) {
+    lines.push(`details: ${error.details}`);
+  }
+
+  if (error.path) {
+    lines.push(`path: ${error.path}`);
+  }
+
+  if (error.hint) {
+    lines.push(`hint: ${error.hint}`);
+  }
+
+  if (watchEnabled) {
+    lines.push('Dashboard keeps running and will recover after the next valid update.');
+  } else {
+    lines.push('Fix the error and rerun dashboard.');
+  }
+
+  return lines.map((line) => truncate(line, width));
+}
+
+module.exports = {
+  renderErrorLines
+};

package/lib/dashboard/tui/components/header.js

@@ -0,0 +1,62 @@
+function truncate(value, width) {
+  const text = String(value);
+  if (!Number.isFinite(width) || width <= 0 || text.length <= width) {
+    return text;
+  }
+
+  if (width <= 3) {
+    return text.slice(0, width);
+  }
+
+  return `${text.slice(0, width - 3)}...`;
+}
+
+function formatTime(value) {
+  if (!value) {
+    return 'n/a';
+  }
+
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    return value;
+  }
+
+  return date.toLocaleTimeString();
+}
+
+function renderHeaderLines(params) {
+  const {
+    snapshot,
+    flow,
+    workspacePath,
+    view,
+    runFilter,
+    watchEnabled,
+    watchStatus,
+    lastRefreshAt,
+    width
+  } = params;
+
+  const projectName = snapshot?.project?.name || 'Unnamed FIRE project';
+  const topLine = `specsmd dashboard | ${flow.toUpperCase()} | ${projectName}`;
+  const subLine = [
+    `path: ${workspacePath}`,
+    `updated: ${formatTime(lastRefreshAt)}`,
+    `watch: ${watchEnabled ? watchStatus : 'off'}`,
+    `view: ${view}`,
+    `filter: ${runFilter}`
+  ].join(' | ');
+
+  const horizontal = '-'.repeat(Math.max(20, Math.min(width || 120, 120)));
+
+  return [
+    truncate(topLine, width),
+    truncate(subLine, width),
+    truncate(horizontal, width)
+  ];
+}
+
+module.exports = {
+  renderHeaderLines,
+  truncate
+};

package/lib/dashboard/tui/components/help-footer.js

@@ -0,0 +1,15 @@
+const { truncate } = require('./header');
+
+function renderHelpLines(showHelp, width) {
+  if (!showHelp) {
+    return [truncate('Press h to show keyboard shortcuts.', width)];
+  }
+
+  return [
+    truncate('Keys: q quit | r refresh | h/? toggle help | tab cycle view | 1 runs | 2 overview | f cycle run filter', width)
+  ];
+}
+
+module.exports = {
+  renderHelpLines
+};

package/lib/dashboard/tui/components/stats-strip.js

@@ -0,0 +1,35 @@
+const { truncate } = require('./header');
+
+function safePercent(part, total) {
+  if (!total || total <= 0) {
+    return 0;
+  }
+
+  return Math.round((part / total) * 100);
+}
+
+function renderStatsLines(snapshot, width) {
+  if (!snapshot?.initialized) {
+    return [truncate('stats: waiting for .specs-fire/state.yaml initialization', width)];
+  }
+
+  const stats = snapshot.stats;
+  const workItemProgress = `${stats.completedWorkItems}/${stats.totalWorkItems}`;
+  const workItemPct = safePercent(stats.completedWorkItems, stats.totalWorkItems);
+
+  const intentProgress = `${stats.completedIntents}/${stats.totalIntents}`;
+  const intentPct = safePercent(stats.completedIntents, stats.totalIntents);
+
+  const line = [
+    `Intents ${intentProgress} (${intentPct}%)`,
+    `Work items ${workItemProgress} (${workItemPct}%)`,
+    `Runs ${stats.activeRunsCount} active / ${stats.completedRuns} completed`,
+    `Blocked ${stats.blockedWorkItems}`
+  ].join(' | ');
+
+  return [truncate(line, width)];
+}
+
+module.exports = {
+  renderStatsLines
+};

package/lib/dashboard/tui/renderer.js

@@ -0,0 +1,78 @@
+const { renderHeaderLines, truncate } = require('./components/header');
+const { renderStatsLines } = require('./components/stats-strip');
+const { renderErrorLines } = require('./components/error-banner');
+const { renderHelpLines } = require('./components/help-footer');
+const { renderRunsViewLines } = require('./views/runs-view');
+const { renderOverviewViewLines } = require('./views/overview-view');
+
+function normalizeWidth(width) {
+  if (!Number.isFinite(width)) {
+    return 120;
+  }
+
+  return Math.max(40, Math.min(Math.floor(width), 180));
+}
+
+function buildDashboardLines(params) {
+  const {
+    snapshot,
+    error,
+    flow,
+    workspacePath,
+    view,
+    runFilter,
+    watchEnabled,
+    watchStatus,
+    showHelp,
+    lastRefreshAt,
+    width
+  } = params;
+
+  const safeWidth = normalizeWidth(width);
+  const lines = [];
+
+  lines.push(...renderHeaderLines({
+    snapshot,
+    flow,
+    workspacePath,
+    view,
+    runFilter,
+    watchEnabled,
+    watchStatus,
+    lastRefreshAt,
+    width: safeWidth
+  }));
+
+  if (snapshot) {
+    lines.push(...renderStatsLines(snapshot, safeWidth));
+    lines.push('');
+  }
+
+  if (error) {
+    lines.push(...renderErrorLines(error, safeWidth, watchEnabled));
+    lines.push('');
+  }
+
+  if (!snapshot) {
+    lines.push(truncate('No snapshot available yet. Waiting for refresh...', safeWidth));
+  } else if (view === 'overview') {
+    lines.push(...renderOverviewViewLines(snapshot, safeWidth));
+  } else {
+    lines.push(...renderRunsViewLines(snapshot, runFilter, safeWidth));
+  }
+
+  lines.push('');
+  lines.push(...renderHelpLines(showHelp, safeWidth));
+
+  return lines;
+}
+
+function formatDashboardText(params) {
+  return buildDashboardLines(params).join('\n');
+}
+
+module.exports = {
+  buildDashboardLines,
+  formatDashboardText,
+  normalizeWidth
+};

package/lib/dashboard/tui/store.js

@@ -0,0 +1,30 @@
+function createInitialUIState() {
+  return {
+    view: 'runs',
+    runFilter: 'all',
+    showHelp: true
+  };
+}
+
+function cycleView(current) {
+  if (current === 'runs') {
+    return 'overview';
+  }
+  return 'runs';
+}
+
+function cycleRunFilter(current) {
+  if (current === 'all') {
+    return 'active';
+  }
+  if (current === 'active') {
+    return 'completed';
+  }
+  return 'all';
+}
+
+module.exports = {
+  createInitialUIState,
+  cycleView,
+  cycleRunFilter
+};

package/lib/dashboard/tui/views/overview-view.js

@@ -0,0 +1,61 @@
+const { truncate } = require('../components/header');
+
+const STANDARD_TYPES = [
+  'constitution',
+  'tech-stack',
+  'coding-standards',
+  'testing-standards',
+  'system-architecture'
+];
+
+function renderOverviewViewLines(snapshot, width) {
+  const lines = ['Overview'];
+
+  if (!snapshot?.initialized) {
+    lines.push('FIRE project folder exists but state.yaml is missing.');
+    lines.push('Run initialization and the overview will appear automatically.');
+    return lines.map((line) => truncate(line, width));
+  }
+
+  const project = snapshot.project || {};
+  const workspace = snapshot.workspace || {};
+
+  lines.push(`Project: ${project.name || 'Unknown'} | FIRE version: ${project.fireVersion || snapshot.version || '0.0.0'}`);
+  lines.push(`Workspace: ${workspace.type || 'unknown'} / ${workspace.structure || 'unknown'} | autonomy: ${workspace.autonomyBias || 'unknown'} | run scope pref: ${workspace.runScopePreference || 'unknown'}`);
+  lines.push('');
+
+  lines.push('Intent Summary');
+  lines.push(`  total: ${snapshot.stats.totalIntents} | completed: ${snapshot.stats.completedIntents} | in_progress: ${snapshot.stats.inProgressIntents} | pending: ${snapshot.stats.pendingIntents} | blocked: ${snapshot.stats.blockedIntents}`);
+  lines.push('');
+
+  lines.push('Work Item Summary');
+  lines.push(`  total: ${snapshot.stats.totalWorkItems} | completed: ${snapshot.stats.completedWorkItems} | in_progress: ${snapshot.stats.inProgressWorkItems} | pending: ${snapshot.stats.pendingWorkItems} | blocked: ${snapshot.stats.blockedWorkItems}`);
+  lines.push('');
+
+  const standardSet = new Set((snapshot.standards || []).map((item) => item.type));
+  lines.push('Standards');
+  for (const type of STANDARD_TYPES) {
+    const marker = standardSet.has(type) ? '[x]' : '[ ]';
+    lines.push(`  ${marker} ${type}.md`);
+  }
+
+  lines.push('');
+  lines.push('Top Intents');
+
+  const intents = (snapshot.intents || []).slice(0, 6);
+  if (intents.length === 0) {
+    lines.push('  - none');
+  } else {
+    for (const intent of intents) {
+      const totalWorkItems = (intent.workItems || []).length;
+      const completedWorkItems = (intent.workItems || []).filter((item) => item.status === 'completed').length;
+      lines.push(`  - ${intent.id}: ${intent.status} (${completedWorkItems}/${totalWorkItems} work items completed)`);
+    }
+  }
+
+  return lines.map((line) => truncate(line, width));
+}
+
+module.exports = {
+  renderOverviewViewLines
+};

package/lib/dashboard/tui/views/runs-view.js

@@ -0,0 +1,98 @@
+const { truncate } = require('../components/header');
+
+function safeArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function formatRunProgress(run) {
+  const workItems = safeArray(run.workItems);
+  const total = workItems.length;
+  const completed = workItems.filter((item) => item.status === 'completed').length;
+  const inProgress = workItems.filter((item) => item.status === 'in_progress').length;
+  return `${completed}/${total} completed${inProgress > 0 ? `, ${inProgress} in_progress` : ''}`;
+}
+
+function renderActiveRunLines(activeRuns, width) {
+  const lines = ['Active Runs'];
+  if (!activeRuns || activeRuns.length === 0) {
+    lines.push('  - none');
+    return lines.map((line) => truncate(line, width));
+  }
+
+  for (const run of activeRuns) {
+    const currentItem = run.currentItem || 'n/a';
+    const artifacts = [
+      run.hasPlan ? 'plan' : null,
+      run.hasWalkthrough ? 'walkthrough' : null,
+      run.hasTestReport ? 'test-report' : null
+    ].filter(Boolean).join(', ') || 'no artifacts yet';
+
+    lines.push(`  - ${run.id} [${run.scope}] current: ${currentItem}`);
+    lines.push(`    progress: ${formatRunProgress(run)} | artifacts: ${artifacts}`);
+  }
+
+  return lines.map((line) => truncate(line, width));
+}
+
+function renderPendingQueueLines(pendingItems, width) {
+  const lines = ['Pending Queue'];
+  if (!pendingItems || pendingItems.length === 0) {
+    lines.push('  - none');
+    return lines.map((line) => truncate(line, width));
+  }
+
+  for (const item of pendingItems.slice(0, 12)) {
+    const deps = item.dependencies && item.dependencies.length > 0
+      ? ` deps:${item.dependencies.join(',')}`
+      : '';
+    lines.push(`  - ${item.id} (${item.mode}/${item.complexity}) in ${item.intentTitle}${deps}`);
+  }
+
+  if (pendingItems.length > 12) {
+    lines.push(`  ... ${pendingItems.length - 12} more pending items`);
+  }
+
+  return lines.map((line) => truncate(line, width));
+}
+
+function renderCompletedRunLines(completedRuns, width) {
+  const lines = ['Recent Completed Runs'];
+  if (!completedRuns || completedRuns.length === 0) {
+    lines.push('  - none');
+    return lines.map((line) => truncate(line, width));
+  }
+
+  for (const run of completedRuns.slice(0, 5)) {
+    const completedAt = run.completedAt || 'unknown';
+    lines.push(`  - ${run.id} [${run.scope}] completed: ${completedAt} | ${formatRunProgress(run)}`);
+  }
+
+  return lines.map((line) => truncate(line, width));
+}
+
+function renderRunsViewLines(snapshot, runFilter, width) {
+  const lines = [];
+
+  if (!snapshot?.initialized) {
+    lines.push('FIRE detected, but state.yaml is not initialized yet.');
+    lines.push('Initialize FIRE project context, then the dashboard will auto-populate.');
+    return lines.map((line) => truncate(line, width));
+  }
+
+  if (runFilter !== 'completed') {
+    lines.push(...renderActiveRunLines(snapshot.activeRuns, width));
+    lines.push('');
+    lines.push(...renderPendingQueueLines(snapshot.pendingItems, width));
+    lines.push('');
+  }
+
+  if (runFilter !== 'active') {
+    lines.push(...renderCompletedRunLines(snapshot.completedRuns, width));
+  }
+
+  return lines.map((line) => truncate(line, width));
+}
+
+module.exports = {
+  renderRunsViewLines
+};

package/lib/installers/CodexInstaller.js

@@ -1,4 +1,8 @@
 const ToolInstaller = require('./ToolInstaller');
+const fs = require('fs-extra');
+const path = require('path');
+const CLIUtils = require('../cli-utils');
+const { theme } = CLIUtils;
 
 class CodexInstaller extends ToolInstaller {
     get key() {
@@ -10,12 +14,79 @@ class CodexInstaller extends ToolInstaller {
     }
 
     get commandsDir() {
-        return '.codex';
+        return path.join('.codex', 'skills');
     }
 
     get detectPath() {
         return '.codex';
     }
+
+    async installCommands(flowPath, config) {
+        const targetSkillsDir = this.commandsDir;
+        console.log(theme.dim(`  Installing skills to ${targetSkillsDir}/...`));
+        await fs.ensureDir(targetSkillsDir);
+
+        const commandsSourceDir = path.join(flowPath, 'commands');
+        if (!await fs.pathExists(commandsSourceDir)) {
+            console.log(theme.warning(`  No commands folder found at ${commandsSourceDir}`));
+            return [];
+        }
+
+        const commandFiles = await fs.readdir(commandsSourceDir);
+        const installedFiles = [];
+
+        for (const cmdFile of commandFiles) {
+            if (!cmdFile.endsWith('.md')) continue;
+
+            try {
+                const sourcePath = path.join(commandsSourceDir, cmdFile);
+                const content = await fs.readFile(sourcePath, 'utf8');
+                const commandName = cmdFile.replace('.md', '');
+                const prefix = (config && config.command && config.command.prefix) ? `${config.command.prefix}-` : '';
+                const skillName = `specsmd-${prefix}${commandName}`;
+
+                const { description, body } = this.parseFrontmatter(content);
+
+                // Build SKILL.md with Codex frontmatter
+                const skillContent = [
+                    '---',
+                    `name: ${skillName}`,
+                    `description: "${description || 'specsmd agent'}"`,
+                    '---',
+                    '',
+                    body
+                ].join('\n');
+
+                // Write SKILL.md
+                const skillDir = path.join(targetSkillsDir, skillName);
+                await fs.ensureDir(skillDir);
+                await fs.writeFile(path.join(skillDir, 'SKILL.md'), skillContent, 'utf8');
+
+                installedFiles.push(skillName);
+            } catch (err) {
+                console.log(theme.warning(`  Failed to install ${cmdFile}: ${err.message}`));
+            }
+        }
+
+        CLIUtils.displayStatus('', `Installed ${installedFiles.length} skills for ${this.name}`, 'success');
+        return installedFiles;
+    }
+
+    /**
+     * Parse YAML frontmatter from a markdown file
+     */
+    parseFrontmatter(content) {
+        const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+        if (!match) return { description: '', body: content };
+
+        const frontmatter = match[1];
+        const body = match[2];
+        const descMatch = frontmatter.match(/description:\s*["']?(.+?)["']?\s*$/m);
+        return {
+            description: descMatch ? descMatch[1] : '',
+            body: body.trim()
+        };
+    }
 }
 
 module.exports = CodexInstaller;