thuban 0.3.1 → 0.3.3

package/README.md

@@ -1,150 +1,185 @@
-# Thuban — Code Health Engine
+# Thuban
 
-**The safety layer for AI-coded software.**
+Thuban is an independent AI software assurance platform for pull requests, releases, and codebase trust. It combines codebase intelligence, scanner-driven risk detection, and Forge-style verification so teams can decide whether AI-assisted changes are safe to merge.
 
-Scan your codebase for hallucinated APIs, ghost code, architecture drift, and tech debt. Fix what can be fixed automatically. One command. Zero dependencies. Zero config.
+## Product wedge
 
-```bash
-npx thuban scan .
+Thuban is built around a PR assurance wedge:
+
+- connect a GitHub repository through a future GitHub App
+- analyze changed files and architectural blast radius
+- run assurance checks and evidence collection
+- issue a clear verdict with remediation guidance
+
+This standalone extraction is based on the Thuban product strategy and the prior CODEX specifications inside `orion-main`.
+
+## Repository layout
+
+```text
+apps/
+  api/        Express placeholder API for ingestion, assurance, and attestations
+  web/        Next.js placeholder operator UI
+packages/
+  scanner/    Extracted Sentinel scanner and monitoring substrate
+  forge/      Extracted Forge verifier and verification data
+docs/
+  source/     Original CODEX and Orion intelligence specs
+  strategy/   Product strategy and viability docs
+  schema/     Thuban-only database schema extract
+  venture/    Original venture README source
 ```
 
----
+## What is real today
 
-## Why Thuban?
+- `packages/scanner/` contains extracted working Sentinel code from Orion
+- `packages/forge/forge-verifier.js` contains extracted Forge verification logic
+- `packages/forge/data/forge-verifications/` contains historical verification artifacts
+- `docs/` contains the original strategy, viability, and CODEX-era source materials
 
-AI coding tools (Copilot, Cursor, Claude, ChatGPT) generate code that **looks correct but isn't**. They invent API methods that don't exist. They paste helper functions nobody calls. They use deprecated patterns from their training data.
+## What is placeholder today
 
-Linters don't catch this. Code review misses it. Thuban was built specifically for it.
+- `apps/api/` is an Express starter aligned to the target product shape
+- `apps/web/` is a minimal Next.js starter for the future assurance dashboard
+- Postgres integration, GitHub App auth, webhook ingestion, PR check-runs, and production orchestration are planned but not yet implemented here
 
----
+See `ARCHITECTURE.md` for a clear real-vs-placeholder breakdown.
 
-## What It Does
+## Architecture overview
 
-| Command | What it does |
-|---------|-------------|
-| `thuban scan [path]` | Full codebase health scan with score (A-F) |
-| `thuban fix [path] --fix` | Auto-fix all fixable issues |
-| `thuban hallucinate [path]` | Detect AI hallucinated APIs |
-| `thuban gate` | Pre-commit hook — blocks hallucinated code in 3 seconds |
-| `thuban gate --fix` | Install the pre-commit gate |
-| `thuban cost [path]` | Tech debt cost calculator (hours + pounds) |
-| `thuban ghosts [path]` | Find dead functions never called |
-| `thuban ai-score [path]` | AI risk score per function (0-100%) |
-| `thuban clones [path]` | Copy-paste drift detection |
-| `thuban passport [path]` | Generate codebase identity file |
-| `thuban executive [path]` | CTO-ready PDF report |
-| `thuban dashboard [path]` | Visual HTML dashboard |
-| `thuban watch [path]` | Live sentinel monitoring |
-| `thuban diff [path]` | Scan only git-changed files |
-| `thuban drift [path]` | Detect annotation/purpose drift |
-| `thuban deps [path]` | Dependency graph + circular detection |
-| `thuban status` | Show license and usage info |
-| `thuban upgrade` | View pricing and subscribe |
-| `thuban activate [key]` | Activate a license key |
+### Apps
 
----
+- `apps/api`: future control plane and integration surface for repos, pull requests, audits, policies, and attestations
+- `apps/web`: future UI for onboarding repos, reviewing audit evidence, and tracking trust history
 
-## Quick Start
+### Packages
 
-### Scan your project
-```bash
-npx thuban scan .
-```
+- `packages/scanner`: repository scanning, dependency graphing, drift detection, health checks, alerting, and secret/credential exposure scanning for hardcoded API keys, passwords, secrets in source code, `.env` files not gitignored, database connection strings with passwords, private keys, high-entropy strings, and secrets still exposed in git history, and secret/credential exposure scanning for hardcoded API keys, passwords, secrets in source code, `.env` files not gitignored, database connection strings with passwords, private keys, high-entropy strings, and secrets still exposed in git history
+- `packages/forge`: attestation and verification workflow plus verification history
 
-### See what it costs you
-```bash
-npx thuban cost .
-```
+### Data
 
-### Find ghost code
-```bash
-npx thuban ghosts .
-```
+- Postgres is the intended system of record
+- the included schema extract in `docs/schema/ORION-ECOSYSTEM-SCHEMA.thuban.json` contains only the `thuban` tables from Orion
+- packaged JSON artifacts are historical examples, not the final persistence model
+
+## Getting started
+
+### Prerequisites
+
+- Node.js 20+
+- npm 10+
+- Postgres 15+ for future API work
+
+### Install
 
-### Block hallucinations on every commit
 ```bash
