jumpstart-mode 1.1.11 → 1.1.13

package/bin/lib/contract-first.js

@@ -0,0 +1,124 @@
+/**
+ * contract-first.js — Contract-First Implementation Assistant (Item 45)
+ *
+ * Generate code from API and event contracts, then verify code
+ * remains compliant.
+ *
+ * Usage:
+ *   node bin/lib/contract-first.js extract|verify|report [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CONTRACT_TYPES = ['rest-api', 'graphql', 'event', 'grpc', 'message-queue'];
+
+/**
+ * Extract API contracts from architecture spec.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function extractContracts(root, options = {}) {
+  const archFile = path.join(root, 'specs', 'architecture.md');
+  if (!fs.existsSync(archFile)) {
+    return { success: false, error: 'Architecture spec not found at specs/architecture.md' };
+  }
+
+  const content = fs.readFileSync(archFile, 'utf8');
+  const contracts = [];
+
+  // Extract API endpoint definitions
+  const endpointPattern = /(?:GET|POST|PUT|PATCH|DELETE)\s+\/[\w/{}:-]+/g;
+  let match;
+  while ((match = endpointPattern.exec(content)) !== null) {
+    const [method, ...pathParts] = match[0].split(/\s+/);
+    contracts.push({
+      type: 'rest-api',
+      method,
+      path: pathParts.join(' '),
+      line: content.substring(0, match.index).split('\n').length
+    });
+  }
+
+  // Extract event definitions
+  const eventPattern = /(?:event|topic|queue)[\s:]+["']?([a-zA-Z0-9._-]+)/gi;
+  while ((match = eventPattern.exec(content)) !== null) {
+    contracts.push({
+      type: 'event',
+      name: match[1],
+      line: content.substring(0, match.index).split('\n').length
+    });
+  }
+
+  return {
+    success: true,
+    total_contracts: contracts.length,
+    contracts,
+    by_type: contracts.reduce((acc, c) => { acc[c.type] = (acc[c.type] || 0) + 1; return acc; }, {})
+  };
+}
+
+/**
+ * Verify that implementation matches contracts.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function verifyCompliance(root, options = {}) {
+  const contractResult = extractContracts(root, options);
+  if (!contractResult.success) return contractResult;
+
+  const srcDir = path.join(root, 'src');
+  let srcContent = '';
+
+  if (fs.existsSync(srcDir)) {
+    function readDir(dir) {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory() && entry.name !== 'node_modules') {
+          readDir(path.join(dir, entry.name));
+        } else if (entry.isFile() && /\.(js|ts|py)$/.test(entry.name)) {
+          try { srcContent += fs.readFileSync(path.join(dir, entry.name), 'utf8') + '\n'; }
+          catch { /* skip */ }
+        }
+      }
+    }
+    readDir(srcDir);
+  }
+
+  const violations = [];
+  const implemented = [];
+
+  for (const contract of contractResult.contracts) {
+    if (contract.type === 'rest-api') {
+      const pathPattern = contract.path.replace(/\{[^}]+\}/g, '[^/]+');
+      const found = new RegExp(pathPattern).test(srcContent) || srcContent.includes(contract.path);
+      if (found) implemented.push(contract);
+      else violations.push({ ...contract, issue: 'Endpoint not found in source' });
+    } else if (contract.type === 'event') {
+      const found = srcContent.includes(contract.name);
+      if (found) implemented.push(contract);
+      else violations.push({ ...contract, issue: 'Event handler not found in source' });
+    }
+  }
+
+  return {
+    success: true,
+    total_contracts: contractResult.total_contracts,
+    implemented: implemented.length,
+    violations: violations.length,
+    compliance: contractResult.total_contracts > 0
+      ? Math.round((implemented.length / contractResult.total_contracts) * 100) : 100,
+    findings: violations
+  };
+}
+
+module.exports = {
+  extractContracts,
+  verifyCompliance,
+  CONTRACT_TYPES
+};

package/bin/lib/cost-router.js

@@ -0,0 +1,148 @@
+/**
+ * cost-router.js — Cost-Aware Model Routing (Item 55)
+ *
+ * Optimize quality and speed against budget targets.
+ *
+ * Usage:
+ *   node bin/lib/cost-router.js route|budget|report [options]
+ *
+ * Config: .jumpstart/cost-routing.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_CONFIG_FILE = path.join('.jumpstart', 'cost-routing.json');
+
+const MODEL_COSTS = {
+  'gpt-4o': { input_per_1k: 0.005, output_per_1k: 0.015, quality: 90, speed: 80 },
+  'gpt-4-turbo': { input_per_1k: 0.01, output_per_1k: 0.03, quality: 92, speed: 70 },
+  'gpt-3.5-turbo': { input_per_1k: 0.0005, output_per_1k: 0.0015, quality: 70, speed: 95 },
+  'claude-3-opus': { input_per_1k: 0.015, output_per_1k: 0.075, quality: 95, speed: 60 },
+  'claude-3-sonnet': { input_per_1k: 0.003, output_per_1k: 0.015, quality: 88, speed: 85 },
+  'claude-3-haiku': { input_per_1k: 0.00025, output_per_1k: 0.00125, quality: 75, speed: 95 }
+};
+
+const BUDGET_PROFILES = {
+  economy: { max_per_task: 0.10, prefer: 'cheapest', min_quality: 65 },
+  balanced: { max_per_task: 0.50, prefer: 'balanced', min_quality: 80 },
+  premium: { max_per_task: 2.00, prefer: 'best-quality', min_quality: 90 }
+};
+
+function loadConfig(configFile) {
+  const filePath = configFile || DEFAULT_CONFIG_FILE;
+  if (!fs.existsSync(filePath)) return { budget_profile: 'balanced', spending: [] };
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); }
+  catch { return { budget_profile: 'balanced', spending: [] }; }
+}
+
+function saveConfig(config, configFile) {
+  const filePath = configFile || DEFAULT_CONFIG_FILE;
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Route to the most cost-effective model.
+ *
+ * @param {object} task - { type, estimated_tokens?, min_quality? }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function routeByCost(task, options = {}) {
+  const configFile = options.configFile || DEFAULT_CONFIG_FILE;
+  const config = loadConfig(configFile);
+  const profile = BUDGET_PROFILES[config.budget_profile] || BUDGET_PROFILES.balanced;
+  const minQuality = task.min_quality || profile.min_quality;
+
+  const candidates = Object.entries(MODEL_COSTS)
+    .filter(([, costs]) => costs.quality >= minQuality)
+    .map(([model, costs]) => {
+      const tokens = task.estimated_tokens || 1000;
+      const cost = (tokens / 1000) * costs.input_per_1k + (tokens / 1000) * costs.output_per_1k;
+      return { model, cost: Math.round(cost * 10000) / 10000, quality: costs.quality, speed: costs.speed };
+    })
+    .sort((a, b) => {
+      if (profile.prefer === 'cheapest') return a.cost - b.cost;
+      if (profile.prefer === 'best-quality') return b.quality - a.quality;
+      return (b.quality + b.speed) / 2 - (a.quality + a.speed) / 2; // balanced
+    });
+
+  const selected = candidates[0];
+
+  return {
+    success: true,
+    selected_model: selected ? selected.model : null,
+    estimated_cost: selected ? selected.cost : 0,
+    quality: selected ? selected.quality : 0,
+    budget_profile: config.budget_profile,
+    alternatives: candidates.slice(1, 3)
+  };
+}
+
+/**
+ * Record spending.
+ *
+ * @param {string} model
+ * @param {number} tokens
+ * @param {object} [options]
+ * @returns {object}
+ */
+function recordSpending(model, tokens, options = {}) {
+  const configFile = options.configFile || DEFAULT_CONFIG_FILE;
+  const config = loadConfig(configFile);
+  const costs = MODEL_COSTS[model];
+
+  if (!costs) return { success: false, error: `Unknown model: ${model}` };
+
+  const cost = (tokens / 1000) * (costs.input_per_1k + costs.output_per_1k);
+
+  if (!config.spending) config.spending = [];
+  config.spending.push({
+    model,
+    tokens,
+    cost: Math.round(cost * 10000) / 10000,
+    recorded_at: new Date().toISOString()
+  });
+
+  saveConfig(config, configFile);
+
+  return { success: true, model, tokens, cost: Math.round(cost * 10000) / 10000 };
+}
+
+/**
+ * Generate cost report.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function generateReport(options = {}) {
+  const configFile = options.configFile || DEFAULT_CONFIG_FILE;
+  const config = loadConfig(configFile);
+  const spending = config.spending || [];
+
+  const totalCost = spending.reduce((sum, s) => sum + s.cost, 0);
+  const byModel = spending.reduce((acc, s) => { acc[s.model] = (acc[s.model] || 0) + s.cost; return acc; }, {});
+
+  return {
+    success: true,
+    budget_profile: config.budget_profile,
+    total_cost: Math.round(totalCost * 100) / 100,
+    total_requests: spending.length,
+    by_model: byModel,
+    recent: spending.slice(-10)
+  };
+}
+
+module.exports = {
+  loadConfig,
+  saveConfig,
+  routeByCost,
+  recordSpending,
+  generateReport,
+  MODEL_COSTS,
+  BUDGET_PROFILES
+};

package/bin/lib/credential-boundary.js

@@ -0,0 +1,155 @@
+/**
+ * credential-boundary.js — Secrets & Credential Boundary Checks (Item 31)
+ *
+ * Detect unsafe plans or code paths involving tokens, keys,
+ * vault usage, and secrets sprawl.
+ *
+ * Usage:
+ *   node bin/lib/credential-boundary.js scan|report [options]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const BOUNDARY_PATTERNS = [
+  { name: 'Hardcoded secret in spec', pattern: /(?:password|secret|token|api.?key)\s*[:=]\s*["'][^"']{8,}/gi, severity: 'critical' },
+  { name: 'Vault reference missing', pattern: /(?:password|secret|token)\s*[:=]\s*(?!.*vault|.*\$\{)/gi, severity: 'warning' },
+  { name: 'Inline connection string', pattern: /(?:mongodb|postgres|mysql|redis):\/\/[^\s"']+:[^\s"']+@/gi, severity: 'critical' },
+  { name: 'Private key material', pattern: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g, severity: 'critical' },
+  { name: 'AWS credential pattern', pattern: /(?:AKIA[0-9A-Z]{16}|aws_secret_access_key)/gi, severity: 'critical' },
+  { name: 'Bearer token in spec', pattern: /[Bb]earer\s+[A-Za-z0-9._~+/=-]{20,}/g, severity: 'high' },
+  { name: 'Secret in environment variable', pattern: /(?:export\s+)?[A-Z_]*(?:SECRET|TOKEN|PASSWORD|KEY)[A-Z_]*\s*=\s*["']?[A-Za-z0-9+/=]{16,}/g, severity: 'high' }
+];
+
+const SAFE_PATTERNS = [
+  /\.env\.example/i,
+  /placeholder|changeme|your[_-]?key|replace[_-]?me|TODO/i,
+  /\$\{[^}]+\}/,
+  /vault:\/\//i,
+  /secretsmanager/i,
+  /keyvault/i
+];
+
+/**
+ * Scan files for credential boundary violations.
+ *
+ * @param {string[]} files - File paths to scan.
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function scanBoundaries(files, root, options = {}) {
+  const findings = [];
+  let filesScanned = 0;
+
+  for (const file of files) {
+    const absPath = path.isAbsolute(file) ? file : path.join(root, file);
+    if (!fs.existsSync(absPath)) continue;
+
+    try {
+      const content = fs.readFileSync(absPath, 'utf8');
+      filesScanned++;
+
+      for (const bp of BOUNDARY_PATTERNS) {
+        const regex = new RegExp(bp.pattern.source, bp.pattern.flags);
+        let match;
+        while ((match = regex.exec(content)) !== null) {
+          const matchedText = match[0];
+
+          // Check if it matches safe patterns
+          const isSafe = SAFE_PATTERNS.some(sp => sp.test(matchedText));
+          if (isSafe) continue;
+
+          const lineNum = content.substring(0, match.index).split('\n').length;
+
+          findings.push({
+            file: path.relative(root, absPath).replace(/\\/g, '/'),
+            line: lineNum,
+            pattern: bp.name,
+            severity: bp.severity,
+            matched: matchedText.substring(0, 50) + (matchedText.length > 50 ? '...' : '')
+          });
+        }
+      }
+    } catch { /* skip unreadable */ }
+  }
+
+  return {
+    success: true,
+    files_scanned: filesScanned,
+    findings,
+    total_findings: findings.length,
+    critical: findings.filter(f => f.severity === 'critical').length,
+    high: findings.filter(f => f.severity === 'high').length,
+    pass: findings.filter(f => f.severity === 'critical').length === 0
+  };
+}
+
+/**
+ * Scan a project root for credential boundary issues.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function scanProject(root, options = {}) {
+  const extensions = options.extensions || ['.md', '.yaml', '.yml', '.json', '.js', '.ts', '.env', '.cfg', '.conf'];
+  const excludeDirs = options.excludeDirs || ['node_modules', '.git', 'dist', 'build', 'vendor'];
+  const files = [];
+
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (!excludeDirs.includes(entry.name)) walk(path.join(dir, entry.name));
+      } else if (entry.isFile()) {
+        const ext = path.extname(entry.name).toLowerCase();
+        if (extensions.includes(ext)) files.push(path.join(dir, entry.name));
+      }
+    }
+  }
+
+  walk(root);
+  return scanBoundaries(files, root, options);
+}
+
+/**
+ * Generate a credential boundary report.
+ *
+ * @param {object} scanResult
+ * @returns {object}
+ */
+function generateReport(scanResult) {
+  const bySeverity = {};
+  const byPattern = {};
+
+  for (const f of scanResult.findings) {
+    bySeverity[f.severity] = (bySeverity[f.severity] || 0) + 1;
+    byPattern[f.pattern] = (byPattern[f.pattern] || 0) + 1;
+  }
+
+  return {
+    success: true,
+    summary: {
+      files_scanned: scanResult.files_scanned,
+      total_findings: scanResult.total_findings,
+      pass: scanResult.pass
+    },
+    by_severity: bySeverity,
+    by_pattern: byPattern,
+    critical_findings: scanResult.findings.filter(f => f.severity === 'critical'),
+    recommendations: scanResult.total_findings > 0
+      ? ['Use vault references instead of hardcoded secrets', 'Move sensitive values to environment variables', 'Add .env to .gitignore']
+      : ['No credential boundary issues detected']
+  };
+}
+
+module.exports = {
+  scanBoundaries,
+  scanProject,
+  generateReport,
+  BOUNDARY_PATTERNS,
+  SAFE_PATTERNS
+};

package/bin/lib/data-classification.js

@@ -0,0 +1,180 @@
+/**
+ * data-classification.js — Data Classification & Handling Controls (Item 30)
+ *
+ * Tag systems and features by public/internal/confidential/restricted
+ * and adapt prompts and policies.
+ *
+ * Usage:
+ *   node bin/lib/data-classification.js classify|check|report [options]
+ *
+ * State file: .jumpstart/state/data-classification.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'data-classification.json');
+
+const CLASSIFICATION_LEVELS = ['public', 'internal', 'confidential', 'restricted'];
+
+const HANDLING_REQUIREMENTS = {
+  public: { encryption_at_rest: false, encryption_in_transit: false, access_logging: false, retention_policy: false },
+  internal: { encryption_at_rest: false, encryption_in_transit: true, access_logging: false, retention_policy: true },
+  confidential: { encryption_at_rest: true, encryption_in_transit: true, access_logging: true, retention_policy: true },
+  restricted: { encryption_at_rest: true, encryption_in_transit: true, access_logging: true, retention_policy: true, mfa_required: true, data_masking: true }
+};
+
+const DATA_TYPE_DEFAULTS = {
+  PII: 'confidential',
+  PHI: 'restricted',
+  PCI: 'restricted',
+  credentials: 'restricted',
+  'business-sensitive': 'confidential',
+  'public-content': 'public',
+  'internal-docs': 'internal'
+};
+
+function defaultState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    classifications: [],
+    data_assets: []
+  };
+}
+
+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');
+}
+
+/**
+ * Classify a system or feature.
+ *
+ * @param {object} asset - { name, type, data_types[], description? }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function classifyAsset(asset, options = {}) {
+  if (!asset || !asset.name) {
+    return { success: false, error: 'asset.name is required' };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  // Auto-classify based on data types
+  let level = 'public';
+  const dataTypes = asset.data_types || [];
+  for (const dt of dataTypes) {
+    const defaultLevel = DATA_TYPE_DEFAULTS[dt];
+    if (defaultLevel) {
+      const idx = CLASSIFICATION_LEVELS.indexOf(defaultLevel);
+      const currentIdx = CLASSIFICATION_LEVELS.indexOf(level);
+      if (idx > currentIdx) level = defaultLevel;
+    }
+  }
+
+  // Allow override
+  if (asset.classification && CLASSIFICATION_LEVELS.includes(asset.classification)) {
+    level = asset.classification;
+  }
+
+  const classification = {
+    id: `DC-${(state.data_assets.length + 1).toString().padStart(3, '0')}`,
+    name: asset.name,
+    type: asset.type || 'system',
+    data_types: dataTypes,
+    classification: level,
+    handling: HANDLING_REQUIREMENTS[level],
+    description: asset.description || '',
+    classified_at: new Date().toISOString()
+  };
+
+  state.data_assets.push(classification);
+  saveState(state, stateFile);
+
+  return { success: true, asset: classification };
+}
+
+/**
+ * Check classification compliance.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function checkCompliance(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const violations = [];
+  for (const asset of state.data_assets) {
+    const requirements = HANDLING_REQUIREMENTS[asset.classification];
+    if (!requirements) continue;
+
+    if (requirements.encryption_at_rest && !asset.encryption_at_rest_verified) {
+      violations.push({ asset: asset.name, requirement: 'encryption_at_rest', classification: asset.classification });
+    }
+    if (requirements.encryption_in_transit && !asset.encryption_in_transit_verified) {
+      violations.push({ asset: asset.name, requirement: 'encryption_in_transit', classification: asset.classification });
+    }
+  }
+
+  return {
+    success: true,
+    total_assets: state.data_assets.length,
+    violations: violations.length,
+    compliant: violations.length === 0,
+    findings: violations
+  };
+}
+
+/**
+ * Generate classification report.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function generateReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const byLevel = {};
+  for (const level of CLASSIFICATION_LEVELS) {
+    byLevel[level] = state.data_assets.filter(a => a.classification === level).length;
+  }
+
+  return {
+    success: true,
+    total_assets: state.data_assets.length,
+    by_level: byLevel,
+    restricted_assets: state.data_assets.filter(a => a.classification === 'restricted'),
+    confidential_assets: state.data_assets.filter(a => a.classification === 'confidential'),
+    assets: state.data_assets
+  };
+}
+
+module.exports = {
+  defaultState,
+  loadState,
+  saveState,
+  classifyAsset,
+  checkCompliance,
+  generateReport,
+  CLASSIFICATION_LEVELS,
+  HANDLING_REQUIREMENTS,
+  DATA_TYPE_DEFAULTS
+};