opstruth 0.1.1

package/src/commands/cloudflare.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import { createResult, finalizeStatus } from '../lib/result.js';
+import { readWranglerConfig } from '../lib/config.js';
+import { detectPackageScripts } from '../lib/detect.js';
+import { pathExists, walkFiles, readText } from '../lib/fs.js';
+import { probeUrl } from '../lib/http.js';
+
+function extractTomlValue(text, key) {
+  const line = text.split(/\r?\n/).find((item) => item.trim().startsWith(key + ' =') || item.trim().startsWith(key + '='));
+  if (!line) return null;
+  return line.split('=').slice(1).join('=').trim().replace(/^['"]|['"]$/g, '') || null;
+}
+export async function runCloudflare({ cwd = process.cwd(), url, strict = false } = {}) {
+  const wrangler = await readWranglerConfig(cwd);
+  const scripts = await detectPackageScripts(cwd);
+  const warnings = [];
+  const verified = [];
+  const data = { configFile: wrangler?.file || null, workerName: null, main: null, compatibilityDate: null, routes: [], vars: [], deployScripts: [], workflows: [] };
+  if (!wrangler) warnings.push('No wrangler config found');
+  else {
+    verified.push('Cloudflare config detected: ' + wrangler.file);
+    if (wrangler.data) {
+      data.workerName = wrangler.data.name || null;
+      data.main = wrangler.data.main || null;
+      data.compatibilityDate = wrangler.data.compatibility_date || null;
+      data.routes = wrangler.data.routes || [];
+      data.vars = Object.keys(wrangler.data.vars || {});
+    } else {
+      data.workerName = extractTomlValue(wrangler.text, 'name');
+      data.main = extractTomlValue(wrangler.text, 'main');
+      data.compatibilityDate = extractTomlValue(wrangler.text, 'compatibility_date');
+      data.vars = [...wrangler.text.matchAll(/^\s*([A-Z0-9_]+)\s*=/gm)].map((match) => match[1]);
+      data.routes = [...wrangler.text.matchAll(/route\s*=\s*["']([^"']+)/g)].map((match) => match[1]);
+    }
+  }
+  for (const [name, script] of Object.entries(scripts)) if (/wrangler\s+deploy/.test(script)) data.deployScripts.push(name);
+  const workflowRoot = path.join(cwd, '.github/workflows');
+  if (await pathExists(workflowRoot)) {
+    for (const file of await walkFiles(workflowRoot)) {
+      const text = await readText(file.full);
+      if (/wrangler|cloudflare/i.test(text)) data.workflows.push(file.rel);
+    }
+  }
+  const checks = [{ name: 'cloudflare config inspection', status: wrangler ? 'pass' : 'warn' }];
+  if (url) {
+    const probe = await probeUrl(url, { method: 'HEAD' });
+    checks.push({ name: 'cloudflare optional route probe', status: probe.status ? 'pass' : 'fail', message: `${url} status=${probe.status || probe.error}`, data: probe });
+    if (!probe.status) warnings.push('Optional Cloudflare route probe failed');
+  }
+  return finalizeStatus(createResult('cloudflare', warnings.length ? 'warn' : 'pass', { summary: 'Cloudflare local configuration truth check completed. No deploy commands were run.', verified, warnings, checks, data, notVerified: ['No Cloudflare deploy was executed', 'Cloudflare dashboard state was not checked'], nextSafeStep: 'Compare declared routes/domains with a read-only route smoke check.' }), { strict });
+}

package/src/commands/evidence.js

@@ -0,0 +1,38 @@
+import path from 'node:path';
+import { createResult, finalizeStatus } from '../lib/result.js';
+import { readText, writeFileSafe, pathExists } from '../lib/fs.js';
+import { getGitInfo } from '../lib/git.js';
+import { evidenceMarkdown } from '../lib/markdown.js';
+
+export async function runEvidence({ cwd = process.cwd(), title = 'opstruth Evidence Pack', phase = 'local proof run', include = [], out = 'evidence/opstruth-report.md', strict = false, aggregate } = {}) {
+  const git = await getGitInfo(cwd);
+  const included = [];
+  for (const item of include) {
+    const full = path.isAbsolute(item) ? item : path.join(cwd, item);
+    if (await pathExists(full)) included.push({ file: item, content: await readText(full) });
+  }
+  const commandsRun = aggregate?.checks?.map((check) => check.command).filter(Boolean) || included.map((item) => 'included ' + item.file);
+  const checks = aggregate ? aggregate.checks.map((check) => `${check.status}: ${check.name || check.command}`) : included.map((item) => 'included evidence file: ' + item.file);
+  const findingEvidence = aggregate?.findings?.flatMap((finding) => [
+    `${finding.status}: ${finding.finding}`,
+    ...(finding.evidence || []).map((item) => `  evidence: ${item}`),
+    ...(finding.whyItMatters ? [`  why it matters: ${finding.whyItMatters}`] : []),
+    ...(finding.nextSafeStep ? [`  next safe step: ${finding.nextSafeStep}`] : [])
+  ]) || [];
+  const risks = aggregate ? [...findingEvidence, ...aggregate.warnings, ...aggregate.failures, ...aggregate.notVerified] : ['Unverified claims remain unless backed by attached command output'];
+  const markdown = evidenceMarkdown({
+    title,
+    status: aggregate?.status || 'not_verified',
+    scope: ['Phase: ' + phase, 'Working directory: ' + cwd, 'Git root: ' + (git.root || 'not a git repository')],
+    filesChanged: git.changedFiles,
+    commandsRun,
+    checks,
+    liveVerification: aggregate?.verified || [],
+    safetyBoundaries: ['Read-only checks only', 'No deploy commands run by opstruth', 'No database mutation commands run by opstruth', 'No OpenAI calls run by opstruth', 'No secrets printed by opstruth'],
+    risks,
+    nextSafeStep: aggregate?.nextSafeStep || 'Run the narrowest missing read-only check and attach it to this evidence pack.'
+  });
+  const outputPath = path.isAbsolute(out) ? out : path.join(cwd, out);
+  await writeFileSafe(outputPath, markdown);
+  return finalizeStatus(createResult('evidence', 'pass', { summary: 'Evidence pack written: ' + outputPath, verified: ['Evidence pack created', 'Safety-sensitive defaults separated from verified facts'], checks: [{ name: 'evidence writer', status: 'pass' }], data: { out: outputPath, included: included.map((item) => item.file), markdown }, nextSafeStep: 'Share the evidence pack with the change or CI artifact.' }), { strict });
+}

package/src/commands/local.js

@@ -0,0 +1,43 @@
+import { createFinding, createResult, finalizeStatus } from '../lib/result.js';
+import { runCommand } from '../lib/exec.js';
+import { probeUrl } from '../lib/http.js';
+
+export async function runLocal({ cwd = process.cwd(), port = [], health = '/', process: processName, service, strict = false } = {}) {
+  const ports = Array.isArray(port) ? port : [port].filter(Boolean);
+  if (!ports.length && !processName && !service) return createResult('local', 'skipped', { skipped: ['Local runtime checks skipped because no --port, --process, or --service was provided'], notVerified: ['Local runtime liveness'], nextSafeStep: 'Run opstruth local --port 3000 --health /health when the app is running.' });
+  const checks = [];
+  const warnings = [];
+  const verified = [];
+  const findings = [];
+  for (const item of ports) {
+    const portNumber = String(item);
+    const ss = await runCommand('sh', ['-lc', `ss -ltnp 2>/dev/null | grep -E '[:.]${portNumber}\\s' || true`], { cwd, timeoutMs: 10000 });
+    const listening = Boolean(ss.stdout.trim());
+    checks.push({ name: 'port ' + portNumber + ' listening', status: listening ? 'pass' : 'warn', command: 'ss -ltnp', message: listening ? 'listening' : 'not listening' });
+    if (listening) verified.push('Port listening: ' + portNumber); else {
+      const message = 'Port not listening: ' + portNumber;
+      warnings.push(message);
+      findings.push(createFinding({ status: 'warn', area: 'local', title: 'Local port not listening', finding: message, evidence: ['port: ' + portNumber, 'probe type: listening port', 'result: not listening'], whyItMatters: 'A local runtime that is not listening cannot provide live confidence for this change.', nextSafeStep: 'Start the runtime yourself and rerun opstruth local.' }));
+    }
+    if (health) {
+      const probe = await probeUrl(`http://127.0.0.1:${portNumber}${health.startsWith('/') ? health : '/' + health}`, { method: 'GET', timeoutMs: 5000 });
+      checks.push({ name: 'health ' + portNumber, status: probe.status && probe.status < 500 ? 'pass' : 'warn', message: 'status=' + (probe.status || probe.error), data: probe });
+      if (!probe.status || probe.status >= 500) {
+        const message = 'Health check failed for port ' + portNumber;
+        warnings.push(message);
+        findings.push(createFinding({ status: 'warn', area: 'local', title: 'Local health check failed', finding: message, evidence: ['port: ' + portNumber, 'health URL: ' + probe.url, 'probe type: GET', 'result: ' + (probe.status || probe.error)], whyItMatters: 'A failing health endpoint limits confidence that the local runtime is usable.', nextSafeStep: 'Start or repair the local service and rerun the health probe.' }));
+      }
+    }
+  }
+  if (processName) {
+    const ps = await runCommand('pgrep', ['-af', processName], { cwd, timeoutMs: 10000 });
+    checks.push({ name: 'process match ' + processName, status: ps.exitCode === 0 ? 'pass' : 'warn', command: ps.command });
+    if (ps.exitCode === 0) verified.push('Process matched: ' + processName); else warnings.push('No process matched: ' + processName);
+  }
+  if (service) {
+    const svc = await runCommand('systemctl', ['--user', 'status', service, '--no-pager'], { cwd, timeoutMs: 10000 });
+    checks.push({ name: 'systemd user service ' + service, status: svc.exitCode === 0 ? 'pass' : 'warn', command: svc.command });
+    if (svc.exitCode === 0) verified.push('Systemd user service visible: ' + service); else warnings.push('Systemd user service not active/visible: ' + service);
+  }
+  return finalizeStatus(createResult('local', warnings.length ? 'warn' : 'pass', { summary: 'Local runtime checks completed without killing or restarting services.', verified, warnings, findings, checks, notVerified: ['Process ownership may be incomplete on restricted systems'], nextSafeStep: warnings.length ? 'Start the runtime yourself and rerun opstruth local.' : 'Attach local liveness evidence if this runtime matters.' }), { strict });
+}

package/src/commands/probes.js

@@ -0,0 +1,68 @@
+import { createResult, finalizeStatus } from '../lib/result.js';
+import { resolveProjectBoundary } from '../lib/boundary.js';
+import { detectStack } from '../lib/detect.js';
+import { PROBE_CATALOGUE, selectProbes } from '../lib/probes.js';
+
+function countBy(items, key) {
+  const counts = {};
+  for (const item of items) counts[item[key] || 'unknown'] = (counts[item[key] || 'unknown'] || 0) + 1;
+  return counts;
+}
+
+function summarizeCounts(label, counts) {
+  return `${label}: ${Object.entries(counts).map(([name, count]) => `${name}=${count}`).join(', ')}`;
+}
+
+export async function runProbes({ cwd = process.cwd(), strict = false, skip = [], only = [] } = {}) {
+  const boundary = await resolveProjectBoundary(cwd);
+  const stack = await detectStack(boundary.root);
+  const selection = await selectProbes({ root: boundary.root, stack, boundary, options: { skip, only } });
+  const byArea = countBy(PROBE_CATALOGUE, 'area');
+  const byMode = countBy(PROBE_CATALOGUE, 'defaultMode');
+  const bySafety = countBy(PROBE_CATALOGUE, 'safetyLevel');
+  const result = createResult('probes', 'pass', {
+    summary: 'Probe catalogue inspected for the current project without running mutating actions.',
+    verified: [
+      'Total probes: ' + PROBE_CATALOGUE.length,
+      summarizeCounts('Probes by area', byArea),
+      summarizeCounts('Probes by default mode', byMode),
+      summarizeCounts('Probes by safety level', bySafety),
+      'Detected safe automatic probes for this project: ' + selection.selected.length,
+      'Project boundary: ' + boundary.root,
+      'Detected platforms: ' + (stack.platforms.length ? stack.platforms.join(', ') : 'none')
+    ],
+    skipped: [
+      ...(boundary.message ? [boundary.message] : []),
+      ...selection.skipped.slice(0, 20).map((probe) => `${probe.id}: ${probe.reason}`)
+    ],
+    checks: selection.selected.map((probe) => ({
+      name: probe.id,
+      status: 'pass',
+      message: `${probe.area}/${probe.stack}: ${probe.name}`
+    })),
+    notVerified: ['Probe catalogue inspection does not run route, local runtime, deploy, or external service checks by itself.'],
+    data: {
+      boundary,
+      stack,
+      total: PROBE_CATALOGUE.length,
+      byArea,
+      byMode,
+      bySafety,
+      detected: selection.selected.map((probe) => ({
+        id: probe.id,
+        name: probe.name,
+        area: probe.area,
+        stack: probe.stack,
+        safetyLevel: probe.safetyLevel,
+        defaultMode: probe.defaultMode,
+        evidenceCollected: probe.evidenceCollected,
+        proves: probe.proves,
+        doesNotProve: probe.doesNotProve,
+        nextSafeStep: probe.nextSafeStep
+      })),
+      skipped: selection.skipped.map((probe) => ({ id: probe.id, area: probe.area, stack: probe.stack, reason: probe.reason }))
+    },
+    nextSafeStep: 'Run opstruth for selected safe probes, or add explicit route/local inputs for stronger runtime evidence.'
+  });
+  return finalizeStatus(result, { strict });
+}

package/src/commands/quality.js

@@ -0,0 +1,66 @@
+import { createResult, finalizeStatus } from '../lib/result.js';
+import { runCommand, excerpt } from '../lib/exec.js';
+import { detectPackageManager, detectPackageScripts } from '../lib/detect.js';
+import { resolveProjectBoundary } from '../lib/boundary.js';
+
+const DEFAULT_SCRIPTS = ['typecheck', 'lint', 'test', 'build', 'ci'];
+
+export function isDefaultPlaceholderTestScript(script = '') {
+  return /^echo\s+["']?Error:\s*no test specified["']?\s*(?:&&|;)\s*exit\s+1$/i.test(script.trim());
+}
+
+function isRunnableQualityScript(name, script) {
+  return !(name === 'test' && isDefaultPlaceholderTestScript(script));
+}
+
+function runnerFor(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 } = {}) {
+  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 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;
+  });
+  if (boundary.message) skipped.push(boundary.message);
+  if (boundary.isGitRepo) {
+    const diff = await runCommand('git', ['diff', '--check'], { cwd, timeoutMs: 60000 });
+    checks.push({ name: 'git diff --check', command: diff.command, exitCode: diff.exitCode, durationMs: diff.durationMs, status: diff.exitCode === 0 ? 'pass' : 'fail', logExcerpt: excerpt(diff.stderr || diff.stdout) });
+    if (diff.exitCode !== 0) failures.push('git diff --check failed');
+  } 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');
+  }
+  if (!Object.keys(availableScripts).length) skipped.push('No package.json scripts detected');
+  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')],
+    warnings,
+    failures,
+    skipped,
+    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.'
+  });
+  return finalizeStatus(result, { strict });
+}