-npx thuban gate --fix
+npm install
 ```
 
-### Generate a CTO report
+### Run the placeholder apps
+
 ```bash
-npx thuban executive .
+npm run dev:api
+npm run dev:web
 ```
 
----
+### Explore the extracted code
 
-## Example Output
+- scanner entrypoint: `packages/scanner/index.js`
+- secret scan utility: `quickSecretScan([...files], { rootPath })` or `new SecretScanner({ rootPath }).scanAll()` with output including file path, line number, secret type, severity, and fix recommendation
+- forge verifier: `packages/forge/forge-verifier.js`
+- product strategy: `docs/strategy/THUBAN-PRODUCT-STRATEGY.md`
+- architecture notes: `ARCHITECTURE.md`
 
-```
-  THUBAN — Code Health Report
+## Thuban Pro recurring scans
 
-  Score: D+ (38/100)
+Thuban Pro adds scheduled recurring scans for local repositories with change detection, local history, and notification stubs.
 
-  CRITICAL: 3 Hallucinated APIs
-    src/api/payments.js:47
-      stripe.charges.createImmediate()
-      ^^^ This method does not exist in Stripe SDK.
+### What it does
 
-  GHOST CODE: 16 functions exist but are never called
-    407 wasted lines (1.9% of codebase)
+- stores monitor configuration per repo in `~/.thuban/monitor/config.json`
+- runs the existing scanner pipeline on a schedule
+- saves each run as JSON history in `~/.thuban/monitor/runs/<repo-id>/`
+- compares each run to the previous run to surface:
+  - new issues
+  - resolved issues
+  - issue-count trend
+  - hallucination / secret / tech-debt metric deltas
+- writes notification records to `~/.thuban/monitor/notifications.json`
+- gates monitor/history/trend commands to Pro and above
 
-  TECH DEBT COST:
-    Manual fix: 47 hours (£3,760 at £80/hr)
-    With Thuban: 4 hours
-    You save: £3,440 (91%)
+### Commands
 
-  Run: thuban fix . --fix
+```bash
+npx thuban monitor . --once
+npx thuban monitor . --frequency daily
+npx thuban monitor . --frequency weekly
+npx thuban monitor . --frequency custom --interval-ms 3600000
+npx thuban history .
+npx thuban trend .
 ```
 
----
+### Notification channels
+
+Current implementation supports:
+
+- `inbox` — local notification inbox persisted to disk
+- `console` — console alert via the existing alert manager
+- `email` — stubbed for future delivery integration
+- `webhook` — stubbed for future delivery integration
+
+Example:
+
+```bash
+npx thuban monitor . --once --notify inbox,console
+```
 
