@merittdev/horus 0.24.4 → 0.24.6

package/README.md

@@ -1,92 +1,205 @@
+<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
 
-[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
-- past incidents in local memory (synced with Horus Cloud when the repo is linked)
+**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.
+
+Horus is a single native CLI binary, and it only reads from production.
+
+[horus.sh](https://horus.sh) · [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
+```
+
+---
+
+## What Horus does
+
+Horus reads from the systems you already run and rebuilds the incident from what they recorded.
+
+Instead of a page of raw logs, you get a **deterministic report** that links runtime signals to the code behind them. It lists suspected causes (ranked), hypotheses, evidence, gaps, and next actions. Optional `--ai` adds an Anthropic narrative on top, written from that evidence.
+
+Horus sits on top of the monitoring and observability tools you already run. They detect problems and show signals. Horus reads from them and works out what happened.
+
+## Getting started
+
+```bash
+cd your-service
+horus init                    # index the repo, start the source host, write .horus/config.json
+horus connect elasticsearch   # optional runtime connectors (see `horus connect --help`)
+horus doctor
+horus investigate "checkout latency spike"
+horus investigations          # list saved IDs
+horus replay <id>
+horus postmortem <id>
+```
+
+`horus --help` lists every command.
+
+## How it works
+
+| Runtime and source | Investigation engine | Report |
+|---|---|---|
+| Elasticsearch · Axiom · cloud logs · Sentry errors | Correlation | Suspected causes (ranked) |
+| Grafana · Prometheus metrics | Timeline | Hypotheses + confidence |
+| MongoDB · Postgres · SQL Server · Firestore · Redis state | Cause ranking | Evidence + gaps |
+| BullMQ · Kafka · Azure Service Bus queues | | Next actions |
+| Source graph + git | | |
+
+Pipeline: **Evidence → Correlation → Hypotheses → Timeline → Report**
+
+## 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
+
+Horus only reads. It never writes to your production systems.
+
+The engine is deterministic. The same evidence gives the same report, and `--ai` only adds a narrative on top.
+
+Connectors read straight from your own clusters. Investigations and incident memory stay in a local SQLite store (`~/.horus/horus-rust.db`) and sync with Horus Cloud when the repo is linked.
+
+The repo you run in is the project. Its `.horus/config.json` holds the config, and `--config <path>` points Horus at another repo.
+
+Every investigation and analysis command takes `--json` (compact by default, `--full` for the raw structure). Each result carries a `nextSteps` array that an agent can follow.
+
+## Core commands
+
+| Command | What it does |
+| --- | --- |
+| `horus init [--env <e>]` | Set up the current repo: config, source-intelligence host, index, queue map |
+| `horus connect <type>` | Add or update a runtime connector (`horus connect --help` lists the types), or `ai` for an AI provider |
+| `horus status [--env]` | Per-project/env connector-health matrix |
+| `horus doctor` | Check local readiness: CLI version, git root, `.horus` config, source-intelligence setup |
+| `horus investigate --env <e> "<hint>"` | Full deterministic investigation report |
+| `horus packet <hint\|savedId> [--for claude] [--json]` | Short briefing sized for a coding agent's context window, with confidence stated plainly |
+| `horus logs` · `state` · `metrics` · `queues [--live]` | Single-source evidence: error signatures, application state, metrics, queue topology and live depths |
+| `horus search` · `explain` · `blast-radius` · `architecture` · `what-changed` · `changes` | Source-aware code intelligence |
+| `horus memory <show\|add\|list\|link\|...>` | Inspect and author incident memory |
+| `horus feedback <id> [--resolved] [--note] [--cause]` | Record the outcome of an investigation |
+| `horus hosts [--reap]` · `horus stop [--all]` | List or stop source-intelligence hosts |
+| `horus report` | File a Horus bug or capability gap as a pre-filled GitHub issue (nothing is sent automatically) |
+| `horus update` | Update Horus (through npm or Homebrew when installed that way) |
+
+## For coding agents
+
+Coding agents can call Horus for evidence before they guess at a cause. Install a skill that tells your agent when to use it, or expose the knowledge index over MCP:
+
+```bash
+horus skill install claude    # also: codex · gemini · cursor · generic
+horus mcp                     # expose the local knowledge index to agents over MCP (stdio)
+```
+
+## Configuration
+
+Config keeps code and runtime apart. Code belongs to the project: `repositories[]`, each served by its own source-intelligence host. Runtime belongs to the environment: `environments[].connectors`, scoped per project and environment, with no global connector defaults.
 
-It then ranks the likely causes and states its confidence plainly.
+A repo carries `.horus/config.json`, discovered by walking up from the working directory like `.git`. `horus.config.{js,ts}` files are also supported and are loaded through an installed `node`.
 
-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.
+Secrets stay out of git. `horus connect` encrypts connector credentials into `.horus/secrets.local.json` (never `config.json`) and adds `.horus/` to `.gitignore`. Environment variables also work at runtime. See [horus.sh/docs/security](https://horus.sh/docs/security).
 
-New in 0.24.3:
-- **Hybrid startup recall.** An investigation opens with matching past incidents, scored by exact code-shaped terms plus local embedding similarity against every hint an incident was seen under. `HORUS_STARTUP_RECALL=off` disables it.
-- **Past incidents in this code.** `horus changes` and `horus what-changed` list earlier investigations whose top code seeds (a method or function behind a cause rated likely or highly likely) the change modifies or removes (`relatedIncidents` in JSON). Context, not a gate.
-- **IncidentBench**, an open benchmark for startup recall: [docs/incident-bench.md](docs/incident-bench.md).
-- Investigations record the calling agent session from `HORUS_AGENT_SESSION` or `CLAUDE_CODE_SESSION_ID`.
+## Source intelligence
+
+Horus expects source intelligence to be present. The bundled backend (code graph, semantic search, impact analysis, ownership, tree-sitter across TypeScript/JavaScript, Python, Go, Java and Rust) lives in [`packages/source-py`](packages/source-py) and ships as `horus_source.whl` beside the binary. `horus init` installs it with [uv](https://docs.astral.sh/uv/). Horus talks to it over HTTP/MCP only.
+
+Horus adds one thing the backend lacks. It stitches queue boundaries, linking a producer's `queue.add(...)` to the consumer's `@Processor` handler.
+
+> If the backend is unavailable, Horus still collects runtime evidence, but source context, impact analysis, change analysis and queue stitching are degraded.
 
 ## Install
 
+See [horus.sh/docs/installation](https://horus.sh/docs/installation) for full install, update and uninstall instructions.
+
 ```sh
+curl -fsSL https://horus.sh/install.sh | bash   # binary + backend
 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 npm and Homebrew packages bundle the matching source-intelligence backend wheel. `horus init` installs it with [uv](https://docs.astral.sh/uv/).
+The npm and Homebrew packages bundle the matching backend wheel. If you install the bare binary from [GitHub Releases](https://github.com/meritt-dev/horus/releases), run `horus update --force` once to fetch the wheel.
+
+Requirements: macOS or Linux (arm64 / x64), `git`, and Python 3.11+ with uv for the source backend. The binary itself needs no Node.js.
+
+If something goes wrong, run `horus doctor`.
 
 ## Upgrading from the TypeScript horus (≤ 0.23.0)
 
-- **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):
+From 0.24.0 Horus is this Rust implementation, on every channel. It is a command-for-command port of the TypeScript CLI (now archived at [Meritt-dev/horus-ts](https://github.com/Meritt-dev/horus-ts)): same commands, flags, help text, output and exit codes.
 
-  ```sh
-  horus db migrate-from-ts
-  ```
+| Installed with | Upgrade |
+| --- | --- |
+| npm | `npm i -g @merittdev/horus@latest` |
+| Homebrew | `brew upgrade horus` (the formula no longer depends on `node`) |
+| curl | `curl -fsSL https://horus.sh/install.sh \| bash` |
 
-  Until you do, `horus` prints a one-line reminder while the new store is empty. Re-running the migration is safe.
+Config and secrets in `~/.horus` and `.horus/config.json` are read as they are.
 
-## Use
+The TS CLI kept investigations and memory in PGlite at `~/.horus/horus.db`. Copy them into the new SQLite store once (needs `node`/`npx`; the TS store is only read):
 
 ```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"
+horus db migrate-from-ts
 ```
 
-`horus --help` lists every command.
-
-## How it compares to the TypeScript CLI
+Until you do, `horus` prints a one-line reminder while the new store is empty. Re-running the migration is safe.
 
-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 on the 11 other repos; 66/76 identical cases on the main project (the rest differ only by local history, live data or clock).
-
-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.
+We benchmarked both CLIs on 12 real repositories ([docs/BENCHMARK.md](docs/BENCHMARK.md)). The Rust build starts in 5 ms instead of 158 ms, idles at 10 MB instead of 153 MB, and runs 2.5 to 11.8× faster per project. Output matched 98 to 100% on 11 of the repos, and 66 of 76 cases were identical on the main one. The rest differ only by local history, live data or the clock. Intended differences are listed in [DIVERGENCES.md](DIVERGENCES.md).
 
 ## Build from source
 
 ```sh
-HORUS_VERSION=0.24.4 cargo build --release -p horus-cli   # → target/release/horus
+HORUS_VERSION=0.24.6 cargo build --release -p horus-cli   # → target/release/horus
+```
+
+Cross-platform builds are covered in [PORTING.md](PORTING.md), and cutting a release in [docs/RELEASE.md](docs/RELEASE.md). To build the backend wheel, run `scripts/release/build-source-wheel.sh` (needs uv, Python 3.11+ and Node.js).
+
+```
+crates/
+  core/         evidence model, config schema, project/env resolution, version pins
+  connectors/   provider contracts, source intelligence client, runtime connectors
+  stitcher/     queue-boundary stitcher
+  db/           local SQLite store
+  engine/       deterministic investigation pipeline (timeline, correlation, hypotheses, gaps)
+  ai/           optional narrative layer
+  knowledge/    local project-knowledge index
+  eval/         read-only accuracy harness
+  cli/          the horus binary
+packages/
+  source-py/    source-intelligence backend (Python), built into horus_source.whl
 ```
 
-Cross-platform release builds are covered in [PORTING.md](PORTING.md), and cutting a release in [docs/RELEASE.md](docs/RELEASE.md).
-
-The workspace mirrors the TS monorepo crate-for-package:
-- `core`
-- `connectors`
-- `db`
-- `stitcher`
-- `engine`
-- `ai`
-- `knowledge`
-- `eval`
-- `cli`
+IncidentBench, the open benchmark for startup recall, is described in [docs/incident-bench.md](docs/incident-bench.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@merittdev/horus",
-  "version": "0.24.4",
+  "version": "0.24.6",
   "description": "Local-first, source-aware production-incident investigation engine",
   "license": "MIT",
   "keywords": [
@@ -13,10 +13,10 @@
   "homepage": "https://horus.sh",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Meritt-dev/horus-rust"
+    "url": "https://github.com/Meritt-dev/horus"
   },
   "bugs": {
-    "url": "https://github.com/Meritt-dev/horus-rust/issues"
+    "url": "https://github.com/Meritt-dev/horus/issues"
   },
   "bin": {
     "horus": "bin/horus.js"
@@ -28,10 +28,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "@merittdev/horus-darwin-arm64": "0.24.4",
-    "@merittdev/horus-darwin-x64": "0.24.4",
-    "@merittdev/horus-linux-arm64": "0.24.4",
-    "@merittdev/horus-linux-x64": "0.24.4"
+    "@merittdev/horus-darwin-arm64": "0.24.6",
+    "@merittdev/horus-darwin-x64": "0.24.6",
+    "@merittdev/horus-linux-arm64": "0.24.6",
+    "@merittdev/horus-linux-x64": "0.24.6"
   },
   "publishConfig": {
     "access": "public"