jumpstart-mode 1.1.11 → 1.1.13

package/bin/lib/bcdr-planning.js

@@ -0,0 +1,158 @@
+/**
+ * bcdr-planning.js — Business Continuity & DR Planning (Item 38)
+ *
+ * Add RTO/RPO, failover design, backup validation, and continuity
+ * considerations into specs.
+ *
+ * Usage:
+ *   node bin/lib/bcdr-planning.js define|check|report [options]
+ *
+ * State file: .jumpstart/state/bcdr.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'bcdr.json');
+
+const SERVICE_TIERS = {
+  platinum: { rto_hours: 0.25, rpo_hours: 0, failover: 'automatic', backup_frequency: 'continuous' },
+  gold: { rto_hours: 1, rpo_hours: 1, failover: 'automatic', backup_frequency: 'hourly' },
+  silver: { rto_hours: 4, rpo_hours: 4, failover: 'manual', backup_frequency: 'daily' },
+  bronze: { rto_hours: 24, rpo_hours: 24, failover: 'manual', backup_frequency: 'weekly' }
+};
+
+const BCDR_COMPONENTS = ['rto-rpo', 'failover-design', 'backup-validation', 'communication-plan', 'recovery-procedures', 'testing-schedule'];
+
+function defaultState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    services: [],
+    dr_tests: []
+  };
+}
+
+function loadState(stateFile) {
+  const filePath = stateFile || DEFAULT_STATE_FILE;
+  if (!fs.existsSync(filePath)) return defaultState();
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); }
+  catch { return defaultState(); }
+}
+
+function saveState(state, stateFile) {
+  const filePath = stateFile || DEFAULT_STATE_FILE;
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  state.last_updated = new Date().toISOString();
+  fs.writeFileSync(filePath, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Define BC/DR requirements for a service.
+ *
+ * @param {object} service - { name, tier, rto_hours?, rpo_hours?, dependencies[]? }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function defineService(service, options = {}) {
+  if (!service || !service.name) return { success: false, error: 'service.name is required' };
+
+  const tier = (service.tier || 'silver').toLowerCase();
+  const template = SERVICE_TIERS[tier];
+  if (!template) {
+    return { success: false, error: `Invalid tier. Must be one of: ${Object.keys(SERVICE_TIERS).join(', ')}` };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const svc = {
+    id: `SVC-${(state.services.length + 1).toString().padStart(3, '0')}`,
+    name: service.name,
+    tier,
+    rto_hours: service.rto_hours || template.rto_hours,
+    rpo_hours: service.rpo_hours || template.rpo_hours,
+    failover: service.failover || template.failover,
+    backup_frequency: service.backup_frequency || template.backup_frequency,
+    dependencies: service.dependencies || [],
+    recovery_procedures: service.recovery_procedures || [],
+    defined_at: new Date().toISOString()
+  };
+
+  state.services.push(svc);
+  saveState(state, stateFile);
+
+  return { success: true, service: svc };
+}
+
+/**
+ * Check BC/DR coverage in specs.
+ *
+ * @param {string} root
+ * @param {object} [options]
+ * @returns {object}
+ */
+function checkCoverage(root, options = {}) {
+  const archFile = path.join(root, 'specs', 'architecture.md');
+  const findings = {};
+
+  if (fs.existsSync(archFile)) {
+    try {
+      const content = fs.readFileSync(archFile, 'utf8');
+      findings['rto-rpo'] = /\bRTO\b|\bRPO\b|recovery.time|recovery.point/i.test(content);
+      findings['failover-design'] = /\bfailover\b|high.availability|redundan/i.test(content);
+      findings['backup-validation'] = /\bbackup\b|snapshot|restore/i.test(content);
+      findings['recovery-procedures'] = /\brecovery\b|disaster|DR\b/i.test(content);
+    } catch { /* ignore */ }
+  }
+
+  findings['communication-plan'] = false;
+  findings['testing-schedule'] = false;
+
+  const covered = Object.values(findings).filter(Boolean).length;
+  const total = BCDR_COMPONENTS.length;
+
+  return {
+    success: true,
+    coverage: Math.round((covered / total) * 100),
+    components: findings,
+    gaps: BCDR_COMPONENTS.filter(c => !findings[c]),
+    recommendations: BCDR_COMPONENTS.filter(c => !findings[c]).map(c => `Add ${c} section to architecture spec`)
+  };
+}
+
+/**
+ * Generate BCDR report.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function generateReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  return {
+    success: true,
+    total_services: state.services.length,
+    by_tier: state.services.reduce((acc, s) => { acc[s.tier] = (acc[s.tier] || 0) + 1; return acc; }, {}),
+    services: state.services,
+    dr_tests: state.dr_tests,
+    lowest_rto: state.services.length > 0 ? Math.min(...state.services.map(s => s.rto_hours)) : null,
+    lowest_rpo: state.services.length > 0 ? Math.min(...state.services.map(s => s.rpo_hours)) : null
+  };
+}
+
+module.exports = {
+  defaultState,
+  loadState,
+  saveState,
+  defineService,
+  checkCoverage,
+  generateReport,
+  SERVICE_TIERS,
+  BCDR_COMPONENTS
+};

package/bin/lib/bidirectional-trace.js

@@ -0,0 +1,199 @@
+/**
+ * bidirectional-trace.js — True Bidirectional Code-to-Spec Traceability
+ *
+ * Auto-links requirements to files, functions, tests, PRs, commits,
+ * and deployments. Provides forward (spec→code) and reverse (code→spec)
+ * trace lookups.
+ *
+ * Usage:
+ *   node bin/lib/bidirectional-trace.js scan|report|link [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Scan a source directory and build a bidirectional trace map.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object} Trace map with forward and reverse indexes.
+ */
+function scanTraceLinks(root, options = {}) {
+  const specsDir = path.join(root, 'specs');
+  const srcDir = path.join(root, options.srcDir || 'src');
+  const testsDir = path.join(root, options.testsDir || 'tests');
+
+  const forwardMap = {};   // specId → [{ file, line, type }]
+  const reverseMap = {};   // file  → [{ specId, line, type }]
+
+  // Patterns for spec references in code
+  const SPEC_ID_PATTERN = /(?:E\d+-S\d+|M\d+-T\d+|NFR-[A-Z]+\d+|VC-\d+)/g;
+
+  function recordLink(specId, file, line, type) {
+    if (!forwardMap[specId]) forwardMap[specId] = [];
+    forwardMap[specId].push({ file, line, type });
+
+    if (!reverseMap[file]) reverseMap[file] = [];
+    reverseMap[file].push({ specId, line, type });
+  }
+
+  function scanDir(dir, fileType) {
+    if (!fs.existsSync(dir)) return;
+    const walk = (d) => {
+      for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        const full = path.join(d, entry.name);
+        if (entry.isDirectory()) {
+          walk(full);
+        } else if (entry.isFile()) {
+          const rel = path.relative(root, full).replace(/\\/g, '/');
+          try {
+            const content = fs.readFileSync(full, 'utf8');
+            const lines = content.split('\n');
+            lines.forEach((line, idx) => {
+              let match;
+              const pattern = new RegExp(SPEC_ID_PATTERN.source, 'g');
+              while ((match = pattern.exec(line)) !== null) {
+                recordLink(match[0], rel, idx + 1, fileType);
+              }
+            });
+          } catch {
+            // skip unreadable files
+          }
+        }
+      }
+    };
+    walk(dir);
+  }
+
+  scanDir(srcDir, 'source');
+  scanDir(testsDir, 'test');
+
+  // Also scan spec files for cross-references
+  if (fs.existsSync(specsDir)) {
+    scanDir(specsDir, 'spec');
+  }
+
+  const stats = {
+    total_spec_ids: Object.keys(forwardMap).length,
+    total_files_with_links: Object.keys(reverseMap).length,
+    total_links: Object.values(forwardMap).reduce((s, a) => s + a.length, 0)
+  };
+
+  return { forward_map: forwardMap, reverse_map: reverseMap, stats };
+}
+
+/**
+ * Trace forward: given a spec ID, find all code that implements it.
+ *
+ * @param {string} specId - Spec ID (e.g., E1-S1, M1-T01).
+ * @param {object} traceMap - Result from scanTraceLinks().
+ * @returns {object[]} Array of { file, line, type }.
+ */
+function traceForward(specId, traceMap) {
+  return (traceMap.forward_map || {})[specId] || [];
+}
+
+/**
+ * Trace reverse: given a file, find all spec IDs it relates to.
+ *
+ * @param {string} filePath - Relative file path.
+ * @param {object} traceMap - Result from scanTraceLinks().
+ * @returns {object[]} Array of { specId, line, type }.
+ */
+function traceReverse(filePath, traceMap) {
+  return (traceMap.reverse_map || {})[filePath] || [];
+}
+
+/**
+ * Build a coverage summary — which spec IDs have no code links (gaps).
+ *
+ * @param {string} root - Project root.
+ * @param {object} traceMap - Result from scanTraceLinks().
+ * @returns {object} Coverage report.
+ */
+function buildCoverageReport(root, traceMap) {
+  const specsDir = path.join(root, 'specs');
+  const prdPath = path.join(specsDir, 'prd.md');
+  const implPath = path.join(specsDir, 'implementation-plan.md');
+
+  const allSpecIds = new Set();
+  const SPEC_ID_PATTERN = /(?:E\d+-S\d+|M\d+-T\d+|NFR-[A-Z]+\d+|VC-\d+)/g;
+
+  function extractFromFile(filePath) {
+    if (!fs.existsSync(filePath)) return;
+    const content = fs.readFileSync(filePath, 'utf8');
+    let match;
+    while ((match = SPEC_ID_PATTERN.exec(content)) !== null) {
+      allSpecIds.add(match[0]);
+    }
+  }
+
+  extractFromFile(prdPath);
+  extractFromFile(implPath);
+
+  // Only count links from source and test files, not from spec files themselves.
+  const codeLinked = new Set();
+  for (const [specId, links] of Object.entries(traceMap.forward_map || {})) {
+    if (links.some(l => l.type === 'source' || l.type === 'test')) {
+      codeLinked.add(specId);
+    }
+  }
+  const gaps = [...allSpecIds].filter(id => !codeLinked.has(id));
+  const covered = [...allSpecIds].filter(id => codeLinked.has(id));
+
+  const coverage_pct = allSpecIds.size > 0
+    ? Math.round((covered.length / allSpecIds.size) * 100)
+    : 0;
+
+  return {
+    total_spec_ids: allSpecIds.size,
+    covered: covered.length,
+    gaps: gaps.length,
+    coverage_pct,
+    gap_list: gaps,
+    covered_list: covered
+  };
+}
+
+/**
+ * Persist a trace map to disk.
+ *
+ * @param {object} traceMap
+ * @param {string} outputPath
+ */
+function saveTraceMap(traceMap, outputPath) {
+  const dir = path.dirname(outputPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(outputPath, JSON.stringify(traceMap, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Load a persisted trace map from disk.
+ *
+ * @param {string} inputPath
+ * @returns {object}
+ */
+function loadTraceMap(inputPath) {
+  if (!fs.existsSync(inputPath)) {
+    return { forward_map: {}, reverse_map: {}, stats: {} };
+  }
+  try {
+    return JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+  } catch {
+    return { forward_map: {}, reverse_map: {}, stats: {} };
+  }
+}
+
+module.exports = {
+  scanTraceLinks,
+  traceForward,
+  traceReverse,
+  buildCoverageReport,
+  saveTraceMap,
+  loadTraceMap
+};

package/bin/lib/branch-workflow.js

@@ -0,0 +1,266 @@
+/**
+ * branch-workflow.js — Branch-Aware Workflow Engine
+ *
+ * Specs, approvals, and implementation plans track by git branch and PR,
+ * not just by repo folder state. Each branch gets its own workflow snapshot.
+ *
+ * Usage:
+ *   node bin/lib/branch-workflow.js track|status|sync [options]
+ *
+ * State file: .jumpstart/state/branch-workflows.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const DEFAULT_BRANCH_STATE_FILE = path.join('.jumpstart', 'state', 'branch-workflows.json');
+
+/**
+ * Safely get the current git branch name.
+ * @param {string} [cwd]
+ * @returns {string} Branch name or 'unknown'.
+ */
+function getCurrentBranch(cwd) {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: cwd || process.cwd(),
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).toString().trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Safely get the current git commit SHA.
+ * @param {string} [cwd]
+ * @returns {string} Commit SHA or 'unknown'.
+ */
+function getCurrentCommit(cwd) {
+  try {
+    return execSync('git rev-parse HEAD', {
+      cwd: cwd || process.cwd(),
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).toString().trim();
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Default branch workflow store.
+ * @returns {object}
+ */
+function defaultBranchStore() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    branches: {}
+  };
+}
+
+/**
+ * Load the branch workflow store from disk.
+ * @param {string} [stateFile]
+ * @returns {object}
+ */
+function loadBranchStore(stateFile) {
+  const filePath = stateFile || DEFAULT_BRANCH_STATE_FILE;
+  if (!fs.existsSync(filePath)) {
+    return defaultBranchStore();
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return defaultBranchStore();
+  }
+}
+
+/**
+ * Save the branch workflow store to disk.
+ * @param {object} store
+ * @param {string} [stateFile]
+ */
+function saveBranchStore(store, stateFile) {
+  const filePath = stateFile || DEFAULT_BRANCH_STATE_FILE;
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  store.last_updated = new Date().toISOString();
+  fs.writeFileSync(filePath, JSON.stringify(store, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Start tracking a branch. Creates or updates the branch workflow entry.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options] - { branch?, pr_number?, pr_url?, stateFile? }
+ * @returns {object}
+ */
+function trackBranch(root, options = {}) {
+  const branch = options.branch || getCurrentBranch(root);
+  const commit = getCurrentCommit(root);
+  const stateFile = options.stateFile || path.join(root, DEFAULT_BRANCH_STATE_FILE);
+  const store = loadBranchStore(stateFile);
+
+  const existing = store.branches[branch] || {
+    branch,
+    created_at: new Date().toISOString(),
+    phase_snapshots: [],
+    approved_artifacts: [],
+    pr_number: null,
+    pr_url: null
+  };
+
+  existing.branch = branch;
+  existing.last_commit = commit;
+  existing.last_seen = new Date().toISOString();
+
+  if (options.pr_number !== undefined) existing.pr_number = options.pr_number;
+  if (options.pr_url !== undefined) existing.pr_url = options.pr_url;
+
+  store.branches[branch] = existing;
+  saveBranchStore(store, stateFile);
+
+  return { success: true, branch: existing };
+}
+
+/**
+ * Record a phase snapshot for a specific branch.
+ *
+ * @param {string} root - Project root.
+ * @param {number} phase - Phase number.
+ * @param {object} snapshot - Additional snapshot data.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function recordPhaseSnapshot(root, phase, snapshot = {}, options = {}) {
+  const branch = options.branch || getCurrentBranch(root);
+  const stateFile = options.stateFile || path.join(root, DEFAULT_BRANCH_STATE_FILE);
+  const store = loadBranchStore(stateFile);
+
+  if (!store.branches[branch]) {
+    store.branches[branch] = {
+      branch,
+      created_at: new Date().toISOString(),
+      phase_snapshots: [],
+      approved_artifacts: [],
+      pr_number: null,
+      pr_url: null
+    };
+  }
+
+  const entry = {
+    phase,
+    recorded_at: new Date().toISOString(),
+    commit: getCurrentCommit(root),
+    ...snapshot
+  };
+
+  store.branches[branch].phase_snapshots.push(entry);
+  saveBranchStore(store, stateFile);
+
+  return { success: true, branch, snapshot: entry };
+}
+
+/**
+ * Record an artifact approval for a specific branch.
+ *
+ * @param {string} root
+ * @param {string} artifactPath
+ * @param {string} approver
+ * @param {object} [options]
+ * @returns {object}
+ */
+function recordBranchApproval(root, artifactPath, approver, options = {}) {
+  const branch = options.branch || getCurrentBranch(root);
+  const stateFile = options.stateFile || path.join(root, DEFAULT_BRANCH_STATE_FILE);
+  const store = loadBranchStore(stateFile);
+
+  if (!store.branches[branch]) {
+    store.branches[branch] = {
+      branch,
+      created_at: new Date().toISOString(),
+      phase_snapshots: [],
+      approved_artifacts: [],
+      pr_number: null,
+      pr_url: null
+    };
+  }
+
+  const entry = {
+    artifact: artifactPath,
+    approver,
+    approved_at: new Date().toISOString(),
+    commit: getCurrentCommit(root)
+  };
+
+  store.branches[branch].approved_artifacts.push(entry);
+  saveBranchStore(store, stateFile);
+
+  return { success: true, branch, approval: entry };
+}
+
+/**
+ * Get the workflow status of a branch.
+ *
+ * @param {string} root
+ * @param {object} [options]
+ * @returns {object}
+ */
+function getBranchStatus(root, options = {}) {
+  const branch = options.branch || getCurrentBranch(root);
+  const stateFile = options.stateFile || path.join(root, DEFAULT_BRANCH_STATE_FILE);
+  const store = loadBranchStore(stateFile);
+
+  const branchData = store.branches[branch];
+  if (!branchData) {
+    return {
+      success: true,
+      branch,
+      tracked: false,
+      message: `Branch "${branch}" is not yet tracked. Run: jumpstart-mode branch-workflow track`
+    };
+  }
+
+  return {
+    success: true,
+    branch,
+    tracked: true,
+    data: branchData,
+    phase_count: (branchData.phase_snapshots || []).length,
+    approved_count: (branchData.approved_artifacts || []).length
+  };
+}
+
+/**
+ * List all tracked branches.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function listTrackedBranches(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_BRANCH_STATE_FILE;
+  const store = loadBranchStore(stateFile);
+
+  const branches = Object.values(store.branches);
+  return { success: true, branches, total: branches.length };
+}
+
+module.exports = {
+  getCurrentBranch,
+  getCurrentCommit,
+  loadBranchStore,
+  saveBranchStore,
+  defaultBranchStore,
+  trackBranch,
+  recordPhaseSnapshot,
+  recordBranchApproval,
+  getBranchStatus,
+  listTrackedBranches
+};