package/src/commands/repo.js

@@ -0,0 +1,30 @@
+import { createResult, finalizeStatus } from '../lib/result.js';
+import { getGitInfo } from '../lib/git.js';
+import { detectStack } from '../lib/detect.js';
+import { resolveProjectBoundary } from '../lib/boundary.js';
+
+export async function runRepo({ cwd = process.cwd(), strict = false } = {}) {
+  const boundary = await resolveProjectBoundary(cwd);
+  const git = await getGitInfo(boundary.root);
+  const root = boundary.root;
+  const stack = await detectStack(root);
+  const detected = [
+    'Project language detected: ' + stack.language,
+    'Node module mode detected: ' + (stack.isEsm ? 'ESM' : 'not declared ESM'),
+    'Package manager detected: ' + (stack.packageManager || 'none'),
+    'Platforms detected: ' + (stack.platforms.length ? stack.platforms.join(', ') : 'none')
+  ];
+  if (stack.isTypeScript) detected.push('TypeScript project detected via tsconfig, TypeScript dependency, .ts/.tsx source, or TS config files');
+  const configNotes = Object.entries(stack.config)
+    .filter(([, values]) => values.length)
+    .map(([name, values]) => `${name} config/files: ${values.join(', ')}`);
+  const result = createResult('repo', 'pass', {
+    summary: 'Read-only repository inspection completed. ' + detected.join(' | '),
+    verified: ['Current working directory inspected: ' + cwd, 'Git root checked: ' + (git.root || 'not a git repository'), 'Important repo files checked', ...detected, ...configNotes],
+    warnings: git.root ? [] : [boundary.message],
+    checks: [{ name: 'repo inspection', status: 'pass' }, { name: 'typescript project detection', status: stack.isTypeScript ? 'pass' : 'not_verified', message: stack.isTypeScript ? 'TypeScript-based project' : 'No TypeScript indicators detected' }],
+    data: { cwd, projectRoot: root, gitRoot: git.root, branch: git.branch, latestCommit: git.latestCommit, dirtyFiles: git.dirtyFiles, changedFiles: git.changedFiles, diffStat: git.diffStat, recentCommits: git.recentCommits, packageManager: stack.packageManager, scripts: stack.scripts, importantFiles: stack.files, platforms: stack.platforms, language: stack.language, isTypeScript: stack.isTypeScript, isEsm: stack.isEsm, config: stack.config },
+    nextSafeStep: 'Review dirty files and run opstruth quality before trusting the change.'
+  });
+  return finalizeStatus(result, { strict });
+}

