@smartmemory/compose 0.1.0

package/lib/roadmap-gen.js

@@ -0,0 +1,210 @@
+/**
+ * roadmap-gen.js — Generate ROADMAP.md from feature.json files.
+ *
+ * feature.json is the source of truth. ROADMAP.md is a rendered view.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { listFeatures } from './feature-json.js';
+
+const STATUS_ORDER = ['IN_PROGRESS', 'PARTIAL', 'PLANNED', 'COMPLETE', 'SUPERSEDED', 'PARKED'];
+
+/**
+ * Compute the aggregate status for a phase based on its features.
+ */
+function phaseStatus(features) {
+  const statuses = new Set(features.map(f => f.status));
+  if (statuses.size === 1) return [...statuses][0];
+  if (statuses.has('IN_PROGRESS') || statuses.has('PARTIAL')) return 'PARTIAL';
+  if (statuses.has('PLANNED') && statuses.has('COMPLETE')) return 'PARTIAL';
+  return 'PLANNED';
+}
+
+/**
+ * Generate ROADMAP.md content from feature.json files.
+ *
+ * @param {string} cwd - Project root
+ * @param {object} [opts]
+ * @param {string} [opts.featuresDir] - Relative path to features dir
+ * @param {string} [opts.projectName] - Project name for header
+ * @param {string} [opts.projectDescription] - Project description for header
+ * @returns {string} - Generated ROADMAP.md content
+ */
+export function generateRoadmap(cwd, opts = {}) {
+  const featuresDir = opts.featuresDir ?? 'docs/features';
+  const features = listFeatures(cwd, featuresDir);
+
+  // Read existing ROADMAP.md to preserve header/preamble
+  const preamble = readPreamble(cwd, opts);
+
+  // Group by phase
+  const phases = new Map();
+  const ungrouped = [];
+
+  for (const f of features) {
+    const phase = f.phase ?? null;
+    if (!phase) {
+      ungrouped.push(f);
+      continue;
+    }
+    if (!phases.has(phase)) phases.set(phase, []);
+    phases.get(phase).push(f);
+  }
+
+  const sections = [preamble.trimEnd()];
+
+  // Sort phases by the minimum position of their features (preserves ROADMAP order)
+  const sortedPhases = [...phases.entries()].sort((a, b) => {
+    const minA = Math.min(...a[1].map(f => f.position ?? 999));
+    const minB = Math.min(...b[1].map(f => f.position ?? 999));
+    return minA - minB;
+  });
+
+  // Render each phase
+  for (const [phase, phaseFeatures] of sortedPhases) {
+    const status = phaseStatus(phaseFeatures);
+    sections.push(renderPhase(phase, status, phaseFeatures));
+  }
+
+  // Render ungrouped features
+  if (ungrouped.length > 0) {
+    sections.push(renderPhase('Features', phaseStatus(ungrouped), ungrouped));
+  }
+
+  // Key documents section
+  const keyDocs = buildKeyDocs(features, featuresDir);
+  if (keyDocs) sections.push(keyDocs);
+
+  return sections.join('\n\n---\n\n') + '\n';
+}
+
+/**
+ * Read the preamble (everything before the first ## Phase/Feature section)
+ * from an existing ROADMAP.md, or generate a default one.
+ */
+function readPreamble(cwd, opts) {
+  const roadmapPath = join(cwd, 'ROADMAP.md');
+  if (existsSync(roadmapPath)) {
+    const text = readFileSync(roadmapPath, 'utf-8');
+    // Find the first ## heading that looks like a phase/feature section
+    const match = text.match(/^(---\s*\n\s*)?(?=## )/m);
+    if (match) {
+      const idx = text.indexOf(match[0]);
+      const pre = text.slice(0, idx).trimEnd();
+      if (pre.length > 0) return pre;
+    }
+  }
+
+  // Default preamble
+  const name = opts.projectName ?? 'Project';
+  const desc = opts.projectDescription ?? '';
+  const today = new Date().toISOString().slice(0, 10);
+  return `# ${name} Roadmap
+
+${desc ? desc + '\n\n' : ''}<!-- Generated from feature.json — do not edit manually -->
+<!-- Run: compose roadmap generate -->
+
+**Last updated:** ${today}
+
+---
+
+## Roadmap Conventions
+
+- **Status:** \`PLANNED\` | \`IN_PROGRESS\` | \`PARTIAL\` | \`COMPLETE\` | \`SUPERSEDED\` | \`PARKED\`
+- Items are numbered sequentially. Never reuse a number.
+- Cross-reference stable IDs (e.g. \`FEAT-1\`) not section headings.`;
+}
+
+/**
+ * Render a phase section with its feature table.
+ */
+function renderPhase(phaseName, status, features) {
+  const lines = [`## ${phaseName} — ${status}`, ''];
+
+  // Phase description from the first feature's phaseDescription if available
+  const desc = features[0]?.phaseDescription;
+  if (desc) {
+    lines.push(desc, '');
+  }
+
+  // Determine table columns based on whether features have sub-items
+  const hasSubItems = features.some(f => f.items && f.items.length > 0);
+
+  if (hasSubItems) {
+    // Expanded: one row per sub-item
+    lines.push('| # | Feature | Item | Status |');
+    lines.push('|---|---------|------|--------|');
+    for (const f of features) {
+      if (f.items && f.items.length > 0) {
+        for (const item of f.items) {
+          const num = item.position ?? '—';
+          const desc = item.description ?? '';
+          const st = item.status ?? f.status;
+          lines.push(`| ${num} | ${f.code} | ${desc} | ${st} |`);
+        }
+      } else {
+        const num = f.position ?? '—';
+        lines.push(`| ${num} | ${f.code} | ${f.description} | ${f.status} |`);
+      }
+    }
+  } else {
+    // Simple: one row per feature
+    lines.push('| # | Feature | Description | Status |');
+    lines.push('|---|---------|-------------|--------|');
+    for (const f of features) {
+      const num = f.position ?? '—';
+      const desc = f.description.length > 80 ? f.description.slice(0, 77) + '...' : f.description;
+      lines.push(`| ${num} | ${f.code} | ${desc} | ${f.status} |`);
+    }
+  }
+
+  // Exit criteria
+  const exit = features[0]?.phaseExit;
+  if (exit) {
+    lines.push('', `**Exit:** ${exit}`);
+  }
+
+  // Links to design docs
+  const docsLinks = features
+    .filter(f => f.designDoc)
+    .map(f => `See \`${f.designDoc}\` for ${f.code} design.`);
+  if (docsLinks.length > 0) {
+    lines.push('', docsLinks.join('\n'));
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Build a Key Documents section from features that have design docs.
+ */
+function buildKeyDocs(features, featuresDir) {
+  const docs = features
+    .filter(f => existsSync || f.designDoc) // always include if designDoc is set
+    .filter(f => f.designDoc)
+    .map(f => `| \`${f.designDoc}\` | ${f.code} design |`);
+
+  if (docs.length === 0) return null;
+
+  return [
+    '## Key Documents',
+    '',
+    '| Document | What it is |',
+    '|---|---|',
+    ...docs,
+  ].join('\n');
+}
+
+/**
+ * Write the generated ROADMAP.md to disk.
+ *
+ * @param {string} cwd - Project root
+ * @param {object} [opts]
+ */
+export function writeRoadmap(cwd, opts = {}) {
+  const content = generateRoadmap(cwd, opts);
+  const roadmapPath = join(cwd, 'ROADMAP.md');
+  writeFileSync(roadmapPath, content);
+  return roadmapPath;
+}

package/lib/roadmap-parser.js

@@ -0,0 +1,176 @@
+/**
+ * roadmap-parser.js — Parse ROADMAP.md into structured feature entries.
+ *
+ * Extracts feature codes, descriptions, statuses, and phase membership
+ * from the markdown table format used by Compose roadmaps.
+ */
+
+const SKIP_STATUSES = new Set(['COMPLETE', 'SUPERSEDED', 'PARKED']);
+
+const PHASE_HEADING_RE = /^##\s+(.+?)(?:\s+—\s+(.+))?$/;
+const MILESTONE_HEADING_RE = /^###\s+(.+?)(?:\s*:\s*(.+))?$/;
+const TABLE_ROW_RE = /^\|(.+)\|$/;
+const FEATURE_CODE_RE = /^[A-Z][\w-]*-\d+/;
+
+/**
+ * @typedef {{ code: string, description: string, status: string, phaseId: string, position: number }} FeatureEntry
+ */
+
+/**
+ * Parse ROADMAP.md text into an ordered list of feature entries.
+ * Anonymous rows (code === '—' or no code) are included for dependency chain
+ * purposes but can be filtered out for build lists.
+ *
+ * @param {string} text - Raw ROADMAP.md content
+ * @returns {FeatureEntry[]}
+ */
+export function parseRoadmap(text) {
+  const lines = text.split('\n');
+  const entries = [];
+  let currentPhaseId = '';
+  let currentPhaseStatus = '';
+  let position = 0;
+  let inTable = false;
+  let columnLayout = null; // { codeCol, descCol, statusCol }
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Phase heading: ## Phase 0: Bootstrap — COMPLETE
+    const phaseMatch = trimmed.match(PHASE_HEADING_RE);
+    if (phaseMatch) {
+      currentPhaseId = phaseMatch[1].trim();
+      currentPhaseStatus = phaseMatch[2]?.trim() ?? '';
+      inTable = false;
+      columnLayout = null;
+      continue;
+    }
+
+    // Milestone heading: ### Milestone 1: Stratum Engine Complete
+    const milestoneMatch = trimmed.match(MILESTONE_HEADING_RE);
+    if (milestoneMatch) {
+      // Nest under parent phase
+      const milestoneLabel = milestoneMatch[1].trim();
+      if (currentPhaseId) {
+        currentPhaseId = `${currentPhaseId} > ${milestoneLabel}`;
+      } else {
+        currentPhaseId = milestoneLabel;
+      }
+      inTable = false;
+      columnLayout = null;
+      continue;
+    }
+
+    // Table row
+    if (!TABLE_ROW_RE.test(trimmed)) {
+      if (inTable) {
+        inTable = false;
+        columnLayout = null;
+      }
+      continue;
+    }
+
+    const cells = trimmed.split('|').slice(1, -1).map(c => c.trim());
+
+    // Skip separator rows (|---|---|---|)
+    if (cells.every(c => /^[-:]+$/.test(c))) {
+      continue;
+    }
+
+    // Detect header row
+    if (!inTable) {
+      inTable = true;
+      columnLayout = detectColumnLayout(cells);
+      continue;
+    }
+
+    if (!columnLayout) continue;
+
+    // Parse data row
+    const code = cells[columnLayout.codeCol] ?? '—';
+    const desc = cells[columnLayout.descCol] ?? '';
+    let status = cells[columnLayout.statusCol] ?? '';
+
+    // Clean up status (strip bold markers, etc.)
+    status = status.replace(/\*\*/g, '').trim();
+
+    // If the entire phase is COMPLETE, override individual statuses
+    if (SKIP_STATUSES.has(currentPhaseStatus)) {
+      status = currentPhaseStatus;
+    }
+
+    const isAnonymous = code === '—' || code === '-' || !FEATURE_CODE_RE.test(code);
+
+    entries.push({
+      code: isAnonymous ? `_anon_${position}` : code,
+      description: desc.replace(/\*\*/g, '').trim(),
+      status: status || 'PLANNED',
+      phaseId: currentPhaseId,
+      position: position++,
+    });
+  }
+
+  return entries;
+}
+
+/**
+ * Detect the column layout of a table header row.
+ *
+ * Supported layouts:
+ *   4-col: # | Feature | Item | Status   → code=Feature, desc=Item
+ *   4-col: ID | Item | Location | Status → code=ID, desc=Item
+ *   3-col: ID | Feature | Status         → code=ID, desc=Feature
+ *   3-col: ID | Item | Status            → code=ID, desc=Item
+ *   3-col: # | Item | Status             → anonymous (# is a row number, not a code)
+ */
+function detectColumnLayout(headerCells) {
+  const lower = headerCells.map(c => c.toLowerCase());
+
+  // 4+ columns: look for a Feature column as the code source
+  if (lower.length >= 4) {
+    const featureIdx = lower.findIndex(c => c === 'feature');
+    if (featureIdx !== -1) {
+      return {
+        codeCol: featureIdx,
+        descCol: featureIdx + 1,
+        statusCol: lower.length - 1,
+      };
+    }
+    // No "feature" column — use first col as code, second as desc
+    return {
+      codeCol: 0,
+      descCol: 1,
+      statusCol: lower.length - 1,
+    };
+  }
+
+  // 3 columns: check if first column is "id" (contains feature codes)
+  if (lower.length === 3 && lower[0] === 'id') {
+    return {
+      codeCol: 0,
+      descCol: 1,
+      statusCol: 2,
+    };
+  }
+
+  // 3-column fallback: # | Item | Status (row-number tables, anonymous)
+  return {
+    codeCol: -1, // will yield undefined → anonymous
+    descCol: Math.min(1, lower.length - 2),
+    statusCol: lower.length - 1,
+  };
+}
+
+/**
+ * Return only features that should be built:
+ * - has a real feature code (not anonymous)
+ * - status is PLANNED or IN_PROGRESS or PARTIAL
+ *
+ * @param {FeatureEntry[]} entries
+ * @returns {FeatureEntry[]}
+ */
+export function filterBuildable(entries) {
+  return entries.filter(e =>
+    !e.code.startsWith('_anon_') && !SKIP_STATUSES.has(e.status)
+  );
+}

package/lib/server-probe.js

@@ -0,0 +1,23 @@
+import { resolvePort } from './resolve-port.js';
+
+/**
+ * Probe whether the Compose server is reachable.
+ * @param {number} [port] - Server port (default: resolvePort())
+ * @param {number} [timeoutMs=500] - Timeout in ms
+ * @returns {Promise<boolean>} true if server responds 2xx to GET /api/health
+ */
+export async function probeServer(port, timeoutMs = 500) {
+  const p = port ?? resolvePort();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`http://localhost:${p}/api/health`, {
+      signal: controller.signal,
+    });
+    return res.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/lib/staleness.js

@@ -0,0 +1,87 @@
+/**
+ * staleness.js — Artifact staleness detection for COMP-CTX (item 101).
+ *
+ * Artifacts embed a phase marker in their first 5 lines:
+ *   <!-- phase: explore_design -->
+ *
+ * If the feature's current phase is past the artifact's written phase,
+ * the artifact is flagged stale.
+ */
+
+import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Canonical phase order — earlier index = earlier phase
+const PHASE_ORDER = [
+  'explore_design',
+  'blueprint',
+  'plan',
+  'build',
+  'ship',
+  'done',
+];
+
+/**
+ * Return numeric index of phase (lower = earlier).
+ * Unknown phases return -1 so they're never considered stale.
+ */
+function phaseIndex(phase) {
+  return PHASE_ORDER.indexOf(phase);
+}
+
+/**
+ * Extract the <!-- phase: <name> --> marker from the first 5 lines of text.
+ * Returns the phase name or null if not found.
+ *
+ * @param {string} content
+ * @returns {string|null}
+ */
+export function extractPhaseMarker(content) {
+  const lines = content.split('\n').slice(0, 5);
+  for (const line of lines) {
+    const m = line.match(/<!--\s*phase:\s*([\w_-]+)\s*-->/);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+/**
+ * Check staleness of tracked artifacts in a feature folder.
+ *
+ * Scans for design.md, blueprint.md, plan.md in featureDir.
+ * For each file that exists and has a phase marker, compares its
+ * phase to currentPhase. If currentPhase is strictly later in
+ * PHASE_ORDER, the artifact is stale.
+ *
+ * @param {string} featureDir   - Absolute path to the feature folder
+ * @param {string} currentPhase - Feature's current phase name
+ * @returns {Array<{ file: string, writtenPhase: string, currentPhase: string, stale: boolean }>}
+ */
+export function checkStaleness(featureDir, currentPhase) {
+  const TRACKED = ['design.md', 'blueprint.md', 'plan.md'];
+  const results = [];
+
+  const currentIdx = phaseIndex(currentPhase);
+
+  for (const filename of TRACKED) {
+    const filePath = join(featureDir, filename);
+    if (!existsSync(filePath)) continue;
+
+    let content;
+    try {
+      content = readFileSync(filePath, 'utf-8');
+    } catch {
+      continue;
+    }
+
+    const writtenPhase = extractPhaseMarker(content);
+    if (!writtenPhase) continue;
+
+    const writtenIdx = phaseIndex(writtenPhase);
+    const stale = writtenIdx !== -1 && currentIdx !== -1 && currentIdx > writtenIdx;
+
+    results.push({ file: filename, writtenPhase, currentPhase, stale });
+  }
+
+  return results;
+}