specsmd 0.1.22 → 0.1.24

package/lib/dashboard/fire/parser.js

@@ -0,0 +1,387 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const {
+  normalizeStatus,
+  normalizeMode,
+  normalizeScope,
+  normalizeComplexity,
+  normalizeState,
+  deriveIntentStatus,
+  calculateStats,
+  parseDependencies,
+  buildPendingItems,
+  normalizeRunWorkItem
+} = require('./model');
+
+const STANDARD_TYPES = [
+  'constitution',
+  'tech-stack',
+  'coding-standards',
+  'testing-standards',
+  'system-architecture'
+];
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) {
+    return {};
+  }
+
+  try {
+    return yaml.load(match[1]) || {};
+  } catch {
+    return {};
+  }
+}
+
+function readFileSafe(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function listSubdirectories(dirPath) {
+  try {
+    return fs.readdirSync(dirPath, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort((a, b) => a.localeCompare(b));
+  } catch {
+    return [];
+  }
+}
+
+function listMarkdownFiles(dirPath) {
+  try {
+    return fs.readdirSync(dirPath)
+      .filter((file) => file.endsWith('.md'))
+      .sort((a, b) => a.localeCompare(b));
+  } catch {
+    return [];
+  }
+}
+
+function parseRunLog(runLogPath) {
+  const content = readFileSafe(runLogPath);
+  if (!content) {
+    return {
+      scope: undefined,
+      workItems: [],
+      currentItem: null,
+      startedAt: undefined,
+      completedAt: undefined
+    };
+  }
+
+  const frontmatter = parseFrontmatter(content);
+  const workItemsRaw = Array.isArray(frontmatter.work_items)
+    ? frontmatter.work_items
+    : (Array.isArray(frontmatter.workItems) ? frontmatter.workItems : []);
+
+  const workItems = workItemsRaw
+    .map((item) => normalizeRunWorkItem(item))
+    .filter((item) => item.id !== '');
+
+  return {
+    scope: normalizeScope(frontmatter.scope),
+    workItems,
+    currentItem: typeof frontmatter.current_item === 'string'
+      ? frontmatter.current_item
+      : (typeof frontmatter.currentItem === 'string' ? frontmatter.currentItem : null),
+    startedAt: typeof frontmatter.started === 'string' ? frontmatter.started : undefined,
+    completedAt: typeof frontmatter.completed === 'string'
+      ? frontmatter.completed
+      : undefined
+  };
+}
+
+function scanWorkItems(intentPath, intentId, stateWorkItems, warnings) {
+  const workItemsPath = path.join(intentPath, 'work-items');
+  const fileWorkItemIds = listMarkdownFiles(workItemsPath)
+    .filter((file) => !file.endsWith('-design.md'))
+    .map((file) => file.replace(/\.md$/, ''));
+
+  const stateWorkItemIds = (stateWorkItems || []).map((item) => item.id).filter(Boolean);
+  const uniqueIds = Array.from(new Set([...fileWorkItemIds, ...stateWorkItemIds])).sort((a, b) => a.localeCompare(b));
+
+  const stateMap = new Map((stateWorkItems || []).map((item) => [item.id, item]));
+
+  return uniqueIds.map((workItemId) => {
+    const stateItem = stateMap.get(workItemId);
+    const filePath = path.join(workItemsPath, `${workItemId}.md`);
+
+    let frontmatter = {};
+    if (fs.existsSync(filePath)) {
+      frontmatter = parseFrontmatter(readFileSafe(filePath) || '');
+    } else if (stateItem) {
+      warnings.push(`Work item ${intentId}/${workItemId} exists in state.yaml but markdown file is missing.`);
+    }
+
+    const dependencies = parseDependencies(frontmatter.depends_on ?? frontmatter.dependencies);
+
+    return {
+      id: workItemId,
+      intentId,
+      title: typeof frontmatter.title === 'string' ? frontmatter.title : workItemId,
+      status: normalizeStatus(stateItem?.status || frontmatter.status) || 'pending',
+      mode: normalizeMode(stateItem?.mode || frontmatter.mode) || 'confirm',
+      complexity: normalizeComplexity(frontmatter.complexity) || 'medium',
+      filePath,
+      description: typeof frontmatter.description === 'string' ? frontmatter.description : undefined,
+      dependencies,
+      createdAt: typeof frontmatter.created === 'string' ? frontmatter.created : undefined,
+      completedAt: typeof frontmatter.completed_at === 'string' ? frontmatter.completed_at : undefined
+    };
+  });
+}
+
+function scanIntents(rootPath, normalizedState, warnings) {
+  const intentsPath = path.join(rootPath, 'intents');
+  const dirIntentIds = listSubdirectories(intentsPath);
+  const stateIntentIds = (normalizedState.intents || []).map((intent) => intent.id).filter(Boolean);
+  const uniqueIntentIds = Array.from(new Set([...dirIntentIds, ...stateIntentIds])).sort((a, b) => a.localeCompare(b));
+
+  const stateIntentMap = new Map((normalizedState.intents || []).map((intent) => [intent.id, intent]));
+
+  return uniqueIntentIds.map((intentId) => {
+    const stateIntent = stateIntentMap.get(intentId);
+    const intentPath = path.join(intentsPath, intentId);
+    const briefPath = path.join(intentPath, 'brief.md');
+
+    let frontmatter = {};
+    if (fs.existsSync(briefPath)) {
+      frontmatter = parseFrontmatter(readFileSafe(briefPath) || '');
+    } else if (stateIntent) {
+      warnings.push(`Intent ${intentId} exists in state.yaml but brief.md is missing.`);
+    }
+
+    const workItems = scanWorkItems(
+      intentPath,
+      intentId,
+      stateIntent?.workItems || [],
+      warnings
+    );
+
+    return {
+      id: intentId,
+      title: typeof frontmatter.title === 'string'
+        ? frontmatter.title
+        : (stateIntent?.title || intentId),
+      status: deriveIntentStatus(stateIntent?.status, workItems),
+      filePath: briefPath,
+      description: typeof frontmatter.description === 'string' ? frontmatter.description : undefined,
+      workItems,
+      createdAt: typeof frontmatter.created === 'string' ? frontmatter.created : undefined,
+      completedAt: typeof frontmatter.completed_at === 'string' ? frontmatter.completed_at : undefined
+    };
+  });
+}
+
+function scanRuns(rootPath, normalizedState) {
+  const runsPath = path.join(rootPath, 'runs');
+  const runDirs = listSubdirectories(runsPath).filter((name) => name.startsWith('run-'));
+
+  const stateActiveMap = new Map((normalizedState.runs?.active || []).map((run) => [run.id, run]));
+  const stateCompletedMap = new Map((normalizedState.runs?.completed || []).map((run) => [run.id, run]));
+
+  const runIds = Array.from(new Set([
+    ...runDirs,
+    ...Array.from(stateActiveMap.keys()),
+    ...Array.from(stateCompletedMap.keys())
+  ])).sort((a, b) => a.localeCompare(b));
+
+  return runIds.map((runId) => {
+    const folderPath = path.join(runsPath, runId);
+    const runLogPath = path.join(folderPath, 'run.md');
+    const parsedRunLog = parseRunLog(runLogPath);
+
+    const stateActiveRun = stateActiveMap.get(runId);
+    const stateCompletedRun = stateCompletedMap.get(runId);
+
+    const workItems = (stateActiveRun?.workItems && stateActiveRun.workItems.length > 0)
+      ? stateActiveRun.workItems
+      : ((stateCompletedRun?.workItems && stateCompletedRun.workItems.length > 0)
+        ? stateCompletedRun.workItems
+        : parsedRunLog.workItems);
+
+    const completedAt = stateCompletedRun?.completed || parsedRunLog.completedAt || undefined;
+
+    return {
+      id: runId,
+      scope: stateActiveRun?.scope || parsedRunLog.scope || 'single',
+      workItems,
+      currentItem: stateActiveRun?.currentItem || parsedRunLog.currentItem || null,
+      folderPath,
+      startedAt: stateActiveRun?.started || parsedRunLog.startedAt || '',
+      completedAt: completedAt === 'null' ? undefined : completedAt,
+      hasPlan: fs.existsSync(path.join(folderPath, 'plan.md')),
+      hasWalkthrough: fs.existsSync(path.join(folderPath, 'walkthrough.md')),
+      hasTestReport: fs.existsSync(path.join(folderPath, 'test-report.md'))
+    };
+  });
+}
+
+function scanStandards(rootPath) {
+  const standardsPath = path.join(rootPath, 'standards');
+
+  return STANDARD_TYPES
+    .filter((type) => fs.existsSync(path.join(standardsPath, `${type}.md`)))
+    .map((type) => ({
+      type,
+      filePath: path.join(standardsPath, `${type}.md`),
+      scope: 'root'
+    }));
+}
+
+function buildActiveRuns(runs, normalizedState) {
+  const byId = new Map((runs || []).map((run) => [run.id, run]));
+
+  return (normalizedState.runs?.active || [])
+    .map((active) => byId.get(active.id) || null)
+    .filter(Boolean);
+}
+
+function buildCompletedRuns(runs) {
+  return (runs || [])
+    .filter((run) => run.completedAt != null)
+    .sort((a, b) => {
+      const aTime = a.completedAt ? Date.parse(a.completedAt) : 0;
+      const bTime = b.completedAt ? Date.parse(b.completedAt) : 0;
+      if (bTime !== aTime) {
+        return bTime - aTime;
+      }
+      return b.id.localeCompare(a.id);
+    });
+}
+
+function createUninitializedSnapshot(workspacePath, rootPath) {
+  return {
+    flow: 'fire',
+    isProject: true,
+    initialized: false,
+    workspacePath,
+    rootPath,
+    version: '0.0.0',
+    project: null,
+    workspace: null,
+    intents: [],
+    runs: [],
+    activeRuns: [],
+    completedRuns: [],
+    pendingItems: [],
+    standards: scanStandards(rootPath),
+    stats: {
+      totalIntents: 0,
+      completedIntents: 0,
+      inProgressIntents: 0,
+      pendingIntents: 0,
+      blockedIntents: 0,
+      totalWorkItems: 0,
+      completedWorkItems: 0,
+      inProgressWorkItems: 0,
+      pendingWorkItems: 0,
+      blockedWorkItems: 0,
+      totalRuns: 0,
+      completedRuns: 0,
+      activeRunsCount: 0
+    },
+    warnings: ['FIRE folder exists but state.yaml has not been created yet.'],
+    generatedAt: new Date().toISOString()
+  };
+}
+
+function parseStateFile(statePath) {
+  const content = readFileSafe(statePath);
+  if (content == null) {
+    throw new Error('Unable to read state.yaml');
+  }
+
+  const parsed = yaml.load(content);
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error('state.yaml is empty or invalid.');
+  }
+
+  return parsed;
+}
+
+function parseFireDashboard(workspacePath) {
+  const rootPath = path.join(workspacePath, '.specs-fire');
+
+  if (!fs.existsSync(rootPath) || !fs.statSync(rootPath).isDirectory()) {
+    return {
+      ok: false,
+      error: {
+        code: 'FIRE_NOT_FOUND',
+        message: `No FIRE workspace found at ${rootPath}`,
+        hint: 'Install FIRE flow or run this command from a FIRE project root.'
+      }
+    };
+  }
+
+  const statePath = path.join(rootPath, 'state.yaml');
+  if (!fs.existsSync(statePath)) {
+    return {
+      ok: true,
+      snapshot: createUninitializedSnapshot(workspacePath, rootPath)
+    };
+  }
+
+  let rawState;
+  try {
+    rawState = parseStateFile(statePath);
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        code: 'STATE_PARSE_ERROR',
+        message: `Failed to parse ${statePath}`,
+        details: error.message,
+        path: statePath
+      }
+    };
+  }
+
+  const warnings = [];
+  const normalizedState = normalizeState(rawState);
+  const intents = scanIntents(rootPath, normalizedState, warnings);
+  const runs = scanRuns(rootPath, normalizedState);
+  const activeRuns = buildActiveRuns(runs, normalizedState);
+  const completedRuns = buildCompletedRuns(runs);
+  const standards = scanStandards(rootPath);
+  const pendingItems = buildPendingItems(intents);
+  const stats = calculateStats(intents, runs, activeRuns);
+
+  return {
+    ok: true,
+    snapshot: {
+      flow: 'fire',
+      isProject: true,
+      initialized: true,
+      workspacePath,
+      rootPath,
+      version: normalizedState.project?.fireVersion || '0.0.0',
+      project: normalizedState.project,
+      workspace: normalizedState.workspace,
+      intents,
+      runs,
+      activeRuns,
+      completedRuns,
+      pendingItems,
+      standards,
+      stats,
+      warnings,
+      generatedAt: new Date().toISOString()
+    }
+  };
+}
+
+module.exports = {
+  STANDARD_TYPES,
+  parseFrontmatter,
+  parseRunLog,
+  parseFireDashboard
+};

