argus-code 0.4.3__tar.gz → 0.5.0__tar.gz

argus_code-0.5.0/.github/workflows/test.yml

@@ -0,0 +1,74 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pytest:
+    name: pytest (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # Don't cancel the whole matrix on one platform's failure — path
+      # handling, symlink behaviour and signal delivery all differ per OS,
+      # and seeing which combination broke is the point.
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --dev --python ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run pytest -q
+
+  dashboard:
+    name: dashboard build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: dashboard/package-lock.json
+
+      - name: Install and build
+        working-directory: dashboard
+        run: |
+          npm ci
+          npm run build
+
+      # The wheel ships dashboard-dist/, not dashboard/dist/. If a source edit
+      # is committed without refreshing the shipped copy, users get the old UI
+      # — including, historically, an unfixed XSS. Fail loudly on drift.
+      #
+      # Compare file *names*, not bytes: Astro content-hashes asset filenames,
+      # so any real source change renames the asset. Byte comparison would
+      # instead trip over line endings, since dashboard-dist/ is tracked (and
+      # so checked out CRLF on Windows) while dashboard/dist/ is a fresh LF
+      # build — a difference that says nothing about staleness.
+      - name: Check dashboard-dist is in sync with dashboard/src
+        run: |
+          (cd dashboard/dist && find . -type f | sort) > /tmp/built.txt
+          (cd dashboard-dist  && find . -type f | sort) > /tmp/shipped.txt
+          if ! diff -u /tmp/shipped.txt /tmp/built.txt; then
+            echo "::error::dashboard-dist/ is stale. Rebuild and commit it — see dashboard/AGENTS.md."
+            exit 1
+          fi
+          echo "dashboard-dist matches the build."

{argus_code-0.4.3 → argus_code-0.5.0}/.gitignore

@@ -27,3 +27,11 @@ venv/
 htmlcov/
 *.egg-info/
 build/
+
+# Dashboard e2e artifacts
+dashboard/playwright-report/
+dashboard/test-results/
+dashboard/.e2e-data/
+
+# TypeScript incremental build cache
+dashboard/*.tsbuildinfo

argus_code-0.5.0/AGENTS.md

@@ -0,0 +1,120 @@
+# 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 React
+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; ~480 tests, ~35s on Windows).
+- Dashboard: `cd dashboard && npm test && npm run build && npm run size` (all must
+  succeed); `npm run e2e` before a release.
+- 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` — React SPA dashboard and the `dashboard-dist` ship chain.
+- `tests/AGENTS.md` — pytest conventions and platform quirks.

{argus_code-0.4.3 → argus_code-0.5.0}/ARCHITECTURE.md

@@ -26,8 +26,9 @@ No network calls (except optional `argus pricing refresh`). No
 telemetry. No LLM calls. Everything stays on your machine.
 
 The backend is Python (≥3.11, FastAPI + uvicorn + pydantic + watchdog
-+ stdlib sqlite3 + typer). The dashboard is Astro + ECharts, statically
-built. Both ship together in the `argus-code` wheel on PyPI.
++ stdlib sqlite3 + typer). The dashboard is a Vite + React SPA (TanStack
+Router/Query/Table, uPlot + SVG charts, Tailwind tokens), statically built.
+Both ship together in the `argus-code` wheel on PyPI.
 
 ## The data layer
 
@@ -119,12 +120,19 @@ python/argus/server/api.py         /api/overview, /api/sessions, /api/tools, …
 python/argus/store/repository.py   parameterized SQL queries
         │
         ▼
-dashboard-dist/                    static HTML+JS bundled from dashboard/src/ (Astro + ECharts)
+dashboard-dist/                    static SPA bundled from dashboard/src/ (Vite + React)
 ```
 
 The dashboard is **statically built**. No server-side rendering, no
-Node in the browser. Pages just `fetch('/api/...')` and render with
-ECharts.
+Node at runtime. Pages fetch `/api/...` through a typed, Zod-validated
+client (`dashboard/src/lib/api/`) via TanStack Query and render with uPlot
+(time series, scatter) and hand-rolled SVG (bars, meters, heatmaps, the
+session minimap). Derived analyses (prior-window deltas, per-project
+rollups, weekday x hour, tool calls per day) are pure functions in
+`dashboard/src/lib/analysis/`, computed client-side from existing endpoints;
+each carries a `// candidate-endpoint:` note where a server aggregate would
+scale better. Deep links such as `/sessions/<id>` are served by the
+`index.html` fallback in `server/app.py` and resolved by the client router.
 
 ## Detection (alerts)
 
@@ -223,10 +231,11 @@ A few patterns to absorb before adding code:
   `ON CONFLICT(id) DO UPDATE`. Re-ingesting a file from offset 0 is
   safe — useful for backfilling derived data after a schema change.
 
-- **HTML-escape every user-controlled string.** Anything from the
-  JSONL that ends up in `innerHTML` goes through `escapeHtml()` from
-  `dashboard/src/scripts/format.ts`. The only HTML allowed through
-  raw is `<mark>` from FTS5 snippets, via `safeSnippet()`.
+- **Never write raw HTML in the dashboard.** React renders every
+  JSONL-derived string as a text node; `dangerouslySetInnerHTML` and
+  `innerHTML` are forbidden (`tests/dashboard/test_no_raw_html.py`). FTS5
+  `<mark>` snippets are split into text runs by
+  `dashboard/src/features/search/cleanSnippet.ts`.
 
 - **CSRF Origin check.** All non-GET `/api/*` routes verify the
   `Origin` header is loopback. Implemented as FastAPI middleware in
@@ -266,10 +275,15 @@ python/argus/
 
 dashboard/
   src/
-    layouts/Default.astro   nav, footer, font, styles
-    pages/                  one .astro per route
-    scripts/                api client, charts, formatters
-    styles/global.css       single theme stylesheet
+    app/                    router, query client, shell (sidebar, top bar, Ctrl+K)
+    routes/                 TanStack file routes (one per page + legacy redirects)
+    features/<page>/        page components and page-specific hooks
+    components/ui/          Panel, Tile, Pill, Chip, Seg, Button, DataTable, ...
+    components/charts/      uPlot wrappers + SVG charts (rules in README.md)
+    lib/api/                Zod schemas, typed client, React Query hooks, fixtures
+    lib/analysis/           pure derived analyses (unit-tested)
+    lib/format/             number / date formatters
+    styles.css              Tailwind v4 tokens (@theme) + base rules
 dashboard-dist/             built dashboard, shipped in the wheel as data
 
 pricing/                    bundled LiteLLM price tables (shipped in wheel as data)
@@ -296,12 +310,12 @@ tests/                      pytest suite, mirrors python/argus/ layout
 
 | Want to… | Touch these |
 |---|---|
-| Add a new dashboard page | `dashboard/src/pages/<name>.astro`, add nav link in `dashboard/src/layouts/Default.astro` |
+| Add a new dashboard page | `dashboard/src/routes/<name>.tsx` + `dashboard/src/features/<name>/<Name>Page.tsx`, add it to `GROUPS` in `dashboard/src/app/shell/Sidebar.tsx` and `PAGES` in `CommandPalette.tsx` |
 | Add a new API endpoint | `python/argus/server/api.py`, add a `repo.<method_name>()` in `python/argus/store/repository.py` |
 | Add a new SQL table or column | New `MIGRATION_N+1` in `python/argus/store/migrations/inline.py`, bump schema check in `db.py`, add `repo` method, add pydantic model in `python/argus/schema/types.py` |
 | Parse a new JSONL field | `python/argus/adapters/claude_code/schemas.py` (pydantic), wire into `pipeline.py` |
 | Tweak cost computation | `python/argus/pricing/compute.py`, then re-ingest to recompute via a backfill |
-| Add a new chart | `dashboard/src/scripts/charts.ts` (theme is shared) |
+| Add a new chart | `dashboard/src/components/charts/` (read its `README.md` first; series colours in `uplotTheme.ts`) |
 | Add a new adapter (Codex, OpenClaw, Hermes, …) | New folder `python/argus/adapters/<agent>/` + `@register class` in `adapter.py`. No edits to CLI / watcher / pipeline / server. |
 | Add an alert detector | New file in `python/argus/detectors/` with a `@register` class whose pure `detect()` returns `Finding`s, plus the side-effect import in `detectors/__init__.py`. The scheduler picks it up automatically. |
 | Change the bundled scaffold template | Edit files under `templates/default/`; they're force-included into the wheel. New top-level dirs need a `force-include` entry in `pyproject.toml`. |

argus_code-0.5.0/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.3 → argus_code-0.5.0}/CONTRIBUTING.md

@@ -15,7 +15,7 @@ first** — it's a 5-minute tour of how the pieces fit together.
 git clone https://github.com/KrishBhimani/argus-code.git
 cd argus-code
 uv sync               # creates .venv and installs deps + dev tools
-uv run pytest         # ~215 tests, ~20s
+uv run pytest         # ~380 tests, ~30s
 uv run argus start    # fast iteration loop — runs directly from source
 ```
 
@@ -24,6 +24,18 @@ Change a file, restart, see the result.
 
 If you don't have `uv` yet: <https://docs.astral.sh/uv/getting-started/installation/>.
 
+## Dashboard dev loop
+
+```sh
+uv run argus start                           # backend on :4242
+cd dashboard && npm install && npm run dev   # Vite on :5173, proxies /api to :4242
+npm test && npm run build && npm run size    # before committing
+```
+
+The dashboard is a Vite + React SPA; see `dashboard/AGENTS.md` for the ship
+chain (`dashboard-dist/` must be refreshed and committed with every source
+change) and `npm run e2e` for the Playwright smoke test.
+
 ## Running the built form
 
 CI builds and tests on every push. To smoke-test the built wheel
@@ -32,11 +44,15 @@ locally exactly as a user would:
 ```sh
 cd dashboard && npm ci && npm run build && cd ..
 cp -r dashboard/dist dashboard-dist          # bundle the dashboard
-uv build                                     # wheel + sdist in dist/
-uv tool install ./dist/argus_cli-*.whl       # install globally
+rm -rf dist && uv build                      # wheel + sdist in dist/
+uv tool install ./dist/argus_code-*.whl      # install globally
 argus start
 ```
 
+The distribution is `argus-code` on PyPI (the `argus_code-*.whl` above); the
+command it installs is `argus`. Clear `dist/` first or a stale wheel from an
+earlier version can be picked up by the glob.
+
 ## Tests
 
 ```sh
@@ -54,11 +70,17 @@ for the full catalog.
 
 ## CI
 
-`.github/workflows/test.yml` runs on every push and PR:
-
-- **Test matrix:** Ubuntu, macOS, Windows × Python 3.11, 3.12, 3.13.
-- **Dashboard build** (release-only): runs `npm ci && npm run build`
-  before `uv build` to bundle the static dashboard into the wheel.
+`.github/workflows/test.yml` runs on every push to `main` and every PR:
+
+- **Test matrix:** Ubuntu, macOS, Windows × Python 3.11, 3.12, 3.13 (9 jobs,
+  `fail-fast: false` so you can see which platform broke).
+- **Dashboard build:** `npm ci && npm run build`, then a check that the
+  tracked `dashboard-dist/` matches what the build produces. A source edit
+  committed without refreshing the shipped copy means users run the old UI —
+  that has historically shipped an unfixed XSS, so the check is a hard fail.
+  It compares file *names*, which Vite content-hashes, rather than bytes
+  (`dashboard-dist/` is tracked and so checked out CRLF on Windows, while a
+  fresh build is LF — a difference that says nothing about staleness).
 
 The Windows runner is non-negotiable — path normalisation, WAL `-shm`
 cleanup, and short-name path quirks are all platform-sensitive.