opstruth 0.1.3 → 0.2.0

package/src/commands/quality.js

@@ -4,6 +4,16 @@ import { detectPackageManager, detectPackageScripts } from '../lib/detect.js';
 import { resolveProjectBoundary } from '../lib/boundary.js';
 
 const DEFAULT_SCRIPTS = ['typecheck', 'lint', 'test', 'build', 'ci'];
+const INDIVIDUAL_SCRIPTS = ['lint', 'typecheck', 'test', 'build'];
+const MUTATION_LIKE_SCRIPT = /\b(supabase\s+(?:secrets\s+set|db\s+push|functions\s+deploy)|wrangler\s+deploy|npm\s+publish|pnpm\s+publish|yarn\s+npm\s+publish|bun\s+publish|pg_cron|psql\s|curl\s+.*production)\b/i;
+
+export const QUALITY_SIGNALS = [
+  { key: 'lint', script: 'lint', label: 'Lint' },
+  { key: 'typecheck', script: 'typecheck', label: 'Typecheck' },
+  { key: 'tests', script: 'test', label: 'Tests' },
+  { key: 'build', script: 'build', label: 'Build' },
+  { key: 'ci', script: 'ci', label: 'CI' }
+];
 
 export function isDefaultPlaceholderTestScript(script = '') {
   return /^echo\s+["']?Error:\s*no test specified["']?\s*(?:&&|;)\s*exit\s+1$/i.test(script.trim());
@@ -13,29 +23,140 @@ function isRunnableQualityScript(name, script) {
   return !(name === 'test' && isDefaultPlaceholderTestScript(script));
 }
 
-function runnerFor(manager) {
+export function isMutationLikeQualityScript(script = '') {
+  return MUTATION_LIKE_SCRIPT.test(script);
+}
+
+export function qualityRunnerFor(manager) {
   if (manager === 'pnpm') return ['pnpm', ['run']];
   if (manager === 'yarn') return ['yarn', []];
   if (manager === 'bun') return ['bun', ['run']];
   return ['npm', ['run']];
 }
-export async function runQuality({ cwd = process.cwd(), continueOnFailure = false, strict = false, scripts: wantedScripts } = {}) {
+
+function signalKeyForScript(script) {
+  return script === 'test' ? 'tests' : script;
+}
+
+function emptySignals(availableScripts) {
+  return Object.fromEntries(QUALITY_SIGNALS.map(({ key, script, label }) => {
+    const rawScript = availableScripts[script];
+    const configured = Object.prototype.hasOwnProperty.call(availableScripts, script);
+    const runnable = configured && isRunnableQualityScript(script, rawScript);
+    const requiresReview = runnable && isMutationLikeQualityScript(rawScript);
+    let status = 'not_configured';
+    let reason = 'package script not found';
+    if (configured && !runnable) {
+      status = 'skipped';
+      reason = 'default npm placeholder test script';
+    } else if (requiresReview) {
+      status = 'skipped';
+      reason = 'script contains mutation-like command and requires human review';
+    } else if (configured) {
+      status = 'not_verified';
+      reason = 'configured but not executed yet';
+    }
+    return [key, {
+      key,
+      label,
+      script,
+      configured,
+      status,
+      reason,
+      command: rawScript || null,
+      proofRoute: null,
+      exitCode: null,
+      durationMs: null,
+      logExcerpt: ''
+    }];
+  }));
+}
+
+function ciCoversScript(ciScript = '', script) {
+  const escaped = script.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  if (script === 'test' && /\bnpm\s+test\b|\bpnpm\s+test\b|\bbun\s+test\b|\byarn\s+test\b/.test(ciScript)) return true;
+  return new RegExp(`\\b(?:npm|pnpm|bun)\\s+run\\s+${escaped}\\b|\\byarn\\s+${escaped}\\b`).test(ciScript);
+}
+
+function checkStatusForSignal(status) {
+  if (status === 'passed') return 'pass';
+  if (status === 'failed' || status === 'timed_out') return 'fail';
+  if (status === 'skipped' || status === 'not_configured') return 'skipped';
+  return 'not_verified';
+}
+
+function signalMessage(signal) {
+  const bits = [signal.status];
+  if (signal.proofRoute) bits.push('via ' + signal.proofRoute);
+  if (signal.reason) bits.push(signal.reason);
+  return bits.join('; ');
+}
+
+function statusFromRun(run) {
+  if (run.exitCode === 0) return 'passed';
+  if (run.exitCode === 124 || run.signal) return 'timed_out';
+  return 'failed';
+}
+
+function failureText(script, signal) {
+  if (signal.status === 'timed_out') return script + ' timed out';
+  return script + ' failed';
+}
+
+async function executeScript({ script, signal, runner, baseArgs, cwd, timeoutMs, checks }) {
+  const run = await runCommand(runner, [...baseArgs, script], { cwd, timeoutMs });
+  const status = statusFromRun(run);
+  signal.status = status;
+  signal.reason = status === 'passed' ? 'configured script exited 0' : `configured script exited ${run.exitCode}`;
+  signal.proofRoute = 'direct';
+  signal.exitCode = run.exitCode;
+  signal.durationMs = run.durationMs;
+  signal.logExcerpt = excerpt((run.stdout || '') + '\n' + (run.stderr || ''));
+  checks.push({
+    name: 'package script ' + script,
+    command: run.command,
+    exitCode: run.exitCode,
+    durationMs: run.durationMs,
+    status: run.exitCode === 0 ? 'pass' : 'fail',
+    logExcerpt: signal.logExcerpt
+  });
+  return run;
+}
+
+function addSignalChecks(checks, signals) {
+  for (const signal of Object.values(signals)) {
+    checks.push({
+      name: 'quality signal ' + signal.key,
+      command: signal.proofRoute === 'direct' ? signal.command : null,
+      exitCode: signal.exitCode,
+      durationMs: signal.durationMs,
+      status: checkStatusForSignal(signal.status),
+      message: signalMessage(signal),
+      logExcerpt: signal.logExcerpt
+    });
+  }
+}
+
+function signalSummary(signals) {
+  return QUALITY_SIGNALS.map(({ key, label }) => `${label}: ${signals[key].status}${signals[key].proofRoute ? ' via ' + signals[key].proofRoute : ''}`).join('; ');
+}
+
+export async function runQuality({ cwd = process.cwd(), continueOnFailure = false, strict = false, scripts: wantedScripts, timeoutMs = 180000 } = {}) {
   const boundary = await resolveProjectBoundary(cwd);
   cwd = boundary.root;
   const packageManager = await detectPackageManager(cwd);
   const availableScripts = await detectPackageScripts(cwd);
   const requested = wantedScripts?.length ? wantedScripts : DEFAULT_SCRIPTS;
-  const selected = requested.filter((name) => Object.prototype.hasOwnProperty.call(availableScripts, name) && isRunnableQualityScript(name, availableScripts[name]));
-  const skippedScripts = requested.filter((name) => !Object.prototype.hasOwnProperty.call(availableScripts, name) || !isRunnableQualityScript(name, availableScripts[name]));
+  const explicitScripts = Boolean(wantedScripts?.length);
+  const signals = emptySignals(availableScripts);
   const checks = [];
   const warnings = [];
   const failures = [];
-  const skipped = skippedScripts.map((name) => {
-    if (Object.prototype.hasOwnProperty.call(availableScripts, name) && !isRunnableQualityScript(name, availableScripts[name])) {
-      return 'default npm placeholder test script skipped';
-    }
-    return 'package script not found, skipped: ' + name;
-  });
+  const skipped = [];
+  const notVerified = [];
+  const selected = [];
+  const [runner, baseArgs] = qualityRunnerFor(packageManager);
+
   if (boundary.message) skipped.push(boundary.message);
   if (boundary.isGitRepo) {
     const diff = await runCommand('git', ['diff', '--check'], { cwd, timeoutMs: 60000 });
@@ -44,23 +165,94 @@ export async function runQuality({ cwd = process.cwd(), continueOnFailure = fals
   } else {
     skipped.push('git diff --check skipped because no git repository was detected');
   }
-  const [runner, baseArgs] = runnerFor(packageManager);
-  for (const script of selected) {
-    if (failures.length && !continueOnFailure) break;
-    const run = await runCommand(runner, [...baseArgs, script], { cwd, timeoutMs: 180000 });
-    checks.push({ name: 'package script ' + script, command: run.command, exitCode: run.exitCode, durationMs: run.durationMs, status: run.exitCode === 0 ? 'pass' : 'fail', logExcerpt: excerpt((run.stdout || '') + '\n' + (run.stderr || '')) });
-    if (run.exitCode !== 0) failures.push(script + ' failed');
+
+  const requestedRunnable = requested.filter((name) => Object.prototype.hasOwnProperty.call(availableScripts, name) && isRunnableQualityScript(name, availableScripts[name]));
+  const requestedUnsafe = requestedRunnable.filter((name) => isMutationLikeQualityScript(availableScripts[name]));
+  for (const name of requestedUnsafe) warnings.push(`package script ${name} requires review before execution`);
+
+  let executionStrategy = 'individual';
+  const ciScript = availableScripts.ci || '';
+  const ciAvailable = requested.includes('ci') && Object.prototype.hasOwnProperty.call(availableScripts, 'ci') && isRunnableQualityScript('ci', ciScript);
+  const ciSafe = ciAvailable && !isMutationLikeQualityScript(ciScript);
+  if (!explicitScripts && ciSafe) executionStrategy = 'ci';
+  if (!explicitScripts && ciAvailable && !ciSafe) executionStrategy = 'individual';
+
+  if (executionStrategy === 'ci') {
+    selected.push('ci');
+    const run = await executeScript({ script: 'ci', signal: signals.ci, runner, baseArgs, cwd, timeoutMs, checks });
+    for (const script of INDIVIDUAL_SCRIPTS) {
+      const signal = signals[signalKeyForScript(script)];
+      if (!signal.configured || signal.status === 'skipped') continue;
+      if (ciCoversScript(ciScript, script)) {
+        signal.status = run.exitCode === 0 ? 'passed' : 'not_verified';
+        signal.reason = run.exitCode === 0 ? 'covered by configured ci script' : 'ci did not pass, so individual result is not verified';
+        signal.proofRoute = 'ci';
+        signal.exitCode = run.exitCode === 0 ? 0 : null;
+        signal.durationMs = run.exitCode === 0 ? run.durationMs : null;
+      } else {
+        signal.status = 'not_verified';
+        signal.reason = 'configured script was not run because ci strategy did not explicitly cover it';
+      }
+    }
+    if (run.exitCode !== 0) failures.push(failureText('ci', signals.ci));
+  } else {
+    const scriptsToRun = requested.filter((name) => name !== 'ci' || explicitScripts).filter((name) => {
+      const raw = availableScripts[name];
+      if (!Object.prototype.hasOwnProperty.call(availableScripts, name)) return false;
+      if (!isRunnableQualityScript(name, raw)) return false;
+      if (isMutationLikeQualityScript(raw)) return false;
+      return QUALITY_SIGNALS.some((signal) => signal.script === name);
+    });
+    for (const script of scriptsToRun) {
+      if (failures.length && !continueOnFailure) break;
+      selected.push(script);
+      const signal = signals[signalKeyForScript(script)];
+      await executeScript({ script, signal, runner, baseArgs, cwd, timeoutMs, checks });
+      if (signal.status === 'failed' || signal.status === 'timed_out') failures.push(failureText(script, signal));
+    }
+  }
+
+  for (const signal of Object.values(signals)) {
+    if (signal.status === 'not_configured') skipped.push(`package script not found, skipped: ${signal.script}`);
+    if (signal.status === 'skipped') skipped.push(`${signal.script} skipped: ${signal.reason}`);
+    if (signal.status === 'not_verified' && signal.configured) notVerified.push(`${signal.script} configured but not verified: ${signal.reason}`);
   }
   if (!Object.keys(availableScripts).length) skipped.push('No package.json scripts detected');
+
+  addSignalChecks(checks, signals);
+
+  const skippedScripts = Object.values(signals)
+    .filter((signal) => ['not_configured', 'skipped'].includes(signal.status))
+    .map((signal) => signal.script);
+
   const result = createResult('quality', failures.length ? 'fail' : warnings.length ? 'warn' : 'pass', {
-    summary: 'Safe local quality gates ran only scripts that exist in package.json. Missing scripts were skipped, not failed.',
-    verified: [boundary.isGitRepo ? 'git diff --check executed' : 'git diff --check skipped outside git repository', 'package.json scripts inspected', 'Existing quality scripts selected: ' + (selected.length ? selected.join(', ') : 'none')],
+    summary: `Safe local quality gates reported distinct proof signals. Execution strategy: ${executionStrategy}.`,
+    verified: [
+      boundary.isGitRepo ? 'git diff --check executed' : 'git diff --check skipped outside git repository',
+      'package.json scripts inspected',
+      'Quality proof signals: ' + signalSummary(signals),
+      'Existing quality scripts selected: ' + (selected.length ? selected.join(', ') : 'none')
+    ],
     warnings,
     failures,
     skipped,
+    notVerified,
     checks,
-    data: { boundary, packageManager, availableScripts, requestedScripts: requested, selectedScripts: selected, skippedScripts },
-    nextSafeStep: failures.length ? 'Fix the failing quality command and rerun opstruth quality.' : 'Attach quality output to the evidence pack.'
+    data: {
+      boundary,
+      packageManager,
+      availableScripts,
+      requestedScripts: requested,
+      selectedScripts: selected,
+      skippedScripts,
+      quality: {
+        executionStrategy,
+        runner,
+        baseArgs,
+        signals
+      }
+    },
+    nextSafeStep: failures.length ? 'Fix the failing quality signal and rerun opstruth quality.' : 'Attach quality signal output to the evidence pack.'
   });
   return finalizeStatus(result, { strict });
 }

package/src/commands/routes.js

@@ -4,6 +4,38 @@ import { loadRoutesConfig, findDefaultRoutesConfig } from '../lib/config.js';
 import { resolveProjectBoundary } from '../lib/boundary.js';
 
 const DEFAULT_HEADERS = ['content-security-policy', 'strict-transport-security', 'x-frame-options', 'referrer-policy'];
+
+export function isLocalRouteUrl(value) {
+  try {
+    const hostname = new URL(value).hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1';
+  } catch {
+    return false;
+  }
+}
+
+export function buildMissingHeaderFinding({ url, routePath, missingHeaders = [], evidence = [] } = {}) {
+  if (!missingHeaders.length) return null;
+  const localPreview = isLocalRouteUrl(url);
+  const finding = localPreview
+    ? `${routePath} local preview missing headers: ${missingHeaders.join(', ')}`
+    : `${routePath} missing headers: ${missingHeaders.join(', ')}`;
+
+  return createFinding({
+    status: 'warn',
+    area: 'routes',
+    title: localPreview ? 'Local preview security headers missing' : 'Route security headers missing',
+    finding,
+    evidence,
+    whyItMatters: localPreview
+      ? 'The local preview response does not include the expected security headers. Local development and preview servers may differ from the deployed hosting layer. Production headers remain Not Verified until a production URL is checked.'
+      : 'Missing browser security headers can weaken runtime protection even when the checked route is available.',
+    nextSafeStep: localPreview
+      ? 'Check an explicitly supplied production URL before drawing production conclusions, and configure local preview headers only when they are useful for parity.'
+      : 'Add the missing headers in the app or hosting layer and rerun route probes.'
+  });
+}
+
 export async function runRoutes({ cwd = process.cwd(), baseUrl, routesFile, strict = false } = {}) {
   const boundary = await resolveProjectBoundary(cwd);
   cwd = boundary.root;
@@ -19,6 +51,7 @@ export async function runRoutes({ cwd = process.cwd(), baseUrl, routesFile, stri
   const warnings = [];
   const failures = [];
   const findings = [];
+  const localPreview = isLocalRouteUrl(finalBase);
   for (const route of routes) {
     const url = new URL(route.path, finalBase).toString();
     const probe = await probeUrl(url, { method: route.method || 'HEAD' });
@@ -38,12 +71,30 @@ export async function runRoutes({ cwd = process.cwd(), baseUrl, routesFile, stri
       failures.push(message);
       findings.push(createFinding({ status: 'fail', area: 'routes', title: 'Route status did not match expectation', finding: message, evidence, whyItMatters: 'A route that fails a read-only smoke check may block users or downstream health checks.', nextSafeStep: 'Inspect the route and rerun without deploying from opstruth.' }));
     }
-    if (missingHeaders.length) {
-      const message = `${route.path} missing headers: ${missingHeaders.join(', ')}`;
-      warnings.push(message);
-      findings.push(createFinding({ status: 'warn', area: 'routes', title: 'Route security headers missing', finding: message, evidence, whyItMatters: 'Missing browser security headers can weaken runtime protection even when the route is available.', nextSafeStep: 'Add the missing headers in the app or hosting layer and rerun route probes.' }));
+    const headerFinding = buildMissingHeaderFinding({ url, routePath: route.path, missingHeaders, evidence });
+    if (headerFinding) {
+      warnings.push(headerFinding.finding);
+      findings.push(headerFinding);
     }
     checks.push({ name: `${route.method || 'HEAD'} ${route.path}`, status: okStatus ? missingHeaders.length ? 'warn' : 'pass' : 'fail', message: `status=${probe.status || 'error'} latency=${probe.latencyMs}ms`, data: probe });
   }
-  return finalizeStatus(createResult('routes', failures.length ? 'fail' : warnings.length ? 'warn' : 'pass', { summary: 'HEAD/GET public route smoke matrix completed.', verified: ['Project boundary: ' + boundary.root, 'Routes checked with read-only HEAD/GET requests', 'Response status, redirects, headers, and latency captured'], warnings, failures, findings, checks, data: { boundary, baseUrl: finalBase, routes, requiredHeaders }, nextSafeStep: failures.length ? 'Investigate failing routes without deploying from opstruth.' : 'Add missing required headers or attach route evidence.' }), { strict });
+  return finalizeStatus(createResult('routes', failures.length ? 'fail' : warnings.length ? 'warn' : 'pass', {
+    summary: localPreview ? 'HEAD/GET local preview route smoke matrix completed.' : 'HEAD/GET public route smoke matrix completed.',
+    verified: [
+      'Project boundary: ' + boundary.root,
+      localPreview ? 'Local preview routes checked with read-only HEAD/GET requests' : 'Routes checked with read-only HEAD/GET requests',
+      'Response status, redirects, headers, and latency captured'
+    ],
+    warnings,
+    failures,
+    findings,
+    checks,
+    notVerified: localPreview ? ['Production security headers were not checked because only a local preview URL was probed'] : [],
+    data: { boundary, baseUrl: finalBase, routes, requiredHeaders, scope: localPreview ? 'local_preview' : 'remote' },
+    nextSafeStep: failures.length
+      ? 'Investigate failing routes without deploying from opstruth.'
+      : localPreview
+        ? 'Check an explicit production URL to verify deployed security headers.'
+        : 'Add missing required headers or attach route evidence.'
+  }), { strict });
 }

package/src/commands/secrets.js

@@ -1,41 +1,58 @@
 import { createFinding, createResult, finalizeStatus } from '../lib/result.js';
-import { scanRiskyReferences } from '../lib/scan.js';
+import { formatSecretSummary, scanRiskyReferencesDetailed } from '../lib/scan.js';
 import { resolveProjectBoundary } from '../lib/boundary.js';
 import { loadOpstruthConfig } from '../lib/config.js';
 
+function secretFindingTitle(item) {
+  if (item.category === 'actionable_source_finding') return 'Actionable secret finding';
+  if (item.category === 'unknown_requires_review') return 'Unknown token-like content';
+  return 'Secret/reference classification';
+}
+
 export async function runSecrets({ cwd = process.cwd(), strict = false } = {}) {
   const boundary = await resolveProjectBoundary(cwd);
   const loaded = await loadOpstruthConfig(boundary.root);
   const secretConfig = loaded.config?.secrets || {};
-  const findings = await scanRiskyReferences(boundary.root, {
+  const scan = await scanRiskyReferencesDetailed(boundary.root, {
     allowlistPaths: secretConfig.allowlistPaths || [],
     allowlistPatterns: secretConfig.allowlistPatterns || []
   });
-  const findingObjects = findings.map((item) => createFinding({
+  const findingObjects = scan.findings.map((item) => createFinding({
     status: 'warn',
     area: 'secrets',
-    title: 'Risky secret or auth reference',
+    title: secretFindingTitle(item),
     finding: `${item.file}:${item.line} matched ${item.pattern}`,
     evidence: [
       'file: ' + item.file,
       'line: ' + item.line,
       'pattern: ' + item.pattern,
+      'category: ' + item.category,
+      'severity: ' + item.severity,
       'kind: ' + item.kind,
       'context: ' + item.context,
       'redacted preview: ' + item.preview
     ],
     whyItMatters: 'Secret-like values and service-role references can create account, data, or infrastructure exposure if committed or exposed to browsers.',
-    nextSafeStep: 'Confirm whether this is a harmless reference. Move real secrets to secret storage and keep only names/placeholders in source.'
+    nextSafeStep: 'Review actionable and unknown findings first. Move real secrets to secret storage and keep only names/placeholders in source.'
   }));
-  const result = createResult('secrets', loaded.warning || findings.length ? 'warn' : 'pass', {
-    summary: 'Redacted risky secret/reference scan completed. .env file contents are skipped.',
-    verified: ['Project boundary scanned: ' + boundary.root, 'Source files scanned with redaction', '.env contents were not printed'],
+  const secretSummary = formatSecretSummary(scan.summary);
+  const result = createResult('secrets', loaded.warning || scan.findings.length ? 'warn' : 'pass', {
+    summary: 'Redacted secret/reference scan completed with grouped categories. .env file contents are skipped unless tracked.',
+    verified: ['Project boundary scanned: ' + boundary.root, 'Source files scanned with redaction', '.env contents were not printed', 'Secret references grouped: ' + secretSummary],
     warnings: [...(loaded.warning ? [loaded.warning] : []), ...findingObjects.map((finding) => finding.finding)],
     findings: findingObjects,
     skipped: boundary.message ? [boundary.message] : [],
-    checks: [{ name: 'secret reference scan', status: findings.length ? 'warn' : 'pass', message: findings.length + ' finding(s)' }],
-    data: { boundary, configFile: loaded.file, allowlistPaths: secretConfig.allowlistPaths || [], allowlistPatterns: secretConfig.allowlistPatterns || [], findings },
-    nextSafeStep: findings.length ? 'Review whether each reference is expected and move real secrets to safe storage.' : 'Keep secrets out of source and rerun before publishing.'
+    checks: [{ name: 'secret reference scan', status: scan.findings.length ? 'warn' : 'pass', message: secretSummary }],
+    data: {
+      boundary,
+      configFile: loaded.file,
+      allowlistPaths: secretConfig.allowlistPaths || [],
+      allowlistPatterns: secretConfig.allowlistPatterns || [],
+      secretSummary: scan.summary,
+      classifiedFindings: scan.records,
+      findings: scan.findings
+    },
+    nextSafeStep: scan.findings.length ? 'Review actionable and unknown findings first; treat documentation references and placeholders as context unless they contain real values.' : 'Keep secrets out of source and rerun before publishing.'
   });
   return finalizeStatus(result, { strict });
 }