opstruth 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opstruth contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# opstruth
+
+Read-only operational truth checks for AI-assisted engineering workflows.
+
+`opstruth` inspects a local project, detects its stack, runs safe probes, collects evidence, explains proof gaps, and avoids pretending unverified systems are safe.
+
+## Install
+
+After npm publication:
+
+```bash
+npm install -g opstruth
+opstruth
+```
+
+One-off usage:
+
+```bash
+npx opstruth
+```
+
+## Commands
+
+```bash
+opstruth
+opstruth welcome
+opstruth probes
+opstruth secrets
+opstruth routes --base-url https://example.com
+opstruth local --port 3000 --health /health
+```
+
+## Safety Model
+
+opstruth is read-only by default. CLI checks do not deploy, mutate databases, trigger queues or jobs, call OpenAI, restart services, publish content, or print raw secrets.
+
+Skipped checks and not-verified areas are reported as proof gaps instead of being treated as safe.
+
+## Repository
+
+Source, docs, and release evidence live at:
+
+```text
+https://github.com/AyobamiH/opstruth
+```
+
+The public website is:
+
+```text
+https://opstruth.woeinvests.workers.dev
+```

package/bin/opstruth.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.js';
+
+await runCli(process.argv.slice(2), process.cwd()).catch((error) => {
+  console.error(error?.stack || error?.message || String(error));
+  process.exitCode = 1;
+});

package/examples/routes.json

@@ -0,0 +1,12 @@
+{
+  "baseUrl": "https://example.com",
+  "routes": [
+    { "path": "/", "method": "HEAD", "expectStatus": [200, 301, 302] },
+    { "path": "/login", "method": "HEAD", "expectStatus": [200, 301, 302] },
+    { "path": "/healthz", "method": "GET", "expectStatus": [200] }
+  ],
+  "requiredHeaders": [
+    "content-security-policy",
+    "strict-transport-security"
+  ]
+}

package/fixtures/next-app/app/page.tsx

@@ -0,0 +1,3 @@
+export default function Page() {
+  return <main>opstruth Next.js fixture</main>;
+}

package/fixtures/next-app/next.config.ts

@@ -0,0 +1,5 @@
+const config = {
+  reactStrictMode: true
+};
+
+export default config;

package/fixtures/next-app/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "opstruth-fixture-next-app",
+  "type": "module",
+  "private": true,
+  "dependencies": {
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "typecheck": "node --version",
+    "lint": "node --version",
+    "test": "node --version",
+    "build": "node --version"
+  }
+}

package/fixtures/next-app/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "compilerOptions": {
+    "jsx": "preserve",
+    "strict": true
+  }
+}

package/fixtures/non-git-folder/README.md

@@ -0,0 +1,3 @@
+# Non-Git Fixture
+
+This folder intentionally has no package.json and is copied to a non-git temp directory during fixture runs.

package/fixtures/non-git-folder/notes.txt

@@ -0,0 +1 @@
+plain text only

package/fixtures/plain-node-app/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "opstruth-fixture-plain-node-app",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "test": "node --version"
+  }
+}

package/fixtures/plain-node-app/src/index.js

@@ -0,0 +1,3 @@
+export function main() {
+  return 'hello from plain node';
+}

package/fixtures/risky-secret-app/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "opstruth-fixture-risky-secret-app",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "test": "node --version"
+  }
+}

package/fixtures/risky-secret-app/src/config.js

@@ -0,0 +1,3 @@
+export const OPENAI_API_KEY = "fake-openai-key-for-redaction";
+export const SUPABASE_SERVICE_ROLE_KEY = "fake-service-role-for-redaction";
+export const authorization = "Bearer fake-bearer-token-for-redaction";

package/fixtures/supabase-cloudflare-app/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "opstruth-fixture-supabase-cloudflare-app",
+  "type": "module",
+  "private": true,
+  "dependencies": {
+    "@supabase/supabase-js": "^2.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "wrangler": "^4.0.0"
+  },
+  "scripts": {
+    "typecheck": "node --version",
+    "deploy": "wrangler deploy"
+  }
+}

