argus-code 0.4.2__tar.gz → 0.4.4__tar.gz

argus_code-0.4.4/AGENTS.md

@@ -0,0 +1,119 @@
+# AGENTS.md — Argus (argus-code) root work contract
+
+> This repository uses the **DOX framework**: AGENTS.md files are binding work
+> contracts for their subtree. Before editing any path, read this file and every
+> AGENTS.md on the route from the repo root down to that path. The nearest doc
+> controls local detail; this root controls repo-wide rules. No child doc may
+> weaken DOX. Re-read the chain in-session; do not rely on memory.
+>
+> **After a meaningful change, run the DOX pass:** update the nearest owning
+> AGENTS.md (and any affected parent/child index) when you change purpose, scope,
+> contracts, workflows, inputs/outputs, or the doc tree itself; delete stale text;
+> then re-check changed paths against the chain. Pure no-behavior edits may leave
+> docs unchanged, but the pass still happens.
+
+## Purpose
+
+Argus is a **local-first** analytics dashboard for Claude Code (and other coding
+agents). A watcher ingests Claude Code's `.jsonl` session transcripts into a local
+SQLite archive (`~/.argus/argus.db`); a FastAPI server serves a static Astro
+dashboard at `http://localhost:4242`. No network, no telemetry, no LLM calls
+(except opt-in `argus pricing refresh`). Backend + dashboard ship together in the
+`argus-code` wheel on PyPI.
+
+Orientation docs (prose, not contracts — read but don't duplicate into AGENTS.md):
+- `ARCHITECTURE.md` — how the pieces fit together (read before adding a feature).
+- `CONTRIBUTING.md` — dev quick start (`uv sync`, `uv run argus start`).
+- `TESTING.md` — test catalog and conventions.
+
+## Ownership
+
+This root owns: the development workflow below, global engineering rules, the
+release process, and the top-level Child DOX Index. Code-level contracts live in
+the nearest child AGENTS.md.
+
+## Local Contracts
+
+### Development workflow (feature / bug → PR → merge → release → tag → publish)
+
+Follow this end-to-end for every feature or bug fix.
+
+1. **Branch.** Never commit feature/bug work directly to `main`. Branch from an
+   up-to-date `main`: `fix/<slug>` for bugs, `feat/<slug>` for features.
+2. **Implement test-first.** Reproduce the bug (or specify the feature) with a
+   failing test, then make it pass. See `tests/AGENTS.md`.
+3. **Commit** in small, logical units. Conventional-commit subjects
+   (`fix:`, `feat:`, `test:`, `release:`, `docs:`). End every commit message with:
+   ```
+   Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
+   ```
+4. **Verify** before opening the PR — see Verification below. Tests must be green
+   (the one known Windows flake is the scheduler timing test; confirm it passes in
+   isolation).
+5. **Push & open PR** against `main`: `gh pr create --base main --head <branch>`.
+   End the PR body with:
+   ```
+   🤖 Generated with [Claude Code](https://claude.com/claude-code)
+   ```
+6. **Merge** with squash and delete the branch:
+   `gh pr merge <n> --squash --delete-branch`. Then sync local `main`.
+7. **Release** (only when cutting a version — see Release process below).
+8. **Tag + GitHub release:** `gh release create vX.Y.Z --target main --title vX.Y.Z --notes "..."`.
+9. **PyPI publish is the maintainer's manual step** — see Release process.
+
+### Release process (manual — no CI release, no stored credentials)
+
+When cutting version `X.Y.Z`:
+1. Bump the version in **both** files with the Edit tool (not PowerShell
+   `Set-Content` — it injects a BOM): `pyproject.toml` (`version = "X.Y.Z"`) and
+   `python/argus/__init__.py` (`__version__ = "X.Y.Z"`).
+2. `uv lock` to sync `uv.lock` to the new version.
+3. If the dashboard changed, rebuild and refresh the shipped copy — see
+   `dashboard/AGENTS.md`.
+4. Clean-build the artifacts: **`rm -rf dist && uv build`** (always clear `dist/`
+   first, or stale files get uploaded).
+5. Confirm the wheel ships the right version + dashboard before publishing.
+6. Tag + GitHub release (workflow step 8).
+7. **Publish to PyPI — maintainer only:** `uv publish --token pypi-<token>`. The
+   token is the maintainer's secret; **an agent must never run this or handle the
+   token.** Stop and hand off.
+
+## Work Guidance
+
+Global engineering rules (binding):
+- **Never destroy user data in `~/.argus/argus.db`.** Migrations must be
+  non-destructive, idempotent, and self-healing. See `python/argus/store/AGENTS.md`.
+- **No hacks to make a test pass.** Fix the real cause, or correct a stale test
+  expectation to match the real contract (and say so). This is a prod package used
+  by many; never hardcode a value just to go green.
+- **Backend runs from source** (`uv run argus start`) — no build step for Python.
+  Only the dashboard has a build step.
+- Plans/specs under `docs/superpowers/` are scratch and gitignored — do not commit them.
+
+## Verification
+
+- Backend: `uv run pytest` (must be green; ~290 tests, ~25s on Windows).
+- Dashboard: `cd dashboard && npm run build` (must succeed).
+- Built form smoke test: see `CONTRIBUTING.md` "Running the built form".
+
+## User Preferences
+
+- Releases are cut deliberately by the maintainer; agents prepare everything up to
+  (and including the GitHub tag/release when asked) but never run `uv publish`.
+- Prefer honest reporting over green-at-any-cost: surface flakes, skips, and
+  pre-existing failures explicitly.
+
+## Child DOX Index
+
+- `python/argus/AGENTS.md` — Python backend package; owns the subsystems without
+  their own doc (`core`, `daemon`, `detectors`, `pricing`, `scaffold`, `schema`)
+  and indexes the four below.
+  - `python/argus/store/AGENTS.md` — SQLite, migrations, repository; data-safety
+    and path-normalization contracts.
+  - `python/argus/collector/AGENTS.md` — ingest pipeline and the missing-data
+    backfill (incl. sub-agent segment re-read).
+  - `python/argus/adapters/AGENTS.md` — Claude Code adapter and transcript-segment
+    extraction; sub-agent file layout.
+  - `python/argus/server/AGENTS.md` — FastAPI routes, static serving, clean shutdown.
+- `dashboard/AGENTS.md` — Astro dashboard and the `dashboard-dist` ship chain.
+- `tests/AGENTS.md` — pytest conventions and platform quirks.

argus_code-0.4.4/CLAUDE.md

@@ -0,0 +1,14 @@
+# CLAUDE.md
+
+This repository uses the **DOX framework** — an `AGENTS.md` hierarchy of binding
+work contracts. `AGENTS.md` (repo root) is the source of truth, including the full
+development workflow (branch → PR → squash-merge → release → tag → publish).
+
+**Before editing any path:** read the root `AGENTS.md`, then every `AGENTS.md` on
+the route down to that path; the nearest doc controls local detail. **After a
+meaningful change:** run the DOX closeout (update the nearest owning doc and any
+affected parent/child indexes). Re-read the chain in-session — don't rely on memory.
+
+The root contract (imported in full below):
+
+@AGENTS.md

{argus_code-0.4.2 → argus_code-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: argus-code
-Version: 0.4.2
+Version: 0.4.4
 Summary: Local-first dashboard for Claude Code cost, token, tool-usage, and full-text search analytics
 Project-URL: Homepage, https://github.com/KrishBhimani/argus-code
 Project-URL: Repository, https://github.com/KrishBhimani/argus-code.git

{argus_code-0.4.2 → argus_code-0.4.4}/SECURITY.md

@@ -33,8 +33,10 @@ Argus is built for one user, one machine. It assumes:
   before rendering in the dashboard, and never executed.
 - **Untrusted browsers visiting localhost.** Other webpages the user
   loads while Argus is running are not trusted. They cannot read
-  Argus data (Same-Origin Policy on responses) and cannot trigger
-  state changes (CSRF Origin check on POST).
+  Argus data (Same-Origin Policy on responses, backed by a loopback
+  `Host` allowlist so DNS rebinding can't turn a hostile domain into
+  a same-origin one) and cannot trigger state changes (CSRF Origin
+  check on POST).
 
 ## Defaults that matter
 
@@ -78,14 +80,23 @@ Things this codebase deliberately does to reduce attack surface:
   `escapeHtml()` before reaching `innerHTML`. The only HTML allowed
   through is `<mark>...</mark>` from FTS5 `snippet()`, applied via a
   separate `safeSnippet()` helper that escapes everything else.
-- `watchdog` does not follow symlinks by default. `discover_session_files`
-  additionally calls `Path.resolve(strict=True)` on each candidate
-  and rejects anything that doesn't canonicalise under the
-  `~/.claude/` tree.
+- `watchdog` does not follow symlinks by default. Every read additionally
+  goes through `ClaudeCodeAdapter.ingest_file`, which calls
+  `Path.resolve(strict=True)` and refuses anything that doesn't
+  canonicalise under the `~/.claude/` tree — symlink or NTFS junction.
+  The check sits at that single choke point (not at each caller) so
+  discovery, the watcher, and the sub-agent walk are all covered by
+  construction; `sub_agent_files_for` filters as well.
 - Per-tick read cap of 64 MiB on session JSONL and `history.jsonl`,
   so a runaway or hostile multi-GB file can't OOM the process.
 - CSRF Origin check on all non-GET API routes (FastAPI middleware in
   `python/argus/server/app.py`).
+- Loopback `Host` header allowlist on **every** route, static mount
+  included (`is_loopback_host` in `python/argus/server/app.py`). This is
+  what stops DNS rebinding: a page on `evil.com` that repoints its own
+  DNS at `127.0.0.1` still sends `Host: evil.com` and gets a 421, so it
+  never reaches the GET routes the Origin check deliberately exempts.
+  Skipped only under `--host 0.0.0.0`, which is already a warned opt-out.
 - No build hooks running on user machines. The wheel ships pure Python
   + bundled data (`dashboard-dist/`, `pricing/`, `templates/`).
   Installation runs no arbitrary code.
@@ -95,7 +106,11 @@ Things this codebase deliberately does to reduce attack surface:
 - `argus claude` scaffolding is a pure file copy — no templating,
   substitution, or code execution. It writes only to the path you hand
   `init` (created if absent) or under `~/.argus/templates/`, and never
-  overwrites an existing `CLAUDE.md`.
+  overwrites an existing `CLAUDE.md`. That containment is enforced, not
+  just intended: every destination must canonicalise under the target
+  directory, so a hostile repo shipping `.claude/` as a symlink or NTFS
+  junction can't redirect the write, and template names are validated as
+  plain directory names so `--template ../../x` can't escape the store.
 
 If you spot a regression on any of the above, that's a real bug and
 worth reporting.

argus_code-0.4.4/dashboard/AGENTS.md

@@ -0,0 +1,35 @@
+# AGENTS.md — dashboard (Astro frontend + ship chain)
+
+Parent: repo-root `AGENTS.md`. The statically-built UI served by `server/`.
+
+## Purpose
+
+Astro + ECharts dashboard. Source pages live in `src/pages/*.astro`
+(`session.astro`, `settings.astro`, `overview`, `timeline`, …) with shared
+scripts in `src/scripts/`.
+
+## Local Contracts
+
+- **Three "dist" directories — don't conflate them:**
+  - `dashboard/dist/` — raw Astro build output. **Gitignored.**
+  - `dashboard-dist/` (repo root) — the **tracked** copy that ships in the wheel
+    via `pyproject.toml` force-include (`"dashboard-dist" = "argus/dashboard-dist"`).
+  - `dist/` (repo root) — `uv build` output uploaded to PyPI. **Gitignored.**
+- **A dashboard source edit is invisible to the package until `dashboard-dist` is
+  refreshed and committed.** After changing anything under `dashboard/src/`:
+  ```sh
+  cd dashboard && npm run build && cd ..
+  git rm -r --quiet dashboard-dist && cp -r dashboard/dist dashboard-dist && git add -A dashboard-dist
+  ```
+  Commit the rebuilt `dashboard-dist` alongside the source change. Astro filenames
+  are content-hashed, so a real change shows as new `_astro/*.js|css` plus updated
+  `*/index.html` — verify the new asset (and absence of stale strings) in
+  `dashboard-dist` before committing.
+- Avoid em dashes / non-ASCII in strings that surface in the **terminal**
+  (CLI/console) — they mojibake on the Windows console. (UI text is fine.)
+
+## Verification
+
+`cd dashboard && npm run build` must succeed. After refreshing `dashboard-dist`,
+optionally confirm the wheel ships it (`rm -rf dist && uv build`, then inspect the
+`.whl`).

{argus_code-0.4.2 → argus_code-0.4.4}/dashboard/src/pages/session.astro

@@ -119,7 +119,16 @@ import Default from '../layouts/Default.astro';
     }
     #to-top:hover { color: var(--text-0); border-color: var(--accent, #f0883e); }
     .sa-wrap { display: grid; grid-template-columns: 38% 62%; gap: 1rem; align-items: start; }
-    .sa-list { display: flex; flex-direction: column; gap: 2px; }
+    .sa-list {
+      display: flex; flex-direction: column; gap: 2px;
+      max-height: calc(100vh - 13rem); overflow-y: auto;
+      padding-right: 0.35rem; scrollbar-gutter: stable;
+      scrollbar-width: thin; scrollbar-color: var(--border) transparent;
+    }
+    .sa-list::-webkit-scrollbar { width: 8px; }
+    .sa-list::-webkit-scrollbar-track { background: transparent; }
+    .sa-list::-webkit-scrollbar-thumb { background: var(--border); border-radius: 4px; }
+    .sa-list::-webkit-scrollbar-thumb:hover { background: var(--text-2); }
     .sa-row { display: flex; align-items: center; gap: 0.5rem; padding: 0.45rem 0.55rem; border-radius: 7px; cursor: pointer; font-size: 0.84rem; }
     .sa-row:hover { background: var(--bg-2); }
     .sa-row.sel { background: var(--bg-2); box-shadow: inset 0 0 0 1px var(--border); }
@@ -127,7 +136,7 @@ import Default from '../layouts/Default.astro';
     .sa-dot.ok { color: var(--good); }
     .sa-dot.error { color: #f85149; }
     .sa-meta { margin-left: auto; color: var(--text-2); font-size: 0.76rem; white-space: nowrap; }
-    .sa-detail { padding: 1rem; }
+    .sa-detail { padding: 1rem; position: sticky; top: 1rem; align-self: start; }
     .sa-stats { display: grid; grid-template-columns: repeat(3, 1fr); gap: 0.5rem; margin-bottom: 0.8rem; }
     .sa-stats > div { background: var(--bg-2); border-radius: 8px; padding: 0.5rem 0.6rem; }
     .sa-stats span { display: block; color: var(--text-2); font-size: 0.7rem; text-transform: uppercase; letter-spacing: 0.03em; }

{argus_code-0.4.2 → argus_code-0.4.4}/dashboard/src/pages/settings.astro

@@ -219,7 +219,7 @@ import Default from '../layouts/Default.astro';
         daemon = (await fetch('/api/ingest/status').then(r => r.json())).daemon === true;
       } catch { /* leave daemon=false */ }
       if (daemon) {
-        actions.innerHTML = `<span style="color:var(--text-2);font-size:0.82rem;">Read-only while <code>argusd</code> is running — manage indexing from the CLI (<code>argus search enable</code>) or stop the daemon with <code>argus daemon stop</code>.</span>`;
+        actions.innerHTML = `<span style="color:var(--text-2);font-size:0.82rem;">Read-only while <code>argusd</code> is running — manage indexing from the CLI (<code>argus indexing enable</code>) or stop the daemon with <code>argus daemon stop</code>.</span>`;
         return;
       }
 

{argus_code-0.4.2 → argus_code-0.4.4}/dashboard/src/pages/tools.astro

@@ -72,7 +72,11 @@ import Default from '../layouts/Default.astro';
             const i = p[0].dataIndex;
             const calls = values[i];
             const err = errors?.[i] ?? 0;
-            return `${labels[i]}<br>Calls: ${calls.toLocaleString()}` +
+            // ECharts renders a custom tooltip formatter's return value as
+            // HTML, so the label -- a tool / MCP-server / sub-agent name read
+            // verbatim from .jsonl -- must be escaped here too, exactly like
+            // every other innerHTML sink on this page.
+            return `${escapeHtml(labels[i])}<br>Calls: ${calls.toLocaleString()}` +
               (err ? `<br>Errors: ${err.toLocaleString()} (${((err/calls)*100).toFixed(1)}%)` : '');
           },
         },