specflow-cc 1.12.0 → 1.14.0

package/bin/lib/spec.cjs

@@ -0,0 +1,130 @@
+/**
+ * bin/lib/spec.cjs — Spec operations
+ *
+ * Exports: cmdSpecLoad(), cmdSpecList(), cmdSpecNextId()
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { output, error, safeReadFile, parseFrontmatter } = require('./core.cjs');
+
+/**
+ * Load and parse a spec file.
+ * @param {string} cwd - Working directory
+ * @param {string} id - Spec ID (e.g., "SPEC-007")
+ * @param {boolean} raw - Output raw string
+ */
+function cmdSpecLoad(cwd, id, raw) {
+  if (!id) {
+    error('Missing spec ID. Usage: spec load <id>');
+  }
+
+  const specPath = path.join(cwd, '.specflow', 'specs', id + '.md');
+  const content = safeReadFile(specPath);
+
+  if (!content) {
+    error('Spec not found: ' + specPath);
+  }
+
+  const parsed = parseFrontmatter(content);
+
+  output({
+    frontmatter: parsed.frontmatter,
+    body: parsed.body,
+  }, raw, parsed.body);
+}
+
+/**
+ * List all specs in .specflow/specs/.
+ * Extracts id, title, status, complexity, priority from each.
+ * Title is parsed from the first # heading in the body.
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Output raw string
+ */
+function cmdSpecList(cwd, raw) {
+  const specsDir = path.join(cwd, '.specflow', 'specs');
+
+  let files;
+  try {
+    files = fs.readdirSync(specsDir).filter(f => f.endsWith('.md')).sort();
+  } catch (e) {
+    error('Cannot read specs directory: ' + specsDir);
+  }
+
+  const specs = [];
+
+  for (const file of files) {
+    const content = safeReadFile(path.join(specsDir, file));
+    if (!content) continue;
+
+    const parsed = parseFrontmatter(content);
+    const fm = parsed.frontmatter;
+
+    // Extract title from first # heading in body
+    let title = '';
+    const titleMatch = parsed.body.match(/^#\s+(.+)$/m);
+    if (titleMatch) {
+      title = titleMatch[1].trim();
+    }
+
+    specs.push({
+      id: fm.id || file.replace('.md', ''),
+      title: title,
+      status: fm.status || '',
+      complexity: fm.complexity || '',
+      priority: fm.priority || '',
+    });
+  }
+
+  output(specs, raw, specs.map(s => s.id).join('\n'));
+}
+
+/**
+ * Calculate the next available SPEC-XXX number.
+ * Scans both .specflow/specs/ and .specflow/archive/ directories.
+ * Ignores non-numeric spec IDs (e.g., SPEC-GSD-A).
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Output raw string
+ */
+function cmdSpecNextId(cwd, raw) {
+  const dirs = [
+    path.join(cwd, '.specflow', 'specs'),
+    path.join(cwd, '.specflow', 'archive'),
+  ];
+
+  let maxNum = 0;
+
+  for (const dir of dirs) {
+    let files;
+    try {
+      files = fs.readdirSync(dir).filter(f => f.endsWith('.md'));
+    } catch (e) {
+      continue; // directory may not exist
+    }
+
+    for (const file of files) {
+      // Match SPEC-NNN pattern (numeric only)
+      const match = file.match(/^SPEC-(\d+)\.md$/);
+      if (match) {
+        const num = parseInt(match[1], 10);
+        if (num > maxNum) maxNum = num;
+      }
+    }
+  }
+
+  const nextNumber = maxNum + 1;
+  const nextId = 'SPEC-' + String(nextNumber).padStart(3, '0');
+
+  output({
+    next_id: nextId,
+    next_number: nextNumber,
+  }, raw, nextId);
+}
+
+module.exports = {
+  cmdSpecLoad,
+  cmdSpecList,
+  cmdSpecNextId,
+};

package/bin/lib/state.cjs

@@ -0,0 +1,241 @@
+/**
+ * bin/lib/state.cjs — STATE.md CRUD operations
+ *
+ * Exports: cmdStateGet(), cmdStateSetActive(), cmdQueueNext()
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { output, error, safeReadFile } = require('./core.cjs');
+
+/**
+ * Extract a bold-field value from STATE.md content.
+ * Matches patterns like: **Field:** value
+ * @param {string} content - STATE.md content
+ * @param {string} field - Field name (e.g., "Status")
+ * @returns {string|null}
+ */
+function extractBoldField(content, field) {
+  const regex = new RegExp(`\\*\\*${field}:\\*\\*\\s*(.+)`, 'i');
+  const match = content.match(regex);
+  return match ? match[1].trim() : null;
+}
+
+/**
+ * Extract the active spec ID from STATE.md.
+ * The spec ID is on the line immediately after "## Active Specification".
+ * @param {string} content - STATE.md content
+ * @returns {string|null}
+ */
+function extractActiveSpec(content) {
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === '## Active Specification') {
+      // Next non-empty line has the spec ID
+      for (let j = i + 1; j < lines.length; j++) {
+        const line = lines[j].trim();
+        if (line && !line.startsWith('**') && !line.startsWith('#')) {
+          return line;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Parse the queue table from STATE.md.
+ * Expects pipe-delimited markdown table with columns:
+ * Priority | ID | Title | Status | Complexity | Depends On
+ * @param {string} content - STATE.md content
+ * @returns {Array<Object>}
+ */
+function parseQueueTable(content) {
+  const lines = content.split('\n');
+  const queue = [];
+  let inQueue = false;
+  let headerFound = false;
+  let separatorFound = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed === '## Queue') {
+      inQueue = true;
+      continue;
+    }
+
+    if (inQueue && trimmed.startsWith('##') && trimmed !== '## Queue') {
+      break; // next section
+    }
+
+    if (!inQueue) continue;
+
+    if (trimmed.startsWith('|') && !headerFound) {
+      // Check if this is the header row
+      if (trimmed.toLowerCase().includes('priority') && trimmed.toLowerCase().includes('id')) {
+        headerFound = true;
+        continue;
+      }
+    }
+
+    if (headerFound && !separatorFound && trimmed.startsWith('|') && trimmed.includes('---')) {
+      separatorFound = true;
+      continue;
+    }
+
+    if (headerFound && separatorFound && trimmed.startsWith('|')) {
+      const cells = trimmed.split('|').map(c => c.trim()).filter(c => c !== '');
+      if (cells.length >= 4) {
+        queue.push({
+          priority: cells[0] || '',
+          id: cells[1] || '',
+          title: cells[2] || '',
+          status: cells[3] || '',
+          complexity: cells[4] || '',
+          depends_on: cells[5] || '',
+        });
+      }
+    }
+  }
+
+  return queue;
+}
+
+/**
+ * Get current active spec, status, and next step from STATE.md.
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Output raw string
+ */
+function cmdStateGet(cwd, raw) {
+  const statePath = path.join(cwd, '.specflow', 'STATE.md');
+  const content = safeReadFile(statePath);
+
+  if (!content) {
+    error('STATE.md not found at ' + statePath);
+  }
+
+  const activeSpec = extractActiveSpec(content);
+  const status = extractBoldField(content, 'Status');
+  const nextStep = extractBoldField(content, 'Next Step');
+
+  const result = {
+    active_spec: activeSpec || null,
+    status: status || null,
+    next_step: nextStep || null,
+  };
+
+  output(result, raw, result.active_spec);
+}
+
+/**
+ * Update active spec, status, and optionally next step in STATE.md.
+ * @param {string} cwd - Working directory
+ * @param {string} id - Spec ID (e.g., "SPEC-007")
+ * @param {string} status - New status
+ * @param {string} [nextStep] - Optional new next step
+ * @param {boolean} raw - Output raw string
+ */
+function cmdStateSetActive(cwd, id, status, nextStep, raw) {
+  const statePath = path.join(cwd, '.specflow', 'STATE.md');
+  const content = safeReadFile(statePath);
+
+  if (!content) {
+    error('STATE.md not found at ' + statePath);
+  }
+
+  const lines = content.split('\n');
+  const result = [];
+  let inActiveSection = false;
+  let specIdReplaced = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+
+    if (trimmed === '## Active Specification') {
+      inActiveSection = true;
+      result.push(lines[i]);
+      continue;
+    }
+
+    if (inActiveSection && trimmed.startsWith('## ') && trimmed !== '## Active Specification') {
+      inActiveSection = false;
+    }
+
+    if (inActiveSection && !specIdReplaced && trimmed && !trimmed.startsWith('**') && !trimmed.startsWith('#')) {
+      // This is the spec ID line — replace it
+      result.push(id);
+      specIdReplaced = true;
+      continue;
+    }
+
+    if (inActiveSection && trimmed.startsWith('**Status:**')) {
+      result.push('**Status:** ' + status);
+      continue;
+    }
+
+    if (inActiveSection && trimmed.startsWith('**Next Step:**')) {
+      if (nextStep !== undefined && nextStep !== null) {
+        result.push('**Next Step:** ' + nextStep);
+      } else {
+        result.push(lines[i]); // preserve existing
+      }
+      continue;
+    }
+
+    result.push(lines[i]);
+  }
+
+  fs.writeFileSync(statePath, result.join('\n'), 'utf8');
+
+  const resultObj = {
+    updated: true,
+    active_spec: id,
+    status: status,
+    next_step: nextStep || extractBoldField(result.join('\n'), 'Next Step'),
+  };
+
+  output(resultObj, raw, 'updated');
+}
+
+/**
+ * Get the first actionable spec from the queue.
+ * "Actionable" = status is not "done" or "complete".
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Output raw string
+ */
+function cmdQueueNext(cwd, raw) {
+  const statePath = path.join(cwd, '.specflow', 'STATE.md');
+  const content = safeReadFile(statePath);
+
+  if (!content) {
+    error('STATE.md not found at ' + statePath);
+  }
+
+  const queue = parseQueueTable(content);
+
+  const next = queue.find(entry => {
+    const s = entry.status.toLowerCase();
+    return s !== 'done' && s !== 'complete';
+  });
+
+  if (next) {
+    output({
+      id: next.id,
+      title: next.title,
+      status: next.status,
+      priority: next.priority,
+    }, raw, next.id);
+  } else {
+    output({ id: null }, raw, '');
+  }
+}
+
+module.exports = {
+  cmdStateGet,
+  cmdStateSetActive,
+  cmdQueueNext,
+  extractActiveSpec,
+};

package/bin/lib/verify.cjs

@@ -0,0 +1,117 @@
+/**
+ * bin/lib/verify.cjs — Structure verification checks
+ *
+ * Exports: cmdVerifyStructure()
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { output, safeReadFile, parseFrontmatter } = require('./core.cjs');
+const { extractActiveSpec } = require('./state.cjs');
+
+/**
+ * Verify .specflow/ directory structure and integrity.
+ * Performs 6 read-only checks. Does NOT repair issues.
+ *
+ * @param {string} cwd - Working directory
+ * @param {boolean} raw - Output raw string
+ */
+function cmdVerifyStructure(cwd, raw) {
+  const checks = [];
+  const errors = [];
+
+  // Check 1: .specflow/ directory exists
+  const specflowDir = path.join(cwd, '.specflow');
+  const specflowExists = fs.existsSync(specflowDir) && fs.statSync(specflowDir).isDirectory();
+  checks.push({ name: '.specflow/ directory exists', passed: specflowExists });
+  if (!specflowExists) {
+    errors.push('.specflow/ directory not found');
+  }
+
+  // Check 2: STATE.md exists and has "Active Specification" section
+  const statePath = path.join(cwd, '.specflow', 'STATE.md');
+  const stateContent = safeReadFile(statePath);
+  const stateHasSection = stateContent ? stateContent.includes('## Active Specification') : false;
+  const stateValid = !!stateContent && stateHasSection;
+  checks.push({ name: 'STATE.md exists with Active Specification section', passed: stateValid });
+  if (!stateContent) {
+    errors.push('STATE.md not found');
+  } else if (!stateHasSection) {
+    errors.push('STATE.md missing "## Active Specification" section');
+  }
+
+  // Check 3: specs/ directory exists
+  const specsDir = path.join(cwd, '.specflow', 'specs');
+  const specsDirExists = fs.existsSync(specsDir) && fs.statSync(specsDir).isDirectory();
+  checks.push({ name: '.specflow/specs/ directory exists', passed: specsDirExists });
+  if (!specsDirExists) {
+    errors.push('.specflow/specs/ directory not found');
+  }
+
+  // Check 4: archive/ directory exists
+  const archiveDir = path.join(cwd, '.specflow', 'archive');
+  const archiveDirExists = fs.existsSync(archiveDir) && fs.statSync(archiveDir).isDirectory();
+  checks.push({ name: '.specflow/archive/ directory exists', passed: archiveDirExists });
+  if (!archiveDirExists) {
+    errors.push('.specflow/archive/ directory not found');
+  }
+
+  // Check 5: Active spec referenced in STATE.md exists in specs/ (if set)
+  let activeSpecCheck = true;
+  if (stateContent) {
+    const activeSpec = extractActiveSpec(stateContent);
+
+    if (activeSpec && activeSpec !== 'None' && activeSpec !== '(none)') {
+      const activeSpecPath = path.join(specsDir, activeSpec + '.md');
+      const activeSpecExists = fs.existsSync(activeSpecPath);
+      activeSpecCheck = activeSpecExists;
+      if (!activeSpecExists) {
+        errors.push('Active spec ' + activeSpec + ' not found in specs/');
+      }
+    }
+  }
+  checks.push({ name: 'Active spec exists in specs/ (if set)', passed: activeSpecCheck });
+
+  // Check 6: All specs in specs/ have valid YAML frontmatter with required fields
+  let allSpecsValid = true;
+  if (specsDirExists) {
+    let specFiles;
+    try {
+      specFiles = fs.readdirSync(specsDir).filter(f => f.endsWith('.md'));
+    } catch (e) {
+      specFiles = [];
+    }
+
+    for (const file of specFiles) {
+      const content = safeReadFile(path.join(specsDir, file));
+      if (!content) {
+        allSpecsValid = false;
+        errors.push('Cannot read spec file: ' + file);
+        continue;
+      }
+
+      const parsed = parseFrontmatter(content);
+      const fm = parsed.frontmatter;
+      const requiredFields = ['id', 'type', 'status'];
+      const missingFields = requiredFields.filter(f => !fm[f]);
+
+      if (missingFields.length > 0) {
+        allSpecsValid = false;
+        errors.push(file + ' missing required frontmatter fields: ' + missingFields.join(', '));
+      }
+    }
+  } else {
+    allSpecsValid = false;
+  }
+  checks.push({ name: 'All specs have valid frontmatter (id, type, status)', passed: allSpecsValid });
+
+  const valid = checks.every(c => c.passed);
+
+  output({ valid, checks, errors }, raw, valid ? 'valid' : 'invalid');
+}
+
+module.exports = {
+  cmdVerifyStructure,
+};

package/bin/sf-tools.cjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * bin/sf-tools.cjs — Centralized CLI for SpecFlow operations
+ *
+ * Usage: node bin/sf-tools.cjs <command> [args...]
+ *
+ * Commands:
+ *   spec load <id>                        Parse spec file, return frontmatter + body
+ *   spec list                             List all specs
+ *   spec next-id                          Next available SPEC-XXX number
+ *   queue next                            First actionable spec from queue
+ *   state get                             Current active spec, status, next step
+ *   state set-active <id> <status> [next] Update active spec in STATE.md
+ *   resolve-model <agent-type>            Model for agent by current profile
+ *   verify-structure                      Check .specflow/ integrity
+ *   generate-slug <text>                  Text to URL-safe slug
+ */
+
+'use strict';
+
+const { output, error, generateSlug } = require('./lib/core.cjs');
+const { cmdStateGet, cmdStateSetActive, cmdQueueNext } = require('./lib/state.cjs');
+const { cmdSpecLoad, cmdSpecList, cmdSpecNextId } = require('./lib/spec.cjs');
+const { cmdResolveModel } = require('./lib/config.cjs');
+const { cmdVerifyStructure } = require('./lib/verify.cjs');
+
+const cwd = process.cwd();
+const args = process.argv.slice(2);
+const raw = args.includes('--raw');
+const filteredArgs = args.filter(a => a !== '--raw');
+
+/**
+ * Command dispatch table.
+ * Keys are "command subcommand" or just "command".
+ */
+const COMMANDS = {
+  'spec load':       () => {
+    if (!filteredArgs[2]) error('Missing spec ID. Usage: spec load <id>');
+    cmdSpecLoad(cwd, filteredArgs[2], raw);
+  },
+  'spec list':       () => cmdSpecList(cwd, raw),
+  'spec next-id':    () => cmdSpecNextId(cwd, raw),
+  'queue next':      () => cmdQueueNext(cwd, raw),
+  'state get':       () => cmdStateGet(cwd, raw),
+  'state set-active': () => {
+    if (!filteredArgs[2] || !filteredArgs[3]) {
+      error('Missing arguments. Usage: state set-active <id> <status> [next_step]');
+    }
+    cmdStateSetActive(cwd, filteredArgs[2], filteredArgs[3], filteredArgs[4], raw);
+  },
+  'resolve-model':   () => {
+    if (!filteredArgs[1]) error('Missing agent type. Usage: resolve-model <agent-type>');
+    cmdResolveModel(cwd, filteredArgs[1], raw);
+  },
+  'verify-structure': () => cmdVerifyStructure(cwd, raw),
+  'generate-slug':   () => {
+    if (!filteredArgs[1]) error('Missing text. Usage: generate-slug <text>');
+    output({ slug: generateSlug(filteredArgs[1]) }, raw, generateSlug(filteredArgs[1]));
+  },
+};
+
+function printUsage() {
+  const usage = `sf-tools — SpecFlow CLI
+
+Usage: node bin/sf-tools.cjs <command> [args...] [--raw]
+
+Commands:
+  spec load <id>                          Parse spec file, return frontmatter + body
+  spec list                               List all specs from .specflow/specs/
+  spec next-id                            Next available SPEC-XXX number
+  queue next                              First actionable spec from queue table
+  state get                               Current active spec, status, next step
+  state set-active <id> <status> [next]   Update active spec, status, next step
+  resolve-model <agent-type>              Resolve model for agent by current profile
+  verify-structure                        Check .specflow/ directory integrity
+  generate-slug <text>                    Convert text to URL-safe slug
+
+Options:
+  --raw    Output plain string instead of JSON
+
+All commands output JSON to stdout. Errors go to stderr with exit code 1.
+`;
+  process.stdout.write(usage);
+}
+
+// Main dispatch
+if (filteredArgs.length === 0) {
+  printUsage();
+  process.exit(0);
+}
+
+// Try two-word command first, then single-word
+const twoWord = filteredArgs[0] + ' ' + (filteredArgs[1] || '');
+const oneWord = filteredArgs[0];
+
+if (COMMANDS[twoWord]) {
+  COMMANDS[twoWord]();
+} else if (COMMANDS[oneWord]) {
+  COMMANDS[oneWord]();
+} else {
+  error('Unknown command: ' + filteredArgs.join(' ') + '. Run without arguments for usage help.');
+}

package/commands/sf/audit.md

@@ -242,75 +242,17 @@ The agent will:
 
 After the agent updates STATE.md, check if rotation is needed:
 
-```bash
-LINE_COUNT=$(wc -l < .specflow/STATE.md)
-if [ $LINE_COUNT -gt 100 ]; then
-    echo "STATE.md exceeds 100 lines ($LINE_COUNT), rotating old decisions..."
-
-    # Parse decisions table and extract all decisions
-    DECISIONS=$(awk '/^## Decisions$/ { found=1; next } /^## / && found { exit } found { print }' .specflow/STATE.md | grep -E '^\| [0-9]{4}-' || true)
-    DECISION_COUNT=$(echo "$DECISIONS" | grep -c '^|' || echo 0)
-
-    if [ "$DECISION_COUNT" -gt 7 ]; then
-        # Keep only 5 most recent decisions
-        RECENT_DECISIONS=$(echo "$DECISIONS" | tail -5)
-        OLD_DECISION_COUNT=$((DECISION_COUNT - 5))
-        OLD_DECISIONS=$(echo "$DECISIONS" | head -n $OLD_DECISION_COUNT)
-
-        # Create or append to archive
-        if [ ! -f .specflow/DECISIONS_ARCHIVE.md ]; then
-            cat > .specflow/DECISIONS_ARCHIVE.md << 'EOF'
-# SpecFlow Decisions Archive
-
-Historical decisions rotated from STATE.md to maintain compactness.
-
-## Archived Decisions
-
-| Date | Decision |
-|------|----------|
-EOF
-        fi
-
-        # Write old decisions to temp file for awk to read (awk -v cannot handle multiline strings)
-        TEMP_OLD=$(mktemp)
-        echo "$OLD_DECISIONS" > "$TEMP_OLD"
-
-        # Append old decisions to archive (insert after table header)
-        TEMP_ARCHIVE=$(mktemp)
-        awk -v oldfile="$TEMP_OLD" '
-            /^\| Date \| Decision \|$/ { print; getline; print; while ((getline line < oldfile) > 0) print line; close(oldfile); next }
-            {print}
-        ' .specflow/DECISIONS_ARCHIVE.md > "$TEMP_ARCHIVE"
-        mv "$TEMP_ARCHIVE" .specflow/DECISIONS_ARCHIVE.md
-        rm -f "$TEMP_OLD"
-
-        # Write recent decisions to temp file for awk to read
-        TEMP_RECENT=$(mktemp)
-        echo "$RECENT_DECISIONS" > "$TEMP_RECENT"
-
-        # Update STATE.md with only recent decisions
-        TEMP_STATE=$(mktemp)
-        awk -v recentfile="$TEMP_RECENT" '
-            /^## Decisions$/ {
-                print
-                print ""
-                print "| Date | Decision |"
-                print "|------|----------|"
-                while ((getline line < recentfile) > 0) print line
-                close(recentfile)
-                in_decisions=1
-                next
-            }
-            /^## / && in_decisions { in_decisions=0 }
-            !in_decisions || !/^\|/ { print }
-        ' .specflow/STATE.md > "$TEMP_STATE"
-        mv "$TEMP_STATE" .specflow/STATE.md
-        rm -f "$TEMP_RECENT"
-
-        echo "Rotated $(echo "$OLD_DECISIONS" | grep -c '^|') old decisions to DECISIONS_ARCHIVE.md"
-    fi
-fi
-```
+1. Use the Read tool to read `.specflow/STATE.md` and count total lines
+2. If total lines <= 100, no action needed
+3. If total lines > 100:
+   a. Read the `## Decisions` section and extract all decision rows (lines matching `| YYYY-`)
+   b. Count decision rows. If <= 7, no rotation needed
+   c. If > 7 decisions:
+      - Identify the 5 most recent decisions (last 5 rows) -- these STAY
+      - Identify older decisions (all rows except last 5) -- these MOVE to archive
+      - Read `.specflow/DECISIONS_ARCHIVE.md` (create with template if missing)
+      - Write updated DECISIONS_ARCHIVE.md: insert old decisions after the table header row
+      - Write updated STATE.md: replace Decisions section content with only the 5 most recent decisions
 
 ## Step 7: Display Result