package/src/commands/routes.js

@@ -0,0 +1,49 @@
+import { createFinding, createResult, finalizeStatus } from '../lib/result.js';
+import { probeUrl } from '../lib/http.js';
+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 async function runRoutes({ cwd = process.cwd(), baseUrl, routesFile, strict = false } = {}) {
+  const boundary = await resolveProjectBoundary(cwd);
+  cwd = boundary.root;
+  let config = routesFile ? await loadRoutesConfig(cwd, routesFile) : null;
+  if (config?.routes?.baseUrl !== undefined || config?.routes?.paths) config = config.routes;
+  if (!config) config = (await findDefaultRoutesConfig(cwd))?.config;
+  const finalBase = baseUrl || config?.baseUrl;
+  if (!finalBase) return createResult('routes', 'skipped', { skipped: ['Route checks skipped because no --base-url or route config was provided'], notVerified: ['Public route availability'], nextSafeStep: 'Run opstruth routes --base-url https://example.com or provide --routes.' });
+  const paths = config?.paths?.length ? config.paths.map((routePath) => ({ path: routePath, method: routePath.includes('health') ? 'GET' : 'HEAD', expectStatus: [200, 301, 302] })) : [];
+  const routes = config?.routes?.length ? config.routes : paths.length ? paths : [{ path: '/', method: 'HEAD', expectStatus: [200, 301, 302] }];
+  const requiredHeaders = config?.requiredHeaders || DEFAULT_HEADERS;
+  const checks = [];
+  const warnings = [];
+  const failures = [];
+  const findings = [];
+  for (const route of routes) {
+    const url = new URL(route.path, finalBase).toString();
+    const probe = await probeUrl(url, { method: route.method || 'HEAD' });
+    const expectStatus = route.expectStatus || [200, 301, 302];
+    const missingHeaders = requiredHeaders.filter((header) => !probe.headers?.[header]);
+    const okStatus = probe.status && expectStatus.includes(probe.status);
+    const evidence = [
+      'url: ' + url,
+      'method: ' + (route.method || 'HEAD'),
+      'status: ' + (probe.status || probe.error),
+      'latency: ' + probe.latencyMs + 'ms',
+      'missing headers: ' + (missingHeaders.length ? missingHeaders.join(', ') : 'none'),
+      'redirect target: ' + (probe.location || 'none')
+    ];
+    if (!okStatus) {
+      const message = `${route.method || 'HEAD'} ${route.path} returned ${probe.status || probe.error}`;
+      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.' }));
+    }
+    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 });
+}

