thuban 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Silverwings Benefits Ltd
+
+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,150 @@
+# Thuban — Code Health Engine
+
+**The safety layer for AI-coded software.**
+
+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.
+
+```bash
+npx thuban scan .
+```
+
+---
+
+## Why Thuban?
+
+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.
+
+Linters don't catch this. Code review misses it. Thuban was built specifically for it.
+
+---
+
+## What It Does
+
+| 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 |
+
+---
+
+## Quick Start
+
+### Scan your project
+```bash
+npx thuban scan .
+```
+
+### See what it costs you
+```bash
+npx thuban cost .
+```
+
+### Find ghost code
+```bash
+npx thuban ghosts .
+```
+
+### Block hallucinations on every commit
+```bash
+npx thuban gate --fix
+```
+
+### Generate a CTO report
+```bash
+npx thuban executive .
+```
+
+---
+
+## Example Output
+
+```
+  THUBAN — Code Health Report
+
+  Score: D+ (38/100)
+
+  CRITICAL: 3 Hallucinated APIs
+    src/api/payments.js:47
+      stripe.charges.createImmediate()
+      ^^^ This method does not exist in Stripe SDK.
+
+  GHOST CODE: 16 functions exist but are never called
+    407 wasted lines (1.9% of codebase)
+
+  TECH DEBT COST:
+    Manual fix: 47 hours (£3,760 at £80/hr)
+    With Thuban: 4 hours
+    You save: £3,440 (91%)
+
+  Run: thuban fix . --fix
+```
+
+---
+
+## Features
+
+- **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
+
+---
+
+## Pricing
+
+| 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 |
+
+---
+
+## Requirements
+
+- Node.js 16+
+- Works on Windows, macOS, Linux
+- Zero npm dependencies — runs with just Node.js built-ins
+
+---
+
+## How It Works
+
+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.
+
+---
+
+## License
+
+Proprietary. Free tier available. See [thuban.dev](https://thuban.dev) for details.
+
+---
+
+Built by [Silverwings](https://silverwingsbenefits.com)