jumpstart-mode 1.1.12 → 1.1.13

package/bin/lib/telemetry-feedback.js

@@ -0,0 +1,118 @@
+/**
+ * telemetry-feedback.js — Production Telemetry Feedback Loop (Item 95)
+ *
+ * Feed real performance and reliability data back into
+ * future planning and architecture.
+ *
+ * Usage:
+ *   node bin/lib/telemetry-feedback.js ingest|analyze|report [options]
+ *
+ * State file: .jumpstart/state/telemetry-feedback.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'telemetry-feedback.json');
+
+const METRIC_TYPES = ['latency', 'error-rate', 'throughput', 'availability', 'saturation', 'cost'];
+
+function defaultState() {
+  return { version: '1.0.0', metrics: [], insights: [], last_updated: null };
+}
+
+function loadState(stateFile) {
+  const fp = stateFile || DEFAULT_STATE_FILE;
+  if (!fs.existsSync(fp)) return defaultState();
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); }
+  catch { return defaultState(); }
+}
+
+function saveState(state, stateFile) {
+  const fp = stateFile || DEFAULT_STATE_FILE;
+  const dir = path.dirname(fp);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  state.last_updated = new Date().toISOString();
+  fs.writeFileSync(fp, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+
+function ingestMetric(name, type, value, options = {}) {
+  if (!name || !type) return { success: false, error: 'name and type are required' };
+  if (!METRIC_TYPES.includes(type)) {
+    return { success: false, error: `Unknown type: ${type}. Valid: ${METRIC_TYPES.join(', ')}` };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const metric = {
+    id: `TEL-${Date.now()}`,
+    name,
+    type,
+    value,
+    unit: options.unit || null,
+    service: options.service || null,
+    timestamp: new Date().toISOString()
+  };
+
+  state.metrics.push(metric);
+  saveState(state, stateFile);
+
+  return { success: true, metric };
+}
+
+function analyzeMetrics(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const byType = {};
+  for (const m of state.metrics) {
+    if (!byType[m.type]) byType[m.type] = [];
+    byType[m.type].push(m.value);
+  }
+
+  const analysis = {};
+  for (const [type, values] of Object.entries(byType)) {
+    const nums = values.filter(v => typeof v === 'number');
+    if (nums.length > 0) {
+      analysis[type] = {
+        count: nums.length,
+        avg: Math.round((nums.reduce((a, b) => a + b, 0) / nums.length) * 100) / 100,
+        min: Math.min(...nums),
+        max: Math.max(...nums)
+      };
+    }
+  }
+
+  return { success: true, total_metrics: state.metrics.length, analysis };
+}
+
+function generateFeedbackReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+  const analysis = analyzeMetrics(options);
+
+  const recommendations = [];
+  if (analysis.analysis.latency && analysis.analysis.latency.avg > 500) {
+    recommendations.push('High average latency detected — consider caching or query optimization');
+  }
+  if (analysis.analysis['error-rate'] && analysis.analysis['error-rate'].avg > 5) {
+    recommendations.push('Elevated error rate — review error handling and resilience patterns');
+  }
+
+  return {
+    success: true,
+    total_metrics: state.metrics.length,
+    total_insights: state.insights.length,
+    analysis: analysis.analysis,
+    recommendations
+  };
+}
+
+module.exports = {
+  ingestMetric, analyzeMetrics, generateFeedbackReport,
+  loadState, saveState, defaultState,
+  METRIC_TYPES
+};

package/bin/lib/test-generator.js

@@ -0,0 +1,146 @@
+/**
+ * test-generator.js — Test Generation Tied to Acceptance Criteria (Item 44)
+ *
+ * Auto-generate unit, integration, API, UI, and contract tests
+ * from requirements.
+ *
+ * Usage:
+ *   node bin/lib/test-generator.js generate|coverage [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const TEST_TYPES = ['unit', 'integration', 'api', 'ui', 'contract', 'e2e'];
+
+const TEST_FRAMEWORKS = {
+  javascript: { framework: 'vitest', extension: '.test.js', import: "import { describe, it, expect } from 'vitest';" },
+  typescript: { framework: 'vitest', extension: '.test.ts', import: "import { describe, it, expect } from 'vitest';" },
+  python: { framework: 'pytest', extension: '_test.py', import: 'import pytest' }
+};
+
+/**
+ * Extract acceptance criteria from PRD content.
+ *
+ * @param {string} content - PRD markdown content.
+ * @returns {object[]}
+ */
+function extractCriteria(content) {
+  const criteria = [];
+  const lines = content.split('\n');
+  let currentStory = null;
+
+  for (const line of lines) {
+    const storyMatch = line.match(/\*\*(E\d+-S\d+)\*\*/);
+    if (storyMatch) currentStory = storyMatch[1];
+
+    const givenMatch = line.match(/^\s*[-*]\s*(Given\s+.+)/i);
+    const whenMatch = line.match(/^\s*[-*]\s*(When\s+.+)/i);
+    const thenMatch = line.match(/^\s*[-*]\s*(Then\s+.+)/i);
+    const acMatch = line.match(/^\s*[-*]\s*AC\d*:\s*(.+)/i);
+
+    if (givenMatch || whenMatch || thenMatch || acMatch) {
+      criteria.push({
+        story: currentStory,
+        criterion: (givenMatch || whenMatch || thenMatch || acMatch)[1].trim(),
+        type: givenMatch ? 'given' : whenMatch ? 'when' : thenMatch ? 'then' : 'acceptance'
+      });
+    }
+  }
+
+  return criteria;
+}
+
+/**
+ * Generate test stubs from acceptance criteria.
+ *
+ * @param {object[]} criteria - Extracted criteria.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function generateTestStubs(criteria, options = {}) {
+  const language = options.language || 'javascript';
+  const fwConfig = TEST_FRAMEWORKS[language];
+  if (!fwConfig) {
+    return { success: false, error: `Unsupported language: ${language}` };
+  }
+
+  const byStory = {};
+  for (const c of criteria) {
+    const story = c.story || 'general';
+    if (!byStory[story]) byStory[story] = [];
+    byStory[story].push(c);
+  }
+
+  const testFiles = [];
+  for (const [story, storyCriteria] of Object.entries(byStory)) {
+    const fileName = `${story.toLowerCase().replace(/[^a-z0-9]/g, '-')}${fwConfig.extension}`;
+    const tests = storyCriteria.map(c => {
+      const testName = c.criterion.replace(/'/g, "\\'").substring(0, 100);
+      return `  it('${testName}', () => {\n    // TODO: Implement test for ${c.type}\n    expect(true).toBe(true);\n  });`;
+    });
+
+    const content = `${fwConfig.import}\n\ndescribe('${story}', () => {\n${tests.join('\n\n')}\n});\n`;
+    testFiles.push({ fileName, content, story, test_count: storyCriteria.length });
+  }
+
+  return {
+    success: true,
+    total_criteria: criteria.length,
+    test_files: testFiles.length,
+    files: testFiles,
+    framework: fwConfig.framework
+  };
+}
+
+/**
+ * Check test coverage against acceptance criteria.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function checkCoverage(root, options = {}) {
+  const prdFile = path.join(root, 'specs', 'prd.md');
+  if (!fs.existsSync(prdFile)) {
+    return { success: false, error: 'PRD not found at specs/prd.md' };
+  }
+
+  const prdContent = fs.readFileSync(prdFile, 'utf8');
+  const criteria = extractCriteria(prdContent);
+
+  // Check test directory for matching tests
+  const testDir = path.join(root, 'tests');
+  let testContent = '';
+  if (fs.existsSync(testDir)) {
+    for (const entry of fs.readdirSync(testDir)) {
+      if (entry.endsWith('.test.js') || entry.endsWith('.test.ts')) {
+        try { testContent += fs.readFileSync(path.join(testDir, entry), 'utf8') + '\n'; }
+        catch { /* skip */ }
+      }
+    }
+  }
+
+  const covered = criteria.filter(c => {
+    const terms = c.criterion.toLowerCase().split(/\s+/).filter(t => t.length > 3);
+    return terms.some(t => testContent.toLowerCase().includes(t));
+  });
+
+  return {
+    success: true,
+    total_criteria: criteria.length,
+    covered: covered.length,
+    coverage: criteria.length > 0 ? Math.round((covered.length / criteria.length) * 100) : 0,
+    uncovered: criteria.filter(c => !covered.includes(c))
+  };
+}
+
+module.exports = {
+  extractCriteria,
+  generateTestStubs,
+  checkCoverage,
+  TEST_TYPES,
+  TEST_FRAMEWORKS
+};