-## Features
+### How scheduling works
 
-- **AI Hallucination Detection** — finds phantom imports and invented APIs
-- **Pre-Commit Gate** — 3-second check blocks bad code before it enters your repo
-- **Ghost Code Detection** — finds functions that exist but are never called
-- **AI Risk Score** — per-function assessment of AI-generated code
-- **Tech Debt Cost Calculator** — translates debt into hours and pounds
-- **Copy-Paste Drift** — finds duplicated code drifting apart across files
-- **Codebase Passport** — one JSON file describing your entire project
-- **Mother Code DNA** — contextual annotations that make your codebase self-aware
-- **Executive Report** — board-ready HTML report (print to PDF)
-- **Auto-Fix** — one command fixes hundreds of issues automatically
-- **Live Sentinel** — real-time monitoring on file save
-- **Visual Dashboard** — HTML reports with score rings and category breakdowns
-- **GitHub CI Action** — grade every PR, block merges below threshold
+- `daily` = every 24 hours
+- `weekly` = every 7 days
+- `custom` = any interval via `--interval-ms`
+- `npx thuban monitor .` starts a foreground daemon-like process until stopped
+- `npx thuban monitor . --once` performs one scheduled-style run immediately and stores history
 
----
+### Diff detection
 
-## Pricing
+Each issue is fingerprinted from file, category, id, line, and message. Thuban compares the latest run against the previous run and records:
 
-| Tier | Price | What you get |
-|------|-------|-------------|
-| **Free** | £0 | 5 scans/month, 100 files, summary output |
-| **Pro** | £19/mo | Unlimited scans, full details, auto-fix, all features |
-| **Team** | £99/mo | 5 seats, CI Action, team reports |
-| **Enterprise** | Custom | Unlimited seats, self-hosted, SLA, SSO |
+- `added`: issues not seen in the previous run
+- `resolved`: issues that disappeared
+- `metricsDelta`: changes in issue count, hallucinations, secrets, and tech debt metrics
 
----
+This makes recurring scans useful for “what changed since yesterday?” rather than just “scan again.”
 
-## Requirements
+## Website deployment
 
-- Node.js 16+
-- Works on Windows, macOS, Linux
-- Zero npm dependencies — runs with just Node.js built-ins
+The public site at `https://thuban.dev` is deployed from the repository root `docs/` folder via GitHub Pages.
 
----
+- workflow: `.github/workflows/deploy-website.yml`
+- trigger: pushes to `main` that change `docs/**`, or manual `workflow_dispatch`
+- deploy artifact: the `docs/` directory uploaded directly to GitHub Pages
+- custom domain: `docs/CNAME`
 
-## How It Works
+Important deployment notes:
 
-Thuban runs entirely locally. Your code never leaves your machine. It uses static analysis, pattern matching, and heuristic detection — no API calls, no cloud, no telemetry.
+- `apps/web/` is a placeholder Next.js app and is not part of the live GitHub Pages deployment
+- there is currently no build/export pipeline from `apps/web/` into `docs/`
+- updating `apps/web/` alone will not change `thuban.dev`
+- to update the live site, edit the static files in `docs/` or add a future export step that writes static output into `docs/`
 
----
+Current practical workflow:
 
-## License
+1. make website content changes in `docs/`
+2. commit and push to `main`
+3. GitHub Actions runs `Deploy Website to GitHub Pages`
+4. GitHub Pages publishes the uploaded `docs/` artifact to `https://thuban.dev`
 
-Proprietary. Free tier available. See [thuban.dev](https://thuban.dev) for details.
+## Planned next steps
 
----
+1. implement GitHub App installation and webhook ingestion
+2. persist repos, analyses, issues, and fixes in Postgres
+3. convert Sentinel and Forge flows into API-driven services
+4. connect PR check-runs and release attestation exports
+5. build the dashboard for audit runs, verdicts, and trust history
 
-Built by [Silverwings](https://silverwingsbenefits.com)