@merittdev/horus 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +100 -116
- package/dist/index.cjs +2635 -459
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,65 +6,78 @@
|
|
|
6
6
|
|
|
7
7
|
**Understand what happened.**
|
|
8
8
|
|
|
9
|
-
Horus
|
|
9
|
+
Open-source incident investigation. Horus connects Elasticsearch, Grafana, MongoDB, BullMQ, and source intelligence into deterministic reports — installable today.
|
|
10
10
|
|
|
11
11
|
CLI-only. Read-only against production systems. Horus never writes to your infrastructure.
|
|
12
12
|
|
|
13
|
-
**Website:** [horus.sh](https://horus.sh)
|
|
13
|
+
**Website:** [horus.sh](https://horus.sh) · **Source:** [github.com/meritt-dev/horus](https://github.com/meritt-dev/horus)
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
16
|
curl -fsSL https://horus.sh/install.sh | bash
|
|
17
|
+
npm install -g @merittdev/horus
|
|
18
|
+
brew install meritt-dev/tap/horus
|
|
17
19
|
```
|
|
18
20
|
|
|
21
|
+
Homebrew tap is live through meritt-dev/tap.
|
|
22
|
+
|
|
19
23
|
---
|
|
20
24
|
|
|
21
25
|
## What Horus does
|
|
22
26
|
|
|
23
|
-
Horus reads from your existing systems and reconstructs the incident through evidence, correlation, and
|
|
27
|
+
Horus reads from your existing systems and reconstructs the incident through evidence, correlation, and ranked hypotheses.
|
|
24
28
|
|
|
25
|
-
It does not dump thousands of logs. It connects runtime signals to source context and returns a **deterministic report** —
|
|
29
|
+
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.
|
|
26
30
|
|
|
27
31
|
Every incident leaves evidence.
|
|
28
32
|
|
|
29
33
|
## What Horus is not
|
|
30
34
|
|
|
31
|
-
|
|
|
32
|
-
|
|
33
|
-
| **Monitoring**
|
|
34
|
-
| **Observability** | Shows signals
|
|
35
|
-
| **Horus**
|
|
35
|
+
| | |
|
|
36
|
+
|---|---|
|
|
37
|
+
| **Monitoring** | Detects problems |
|
|
38
|
+
| **Observability** | Shows signals |
|
|
39
|
+
| **Horus** | Reconstructs what happened |
|
|
36
40
|
|
|
37
41
|
Horus is not another dashboard, alerting tool, or log viewer. It sits on top of the systems you already use.
|
|
38
42
|
|
|
39
43
|
> Monitoring detects. Observability shows. Horus reconstructs.
|
|
40
44
|
|
|
45
|
+
## Getting started
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
horus setup
|
|
49
|
+
horus init
|
|
50
|
+
horus index
|
|
51
|
+
horus connect elasticsearch # optional runtime connectors
|
|
52
|
+
horus investigate "checkout latency spike"
|
|
53
|
+
horus investigations # list saved IDs
|
|
54
|
+
horus replay <id>
|
|
55
|
+
horus postmortem <id>
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Horus source intelligence requires a local code-graph host (the curl installer attempts to install it). Postgres is required for the audit store.
|
|
59
|
+
|
|
41
60
|
## How it works
|
|
42
61
|
|
|
43
62
|
**Evidence in. Explanation out.**
|
|
44
63
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
|
50
|
-
|
|
|
51
|
-
|
|
|
52
|
-
| Metrics | Timeline | Confidence |
|
|
53
|
-
| Traces | Hypotheses | Evidence |
|
|
54
|
-
| Queues | Reconstruction | Contradictions |
|
|
55
|
-
| Databases | | Recommended Actions |
|
|
64
|
+
| Runtime + Source | Investigation Engine | Investigation Report |
|
|
65
|
+
|---|---|---|
|
|
66
|
+
| Elasticsearch logs | Correlation | Suspected causes (ranked) |
|
|
67
|
+
| Grafana metrics | Timeline | Hypotheses + confidence |
|
|
68
|
+
| MongoDB state | Cause ranking | Evidence + gaps |
|
|
69
|
+
| BullMQ queues | | Next actions |
|
|
70
|
+
| Source graph + git | | |
|
|
56
71
|
|
|
57
72
|
Pipeline: **Evidence → Correlation → Hypotheses → Timeline → Report**
|
|
58
73
|
|
|
59
|
-
Signals are easy. Correlation is hard. Every system sees a piece of the incident — Horus connects evidence across sources so the sequence of events becomes visible.
|
|
60
|
-
|
|
61
74
|
## Sources Horus investigates
|
|
62
75
|
|
|
63
|
-
|
|
76
|
+
Elasticsearch · Grafana · MongoDB · BullMQ · Git changes · Source graph · Queue map · Ownership
|
|
64
77
|
|
|
65
|
-
|
|
78
|
+
Trace reconstruction is not shipped yet. Connectors are read-only and project-scoped.
|
|
66
79
|
|
|
67
|
-
## Example
|
|
80
|
+
## Example output (illustrative)
|
|
68
81
|
|
|
69
82
|
```bash
|
|
70
83
|
horus investigate \
|
|
@@ -74,89 +87,58 @@ horus investigate \
|
|
|
74
87
|
```
|
|
75
88
|
|
|
76
89
|
```text
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
✓ Redis
|
|
80
|
-
✓ BullMQ
|
|
81
|
-
✓ Git
|
|
82
|
-
✓ Ownership
|
|
83
|
-
|
|
84
|
-
Building timeline...
|
|
85
|
-
✓ 14 events reconstructed
|
|
90
|
+
# Investigation inv-347
|
|
91
|
+
Hint: checkout latency spike
|
|
86
92
|
|
|
87
|
-
|
|
88
|
-
|
|
93
|
+
## Suspected causes (ranked)
|
|
94
|
+
1. [0.82 / high] Redis connection pool exhaustion [↑ queue]
|
|
89
95
|
|
|
90
|
-
|
|
96
|
+
## Hypotheses
|
|
97
|
+
[supported] [0.78] queue: backlog growth preceded latency spike
|
|
91
98
|
|
|
92
|
-
|
|
93
|
-
|
|
99
|
+
## Evidence gaps
|
|
100
|
+
- queue runtime state: worker heartbeat unavailable
|
|
94
101
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
• Worker starvation
|
|
99
|
-
• Request timeout increase
|
|
102
|
+
## Evidence
|
|
103
|
+
- ev-01 [elasticsearch/error] Request timeout increase
|
|
104
|
+
- ev-04 [bullmq/queue] checkout-jobs backlog growth
|
|
100
105
|
|
|
101
|
-
|
|
102
|
-
|
|
106
|
+
## Next actions
|
|
107
|
+
- Inspect worker concurrency changes in deploy #784
|
|
103
108
|
```
|
|
104
109
|
|
|
105
110
|
## Principles
|
|
106
111
|
|
|
107
|
-
**Read-only** — Horus never writes to your production systems.
|
|
112
|
+
**Read-only** — Horus never writes to your production systems.
|
|
108
113
|
|
|
109
|
-
**Deterministic first** —
|
|
114
|
+
**Deterministic first** — The engine is deterministic; optional `--ai` adds an Anthropic narrative.
|
|
110
115
|
|
|
111
|
-
**Local-first** —
|
|
116
|
+
**Local-first** — Connectors read from your own clusters, not a hosted black box.
|
|
112
117
|
|
|
113
|
-
**Project-scoped** — Every investigation belongs to a specific project and environment.
|
|
118
|
+
**Project-scoped** — Every investigation belongs to a specific project and environment.
|
|
114
119
|
|
|
115
120
|
## Capabilities
|
|
116
121
|
|
|
117
|
-
|
|
122
|
+
Installable today. More connectors and AI providers are in progress.
|
|
118
123
|
|
|
119
124
|
**Today**
|
|
120
125
|
|
|
121
|
-
- Elasticsearch
|
|
122
|
-
-
|
|
123
|
-
-
|
|
124
|
-
-
|
|
126
|
+
- Elasticsearch logs
|
|
127
|
+
- Grafana metrics
|
|
128
|
+
- MongoDB state
|
|
129
|
+
- BullMQ queue evidence
|
|
130
|
+
- Source intelligence (code graph)
|
|
125
131
|
- Timeline generation
|
|
126
132
|
- Evidence correlation
|
|
133
|
+
- Investigation replay
|
|
134
|
+
- Postmortem drafts
|
|
127
135
|
|
|
128
136
|
**Coming next**
|
|
129
137
|
|
|
130
138
|
- Kubernetes evidence
|
|
131
|
-
-
|
|
132
|
-
- Incident replay
|
|
139
|
+
- Distributed trace reconstruction
|
|
133
140
|
- Slack evidence ingestion
|
|
134
|
-
|
|
135
|
-
## Can I use Horus today?
|
|
136
|
-
|
|
137
|
-
The investigation engine runs end-to-end. Some surfaces require a local setup before they work — Postgres for the audit store, a source-intelligence host, and at least one configured runtime connector for live evidence.
|
|
138
|
-
|
|
139
|
-
| Feature | Status | Notes |
|
|
140
|
-
| ------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
|
|
141
|
-
| Install (`curl` or direct download) | Partial | Builds and runs from source; public binary release not yet published |
|
|
142
|
-
| `horus init` | Works today | Creates `.horus/config.json` and registers the project |
|
|
143
|
-
| `horus doctor` | Works today | Checks CLI, git root, config, and source-intelligence setup |
|
|
144
|
-
| `horus setup` | Works today | Verifies prerequisites and guides fixes |
|
|
145
|
-
| Source indexing (`horus index`) | Partial | Command works; requires a source-intelligence host running locally |
|
|
146
|
-
| `horus investigate` | Works today | Full deterministic report; requires Postgres + at least one connector or git history |
|
|
147
|
-
| `horus replay` | Works today | Re-renders a saved investigation from the audit store; no re-query |
|
|
148
|
-
| `horus postmortem` | Works today | Drafts an editable Markdown postmortem from a saved investigation |
|
|
149
|
-
| Runtime connectors (ES / Mongo / Grafana / Redis) | Partial | Connectors exist; each requires a live instance and per-project connector config |
|
|
150
|
-
| AI narrative (`--ai` flag on `investigate`) | Partial | Requires `ANTHROPIC_API_KEY`; falls back to deterministic output automatically on failure |
|
|
151
|
-
| Local AI provider bridge | Partial | Provider detection works; execution requires a local model installed |
|
|
152
|
-
|
|
153
|
-
**Prerequisites before Horus works end-to-end:**
|
|
154
|
-
|
|
155
|
-
- Postgres 16 (audit store) — `docker compose up -d` starts it
|
|
156
|
-
- At least one runtime connector configured via `horus connect <type>`
|
|
157
|
-
- Source-intelligence host running locally for source-aware commands (`horus index`, `horus explain`, `horus blast-radius`, `horus architecture`, `horus search`)
|
|
158
|
-
|
|
159
|
-
`horus replay` and `horus postmortem` work from the saved audit store and require neither live connectors nor a source-intelligence host.
|
|
141
|
+
- Local AI provider execution
|
|
160
142
|
|
|
161
143
|
---
|
|
162
144
|
|
|
@@ -166,7 +148,7 @@ Horus is organized in four layers:
|
|
|
166
148
|
|
|
167
149
|
**Source Intelligence**
|
|
168
150
|
|
|
169
|
-
-
|
|
151
|
+
- Horus source intelligence backend — code graph, semantic search, impact analysis, ownership.
|
|
170
152
|
|
|
171
153
|
**Runtime Evidence**
|
|
172
154
|
|
|
@@ -189,19 +171,19 @@ Horus is organized in four layers:
|
|
|
189
171
|
|
|
190
172
|
### Source intelligence is built into Horus
|
|
191
173
|
|
|
192
|
-
**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 source
|
|
174
|
+
**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.
|
|
193
175
|
|
|
194
176
|
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.
|
|
195
177
|
|
|
196
|
-
> If the source
|
|
178
|
+
> 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.
|
|
197
179
|
|
|
198
|
-
Horus talks to the source
|
|
180
|
+
Horus talks to the source intelligence backend over **HTTP/MCP only** (no CLI shell-outs for queries). Run `horus index` in a repository to start and register its source intelligence host.
|
|
199
181
|
|
|
200
182
|
## Configuration
|
|
201
183
|
|
|
202
184
|
The config model separates **code** from **runtime**:
|
|
203
185
|
|
|
204
|
-
- **Code belongs to the project** — `repositories[]`, each served by its own source
|
|
186
|
+
- **Code belongs to the project** — `repositories[]`, each served by its own source intelligence host.
|
|
205
187
|
- **Runtime belongs to the environment** — `environments[].connectors` (Elasticsearch, MongoDB, Grafana, Redis/BullMQ).
|
|
206
188
|
|
|
207
189
|
```ts
|
|
@@ -248,28 +230,32 @@ export default defineConfig({
|
|
|
248
230
|
|
|
249
231
|
## Install
|
|
250
232
|
|
|
233
|
+
See **[docs/install.md](./docs/install.md)** for full install, update, and uninstall instructions.
|
|
234
|
+
|
|
251
235
|
```bash
|
|
252
236
|
curl -fsSL https://horus.sh/install.sh | bash
|
|
237
|
+
npm install -g @merittdev/horus
|
|
238
|
+
brew install meritt-dev/tap/horus
|
|
253
239
|
horus --version
|
|
254
240
|
horus setup
|
|
255
241
|
```
|
|
256
242
|
|
|
257
|
-
The installer downloads the Horus CLI from GitHub Releases and
|
|
243
|
+
The curl installer downloads the Horus CLI from GitHub Releases and attempts to install the Horus source intelligence backend. All three channels install the same `horus` binary.
|
|
258
244
|
|
|
259
245
|
### What the installer installs
|
|
260
246
|
|
|
261
|
-
| Component
|
|
262
|
-
|
|
|
263
|
-
| **Horus CLI**
|
|
264
|
-
| **Horus source
|
|
247
|
+
| Component | Role | Required |
|
|
248
|
+
| --- | --- | --- |
|
|
249
|
+
| **Horus CLI** | The `horus` command | Yes |
|
|
250
|
+
| **Horus source intelligence backend** | Enables `horus index`, `horus explain`, `horus changes`, `horus architecture` | Optional |
|
|
265
251
|
|
|
266
252
|
### Prerequisites
|
|
267
253
|
|
|
268
|
-
| Requirement
|
|
269
|
-
|
|
|
270
|
-
| Node.js 22+
|
|
271
|
-
| Postgres 16
|
|
272
|
-
| Python 3.11+ + uv/pip | Required only for the source
|
|
254
|
+
| Requirement | Role |
|
|
255
|
+
| --- | --- |
|
|
256
|
+
| Node.js 22+ | Horus CLI runtime (the installed binary needs Node.js) |
|
|
257
|
+
| Postgres 16 | Investigation audit store — run locally via `docker compose up -d` or use a managed instance |
|
|
258
|
+
| Python 3.11+ + uv/pip | Required only for the Horus source intelligence backend |
|
|
273
259
|
|
|
274
260
|
The installer **does not** configure Elasticsearch, MongoDB, Grafana, Redis, or any production system. Runtime connectors are added per-project after install via `horus connect`.
|
|
275
261
|
|
|
@@ -283,20 +269,18 @@ sudo mv horus /usr/local/bin/horus
|
|
|
283
269
|
horus --version
|
|
284
270
|
```
|
|
285
271
|
|
|
286
|
-
**
|
|
287
|
-
|
|
288
|
-
To **update** to a newer version, re-run the installer — it overwrites the binary and leaves your config untouched. To **uninstall**, see **[docs/install.md#uninstall](./docs/install.md#uninstall)** for what to remove and what to keep.
|
|
272
|
+
To **update** to a newer version, re-run the installer — it overwrites the binary and leaves your config untouched. To **uninstall**, see **[docs/install.md#uninstall](./docs/install.md#uninstall)**.
|
|
289
273
|
|
|
290
|
-
If something goes wrong after install, see **[docs/troubleshooting.md](./docs/troubleshooting.md)
|
|
274
|
+
If something goes wrong after install, see **[docs/troubleshooting.md](./docs/troubleshooting.md)**.
|
|
291
275
|
|
|
292
|
-
## Local development
|
|
276
|
+
## Local development
|
|
293
277
|
|
|
294
278
|
```bash
|
|
295
279
|
pnpm install
|
|
296
280
|
docker compose up -d # Postgres 16 on localhost:5433
|
|
297
281
|
pnpm build # builds apps/horus/dist/index.cjs
|
|
298
282
|
|
|
299
|
-
# Per repository: start the source
|
|
283
|
+
# Per repository: start the source intelligence host and stitch queue boundaries
|
|
300
284
|
horus index
|
|
301
285
|
|
|
302
286
|
source ~/.horus.env
|
|
@@ -322,15 +306,15 @@ horus investigate --help
|
|
|
322
306
|
|
|
323
307
|
### Core commands
|
|
324
308
|
|
|
325
|
-
| Command
|
|
326
|
-
|
|
|
327
|
-
| `horus status [--project --env]`
|
|
328
|
-
| `horus index --project <p> --env <e>`
|
|
329
|
-
| `horus investigate --project <p> --env <e> "<hint>"`
|
|
330
|
-
| `horus logs [service] --project <p> --env <e>`
|
|
331
|
-
| `horus state --project <p> --env <e>`
|
|
332
|
-
| `horus metrics [hint] --project <p> --env <e>`
|
|
333
|
-
| `horus explain <symbol>` · `blast-radius` · `architecture` · `what-changed` | Source-aware code intelligence (requires source
|
|
309
|
+
| Command | What it does |
|
|
310
|
+
| --- | --- |
|
|
311
|
+
| `horus status [--project --env]` | Per-project/env connector-health matrix |
|
|
312
|
+
| `horus index --project <p> --env <e>` | Build the queue map (stitcher) for a project |
|
|
313
|
+
| `horus investigate --project <p> --env <e> "<hint>"` | Full deterministic investigation report |
|
|
314
|
+
| `horus logs [service] --project <p> --env <e>` | Error-signature evidence (`--raw` for lines) |
|
|
315
|
+
| `horus state --project <p> --env <e>` | MongoDB application-state evidence (read-only) |
|
|
316
|
+
| `horus metrics [hint] --project <p> --env <e>` | Grafana metrics evidence |
|
|
317
|
+
| `horus explain <symbol>` · `blast-radius` · `architecture` · `what-changed` | Source-aware code intelligence (requires source intelligence backend) |
|
|
334
318
|
|
|
335
319
|
## Local project workflow (git-style)
|
|
336
320
|
|
|
@@ -347,7 +331,7 @@ horus investigate --name atlas-payments "checkout latency spike"
|
|
|
347
331
|
horus projects
|
|
348
332
|
```
|
|
349
333
|
|
|
350
|
-
`horus index` reuses an already-running source
|
|
334
|
+
`horus index` reuses an already-running source intelligence host when one is healthy. Runtime connectors are added to the env block of `.horus/config.json` afterwards.
|
|
351
335
|
|
|
352
336
|
## Layout
|
|
353
337
|
|
|
@@ -366,6 +350,6 @@ config/ horus.config.ts
|
|
|
366
350
|
## Foundation
|
|
367
351
|
|
|
368
352
|
- TypeScript monorepo (pnpm + Turborepo)
|
|
369
|
-
- Postgres + Drizzle — semantic search delegated to source
|
|
370
|
-
- Built-in **source
|
|
353
|
+
- Postgres + Drizzle — semantic search delegated to source intelligence backend
|
|
354
|
+
- Built-in **Horus source intelligence backend**, over HTTP/MCP only
|
|
371
355
|
- Project/environment-scoped connectors; read-only against production
|