opstruth 0.1.1

package/src/lib/exec.js

@@ -0,0 +1,28 @@
+import { spawn } from 'node:child_process';
+import { redact } from './redact.js';
+
+export function runCommand(command, args = [], { cwd = process.cwd(), timeoutMs = 120000 } = {}) {
+  const started = Date.now();
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, shell: false, windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
+    child.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
+    child.stderr?.on('data', (chunk) => { stderr += chunk.toString(); });
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      resolve({ command: [command, ...args].join(' '), exitCode: 127, durationMs: Date.now() - started, stdout: '', stderr: redact(error.message) });
+    });
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      resolve({ command: [command, ...args].join(' '), exitCode: code ?? (signal ? 124 : 1), signal, durationMs: Date.now() - started, stdout: redact(stdout), stderr: redact(stderr) });
+    });
+  });
+}
+
+export function excerpt(text = '', lines = 30) {
+  const clean = redact(text).trim();
+  if (!clean) return '';
+  return clean.split(/\r?\n/).slice(-lines).join('\n');
+}

package/src/lib/fs.js

@@ -0,0 +1,36 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isIgnoredExtension } from './boundary.js';
+
+export async function pathExists(filePath) {
+  try { await fs.access(filePath); return true; } catch { return false; }
+}
+export async function readText(filePath) { return fs.readFile(filePath, 'utf8'); }
+export async function readJson(filePath) { return JSON.parse(await readText(filePath)); }
+export async function writeFileSafe(filePath, content) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, content, 'utf8');
+}
+export async function listPresent(root, files) {
+  const present = [];
+  for (const file of files) if (await pathExists(path.join(root, file))) present.push(file);
+  return present;
+}
+export async function walkFiles(root, { skipDirs = [], maxFiles = 5000, skipBinary = true } = {}) {
+  const results = [];
+  async function walk(dir) {
+    if (results.length >= maxFiles) return;
+    let entries = [];
+    try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      const rel = path.relative(root, full).replaceAll('\\', '/');
+      if (entry.isDirectory()) {
+        if (!skipDirs.includes(entry.name) && !skipDirs.includes(rel)) await walk(full);
+      } else if (entry.isFile() && (!skipBinary || !isIgnoredExtension(entry.name))) results.push({ full, rel });
+      if (results.length >= maxFiles) return;
+    }
+  }
+  await walk(root);
+  return results;
+}

package/src/lib/git.js

@@ -0,0 +1,27 @@
+import { runCommand } from './exec.js';
+
+export async function git(args, cwd) { return runCommand('git', args, { cwd, timeoutMs: 30000 }); }
+export async function gitText(args, cwd) {
+  const result = await git(args, cwd);
+  return result.exitCode === 0 ? result.stdout.trim() : '';
+}
+export async function getGitInfo(cwd) {
+  const root = await gitText(['rev-parse', '--show-toplevel'], cwd);
+  const workingRoot = root || cwd;
+  const [branch, latestCommit, status, diffStat, recentCommits] = await Promise.all([
+    gitText(['branch', '--show-current'], workingRoot),
+    gitText(['log', '-1', '--pretty=%h %s'], workingRoot),
+    gitText(['status', '--short'], workingRoot),
+    gitText(['diff', '--stat'], workingRoot),
+    gitText(['log', '--oneline', '-5'], workingRoot)
+  ]);
+  return {
+    root: root || null,
+    branch: branch || null,
+    latestCommit: latestCommit || null,
+    dirtyFiles: status ? status.split(/\r?\n/).filter(Boolean) : [],
+    changedFiles: status ? status.split(/\r?\n/).map((line) => line.slice(3).trim()).filter(Boolean) : [],
+    diffStat: diffStat || '',
+    recentCommits: recentCommits ? recentCommits.split(/\r?\n/).filter(Boolean) : []
+  };
+}

package/src/lib/http.js