package/src/commands/secrets.js

@@ -0,0 +1,33 @@
+import { createFinding, createResult, finalizeStatus } from '../lib/result.js';
+import { scanRiskyReferences } from '../lib/scan.js';
+import { resolveProjectBoundary } from '../lib/boundary.js';
+
+export async function runSecrets({ cwd = process.cwd(), strict = false } = {}) {
+  const boundary = await resolveProjectBoundary(cwd);
+  const findings = await scanRiskyReferences(boundary.root);
+  const findingObjects = findings.map((item) => createFinding({
+    status: 'warn',
+    area: 'secrets',
+    title: 'Risky secret or auth reference',
+    finding: `${item.file}:${item.line} matched ${item.pattern}`,
+    evidence: [
+      'file: ' + item.file,
+      'line: ' + item.line,
+      'pattern: ' + item.pattern,
+      '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.'
+  }));
+  const result = createResult('secrets', 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'],
+    warnings: 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, 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.'
+  });
+  return finalizeStatus(result, { strict });
+}

package/src/commands/supabase.js

@@ -0,0 +1,39 @@
+import path from 'node:path';
+import { createResult, finalizeStatus } from '../lib/result.js';
+import { walkFiles, readText, pathExists } from '../lib/fs.js';
+
+const DEFAULT_PROTECTED = ['agent_jobs', 'platform_credentials', 'worker_logs'];
+export async function runSupabase({ cwd = process.cwd(), protectedTable = DEFAULT_PROTECTED, frontendDir = 'src', migrationsDir = 'supabase/migrations', strict = false } = {}) {
+  const protectedTables = Array.isArray(protectedTable) ? protectedTable : [protectedTable];
+  const migrationRoot = path.join(cwd, migrationsDir);
+  const frontendRoot = path.join(cwd, frontendDir);
+  const warnings = [];
+  const verified = [];
+  const data = { protectedTables, policies: [], frontendAccess: [], riskyWrites: [] };
+  if (await pathExists(migrationRoot)) {
+    const migrations = await walkFiles(migrationRoot, { skipDirs: [] });
+    for (const file of migrations.filter((item) => item.rel.endsWith('.sql'))) {
+      const text = await readText(file.full);
+      const lower = text.toLowerCase();
+      data.policies.push({ file: path.join(migrationsDir, file.rel), createPolicy: /create\s+policy/i.test(text), enableRls: /alter\s+table[\s\S]+enable\s+row\s+level\s+security/i.test(text), grant: /\bgrant\b/i.test(text), revoke: /\brevoke\b/i.test(text), securityDefiner: /security\s+definer/i.test(text), functions: (lower.match(/create\s+(or\s+replace\s+)?function/g) || []).length });
+    }
+    verified.push('Supabase migrations inspected: ' + data.policies.length);
+  } else warnings.push('Supabase migrations directory not found: ' + migrationsDir);
+  if (await pathExists(frontendRoot)) {
+    const files = await walkFiles(frontendRoot, { skipDirs: ['node_modules', 'dist', 'build', '.next', 'coverage'] });
+    for (const file of files.filter((item) => /\.(js|jsx|ts|tsx)$/.test(item.rel))) {
+      const text = await readText(file.full);
+      for (const table of protectedTables) {
+        const fromPattern = new RegExp(`\\.from\\([\"']${table}[\"']\\)`, 'g');
+        if (fromPattern.test(text)) data.frontendAccess.push({ file: path.join(frontendDir, file.rel), table });
+      }
+      if (/\.(insert|update|delete|upsert)\s*\(/.test(text)) data.riskyWrites.push({ file: path.join(frontendDir, file.rel), operation: 'frontend write method' });
+    }
+    verified.push('Frontend Supabase references inspected');
+  } else warnings.push('Frontend directory not found: ' + frontendDir);
+  for (const access of data.frontendAccess) warnings.push(`Protected table referenced from frontend: ${access.table} in ${access.file}`);
+  for (const write of data.riskyWrites) warnings.push(`Frontend write call found: ${write.file}`);
+  const noRls = data.policies.filter((item) => !item.enableRls && !item.createPolicy);
+  if (data.policies.length && noRls.length) warnings.push('Some migration files did not include obvious RLS policy statements');
+  return finalizeStatus(createResult('supabase', warnings.length ? 'warn' : 'pass', { summary: 'Static Supabase exposure audit completed without connecting to Supabase.', verified, warnings, checks: [{ name: 'supabase static audit', status: warnings.length ? 'warn' : 'pass' }], data, notVerified: ['Live Supabase permissions were not checked', 'No migrations were applied'], nextSafeStep: 'Review protected table findings and run a live permission audit outside opstruth if needed.' }), { strict });
+}

package/src/lib/boundary.js

@@ -0,0 +1,74 @@
+import path from 'node:path';
+import { runCommand } from './exec.js';
+
+export const DEFAULT_IGNORED_DIRS = [
+  '.git',
+  'node_modules',
+  'dist',
+  'build',
+  '.next',
+  'coverage',
+  '.cache',
+  '.config',
+  '.local',
+  '.npm',
+  '.pnpm-store',
+  '.yarn',
+  '.bun',
+  '.vscode-server',
+  '.cursor',
+  '.agents',
+  'Downloads',
+  'Desktop',
+  'Documents',
+  'Pictures',
+  'Videos',
+  'Music',
+  'evidence'
+];
+
+export const DEFAULT_BINARY_EXTENSIONS = [
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.ico',
+  '.pdf',
+  '.zip',
+  '.gz',
+  '.tgz',
+  '.br',
+  '.sqlite',
+  '.db',
+  '.wasm',
+  '.lockb'
+];
+
+export async function resolveProjectBoundary(cwd = process.cwd()) {
+  const git = await runCommand('git', ['rev-parse', '--show-toplevel'], { cwd, timeoutMs: 10000 });
+  if (git.exitCode === 0 && git.stdout.trim()) {
+    return {
+      cwd,
+      root: git.stdout.trim(),
+      gitRoot: git.stdout.trim(),
+      isGitRepo: true,
+      message: ''
+    };
+  }
+  return {
+    cwd,
+    root: cwd,
+    gitRoot: null,
+    isGitRepo: false,
+    message: 'No git repository detected. opstruth is scanning the current directory with safety ignores. For best results, run inside a project repo.'
+  };
+}
+
+export function mergeIgnores(extra = []) {
+  return [...new Set([...DEFAULT_IGNORED_DIRS, ...(extra || [])])];
+}
+
+export function isIgnoredExtension(file) {
+  return DEFAULT_BINARY_EXTENSIONS.includes(path.extname(file).toLowerCase());
+}

package/src/lib/config.js

@@ -0,0 +1,31 @@
+import path from 'node:path';
+import { pathExists, readJson, readText } from './fs.js';
+
+export async function loadRoutesConfig(root, file) {
+  if (!file) return null;
+  const full = path.isAbsolute(file) ? file : path.join(root, file);
+  if (!(await pathExists(full))) return null;
+  return readJson(full);
+}
+export async function findDefaultRoutesConfig(root) {
+  for (const file of ['opstruth.config.json', 'opstruth.routes.json', 'routes.json']) {
+    const full = path.join(root, file);
+    if (await pathExists(full)) {
+      const config = await readJson(full);
+      return { file, config: config.routes?.baseUrl !== undefined || config.routes?.paths ? config.routes : config };
+    }
+  }
+  return null;
+}
+export async function readWranglerConfig(root) {
+  for (const file of ['wrangler.json', 'wrangler.jsonc']) {
+    const full = path.join(root, file);
+    if (await pathExists(full)) {
+      const text = await readText(full);
+      return { file, text, data: JSON.parse(text.replace(/\/\/.*$/gm, '')) };
+    }
+  }
+  const toml = path.join(root, 'wrangler.toml');
+  if (await pathExists(toml)) return { file: 'wrangler.toml', text: await readText(toml), data: null };
+  return null;
+}

package/src/lib/detect.js

@@ -0,0 +1,111 @@
+import path from 'node:path';
+import { pathExists, readJson, listPresent, walkFiles } from './fs.js';
+import { mergeIgnores } from './boundary.js';
+
+const IMPORTANT_FILES = [
+  'package.json',
+  'tsconfig.json',
+  'vite.config.js',
+  'vite.config.ts',
+  'vite.config.mjs',
+  'next.config.js',
+  'next.config.mjs',
+  'next.config.ts',
+  'eslint.config.js',
+  'eslint.config.mjs',
+  'eslint.config.cjs',
+  'eslint.config.ts',
+  '.eslintrc',
+  '.eslintrc.js',
+  '.eslintrc.cjs',
+  '.eslintrc.json',
+  'vitest.config.js',
+  'vitest.config.mjs',
+  'vitest.config.ts',
+  'playwright.config.js',
+  'playwright.config.mjs',
+  'playwright.config.ts',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+  'package-lock.json',
+  'bun.lockb',
+  'bun.lock',
+  'wrangler.toml',
+  'wrangler.json',
+  'wrangler.jsonc',
+  'Dockerfile',
+  'docker-compose.yml',
+  'docker-compose.yaml',
+  'README.md',
+  'AGENTS.md',
+  '.github/workflows',
+  'supabase',
+  'supabase/migrations'
+];
+
+export async function detectPackageManager(root) {
+  if (await pathExists(path.join(root, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (await pathExists(path.join(root, 'yarn.lock'))) return 'yarn';
+  if (await pathExists(path.join(root, 'bun.lockb')) || await pathExists(path.join(root, 'bun.lock'))) return 'bun';
+  if (await pathExists(path.join(root, 'package-lock.json'))) return 'npm';
+  if (await pathExists(path.join(root, 'package.json'))) return 'npm';
+  return null;
+}
+
+export async function detectPackageScripts(root) {
+  const file = path.join(root, 'package.json');
+  if (!(await pathExists(file))) return {};
+  try { return (await readJson(file)).scripts || {}; } catch { return {}; }
+}
+
+async function hasSourceExtension(root, extensions) {
+  const files = await walkFiles(root, { skipDirs: mergeIgnores(), maxFiles: 1000 });
+  return files.some((file) => extensions.some((extension) => file.rel.endsWith(extension)));
+}
+
+export async function detectStack(root) {
+  const packageFile = path.join(root, 'package.json');
+  let pkg = {};
+  if (await pathExists(packageFile)) {
+    try { pkg = await readJson(packageFile); } catch { pkg = {}; }
+  }
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const files = await listPresent(root, IMPORTANT_FILES);
+  const hasTsSource = await hasSourceExtension(root, ['.ts', '.tsx']);
+  const isTypeScript = Boolean(files.includes('tsconfig.json') || deps.typescript || hasTsSource || files.includes('vite.config.ts') || files.includes('next.config.ts'));
+  const isEsm = pkg.type === 'module' || files.some((file) => file.endsWith('.mjs'));
+  const config = {
+    typescript: files.filter((file) => file === 'tsconfig.json'),
+    vite: files.filter((file) => file.startsWith('vite.config')),
+    next: files.filter((file) => file.startsWith('next.config')),
+    eslint: files.filter((file) => file.includes('eslint')),
+    vitest: files.filter((file) => file.startsWith('vitest.config')),
+    playwright: files.filter((file) => file.startsWith('playwright.config')),
+    lockfiles: files.filter((file) => ['pnpm-lock.yaml', 'yarn.lock', 'package-lock.json', 'bun.lockb', 'bun.lock'].includes(file))
+  };
+  const platforms = [];
+  if (isTypeScript) platforms.push('TypeScript');
+  if (deps.react) platforms.push('React');
+  if (deps.vite || config.vite.length) platforms.push('Vite');
+  if (deps.next || config.next.length) platforms.push('Next.js');
+  if (isEsm) platforms.push('Node ESM');
+  if (files.some((file) => file.startsWith('wrangler'))) platforms.push('Cloudflare');
+  if (files.includes('supabase') || files.includes('supabase/migrations')) platforms.push('Supabase');
+  if (files.some((file) => file.toLowerCase().includes('docker'))) platforms.push('Docker');
+  if (files.includes('.github/workflows')) platforms.push('GitHub Actions');
+  return {
+    packageName: pkg.name || null,
+    packageManager: await detectPackageManager(root),
+    scripts: pkg.scripts || {},
+    files,
+    platforms,
+    language: isTypeScript ? 'TypeScript' : 'JavaScript',
+    isTypeScript,
+    isEsm,
+    config,
+    dependencies: Object.keys(deps).sort()
+  };
+}
+
+export async function hasSupabase(root) { return pathExists(path.join(root, 'supabase')); }
+export async function hasCloudflare(root) { return (await pathExists(path.join(root, 'wrangler.toml'))) || (await pathExists(path.join(root, 'wrangler.json'))) || (await pathExists(path.join(root, 'wrangler.jsonc'))); }