@merittdev/horus 0.23.0 → 0.24.1

package/README.md

@@ -1,377 +1,87 @@
-<p align="center">
-  <img src="https://meritt-dev-assets.s3.eu-central-1.amazonaws.com/public/horus-logo-dark-20260614171147.svg" width="72" alt="Horus" />
-</p>
-
 # Horus
 
-**Understand what happened.**
-
-Open-source incident investigation. Horus connects Elasticsearch, Sentry, Grafana, MongoDB, Postgres, Redis (incl. BullMQ queues), Axiom logs, Shopify Admin, Azure Monitor, CloudWatch Logs, Google Cloud Logging, Prometheus, Azure Service Bus, Kafka, Firestore, SQL Server, and source intelligence into deterministic reports — installable today.
-
-CLI-only. Read-only against production systems. Horus never writes to your infrastructure.
-
-**Website:** [horus.sh](https://horus.sh) · **Source:** [github.com/meritt-dev/horus](https://github.com/meritt-dev/horus)
-
-```bash
-curl -fsSL https://horus.sh/install.sh | bash
-npm install -g @merittdev/horus
-brew install meritt-dev/tap/horus
-```
-
-Homebrew tap is live through meritt-dev/tap.
-
----
-
-## What Horus does
-
-Horus reads from your existing systems and reconstructs the incident through evidence, correlation, and ranked hypotheses.
-
-It does not dump thousands of logs. It connects runtime signals to source context and returns a **deterministic report** — suspected causes (ranked), hypotheses, evidence, gaps, and next actions. Evidence before inference. Optional `--ai` adds an Anthropic narrative on top.
-
-Every incident leaves evidence.
-
-## What Horus is not
-
-| | |
-|---|---|
-| **Monitoring** | Detects problems |
-| **Observability** | Shows signals |
-| **Horus** | Reconstructs what happened |
-
-Horus is not another dashboard, alerting tool, or log viewer. It sits on top of the systems you already use.
-
-> Monitoring detects. Observability shows. Horus reconstructs.
-
-## Getting started
-
-```bash
-horus init
-horus connect elasticsearch   # optional runtime connectors
-horus investigate "checkout latency spike"
-horus investigations          # list saved IDs
-horus replay <id>
-horus postmortem <id>
-```
-
-Horus source intelligence requires a local code-graph host (the curl installer attempts to install it). Postgres is required for the audit store.
-
-## How it works
-
-**Evidence in. Explanation out.**
-
-| Runtime + Source | Investigation Engine | Investigation Report |
-|---|---|---|
-| Elasticsearch · Axiom logs · Sentry errors | Correlation | Suspected causes (ranked) |
-| Grafana metrics | Timeline | Hypotheses + confidence |
-| MongoDB · Postgres · Redis state | Cause ranking | Evidence + gaps |
-| BullMQ queue runtime | | Next actions |
-| Source graph + git | | |
-
-Pipeline: **Evidence → Correlation → Hypotheses → Timeline → Report**
-
-## Sources Horus investigates
-
-Elasticsearch · Sentry · Grafana · MongoDB · Postgres · Redis · BullMQ · Axiom · Git changes · Source graph · Queue map · Ownership
-
-[Set up the eight new connectors](docs/connectors.md): cloud logs, direct Prometheus, broker snapshots, Firestore and SQL Server.
-
-Trace reconstruction is not shipped yet. Connectors are read-only and project-scoped.
-
-## Example output (illustrative)
-
-```bash
-cd ~/code/atlas-payments
-horus investigate --env production "checkout latency spike"
-```
-
-```text
-# Investigation inv-347
-Hint: checkout latency spike
-
-## Suspected causes (ranked)
-1. [0.82 / high] Redis connection pool exhaustion [↑ queue]
-
-## Hypotheses
-  [supported] [0.78] queue: backlog growth preceded latency spike
-
-## Evidence gaps
-  - queue runtime state: worker heartbeat unavailable
-
-## Evidence
-- ev-01 [elasticsearch/error] Request timeout increase
-- ev-04 [bullmq/queue] checkout-jobs backlog growth
-
-## Next actions
-- Inspect worker concurrency changes in deploy #784
-```
-
-## Principles
-
-**Read-only** — Horus never writes to your production systems.
-
-**Deterministic first** — The engine is deterministic; optional `--ai` adds an Anthropic narrative.
-
-**Local-first** — Connectors read from your own clusters, not a hosted black box.
-
-**Project-scoped** — The repo you run in (its `.horus/config.json`) is the project identity; `--config <path>` targets another repo.
-
-**Agent-ready** — Every investigation/analysis command takes `--json` (compact by default, `--full` for the raw structure) with a `nextSteps` array to chain from. `horus packet` builds a compact, honesty-framed briefing sized for an agent's context window.
-
-## Capabilities
-
-Installable today. More connectors and AI providers are in progress.
-
-**Today**
-
-- Elasticsearch logs
-- Axiom logs
-- Sentry errors
-- Grafana metrics
-- MongoDB / Postgres / Redis state
-- BullMQ queue evidence
-- Shopify Admin (GraphQL — queries you supply)
-- Source intelligence (code graph)
-- Timeline generation
-- Evidence correlation
-- Investigation replay
-- Postmortem drafts
-
-**Coming next**
+[Horus](https://horus.sh), the incident-investigation CLI. From 0.24.0 this Rust implementation **is** `horus`: the npm package `@merittdev/horus`, the Homebrew formula `horus` and the GitHub release binaries all ship it.
+It traces a production symptom through the code (via the source-intelligence backend) and your runtime systems:
+- logs
+- metrics
+- queues
+- databases
+- error trackers
+- Horus Cloud memory
 
-- Kubernetes evidence
-- Distributed trace reconstruction
-- Slack evidence ingestion
-- Local AI provider execution
+It then ranks the likely causes and states its confidence plainly.
 
----
-
-## Architecture
-
-Horus is organized in four layers:
-
-**Source Intelligence**
-
-- Horus source intelligence backend (`packages/source-py`, ships inside the bundle) — code graph, semantic search, impact analysis, ownership across TypeScript/JavaScript, Python, Go, Java, and Rust (tree-sitter).
-
-**Runtime Evidence**
-
-- **Elasticsearch** — logs → synthesized error-signature evidence
-- **Axiom** — structured logs (APL) → synthesized error-signature evidence, same path as Elasticsearch
-- **Sentry** — grouped exceptions (issues) → same error-signature / direct-seed path as logs
-- **MongoDB / Postgres** — application/operational state
-- **Grafana** — metrics via its datasource proxy
-- **Redis / BullMQ** — cache & queue runtime state
-- **Shopify Admin** — application state via GraphQL queries you supply at investigation time (`--shopify-query`) or declare in config; the connector embeds none. Read-only, Client-Credentials auth.
-- **Git** — change history, ownership signals
-
-**Investigation** (deterministic)
-
-- **Queue Stitcher** — connects producer `queue.add(...)` to consumer `@Processor` handlers
-- **Timeline Engine** — orders evidence into a sequence of events
-- **Correlation Engine** — connects evidence across sources into incident threads
-
-**Presentation**
-
-- **Deterministic investigation report** — evidence, timeline, hypotheses, gap analysis, next actions
-- **Optional AI narrative** — a later layer on top of the deterministic report
-
-### Source intelligence is built into Horus
-
-**Source intelligence is the expected intelligence layer used by Horus** — not an optional integration. Semantic search, impact analysis, ownership signals, change detection, and the process graph live in the Horus source intelligence backend; Horus does not duplicate them.
-
-The **only** code-intelligence gap Horus owns is **queue-boundary stitching**: the source graph terminates around `queue.add(...)` and doesn't connect a producer to the consumer's `@Processor`. The stitcher synthesizes those producer → queue → worker edges.
-
-> If the Horus source intelligence backend is unavailable, Horus can still collect runtime evidence, but source context, impact analysis, change analysis, and queue stitching become degraded.
-
-Horus talks to the source intelligence backend over **HTTP/MCP only** (no CLI shell-outs for queries). Run `horus init` in a repository to start and register its source intelligence host.
-
-## Configuration
-
-The config model separates **code** from **runtime**:
-
-- **Code belongs to the project** — `repositories[]`, each served by its own source intelligence host.
-- **Runtime belongs to the environment** — `environments[].connectors` (Elasticsearch, Sentry, MongoDB, Postgres, Grafana, Redis/BullMQ, Axiom).
-
-```ts
-// config/horus.config.ts
-export default defineConfig({
-  projects: [
-    {
-      name: 'atlas-payments',
-      repositories: [
-        {
-          name: 'atlas-payments',
-          path: '/repos/atlas-payments',
-          source: { hostUrl: 'http://127.0.0.1:8420' },
-        },
-      ],
-      environments: [
-        {
-          name: 'production',
-          readOnly: true,
-          connectors: {
-            elasticsearch: {
-              indexPattern: 'atlas-payments-prod-*',
-              serviceName: 'atlas-payments-prod',
-            },
-            mongodb: {
-              database: 'atlas_payments_prod',
-              collections: ['orders', 'payments', 'workers'],
-            },
-            grafana: {},
-          },
-        },
-      ],
-    },
-  ],
-});
-```
-
-Local persistence is **embedded** (a bundled pglite database at `~/.horus/horus.db`) — no database to run or configure. Teams that need shared state use **Horus Cloud** (an API mirror), not a self-run Postgres.
-
-**No connector runs without an explicit project/env scope** — there are no global connector defaults.
-
-**Secrets are never committed.** `horus connect` encrypts connector credentials at rest into `.horus/secrets.local.json` (AES-256-GCM, never `config.json`) and auto-adds `.horus/` to `.gitignore`; environment variables are also supported at runtime. For the full secrets and gitignore model, see **[horus.sh/docs/security](https://horus.sh/docs/security)**.
+It is a command-for-command port of the TypeScript `horus` 0.23.0 ([Meritt-dev/horus](https://github.com/Meritt-dev/horus)): same commands, flags, help text, output and exit codes, now as a single native binary.
 
 ## Install
 
-See **[horus.sh/docs/installation](https://horus.sh/docs/installation)** for full install, update, and uninstall instructions.
-
-```bash
-curl -fsSL https://horus.sh/install.sh | bash
-npm install -g @merittdev/horus
-brew install meritt-dev/tap/horus
-horus --version
-horus init
+```sh
+npm i -g @merittdev/horus                       # npm (macOS / Linux, arm64 / x64)
+brew install meritt-dev/tap/horus               # Homebrew
+curl --proto '=https' --tlsv1.2 -LsSf \
+  https://github.com/Meritt-dev/horus-rust/releases/latest/download/horus-cli-installer.sh | sh
+horus update --force                            # after the curl installer: installs the bundled backend
 ```
 
-The curl installer downloads the Horus CLI from GitHub Releases and installs the source intelligence backend from the wheel **bundled in the same release** — one bundle, one version, nothing on PyPI. All three channels ship the same `horus` binary with the backend wheel alongside it; `horus init` installs the backend automatically when it's missing.
+The npm and Homebrew packages bundle the matching source-intelligence backend wheel. `horus init` installs it with [uv](https://docs.astral.sh/uv/).
 
-### What the installer installs
+## Upgrading from the TypeScript horus (≤ 0.23.0)
 
-| Component | Role | Required |
-| --- | --- | --- |
-| **Horus CLI** | The `horus` command | Yes |
-| **Horus source intelligence backend** | Enables `horus init`, `horus explain`, `horus changes`, `horus architecture` | Optional |
+- **npm:** `npm i -g @merittdev/horus@latest` (or `horus update`) replaces the TS build with this one. Node is still required for npm itself, not for Horus.
+- **Homebrew:** `brew upgrade horus`. The formula no longer depends on `node`.
+- **Config and secrets** in `~/.horus` and `.horus/config.json` are read as-is.
+- **Local history.** The TS CLI kept investigations and memory in a PGlite store at `~/.horus/horus.db`. This build uses SQLite at `~/.horus/horus-rust.db`. Copy the history over once (needs `node`/`npx`; the TS store is only read):
 
-### Prerequisites
+  ```sh
+  horus db migrate-from-ts
+  ```
 
-| Requirement | Role |
-| --- | --- |
-| Node.js 22+ | Horus CLI runtime (the installed binary needs Node.js) |
-| Python 3.11+ + uv/pip | Required only for the Horus source intelligence backend |
+  Until you do, `horus` prints a one-line reminder while the new store is empty. Re-running the migration is safe.
 
-The investigation audit store is **embedded** (bundled pglite, zero setup) — there is no Postgres to install. Teams that need shared state use **Horus Cloud**.
+## Use
 
-The installer **does not** configure Elasticsearch, MongoDB, Grafana, Redis, or any production system. Runtime connectors are added per-project after install via `horus connect`.
-
-### Direct download (without the curl installer)
-
-```bash
-# Replace vX.Y.Z with the current release tag (see github.com/meritt-dev/horus/releases)
-curl -fsSL https://github.com/meritt-dev/horus/releases/download/vX.Y.Z/horus-vX.Y.Z -o horus
-chmod +x horus
-sudo mv horus /usr/local/bin/horus
-horus --version
-```
-
-To **update** to a newer version, re-run the installer — it overwrites the binary and leaves your config untouched. To **uninstall**, see **[horus.sh/docs/installation#uninstall](https://horus.sh/docs/installation#uninstall)**.
-
-If something goes wrong after install, run `horus doctor` and see **[horus.sh/docs/installation#troubleshooting](https://horus.sh/docs/installation#troubleshooting)**.
-
-## Local development
-
-```bash
-pnpm install
-pnpm build                            # builds apps/horus/dist/index.cjs
-
-# Per repository: start the source intelligence host and stitch queue boundaries
-horus init
-
-source ~/.horus.env
-
-node apps/horus/dist/index.cjs status
-```
-
-**Verify the full v0.1 user path (init → investigate → replay → postmortem):**
-
-```bash
-# No-services startup check (version, help, doctor):
-./scripts/smoke-test.sh apps/horus/dist/index.cjs
-
-# Full end-to-end flow (uses the embedded pglite store — no services to start):
-./scripts/e2e-smoke.sh apps/horus/dist/index.cjs
-```
-
-```bash
-horus --help
-horus help <command>
-horus investigate --help
+```sh
+cd your-service
+horus init                       # index the repo, start the source host, write .horus/config.json
+horus connect elasticsearch …    # add runtime connectors (see `horus connect --help`)
+horus doctor
+horus investigate "checkout requests timing out since the last deploy"
 ```
 
-### Core commands
-
-| Command | What it does |
-| --- | --- |
-| `horus status [--env]` | Per-project/env connector-health matrix |
-| `horus connect <type>` | Add/update a runtime connector — `elasticsearch` / `mongodb` / `postgres` / `sentry` / `axiom` / `grafana` / `redis` (plus `ai` to configure an AI provider) |
-| `horus init [--env <e>]` | Set up the current repo: config, source-intelligence host, index, queue map |
-| `horus hosts [--reap]` | List source-intelligence hosts and live status; `--reap` stops orphaned hosts |
-| `horus stop [--all]` | Stop this repo's source-intelligence host (`--all` stops every host) |
-| `horus investigate --env <e> "<hint>"` | Full deterministic investigation report (`--format json` for agents) |
-| `horus packet <hint\|savedId> [--for claude] [--json]` | Compact, honesty-framed briefing for a coding-agent context window |
-| `horus logs [service] --env <e>` | Error-signature evidence (`--raw` for lines) |
-| `horus state --env <e>` | MongoDB application-state evidence (read-only) |
-| `horus metrics [hint] --env <e>` | Grafana metrics evidence |
-| `horus queues [name] [--live]` | Queue topology from source intelligence; `--live` reads real-time Redis/BullMQ state |
-| `horus search <query>` · `explain <symbol>` · `blast-radius` · `architecture` · `what-changed` | Source-aware code intelligence — one canonical resolver, so a query resolves to the same symbol across commands (qualified `Class.method` supported) |
-| `horus memory <show\|add\|list\|link\|...>` | Inspect/author deterministic incident memory; `memory link` adds `supersedes` / `contradicts` / `recurs-with` edges |
-| `horus feedback <id> [--resolved] [--note] [--cause]` | Record outcome feedback on an investigation (improves Horus) |
-| `horus report [hint] [--title --body --labels]` | File a Horus bug or capability gap — opens a pre-filled GitHub issue (no auth, nothing sent automatically) |
-
-## Local project workflow (git-style)
+`horus --help` lists every command.
 
-A repo carries a `.horus/config.json` (discovered by walking up from the working directory, like `.git`) — the repo's config IS the project identity. Work from inside the repo, or pass `--config <path>` to target another repo explicitly.
+## How it compares to the TypeScript CLI
 
-```bash
-cd /repos/atlas-payments
-horus init
+We ran side-by-side benchmarks against 12 real repositories ([docs/BENCHMARK.md](docs/BENCHMARK.md)):
+- **Startup:** 5 ms vs 158 ms cold start.
+- **Memory:** 10 MB vs 153 MB idle; 140–175 MB vs about 1 GB for a full investigation.
+- **Speed:** 2.5–11.8× faster per project.
+- **Output parity:** 98–100% mean match.
 
-horus investigate "checkout latency spike"
-horus investigate --config /repos/atlas-payments/.horus/config.json "checkout latency spike"   # from anywhere
-horus projects   # list registered repos (informational)
-```
-
-`horus init` reuses an already-running source intelligence host when one is healthy. Runtime connectors are added to the env block of `.horus/config.json` afterwards.
-
-## For coding agents
+The intended differences are listed in [DIVERGENCES.md](DIVERGENCES.md). The main ones:
+- **Local database.** History lives in `~/.horus/horus-rust.db` (SQLite), not the TS CLI's PGlite `~/.horus/horus.db`; `horus db migrate-from-ts` copies it over. Horus Cloud memory syncs into both.
+- **JS/TS config files.** `horus.config.{js,ts}` is loaded through an installed `node`. `.horus/config.json` needs nothing extra.
+- **Cloud writes switch.** `HORUS_RUST_CLOUD_WRITE=0` keeps a run local: no Cloud writes and no telemetry.
 
-Horus is built to be an agent's evidence layer. Install a skill that teaches your agent to reach for Horus before guessing:
+## Build from source
 
-```bash
-horus skill install claude    # .claude/skills/horus/SKILL.md  (also: codex · gemini · cursor · generic)
-horus mcp                     # expose the local knowledge index to agents over MCP (stdio)
+```sh
+HORUS_VERSION=0.24.1 cargo build --release -p horus-cli   # → target/release/horus
 ```
 
-Every investigation/analysis command takes `--json` (`--format json` for `investigate`/`replay`) — compact by default, `--full` for the raw structure — and each result carries a deterministic `nextSteps` array. `horus packet "<hint>" --json` returns a compact briefing sized for a context window.
+Cross-platform release builds are covered in [PORTING.md](PORTING.md), and cutting a release in [docs/RELEASE.md](docs/RELEASE.md).
 
-## Layout
-
-```
-packages/
-  core/         evidence model, config schema + project/env resolution, version pins
-  connectors/   provider contracts + source intelligence (HTTP/MCP) · Elasticsearch · Sentry · Axiom · Grafana · MongoDB · Postgres · Redis · BullMQ · application-state · Git
-  stitcher/     queue-boundary stitcher
-  db/           Drizzle schema + migrations (plain Postgres, no pgvector)
-  engine/       deterministic investigation pipeline (timeline, correlation, hypotheses, gaps)
-  cli/          commander CLI
-apps/horus/     composition root (bundled bin)
-config/         horus.config.ts
-```
+The workspace mirrors the TS monorepo crate-for-package:
+- `core`
+- `connectors`
+- `db`
+- `stitcher`
+- `engine`
+- `ai`
+- `knowledge`
+- `eval`
+- `cli`
 
-## Foundation
+## License
 
-- TypeScript monorepo (pnpm + Turborepo)
-- Postgres + Drizzle — semantic search delegated to source intelligence backend
-- Built-in **Horus source intelligence backend**, over HTTP/MCP only
-- Project/environment-scoped connectors; read-only against production
+MIT

package/bin/horus.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Launcher for the native Horus binary (esbuild/biome pattern). npm installs exactly one
+// platform package through optionalDependencies; this shim runs its `bin/horus`, inheriting
+// stdio and forwarding signals and the exit status. No postinstall, no download.
+'use strict';
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const launcher = require('../package.json').name;
+const pkg = `${launcher}-${process.platform}-${process.arch}`;
+
+let binary;
+try {
+  binary = path.join(path.dirname(require.resolve(`${pkg}/package.json`)), 'bin', 'horus');
+} catch {
+  const supported = Object.keys(require('../package.json').optionalDependencies || {}).join(', ');
+  console.error(
+    `horus: no native binary for ${process.platform}-${process.arch} (expected the optional package ${pkg}).\n` +
+      `Supported: ${supported}.\n` +
+      'If you installed with --omit=optional or --no-optional, reinstall without it.',
+  );
+  process.exit(1);
+}
+
+// Some npm versions drop the executable bit from non-`bin` files.
+try {
+  fs.accessSync(binary, fs.constants.X_OK);
+} catch {
+  fs.chmodSync(binary, 0o755);
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' });
+const forward = (signal) => child.kill(signal);
+const signals = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT'];
+for (const s of signals) process.on(s, forward);
+child.on('error', (err) => {
+  console.error(`horus: failed to start ${binary}: ${err.message}`);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  for (const s of signals) process.off(s, forward);
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 1);
+});

package/package.json

@@ -1,39 +1,8 @@
 {
   "name": "@merittdev/horus",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "Local-first, source-aware production-incident investigation engine",
-  "type": "module",
-  "bin": {
-    "horus": "./dist/index.cjs"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "test": "tsup && vitest run --passWithNoTests",
-    "prepublishOnly": "tsup",
-    "prepack": "cp ../../README.md README.md"
-  },
-  "engines": {
-    "node": ">=22"
-  },
-  "devDependencies": {
-    "@electric-sql/pglite": "^0.5.3",
-    "@horus/ai": "workspace:*",
-    "@horus/cli": "workspace:*",
-    "@horus/connectors": "workspace:*",
-    "@horus/core": "workspace:*",
-    "@horus/db": "workspace:*",
-    "@horus/engine": "workspace:*",
-    "@horus/eval": "workspace:*",
-    "@horus/stitcher": "workspace:*",
-    "@types/node": "^22.10.2",
-    "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
-  },
+  "license": "MIT",
   "keywords": [
     "incident-investigation",
     "observability",
@@ -41,19 +10,29 @@
     "debugging",
     "cli"
   ],
-  "license": "MIT",
-  "author": {
-    "name": "Meritt Dev",
-    "url": "https://horus.sh"
-  },
+  "homepage": "https://horus.sh",
   "repository": {
     "type": "git",
-    "url": "https://github.com/meritt-dev/horus"
+    "url": "https://github.com/Meritt-dev/horus-rust"
   },
   "bugs": {
-    "url": "https://github.com/meritt-dev/horus/issues"
+    "url": "https://github.com/Meritt-dev/horus-rust/issues"
+  },
+  "bin": {
+    "horus": "bin/horus.js"
+  },
+  "files": [
+    "bin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@merittdev/horus-darwin-arm64": "0.24.1",
+    "@merittdev/horus-darwin-x64": "0.24.1",
+    "@merittdev/horus-linux-arm64": "0.24.1",
+    "@merittdev/horus-linux-x64": "0.24.1"
   },
-  "homepage": "https://horus.sh",
   "publishConfig": {
     "access": "public"
   }