package/fixtures/supabase-cloudflare-app/src/supabaseClient.ts

@@ -0,0 +1,7 @@
+import { createClient } from '@supabase/supabase-js';
+
+const url = 'https://example.supabase.co';
+const anonKey = 'public-anon-placeholder';
+
+export const supabase = createClient(url, anonKey);
+export const jobsQuery = supabase.from('agent_jobs').select('*');

package/fixtures/supabase-cloudflare-app/src/worker.ts

@@ -0,0 +1,5 @@
+export default {
+  fetch() {
+    return new Response('ok');
+  }
+};

package/fixtures/supabase-cloudflare-app/supabase/migrations/001_init.sql

@@ -0,0 +1,11 @@
+create table public.agent_jobs (
+  id uuid primary key,
+  status text not null
+);
+
+alter table public.agent_jobs enable row level security;
+
+create policy "read own jobs"
+on public.agent_jobs
+for select
+using (true);

package/fixtures/supabase-cloudflare-app/wrangler.toml

@@ -0,0 +1,6 @@
+name = "opstruth-fixture-worker"
+main = "src/worker.ts"
+compatibility_date = "2026-01-01"
+routes = [
+  { pattern = "fixture.example.com/*", custom_domain = true }
+]

package/fixtures/vite-react-app/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "opstruth-fixture-vite-react-app",
+  "type": "module",
+  "private": true,
+  "dependencies": {
+    "@vitejs/plugin-react": "^5.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vite": "^6.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "typecheck": "node --version",
+    "lint": "node --version",
+    "test": "node --version",
+    "build": "node --version"
+  }
+}

package/fixtures/vite-react-app/src/App.tsx

@@ -0,0 +1,3 @@
+export function App() {
+  return <main>opstruth Vite fixture</main>;
+}

package/fixtures/vite-react-app/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "strict": true
+  }
+}