package/lib/dashboard/flow-detect.js

@@ -0,0 +1,86 @@
+const fs = require('fs');
+const path = require('path');
+
+const SUPPORTED_FLOWS = ['fire', 'aidlc', 'simple'];
+
+function directoryExists(dirPath) {
+  try {
+    return fs.statSync(dirPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function getFlowMarkerPath(workspacePath, flow) {
+  switch (flow) {
+    case 'fire':
+      return path.join(workspacePath, '.specs-fire');
+    case 'aidlc':
+      return path.join(workspacePath, 'memory-bank');
+    case 'simple':
+      return path.join(workspacePath, 'specs');
+    default:
+      return null;
+  }
+}
+
+function detectAvailableFlows(workspacePath) {
+  return SUPPORTED_FLOWS.filter((flow) => {
+    const markerPath = getFlowMarkerPath(workspacePath, flow);
+    return markerPath && directoryExists(markerPath);
+  });
+}
+
+function detectFlow(workspacePath, explicitFlow) {
+  const availableFlows = detectAvailableFlows(workspacePath);
+
+  if (explicitFlow) {
+    if (!SUPPORTED_FLOWS.includes(explicitFlow)) {
+      const valid = SUPPORTED_FLOWS.join(', ');
+      throw new Error(`Invalid flow \"${explicitFlow}\". Valid options: ${valid}`);
+    }
+
+    const markerPath = getFlowMarkerPath(workspacePath, explicitFlow);
+    const exists = markerPath ? directoryExists(markerPath) : false;
+
+    return {
+      flow: explicitFlow,
+      source: 'flag',
+      markerPath,
+      detected: exists,
+      availableFlows,
+      warning: exists
+        ? undefined
+        : `Flow \"${explicitFlow}\" was selected explicitly but ${markerPath} was not found.`
+    };
+  }
+
+  for (const flow of SUPPORTED_FLOWS) {
+    const markerPath = getFlowMarkerPath(workspacePath, flow);
+    if (markerPath && directoryExists(markerPath)) {
+      return {
+        flow,
+        source: 'auto',
+        markerPath,
+        detected: true,
+        availableFlows
+      };
+    }
+  }
+
+  return {
+    flow: null,
+    source: 'auto',
+    markerPath: null,
+    detected: false,
+    availableFlows
+  };
+}
+
+module.exports = {
+  SUPPORTED_FLOWS,
+  directoryExists,
+  getFlowMarkerPath,
+  detectAvailableFlows,
+  detectFlow
+};

package/lib/dashboard/index.js

@@ -0,0 +1,134 @@
+const path = require('path');
+const { detectFlow } = require('./flow-detect');
+const { parseFireDashboard } = require('./fire/parser');
+const { formatDashboardText } = require('./tui/renderer');
+const { createDashboardApp } = require('./tui/app');
+
+function parseRefreshMs(raw) {
+  const parsed = Number.parseInt(String(raw || '1000'), 10);
+  if (Number.isNaN(parsed)) {
+    return 1000;
+  }
+
+  return Math.max(200, Math.min(parsed, 5000));
+}
+
+function getUnsupportedFlowMessage(flow) {
+  if (flow === 'aidlc') {
+    return 'AI-DLC dashboard is coming soon. FIRE dashboard is available now.';
+  }
+
+  if (flow === 'simple') {
+    return 'Simple flow dashboard is coming soon. FIRE dashboard is available now.';
+  }
+
+  return `Flow \"${flow}\" dashboard is not available yet.`;
+}
+
+async function runFireDashboard(options) {
+  const workspacePath = path.resolve(options.path || process.cwd());
+  const rootPath = path.join(workspacePath, '.specs-fire');
+  const watchEnabled = options.watch !== false;
+  const refreshMs = parseRefreshMs(options.refreshMs);
+
+  const parseSnapshot = async () => parseFireDashboard(workspacePath);
+
+  const initialResult = await parseSnapshot();
+
+  if (!watchEnabled) {
+    if (!initialResult.ok) {
+      const output = formatDashboardText({
+        snapshot: null,
+        error: initialResult.error,
+        flow: 'fire',
+        workspacePath,
+        view: 'runs',
+        runFilter: 'all',
+        watchEnabled: false,
+        watchStatus: 'off',
+        showHelp: true,
+        lastRefreshAt: new Date().toISOString(),
+        width: process.stdout.columns || 120
+      });
+      console.log(output);
+      process.exitCode = 1;
+      return;
+    }
+
+    const output = formatDashboardText({
+      snapshot: initialResult.snapshot,
+      error: null,
+      flow: 'fire',
+      workspacePath,
+      view: 'runs',
+      runFilter: 'all',
+      watchEnabled: false,
+      watchStatus: 'off',
+      showHelp: true,
+      lastRefreshAt: new Date().toISOString(),
+      width: process.stdout.columns || 120
+    });
+    console.log(output);
+    return;
+  }
+
+  const ink = await import('ink');
+  const reactNamespace = await import('react');
+  const React = reactNamespace.default || reactNamespace;
+
+  const App = createDashboardApp({
+    React,
+    ink,
+    parseSnapshot,
+    workspacePath,
+    rootPath,
+    flow: 'fire',
+    refreshMs,
+    watchEnabled,
+    initialSnapshot: initialResult.ok ? initialResult.snapshot : null,
+    initialError: initialResult.ok ? null : initialResult.error
+  });
+
+  const { waitUntilExit } = ink.render(React.createElement(App), {
+    exitOnCtrlC: true
+  });
+
+  await waitUntilExit();
+}
+
+async function run(options = {}) {
+  const workspacePath = path.resolve(options.path || process.cwd());
+
+  let detection;
+  try {
+    detection = detectFlow(workspacePath, options.flow);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!detection.flow) {
+    console.error('No supported flow detected. Expected one of: .specs-fire, memory-bank, specs');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (detection.warning) {
+    console.warn(`Warning: ${detection.warning}`);
+  }
+
+  if (detection.flow !== 'fire') {
+    console.log(getUnsupportedFlowMessage(detection.flow));
+    return;
+  }
+
+  await runFireDashboard(options);
+}
+
+module.exports = {
+  run,
+  runFireDashboard,
+  parseRefreshMs,
+  getUnsupportedFlowMessage
+};

package/lib/dashboard/runtime/watch-runtime.js

@@ -0,0 +1,113 @@
+const chokidar = require('chokidar');
+const path = require('path');
+
+function createDebouncedTrigger(callback, delayMs) {
+  let timeoutId = null;
+
+  const trigger = () => {
+    if (timeoutId != null) {
+      clearTimeout(timeoutId);
+    }
+
+    timeoutId = setTimeout(() => {
+      timeoutId = null;
+      callback();
+    }, delayMs);
+  };
+
+  const cancel = () => {
+    if (timeoutId != null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+  };
+
+  return {
+    trigger,
+    cancel,
+    isPending: () => timeoutId != null
+  };
+}
+
+function createWatchRuntime(options) {
+  const {
+    rootPath,
+    onRefresh,
+    onError,
+    debounceMs = 250
+  } = options;
+
+  if (!rootPath || typeof rootPath !== 'string') {
+    throw new Error('rootPath is required for watch runtime');
+  }
+
+  if (typeof onRefresh !== 'function') {
+    throw new Error('onRefresh callback is required for watch runtime');
+  }
+
+  const reportError = typeof onError === 'function' ? onError : () => {};
+
+  let watcher = null;
+  let started = false;
+  const debounced = createDebouncedTrigger(onRefresh, debounceMs);
+
+  const watchTargets = [
+    path.join(rootPath, 'state.yaml'),
+    path.join(rootPath, 'intents'),
+    path.join(rootPath, 'runs'),
+    path.join(rootPath, 'standards')
+  ];
+
+  function start() {
+    if (started) {
+      return;
+    }
+
+    started = true;
+
+    try {
+      watcher = chokidar.watch(watchTargets, {
+        persistent: true,
+        ignoreInitial: true,
+        awaitWriteFinish: {
+          stabilityThreshold: 150,
+          pollInterval: 50
+        },
+        depth: 10
+      });
+
+      watcher.on('all', () => {
+        debounced.trigger();
+      });
+
+      watcher.on('error', (error) => {
+        reportError(error);
+      });
+    } catch (error) {
+      reportError(error);
+    }
+  }
+
+  async function close() {
+    debounced.cancel();
+
+    if (watcher) {
+      const activeWatcher = watcher;
+      watcher = null;
+      started = false;
+      await activeWatcher.close();
+    }
+  }
+
+  return {
+    start,
+    close,
+    isActive: () => started,
+    hasPendingRefresh: () => debounced.isPending()
+  };
+}
+
+module.exports = {
+  createDebouncedTrigger,
+  createWatchRuntime
+};