package/bin/lib/timeline.js

@@ -36,6 +36,7 @@ const EVENT_TYPES = [
   'approval', 'rejection',
   'subagent_invoked', 'subagent_completed',
   'llm_turn_start', 'llm_turn_end',
+  'prompt_logged',
   'research_query', 'checkpoint_created', 'rewind',
   'handoff', 'usage_logged', 'custom'
 ];
@@ -780,7 +781,7 @@ function _shouldCapture(eventType, capture) {
     case 'research_query':
       return capture.research;
     default:
-      return true; // Always capture: phase_start, phase_end, handoff, checkpoint, rewind, usage_logged, custom
+      return true; // Always capture: phase_start, phase_end, prompt_logged, handoff, checkpoint, rewind, usage_logged, custom
   }
 }
 

package/bin/lib/tool-bridge.js

@@ -255,6 +255,113 @@ function createToolBridge(options = {}) {
       return { success: !!evt, event_id: evt ? evt.id : null };
     },
 
+    /**
+     * Log token usage and cost to .jumpstart/usage-log.json.
+     */
+    async log_usage(args) {
+      try {
+        const { logUsage } = await import('./usage.js');
+        const logPath = path.join(workspaceDir, '.jumpstart', 'usage-log.json');
+        const entry = {
+          phase: args.phase || 'unknown',
+          agent: args.agent || 'unknown',
+          action: args.action || 'unknown',
+          estimated_tokens: args.estimated_tokens || 0,
+          estimated_cost_usd: args.estimated_cost_usd || (args.estimated_tokens || 0) * 0.000002,
+          model: args.model || null,
+          metadata: args.metadata || null
+        };
+        const log = logUsage(logPath, entry);
+        return { success: true, total_tokens: log.total_tokens, total_entries: log.entries.length };
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    },
+
+    // ── Item-Tagged Feature Tool Handlers ──────────────────────────────────
+
+    async run_revert(args) {
+      try {
+        const { revertArtifact } = await import('./revert.js');
+        return revertArtifact({ artifact: args.artifact, reason: args.reason, archive_dir: args.archive_dir });
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    },
+
+    async run_adr_index(args) {
+      try {
+        const { buildIndex, searchIndex } = await import('./adr-index.js');
+        const root = args.root || workspaceDir;
+        if (args.action === 'search') {
+          const index = buildIndex(root);
+          return searchIndex(index, args.query || '', { tag: args.tag });
+        }
+        return buildIndex(root);
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    },
+
+    async run_complexity(args) {
+      try {
+        const { calculateComplexity } = await import('./complexity.js');
+        return calculateComplexity({ description: args.description || '', root: args.root || workspaceDir });
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    },
+
+    async run_crossref(args) {
+      try {
+        const { validateCrossRefs } = await import('./crossref.js');
+        return validateCrossRefs(args.specs_dir || 'specs', args.root || workspaceDir);
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    },
+
+    async run_init(args) {
+      try {
+        const { generateInitConfig } = await import('./init.js');
+        return generateInitConfig({ skill_level: args.skill_level || 'intermediate', project_type: args.project_type || 'greenfield' });
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    },
+
+    async run_lock(args) {
+      try {
+        const { acquireLock, releaseLock, lockStatus, listLocks } = await import('./locks.js');
+        if (args.action === 'acquire') return acquireLock(args.file, args.agent || 'headless');
+        if (args.action === 'release') return releaseLock(args.file, args.agent || 'headless');
+        if (args.action === 'status') return lockStatus(args.file);
+        return listLocks();
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    },
+
+    async run_timestamp(args) {
+      try {
+        const { now, validate, audit } = await import('./timestamps.js');
+        if (args.action === 'validate') return validate(args.value);
+        if (args.action === 'audit') return audit(args.file);
+        return { timestamp: now() };
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    },
+
+    async run_scan(args) {
+      try {
+        const { scan } = await import('./scanner.js');
+        return scan({ root: args.root || workspaceDir, ignore: args.ignore });
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    },
+
     // ── Quality Gate Tool Handlers ──────────────────────────────────────────
 
     async run_secret_scan(args) {

package/bin/lib/tool-guardrails.js

@@ -0,0 +1,139 @@
+/**
+ * tool-guardrails.js — Tool Execution Guardrails (Item 58)
+ *
+ * Validate risky file operations, deletions, schema changes,
+ * and wide-scope edits before execution.
+ *
+ * Usage:
+ *   node bin/lib/tool-guardrails.js check|policy|report [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const RISK_RULES = [
+  { id: 'delete-protection', pattern: /^(?:rm|del|remove)\s+/i, risk: 'high', description: 'File deletion operation' },
+  { id: 'recursive-delete', pattern: /rm\s+-rf?\s/i, risk: 'critical', description: 'Recursive deletion' },
+  { id: 'schema-change', pattern: /(?:ALTER|DROP|TRUNCATE)\s+(?:TABLE|DATABASE|SCHEMA)/i, risk: 'high', description: 'Database schema modification' },
+  { id: 'config-write', pattern: /(?:\.env|config|secrets?)\s*$/i, risk: 'high', description: 'Configuration file modification' },
+  { id: 'wide-glob', pattern: /\*\*\/\*|\*\.\*/i, risk: 'medium', description: 'Wide glob pattern' },
+  { id: 'sudo-usage', pattern: /\bsudo\b/i, risk: 'critical', description: 'Elevated privilege usage' },
+  { id: 'network-call', pattern: /\b(?:curl|wget|fetch)\s+http/i, risk: 'medium', description: 'External network call' },
+  { id: 'git-force', pattern: /git\s+(?:push\s+--force|reset\s+--hard)/i, risk: 'high', description: 'Force git operation' }
+];
+
+const PROTECTED_PATHS = [
+  '.env', '.env.local', '.env.production',
+  '.git/', 'node_modules/',
+  'package-lock.json', 'yarn.lock',
+  '.jumpstart/state/'
+];
+
+/**
+ * Check a command or operation for guardrail violations.
+ *
+ * @param {string} operation - Command or file path.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function checkOperation(operation, options = {}) {
+  if (!operation) return { success: false, error: 'operation is required' };
+
+  const violations = [];
+
+  // Check against risk rules
+  for (const rule of RISK_RULES) {
+    if (rule.pattern.test(operation)) {
+      violations.push({
+        rule_id: rule.id,
+        risk: rule.risk,
+        description: rule.description,
+        matched: operation.substring(0, 100)
+      });
+    }
+  }
+
+  // Check against protected paths
+  for (const pp of PROTECTED_PATHS) {
+    if (operation.includes(pp)) {
+      violations.push({
+        rule_id: 'protected-path',
+        risk: 'high',
+        description: `Operation targets protected path: ${pp}`,
+        matched: pp
+      });
+    }
+  }
+
+  const maxRisk = violations.reduce((max, v) => {
+    const riskOrder = { critical: 4, high: 3, medium: 2, low: 1 };
+    return riskOrder[v.risk] > riskOrder[max] ? v.risk : max;
+  }, 'low');
+
+  return {
+    success: true,
+    operation: operation.substring(0, 200),
+    allowed: violations.filter(v => v.risk === 'critical').length === 0,
+    requires_approval: violations.some(v => v.risk === 'high' || v.risk === 'critical'),
+    risk_level: violations.length > 0 ? maxRisk : 'none',
+    violations,
+    total_violations: violations.length
+  };
+}
+
+/**
+ * Validate a file operation (create/edit/delete).
+ *
+ * @param {string} action - 'create' | 'edit' | 'delete'
+ * @param {string} filePath
+ * @param {object} [options]
+ * @returns {object}
+ */
+function validateFileOperation(action, filePath, options = {}) {
+  const warnings = [];
+
+  if (action === 'delete') {
+    warnings.push({ level: 'high', message: `Deleting file: ${filePath}` });
+
+    for (const pp of PROTECTED_PATHS) {
+      if (filePath.includes(pp)) {
+        return {
+          success: true,
+          allowed: false,
+          reason: `Cannot delete protected path: ${pp}`,
+          warnings
+        };
+      }
+    }
+  }
+
+  if (action === 'edit') {
+    const ext = path.extname(filePath).toLowerCase();
+    if (['.env', '.pem', '.key'].includes(ext)) {
+      warnings.push({ level: 'high', message: 'Editing sensitive file type' });
+    }
+  }
+
+  const linesChanged = options.lines_changed || 0;
+  if (linesChanged > 100) {
+    warnings.push({ level: 'medium', message: `Large edit: ${linesChanged} lines changed` });
+  }
+
+  return {
+    success: true,
+    allowed: true,
+    action,
+    file: filePath,
+    warnings,
+    requires_review: warnings.some(w => w.level === 'high')
+  };
+}
+
+module.exports = {
+  checkOperation,
+  validateFileOperation,
+  RISK_RULES,
+  PROTECTED_PATHS
+};