package/fixtures/vite-react-app/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()]
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "opstruth",
+  "version": "0.1.1",
+  "description": "Read-only operational truth checks for AI-assisted engineering workflows.",
+  "type": "module",
+  "bin": {
+    "opstruth": "./bin/opstruth.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "examples/",
+    "fixtures/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "node --check bin/opstruth.js",
+    "lint": "node --check bin/opstruth.js && find src -name '*.js' -print -exec node --check {} \\;",
+    "test": "node --test",
+    "build": "node --check bin/opstruth.js",
+    "ci": "npm run lint && npm test && npm run build",
+    "demo:fixtures": "./scripts/demo-fixtures.sh"
+  },
+  "keywords": [
+    "ai-assisted-development",
+    "codex",
+    "devtools",
+    "cli",
+    "operational-truth",
+    "cloudflare",
+    "supabase",
+    "typescript",
+    "evidence"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AyobamiH/opstruth.git",
+    "directory": "cli"
+  },
+  "homepage": "https://opstruth.woeinvests.workers.dev",
+  "bugs": {
+    "url": "https://github.com/AyobamiH/opstruth/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/demo-fixtures.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env sh
+set -eu
+
+ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
+REPO_ROOT="$(CDPATH= cd -- "$ROOT/.." && pwd)"
+BIN="$ROOT/bin/opstruth.js"
+OUT_DIR="$REPO_ROOT/evidence/fixture-runs"
+TMP_ROOT="${TMPDIR:-/tmp}/opstruth-fixture-runs-$$"
+
+mkdir -p "$OUT_DIR" "$TMP_ROOT"
+
+run_fixture() {
+  name="$1"
+  git_mode="$2"
+  src="$ROOT/fixtures/$name"
+  work="$TMP_ROOT/$name"
+  mkdir -p "$work"
+  cp -R "$src/." "$work/"
+  if [ "$git_mode" = "git" ]; then
+    git init "$work" >/dev/null 2>&1
+  fi
+  echo "==> $name"
+  (cd "$work" && node "$BIN" --out "$OUT_DIR/$name.md") >/dev/null
+  echo "    wrote $OUT_DIR/$name.md"
+}
+
+run_fixture "vite-react-app" "git"
+run_fixture "next-app" "git"
+run_fixture "supabase-cloudflare-app" "git"
+run_fixture "plain-node-app" "git"
+run_fixture "non-git-folder" "nogit"
+run_fixture "risky-secret-app" "git"
+
+echo
+echo "Fixture evidence written to $OUT_DIR"

package/scripts/demo-run.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env sh
+set -eu
+
+ROOT="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
+REPO_ROOT="$(CDPATH= cd -- "$ROOT/.." && pwd)"
+BIN="$ROOT/bin/opstruth.js"
+OUT_DIR="$REPO_ROOT/evidence/fixture-runs"
+TMP_ROOT="${TMPDIR:-/tmp}/opstruth-demo-run-$$"
+
+mkdir -p "$OUT_DIR" "$TMP_ROOT"
+
+echo "==> Welcome"
+node "$BIN" welcome
+
+echo
+echo "==> Vite React fixture"
+mkdir -p "$TMP_ROOT/vite-react-app"
+cp -R "$ROOT/fixtures/vite-react-app/." "$TMP_ROOT/vite-react-app/"
+git init "$TMP_ROOT/vite-react-app" >/dev/null 2>&1
+(cd "$TMP_ROOT/vite-react-app" && node "$BIN" --out "$OUT_DIR/demo-vite-react-app.md")
+
+echo
+echo "==> Risky secret fixture"
+mkdir -p "$TMP_ROOT/risky-secret-app"
+cp -R "$ROOT/fixtures/risky-secret-app/." "$TMP_ROOT/risky-secret-app/"
+git init "$TMP_ROOT/risky-secret-app" >/dev/null 2>&1
+(cd "$TMP_ROOT/risky-secret-app" && node "$BIN" secrets --out "$OUT_DIR/demo-risky-secret-app.md")
+
+echo
+echo "Evidence files:"
+echo "- $OUT_DIR/demo-vite-react-app.md"
+echo "- $OUT_DIR/demo-risky-secret-app.md"

package/src/cli.js

@@ -0,0 +1,254 @@
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import readline from 'node:readline/promises';
+import { runOrchestrator } from './orchestrator.js';
+import { runRepo } from './commands/repo.js';
+import { runQuality } from './commands/quality.js';
+import { runRoutes } from './commands/routes.js';
+import { runSecrets } from './commands/secrets.js';
+import { runSupabase } from './commands/supabase.js';
+import { runCloudflare } from './commands/cloudflare.js';
+import { runLocal } from './commands/local.js';
+import { runEvidence } from './commands/evidence.js';
+import { runProbes } from './commands/probes.js';
+import { resultToMarkdown } from './lib/markdown.js';
+import { writeFileSafe } from './lib/fs.js';
+import { redactObject } from './lib/redact.js';
+import { exitCodeFor } from './lib/result.js';
+
+const COMMANDS = new Set(['repo', 'quality', 'routes', 'secrets', 'supabase', 'cloudflare', 'local', 'evidence', 'probes', 'welcome', 'init']);
+function take(args, index) { return args[index + 1]; }
+export function parseArgs(argv) {
+  const options = { skip: [], only: [], port: [], protectedTable: [], include: [] };
+  let command = null;
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('-') && !command && COMMANDS.has(arg)) { command = arg; continue; }
+    if (arg === '--help' || arg === '-h') options.help = true;
+    if (arg === '--json') options.json = true;
+    else if (arg === '--out') options.out = take(argv, i++);
+    else if (arg === '--base-url') options.baseUrl = take(argv, i++);
+    else if (arg === '--routes') options.routesFile = take(argv, i++);
+    else if (arg === '--port') options.port.push(take(argv, i++));
+    else if (arg === '--health') { options.health = take(argv, i++); options.healthProvided = true; }
+    else if (arg === '--skip') options.skip.push(take(argv, i++));
+    else if (arg === '--only') options.only.push(take(argv, i++));
+    else if (arg === '--yes' || arg === '-y') options.yes = true;
+    else if (arg === '--strict') options.strict = true;
+    else if (arg === '--continue') options.continueOnFailure = true;
+    else if (arg === '--protected-table') options.protectedTable.push(take(argv, i++));
+    else if (arg === '--frontend-dir') options.frontendDir = take(argv, i++);
+    else if (arg === '--migrations-dir') options.migrationsDir = take(argv, i++);
+    else if (arg === '--url') options.url = take(argv, i++);
+    else if (arg === '--title') options.title = take(argv, i++);
+    else if (arg === '--phase') options.phase = take(argv, i++);
+    else if (arg === '--include') options.include.push(take(argv, i++));
+    else if (arg === '--process') options.process = take(argv, i++);
+    else if (arg === '--service') options.service = take(argv, i++);
+    else if (arg === '--script') { options.scripts ||= []; options.scripts.push(take(argv, i++)); }
+  }
+  if (!options.protectedTable.length) delete options.protectedTable;
+  return { command, options };
+}
+async function dispatch(command, options) {
+  if (command === 'welcome') return welcomeText();
+  if (command === 'init') return runInit(options);
+  if (!command) return runOrchestrator(options);
+  if (command === 'repo') return runRepo(options);
+  if (command === 'quality') return runQuality(options);
+  if (command === 'routes') return runRoutes(options);
+  if (command === 'secrets') return runSecrets(options);
+  if (command === 'supabase') return runSupabase(options);
+  if (command === 'cloudflare') return runCloudflare(options);
+  if (command === 'local') return runLocal(options);
+  if (command === 'evidence') return runEvidence(options);
+  if (command === 'probes') return runProbes(options);
+  throw new Error('Unknown command: ' + command);
+}
+
+function writeStdout(text) {
+  return new Promise((resolve) => {
+    process.stdout.write(text, resolve);
+  });
+}
+
+const ASCII_HEADER = `   ____        _______          __  __
+  / __ \\____  / ____(_)___  ____/ /_/ /
+ / / / / __ \\/ /_  / / __ \\/ __  / __/
+/ /_/ / /_/ / __/ / / / / / /_/ / /_
+\\____/ .___/_/   /_/_/ /_/\\__,_/\\__/
+    /_/
+
+Operational truth checks for AI-assisted engineering.
+`;
+
+function helpText(command) {
+  const common = [
+    ASCII_HEADER,
+    'Usage:',
+    '  opstruth [--strict] [--json] [--out file]',
+    '  opstruth <command> [options]',
+    '',
+    'Commands:',
+    '  welcome      Explain what opstruth is and how to use it',
+    '  init         Create opstruth.config.json after confirmation',
+    '  repo         Inspect git/repo/stack facts',
+    '  quality      Run safe package quality scripts that exist',
+    '  routes       Probe configured HTTP routes with HEAD/GET',
+    '  secrets      Scan source for risky references with redaction',
+    '  supabase     Static Supabase safety checks',
+    '  cloudflare   Static Cloudflare/Wrangler checks',
+    '  local        Check explicit local ports/processes/services',
+    '  evidence     Write a markdown evidence pack',
+    '  probes       Inspect the stack-aware probe catalogue',
+    '',
+    'Global options:',
+    '  --strict            Treat warnings/skips as failing confidence',
+    '  --json              Print JSON output',
+    '  --out <file>        Write command output/evidence',
+    '  --skip <area|id>    Skip a command or probe area',
+    '  --only <area|id>    Select a probe area or id',
+    '  -h, --help          Print help and exit 0'
+  ];
+  const route = [
+    ASCII_HEADER,
+    'Usage: opstruth routes --base-url <url> [--routes file] [--strict]',
+    '',
+    'Read-only route probes collect URL, method, status, latency, redirects, and security-header evidence.',
+    '',
+    'Options:',
+    '  --base-url <url>    Base URL to probe',
+    '  --routes <file>     JSON route config',
+    '  --json              Print JSON output',
+    '  -h, --help          Print help and exit 0'
+  ];
+  const repo = [
+    ASCII_HEADER,
+    'Usage: opstruth repo [--json] [--strict]',
+    '',
+    'Read-only repository inspection reports cwd, git root, branch, latest commit, dirty files, and detected stack.',
+    '',
+    'Options:',
+    '  --json              Print JSON output',
+    '  -h, --help          Print help and exit 0'
+  ];
+  if (command === 'routes') return route.join('\n') + '\n';
+  if (command === 'repo') return repo.join('\n') + '\n';
+  return common.join('\n') + '\n';
+}
+
+function welcomeText() {
+  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.',
+    '',
+    'Common workflows:',
+    '- opstruth',
+    '- opstruth --strict',
+    '- opstruth routes --base-url https://example.com',
+    '- opstruth local --port 3000 --health /health',
+    '- opstruth evidence --title "Release proof"',
+    '',
+    'Safety philosophy:',
+    'opstruth prefers skipped or not verified over pretending something is safe. Dangerous actions require explicit approval and are not part of the default run.',
+    ''
+  ].join('\n');
+}
+
+const INIT_CONFIG = {
+  routes: {
+    baseUrl: '',
+    paths: ['/', '/login', '/healthz'],
+    requiredHeaders: [
+      'content-security-policy',
+      'strict-transport-security',
+      'x-frame-options',
+      'referrer-policy'
+    ]
+  },
+  local: {
+    ports: [],
+    healthPath: '/health'
+  },
+  supabase: {
+    protectedTables: [
+      'agent_jobs',
+      'platform_credentials',
+      'worker_logs'
+    ]
+  },
+  ignore: [
+    '.cache',
+    '.agents',
+    'node_modules',
+    'dist',
+    'build'
+  ]
+};
+
+async function readStdin() {
+  if (process.stdin.isTTY) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      return await rl.question('');
+    } finally {
+      rl.close();
+    }
+  }
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => resolve(input));
+  });
+}
+
+async function runInit(options) {
+  const cwd = options.cwd || process.cwd();
+  const outPath = path.join(cwd, 'opstruth.config.json');
+  try {
+    await readFile(outPath, 'utf8');
+    return 'opstruth.config.json already exists. No changes made.\n';
+  } catch {
+    // Continue when the file is absent.
+  }
+  if (!options.yes) {
+    process.stdout.write('Create opstruth.config.json in this directory? Type yes to continue: ');
+    const answer = (await readStdin()).trim().toLowerCase();
+    if (answer !== 'yes') return 'No changes made.\n';
+  }
+  await writeFileSafe(outPath, JSON.stringify(INIT_CONFIG, null, 2) + '\n');
+  return 'Created opstruth.config.json\n';
+}
+
+export async function runCli(argv, cwd = process.cwd()) {
+  const { command, options } = parseArgs(argv);
+  options.cwd = cwd;
+  if (options.help) {
+    await writeStdout(helpText(command));
+    process.exitCode = 0;
+    return;
+  }
+  const result = await dispatch(command, options);
+  if (typeof result === 'string') {
+    await writeStdout(result);
+    process.exitCode = 0;
+    return;
+  }
+  const output = options.json ? JSON.stringify(redactObject(result), null, 2) + '\n' : resultToMarkdown(result);
+  if (options.out && command) {
+    const outPath = path.isAbsolute(options.out) ? options.out : path.join(cwd, options.out);
+    await writeFileSafe(outPath, output);
+  }
+  await writeStdout(output);
+  process.exitCode = exitCodeFor(result, { strict: options.strict });
+}