specflow-cc 1.13.0 → 1.14.0

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/done.md

@@ -175,7 +175,7 @@ mkdir -p .specflow/archive
 Update frontmatter:
 - status → "done"
 
-Add completion timestamp:
+Add completion summary section to the spec:
 
 ```markdown
 ---
@@ -185,14 +185,33 @@ Add completion timestamp:
 **Completed:** {date} {time}
 **Total Commits:** {count from Execution Summary}
 **Review Cycles:** {count of Review v[N] entries}
+
+### Outcome
+
+{1-2 sentence summary of what was delivered}
+
+### Key Files
+
+- `{path}` — {what it does/why it matters}
+
+### Patterns Established
+
+{List any new patterns, conventions, or architectural decisions introduced.
+If none: "None — followed existing patterns."}
+
+### Deviations
+
+{Any deviations from the original spec during implementation.
+If none: "None — implemented as specified."}
 ```
 
 ## Step 7: Extract Decisions
 
-Scan specification for important decisions:
+Scan specification and Completion section for important decisions:
 - Technology choices mentioned in Context or Assumptions
 - Patterns established during implementation
 - Constraints discovered
+- Deviations that became new conventions
 
 If significant decisions found, add to STATE.md Decisions table: