jumpstart-mode 1.1.11 → 1.1.13

package/bin/lib/sla-slo.js

@@ -0,0 +1,210 @@
+/**
+ * sla-slo.js — SLA & SLO Specification Support (Item 28)
+ *
+ * Make operational expectations first-class citizens in the PRD
+ * and architecture.
+ *
+ * Usage:
+ *   node bin/lib/sla-slo.js define|check|report [options]
+ *
+ * State file: .jumpstart/state/sla-slo.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'sla-slo.json');
+
+const SLO_TYPES = ['availability', 'latency', 'throughput', 'error-rate', 'durability', 'freshness'];
+
+const DEFAULT_SLO_TEMPLATES = {
+  'web-api': [
+    { type: 'availability', target: 99.9, unit: 'percent', window: '30d' },
+    { type: 'latency', target: 200, unit: 'ms', percentile: 'p99', window: '30d' },
+    { type: 'error-rate', target: 0.1, unit: 'percent', window: '30d' }
+  ],
+  'batch-processing': [
+    { type: 'availability', target: 99.5, unit: 'percent', window: '30d' },
+    { type: 'throughput', target: 1000, unit: 'records/sec', window: '1h' },
+    { type: 'freshness', target: 60, unit: 'minutes', window: '24h' }
+  ],
+  'data-pipeline': [
+    { type: 'availability', target: 99.0, unit: 'percent', window: '30d' },
+    { type: 'freshness', target: 15, unit: 'minutes', window: '24h' },
+    { type: 'durability', target: 99.999, unit: 'percent', window: '30d' }
+  ]
+};
+
+function defaultState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    slos: [],
+    slas: [],
+    error_budgets: []
+  };
+}
+
+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 an SLO.
+ *
+ * @param {object} slo - { name, service, type, target, unit, window, description? }
+ * @param {object} [options]
+ * @returns {object}
+ */
+function defineSLO(slo, options = {}) {
+  if (!slo || !slo.name || !slo.service || !slo.target) {
+    return { success: false, error: 'name, service, and target are required' };
+  }
+
+  const type = (slo.type || 'availability').toLowerCase();
+  if (!SLO_TYPES.includes(type)) {
+    return { success: false, error: `Invalid type. Must be one of: ${SLO_TYPES.join(', ')}` };
+  }
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const newSLO = {
+    id: `SLO-${Date.now().toString(36).toUpperCase()}`,
+    name: slo.name,
+    service: slo.service,
+    type,
+    target: slo.target,
+    unit: slo.unit || 'percent',
+    window: slo.window || '30d',
+    description: slo.description || '',
+    created_at: new Date().toISOString()
+  };
+
+  state.slos.push(newSLO);
+  saveState(state, stateFile);
+
+  return { success: true, slo: newSLO };
+}
+
+/**
+ * Apply an SLO template by service type.
+ *
+ * @param {string} serviceName
+ * @param {string} templateType - 'web-api' | 'batch-processing' | 'data-pipeline'
+ * @param {object} [options]
+ * @returns {object}
+ */
+function applyTemplate(serviceName, templateType, options = {}) {
+  const template = DEFAULT_SLO_TEMPLATES[templateType];
+  if (!template) {
+    return { success: false, error: `Unknown template: ${templateType}. Available: ${Object.keys(DEFAULT_SLO_TEMPLATES).join(', ')}` };
+  }
+
+  const results = [];
+  for (const t of template) {
+    const result = defineSLO({
+      name: `${serviceName} ${t.type}`,
+      service: serviceName,
+      ...t
+    }, options);
+    results.push(result);
+  }
+
+  return { success: true, service: serviceName, template: templateType, slos_created: results.length };
+}
+
+/**
+ * Check SLO coverage in specs.
+ *
+ * @param {string} root - Project root.
+ * @param {object} [options]
+ * @returns {object}
+ */
+function checkSLOCoverage(root, options = {}) {
+  const stateFile = options.stateFile || path.join(root, DEFAULT_STATE_FILE);
+  const state = loadState(stateFile);
+
+  const archFile = path.join(root, 'specs', 'architecture.md');
+  const prdFile = path.join(root, 'specs', 'prd.md');
+
+  let archHasSLO = false;
+  let prdHasSLO = false;
+
+  if (fs.existsSync(archFile)) {
+    try {
+      const content = fs.readFileSync(archFile, 'utf8');
+      archHasSLO = /\bSL[OA]\b|service.level|availability|latency.target/i.test(content);
+    } catch { /* ignore */ }
+  }
+
+  if (fs.existsSync(prdFile)) {
+    try {
+      const content = fs.readFileSync(prdFile, 'utf8');
+      prdHasSLO = /\bSL[OA]\b|service.level|availability|uptime/i.test(content);
+    } catch { /* ignore */ }
+  }
+
+  return {
+    success: true,
+    defined_slos: state.slos.length,
+    architecture_mentions_slo: archHasSLO,
+    prd_mentions_slo: prdHasSLO,
+    coverage: state.slos.length > 0 ? 'defined' : 'missing',
+    recommendations: state.slos.length === 0 ? ['Define SLOs using `jumpstart-mode sla-slo define`'] : []
+  };
+}
+
+/**
+ * Generate SLO report.
+ *
+ * @param {object} [options]
+ * @returns {object}
+ */
+function generateReport(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  return {
+    success: true,
+    slos: state.slos,
+    slas: state.slas,
+    total_slos: state.slos.length,
+    total_slas: state.slas.length,
+    by_service: state.slos.reduce((acc, s) => {
+      acc[s.service] = acc[s.service] || [];
+      acc[s.service].push(s);
+      return acc;
+    }, {}),
+    by_type: state.slos.reduce((acc, s) => {
+      acc[s.type] = (acc[s.type] || 0) + 1;
+      return acc;
+    }, {})
+  };
+}
+
+module.exports = {
+  defaultState,
+  loadState,
+  saveState,
+  defineSLO,
+  applyTemplate,
+  checkSLOCoverage,
+  generateReport,
+  SLO_TYPES,
+  DEFAULT_SLO_TEMPLATES
+};

package/bin/lib/smoke-tester.js

@@ -0,0 +1,344 @@
+/**
+ * smoke-tester.js — Automated Smoke Testing
+ *
+ * Performs a "vitality" check on the application: attempts a build
+ * and optionally starts the app to verify it responds (e.g., 200 OK
+ * on a health route). Provides immediate feedback to the Developer
+ * agent during Phase 4 implementation.
+ *
+ * Usage:
+ *   echo '{"root":"."}' | node bin/lib/smoke-tester.js
+ *
+ * Input (stdin JSON):
+ *   {
+ *     "root": ".",
+ *     "config": {
+ *       "build_command": "npm run build",
+ *       "start_command": "npm start",
+ *       "health_url": "http://localhost:3000/health",
+ *       "health_timeout": 10000,
+ *       "skip_health_check": false
+ *     }
+ *   }
+ *
+ * Output (stdout JSON):
+ *   {
+ *     "build": { "pass": true, "command": "npm run build", "duration_ms": 3200 },
+ *     "health": { "pass": true, "url": "http://localhost:3000/health", "status": 200 },
+ *     "pass": true
+ *   }
+ */
+
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const fs = require('fs');
+const path = require('path');
+const { execSync, spawn } = require('child_process');
+const http = require('http');
+const https = require('https');
+
+/**
+ * Detect the project's build command from package.json or common configs.
+ *
+ * @param {string} root - Project root path.
+ * @returns {{ build: string|null, start: string|null, type: string }}
+ */
+function detectProjectCommands(root) {
+  const result = { build: null, start: null, type: 'unknown' };
+
+  // Check package.json
+  const pkgPath = path.join(root, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      result.type = 'node';
+      if (pkg.scripts) {
+        if (pkg.scripts.build) result.build = 'npm run build';
+        if (pkg.scripts.start) result.start = 'npm start';
+        if (pkg.scripts.dev) result.start = result.start || 'npm run dev';
+      }
+    } catch {
+      // ignore
+    }
+    return result;
+  }
+
+  // Check for Python projects
+  if (fs.existsSync(path.join(root, 'pyproject.toml')) ||
+      fs.existsSync(path.join(root, 'setup.py'))) {
+    result.type = 'python';
+    if (fs.existsSync(path.join(root, 'Makefile'))) {
+      result.build = 'make build';
+    }
+    return result;
+  }
+
+  // Check for Go projects
+  if (fs.existsSync(path.join(root, 'go.mod'))) {
+    result.type = 'go';
+    result.build = 'go build ./...';
+    return result;
+  }
+
+  // Check Makefile as fallback
+  if (fs.existsSync(path.join(root, 'Makefile'))) {
+    result.build = 'make';
+    return result;
+  }
+
+  return result;
+}
+
+/**
+ * Run a build command and report results.
+ *
+ * @param {string} command - Build command to run.
+ * @param {string} root - Project root path.
+ * @returns {{ pass: boolean, command: string, duration_ms: number, output: string, exit_code: number }}
+ */
+function runBuild(command, root) {
+  const start = Date.now();
+  let output = '';
+  let exitCode = 0;
+
+  try {
+    output = execSync(command, {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+      timeout: 120000
+    });
+  } catch (err) {
+    output = (err.stdout || '') + (err.stderr || '');
+    exitCode = err.status || 1;
+  }
+
+  const duration = Date.now() - start;
+
+  return {
+    pass: exitCode === 0,
+    command,
+    duration_ms: duration,
+    output: output.substring(0, 2000),
+    exit_code: exitCode
+  };
+}
+
+/**
+ * Perform a health check by making an HTTP(S) GET request.
+ *
+ * @param {string} url - URL to check.
+ * @param {number} timeout - Timeout in milliseconds.
+ * @returns {Promise<{ pass: boolean, url: string, status: number|null, error: string|null }>}
+ */
+function checkHealth(url, timeout = 10000) {
+  return new Promise((resolve) => {
+    const client = url.startsWith('https') ? https : http;
+    let settled = false;
+    const settle = (result) => {
+      if (!settled) {
+        settled = true;
+        resolve(result);
+      }
+    };
+
+    let req;
+    const timer = setTimeout(() => {
+      if (req) { try { req.destroy(); } catch { /* ignore */ } }
+      settle({ pass: false, url, status: null, error: 'Timeout' });
+    }, timeout);
+
+    try {
+      req = client.get(url, (res) => {
+        clearTimeout(timer);
+        settle({
+          pass: res.statusCode >= 200 && res.statusCode < 400,
+          url,
+          status: res.statusCode,
+          error: null
+        });
+        res.resume();
+      });
+
+      req.on('error', (err) => {
+        clearTimeout(timer);
+        settle({ pass: false, url, status: null, error: err.message || err.code || 'Connection failed' });
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      settle({ pass: false, url, status: null, error: err.message });
+    }
+  });
+}
+
+/**
+ * Start a server process and wait for it to be ready.
+ *
+ * @param {string} command - Start command.
+ * @param {string} root - Project root path.
+ * @param {string} healthUrl - URL to check for readiness.
+ * @param {number} timeout - Total timeout in milliseconds.
+ * @returns {Promise<{ process: object|null, ready: boolean, error: string|null }>}
+ */
+function startAndWait(command, root, healthUrl, timeout = 15000) {
+  return new Promise((resolve) => {
+    const parts = command.split(' ');
+    const proc = spawn(parts[0], parts.slice(1), {
+      cwd: root,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: false
+    });
+
+    let stderr = '';
+    proc.stderr.on('data', d => { stderr += d.toString(); });
+
+    const deadline = Date.now() + timeout;
+    const pollInterval = 1000;
+
+    const poll = async () => {
+      if (Date.now() > deadline) {
+        try { proc.kill(); } catch { /* ignore */ }
+        resolve({ process: null, ready: false, error: 'Startup timeout exceeded' });
+        return;
+      }
+
+      const health = await checkHealth(healthUrl, 2000);
+      if (health.pass) {
+        resolve({ process: proc, ready: true, error: null });
+      } else {
+        setTimeout(poll, pollInterval);
+      }
+    };
+
+    proc.on('error', (err) => {
+      resolve({ process: null, ready: false, error: err.message });
+    });
+
+    proc.on('exit', (code) => {
+      if (code !== 0 && code !== null) {
+        resolve({ process: null, ready: false, error: `Process exited with code ${code}: ${stderr.substring(0, 500)}` });
+      }
+    });
+
+    // Start polling after a brief delay
+    setTimeout(poll, 1500);
+  });
+}
+
+/**
+ * Run the full smoke test suite.
+ *
+ * @param {object} input - Smoke test options.
+ * @param {string} [input.root] - Project root.
+ * @param {object} [input.config] - Override config.
+ * @returns {Promise<object>} Smoke test results.
+ */
+async function runSmokeTest(input) {
+  const { root = '.', config = {} } = input;
+  const resolvedRoot = path.resolve(root);
+
+  // Detect or use provided commands
+  const detected = detectProjectCommands(resolvedRoot);
+  const buildCommand = config.build_command || detected.build;
+  const startCommand = config.start_command || detected.start;
+  const healthUrl = config.health_url || 'http://localhost:3000/health';
+  const healthTimeout = config.health_timeout || 10000;
+  const skipHealthCheck = config.skip_health_check || false;
+
+  const result = {
+    project_type: detected.type,
+    build: null,
+    health: null,
+    pass: true
+  };
+
+  // Step 1: Build
+  if (buildCommand) {
+    result.build = runBuild(buildCommand, resolvedRoot);
+    if (!result.build.pass) {
+      result.pass = false;
+      return result;
+    }
+  } else {
+    result.build = {
+      pass: true,
+      command: null,
+      duration_ms: 0,
+      output: 'No build command detected.',
+      exit_code: 0
+    };
+  }
+
+  // Step 2: Health check (optional)
+  if (!skipHealthCheck && startCommand) {
+    const startup = await startAndWait(startCommand, resolvedRoot, healthUrl, healthTimeout);
+
+    if (startup.ready) {
+      const health = await checkHealth(healthUrl, 5000);
+      result.health = health;
+      result.pass = result.pass && health.pass;
+    } else {
+      result.health = {
+        pass: false,
+        url: healthUrl,
+        status: null,
+        error: startup.error || 'Could not start server'
+      };
+      result.pass = false;
+    }
+
+    // Clean up server process
+    if (startup.process) {
+      try { startup.process.kill(); } catch { /* ignore */ }
+    }
+  } else {
+    result.health = {
+      pass: true,
+      url: null,
+      status: null,
+      error: skipHealthCheck ? 'Health check skipped' : 'No start command detected'
+    };
+  }
+
+  return result;
+}
+
+// ─── CLI Entry Point ──────────────────────────────────────────────────────────
+
+if (process.argv[1] && (
+  process.argv[1].endsWith('smoke-tester.js') ||
+  process.argv[1].endsWith('smoke-tester')
+)) {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { input += chunk; });
+  process.stdin.on('end', () => {
+    (async () => {
+      try {
+        const parsed = input.trim() ? JSON.parse(input) : {};
+        const result = await runSmokeTest(parsed);
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        process.exit(result.pass ? 0 : 1);
+      } catch (err) {
+        process.stdout.write(JSON.stringify({ error: err.message }) + '\n');
+        process.exit(2);
+      }
+    })();
+  });
+
+  if (process.stdin.isTTY) {
+    (async () => {
+      const result = await runSmokeTest({});
+      process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+      process.exit(result.pass ? 0 : 1);
+    })();
+  }
+}
+
+export {
+  runSmokeTest,
+  detectProjectCommands,
+  runBuild,
+  checkHealth,
+  startAndWait
+};

package/bin/lib/spec-comments.js

@@ -0,0 +1,147 @@
+/**
+ * spec-comments.js — Inline Spec Review Comments (Item 63)
+ *
+ * Comment, resolve, assign, and approve within artifact sections.
+ *
+ * Usage:
+ *   node bin/lib/spec-comments.js add|resolve|list|assign [options]
+ *
+ * State file: .jumpstart/state/spec-comments.json
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_STATE_FILE = path.join('.jumpstart', 'state', 'spec-comments.json');
+
+const COMMENT_STATUSES = ['open', 'resolved', 'wontfix', 'deferred'];
+
+function defaultState() {
+  return {
+    version: '1.0.0',
+    created_at: new Date().toISOString(),
+    last_updated: null,
+    comments: []
+  };
+}
+
+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');
+}
+
+/**
+ * Add a review comment to a spec artifact.
+ */
+function addComment(artifact, section, text, options = {}) {
+  if (!artifact || !text) return { success: false, error: 'artifact and text are required' };
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const comment = {
+    id: `C-${Date.now()}`,
+    artifact,
+    section: section || null,
+    text,
+    author: options.author || 'anonymous',
+    assignee: options.assignee || null,
+    status: 'open',
+    created_at: new Date().toISOString(),
+    resolved_at: null,
+    replies: []
+  };
+
+  state.comments.push(comment);
+  saveState(state, stateFile);
+
+  return { success: true, comment };
+}
+
+/**
+ * Resolve a comment.
+ */
+function resolveComment(commentId, resolution, options = {}) {
+  if (!commentId) return { success: false, error: 'commentId is required' };
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const comment = state.comments.find(c => c.id === commentId);
+  if (!comment) return { success: false, error: `Comment ${commentId} not found` };
+
+  comment.status = 'resolved';
+  comment.resolution = resolution || 'Resolved';
+  comment.resolved_at = new Date().toISOString();
+  comment.resolved_by = options.author || 'anonymous';
+  saveState(state, stateFile);
+
+  return { success: true, comment };
+}
+
+/**
+ * List comments, optionally filtered.
+ */
+function listComments(options = {}) {
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  let comments = state.comments;
+
+  if (options.artifact) {
+    comments = comments.filter(c => c.artifact === options.artifact);
+  }
+  if (options.status) {
+    comments = comments.filter(c => c.status === options.status);
+  }
+  if (options.assignee) {
+    comments = comments.filter(c => c.assignee === options.assignee);
+  }
+
+  return {
+    success: true,
+    total: comments.length,
+    comments
+  };
+}
+
+/**
+ * Assign a comment to a reviewer.
+ */
+function assignComment(commentId, assignee, options = {}) {
+  if (!commentId || !assignee) return { success: false, error: 'commentId and assignee are required' };
+
+  const stateFile = options.stateFile || DEFAULT_STATE_FILE;
+  const state = loadState(stateFile);
+
+  const comment = state.comments.find(c => c.id === commentId);
+  if (!comment) return { success: false, error: `Comment ${commentId} not found` };
+
+  comment.assignee = assignee;
+  saveState(state, stateFile);
+
+  return { success: true, comment };
+}
+
+module.exports = {
+  addComment,
+  resolveComment,
+  listComments,
+  assignComment,
+  loadState,
+  saveState,
+  defaultState,
+  COMMENT_STATUSES
+};