@@ -0,0 +1,14 @@
+export async function probeUrl(url, { method = 'HEAD', timeoutMs = 15000 } = {}) {
+  const started = Date.now();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { method, redirect: 'manual', signal: controller.signal });
+    const headers = Object.fromEntries(response.headers.entries());
+    return { url, method, status: response.status, ok: response.ok, redirected: response.status >= 300 && response.status < 400, location: headers.location || null, headers, latencyMs: Date.now() - started };
+  } catch (error) {
+    return { url, method, status: null, ok: false, error: error.message, latencyMs: Date.now() - started };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/lib/markdown.js

@@ -0,0 +1,202 @@
+import { redactObject } from './redact.js';
+
+const ASCII_HEADER = `   ____        _______          __  __
+  / __ \\____  / ____(_)___  ____/ /_/ /
+ / / / / __ \\/ /_  / / __ \\/ __  / __/
+/ /_/ / /_/ / __/ / / / / / /_/ / /_
+\\____/ .___/_/   /_/_/ /_/\\__,_/\\__/
+    /_/
+
+Operational truth checks for AI-assisted engineering.`;
+
+function statusLabel(status) {
+  if (status === 'pass') return 'Pass';
+  if (status === 'warn') return 'Partial pass';
+  if (status === 'fail') return 'Fail';
+  if (status === 'skipped') return 'Skipped';
+  return 'Not verified';
+}
+
+function list(items = [], fallback = '- None', limit = 12) {
+  if (!items.length) return fallback;
+  const shown = items.slice(0, limit).map((item) => '- ' + String(item).replace(/\n/g, ' '));
+  const remaining = items.length - shown.length;
+  if (remaining > 0) shown.push('- +' + remaining + ' more');
+  return shown.join('\n');
+}
+
+function findingList(findings = [], limit = 8) {
+  if (!findings.length) return '- None';
+  const lines = [];
+  for (const finding of findings.slice(0, limit)) {
+    lines.push('- [' + (finding.status || 'warn') + '] ' + finding.title + ': ' + finding.finding);
+    for (const evidence of (finding.evidence || []).slice(0, 6)) lines.push('  evidence: ' + String(evidence).replace(/\n/g, ' '));
+    if (finding.whyItMatters) lines.push('  why it matters: ' + finding.whyItMatters);
+    if (finding.nextSafeStep) lines.push('  next safe step: ' + finding.nextSafeStep);
+  }
+  if (findings.length > limit) lines.push('- +' + (findings.length - limit) + ' more findings in JSON output/evidence data');
+  return lines.join('\n');
+}
+
+function table(headers, rows) {
+  if (!rows.length) return '- None';
+  const head = '| ' + headers.join(' | ') + ' |';
+  const divider = '| ' + headers.map(() => '---').join(' | ') + ' |';
+  const body = rows.map((row) => '| ' + row.map((cell) => String(cell ?? '').replace(/\n/g, ' ')).join(' | ') + ' |');
+  return [head, divider, ...body].join('\n');
+}
+
+function checkList(checks = [], limit = 12) {
+  if (!checks.length) return '- None';
+  return table(['Status', 'Check', 'Detail'], checks.slice(0, limit).map((check) => [
+    check.status || 'not_verified',
+    check.name || check.command || 'check',
+    [Number.isFinite(check.exitCode) ? 'exit ' + check.exitCode : '', Number.isFinite(check.durationMs) ? check.durationMs + 'ms' : '', check.message || ''].filter(Boolean).join(', ')
+  ])).concat(checks.length > limit ? '\n- +' + (checks.length - limit) + ' more checks in JSON output/evidence data' : '');
+}
+
+function confidenceFor(result) {
+  if (result.failures?.length) return 'Blocked: at least one check failed. Fix failures before trusting this change.';
+  if (result.warnings?.length) return 'Good for local iteration. Some proof gaps remain before production confidence.';
+  if (result.skipped?.length || result.notVerified?.length) return 'Basic checks passed. Runtime or production verification may still be incomplete.';
+  return 'Strong local confidence for the checks opstruth can perform read-only.';
+}
+
+function summarizeChildren(result) {
+  const children = result.data?.childResults || [];
+  return table(['Area', 'Status', 'What happened'], children.map((child) => [
+    child.command,
+    statusLabel(child.status),
+    child.failures?.[0] || child.warnings?.[0] || child.skipped?.[0] || child.verified?.[0] || child.summary || 'Completed'
+  ]));
+}
+
+function orchestratorMarkdown(raw) {
+  const result = redactObject(raw);
+  const evidencePath = result.data?.evidence?.out;
+  return [
+    ASCII_HEADER,
+    '',
+    'Welcome to opstruth.',
+    '',
+    'This tool runs read-only operational checks to help you understand:',
+    '- what changed',
+    '- what is configured',
+    '- what looks risky',
+    '- what was verified',
+    '- what was not verified',
+    '',
+    'It will not deploy, mutate databases, trigger jobs, publish content, restart services, call OpenAI, or print raw secrets.',
+    '',
+    '# opstruth',
+    '',
+    'STATUS: ' + statusLabel(result.status),
+    '',
+    'One-command operational truth check completed. opstruth only ran read-only checks.',
+    '',
+    '## What Matters Most',
+    list(result.failures, '- No failures', 5),
+    '',
+    '## Verified',
+    list(result.verified, '- None', 8),
+    '',
+    '## Warnings',
+    list(result.warnings, '- None', 8),
+    '',
+    '## Failures',
+    list(result.failures, '- None', 8),
+    '',
+    '## Skipped Or Not Configured',
+    list(result.skipped, '- None', 8),
+    '',
+    '## Not Verified',
+    list(result.notVerified, '- None', 8),
+    '',
+    '## Check Summary',
+    summarizeChildren(result),
+    '',
+    '## Why You Can Trust This Result',
+    '- Project boundary was resolved before stack detection',
+    '- Probes are read-only by default',
+    '- Warnings and failures include evidence where available',
+    '- Skipped checks are reported separately from failures',
+    '- Not verified is reported as a proof gap, not as safe',
+    '',
+    '## Evidence Available',
+    list((result.data?.probes?.selected || []).slice(0, 12).map((probe) => `${probe.id}: ${probe.evidenceCollected?.join(', ') || 'metadata'}`), '- None'),
+    '',
+    '## What opstruth Did Not Do',
+    '- No deploys were run',
+    '- No database mutations were run',
+    '- No queues or jobs were triggered',
+    '- No OpenAI or external AI API calls were made',
+    '- No raw secrets were printed',
+    '',
+    '## Overall Confidence',
+    confidenceFor(result),
+    '',
+    '## Evidence',
+    findingList(result.findings),
+    '',
+    evidencePath ? '- Evidence written to: ' + evidencePath : '- Evidence file was not written',
+    '',
+    '## Next Safe Step',
+    result.nextSafeStep || 'Run the narrowest missing read-only check with explicit inputs.'
+  ].join('\n') + '\n';
+}
+
+export function resultToMarkdown(raw) {
+  const result = redactObject(raw);
+  if (result.command === 'opstruth') return orchestratorMarkdown(result);
+  const title = 'opstruth ' + result.command;
+  const lines = ['# ' + title, '', 'STATUS: ' + statusLabel(result.status)];
+  if (result.summary) lines.push('', result.summary, '');
+  lines.push('## Verified', list(result.verified, '- None', 8), '', '## Warnings', list(result.warnings, '- None', 8), '', '## Failures', list(result.failures, '- None', 8), '', '## Skipped', list(result.skipped, '- None', 8), '', '## Not Verified', list(result.notVerified, '- None', 8), '', '## Checks', checkList(result.checks), '', '## Evidence', findingList(result.findings), '', '## Overall Confidence', confidenceFor(result), '', '## Next Safe Step', result.nextSafeStep || 'Review warnings and run the narrowest missing read-only check.');
+  return lines.join('\n') + '\n';
+}
+
+export function evidenceMarkdown({ title = 'opstruth Evidence Pack', status = 'not_verified', scope = [], filesChanged = [], commandsRun = [], checks = [], liveVerification = [], safetyBoundaries = [], risks = [], nextSafeStep = '' } = {}) {
+  const riskRows = risks.length ? risks.map((risk) => ['Review', risk]) : [['None recorded', 'No warnings or failures were provided to this evidence pack']];
+  return [
+    '# ' + title,
+    '',
+    '## Status',
+    statusLabel(status),
+    '',
+    '## Operator Summary',
+    'This evidence pack separates verified facts from unverified claims. opstruth is read-only and does not prove production state unless route or runtime checks were explicitly configured.',
+    '',
+    '## Scope',
+    list(scope, '- Not specified'),
+    '',
+    '## Files Changed',
+    list(filesChanged, '- No changed files detected', 20),
+    '',
+    '## Commands Run',
+    list(commandsRun, '- No command evidence attached', 20),
+    '',
+    '## Check Results',
+    list(checks, '- No checks attached', 25),
+    '',
+    '## Verified Facts',
+    list(liveVerification, '- No live verification evidence attached', 20),
+    '',
+    '## Risks And Gaps',
+    table(['Severity', 'Finding'], riskRows.slice(0, 25)),
+    '',
+    '## What Was Not Done',
+    '| Area | opstruth result |',
+    '| --- | --- |',
+    '| Jobs or queues | Not triggered by opstruth; not verified unless separate evidence is attached |',
+    '| OpenAI or external AI calls | Not called by opstruth; usage not monitored |',
+    '| Publishing | Not changed by opstruth |',
+    '| Deploys | No deploy command run by opstruth |',
+    '| Database mutations | No database mutation command run by opstruth |',
+    '',
+    '## Safety Boundaries',
+    list(safetyBoundaries, '- Read-only checks only'),
+    '',
+    '## Next Safe Step',
+    nextSafeStep || 'Run the narrowest missing read-only verification and attach the result.'
+  ].join('\n') + '\n';
+}