@webfueler/oc-dash 0.1.5 → 0.1.7

package/README.md

@@ -1,176 +1,122 @@
 # oc-dash
 
-A small local webapp that reads the opencode2 service API and shows session
-costs, token totals, and the subagent spend the opencode2 TUI never displays.
-
-Single package: Hono backend on Node 22, React + Vite + TypeScript frontend,
-plain CSS, inline-SVG activity chart. No chart library, no CSS framework.
-
-## What it shows
-
-- **Cost hero** — one hero card with the range's total cost (USD, money-green),
-  a `≈ $X/day` figure where the range spans full days (omitted for today), and
-  a compact stat strip below it: tokens, prompts · steps, sessions ·
-  subagents, active days · streak. When the stats endpoint is unavailable, the
-  hero carries a fallback badge and the strip shows totals computed from the
-  session list instead.
-- **Sessions table** — every session in the range with title, agent, model
-  chip (full `provider/model · variant` string on hover), own cost, **incl.
-  subagents** (recursive: parent cost plus the cost of all descendants at any
-  depth), tokens, last activity, and outcome. Child sessions nest under their
-  parent, **collapsed by default**: clicking a parent row (or focusing it and
-  pressing Enter/Space) expands its subagents, and Expand all / Collapse all
-  buttons sit in the section head. Tree state resets when the range changes.
-  Rows whose outcome is `succeeded` render a dim check; `failed` and
-  `interrupted` keep loud badges. A project filter is built from the session
-  directories.
-- **Models table** — steps, tokens, and cost per model, with an `unpriced`
-  flag on models that burn tokens but report zero cost.
-- **Activity chart** — steps per day, drawn as inline SVG: bars are
-  width-capped and slot-centered, dotted gridlines mark 25/50/75% of the peak,
-  zero-step days stay visible as stubs, and the Today range shows the trailing
-  7 days with the in-range day accented (`/api/summary` gains an additive,
-  Today-only `contextActivity` field for this).
-
-Refreshes every 30 seconds while the tab is visible; refreshes immediately
-when the tab becomes visible again.
-
-## Requirements
-
-- Node 22+
-- npm
-- A running local opencode2 service (the app only ever issues read-only GETs
-  and never stops or restarts the service)
-
-## Run without cloning
+Track exactly what AI usage costs in opencode2. oc-dash is a local dashboard
+over the service API that shows spend session by session, subagents included,
+under any time range and filter combination.
 
-```sh
-npx @webfueler/oc-dash
-```
+## What it looks like
 
-Needs Node 22+ and npm. Serves the built frontend and API from a single
-process on http://localhost:4021 (override with `PORT`, e.g.
-`PORT=4022 npx @webfueler/oc-dash`).
+One page: a cost hero, project and model filters with a filtered totals card,
+then the sessions table, the models table, and an activity chart.
 
-Prefer the short command? A global install puts it on your PATH:
+![oc-dash dashboard, dark mode, 7-day range: the total cost hero, the project and model filters with the project filter set to oc-setup and the filtered totals card below it, then the sessions table, the models table, and the activity chart.](docs/screenshot.png)
 
-```sh
-npm i -g @webfueler/oc-dash
-oc-dash
-```
+## What you can learn
 
-The dashboard only reads from the opencode2 service, which must already
-be installed and running. When no registered service answers the
-startup probe, oc-dash prints a short message and exits non-zero — it
-never starts, stops, or restarts a service. Start the service with:
+- The total spend for a range, with a per-day average when the range covers
+  full days, plus tokens, prompts, steps, sessions, subagents, and streaks.
+- Spend per project and per model under combined filters. Pick one or both;
+  the filtered totals card recomputes for the cut on screen.
+- Subagent spend. Child sessions nest under their parent, and the Incl.
+  subagents column rolls descendant cost into the parent at any depth.
+- Which sessions cost the most. Click the Own cost, Incl. subagents, or
+  Tokens header to sort; each cycles default, ascending, descending.
+- Which models burned tokens at zero reported cost. The Models table flags
+  them `unpriced`.
 
-```sh
-opencode serve --service
-```
+## Reading the numbers
+
+- A number served by the stats endpoint is exact for the window and filter
+  cut on screen.
+- When a cut cannot be served, the card sums the session rows instead and
+  marks the result `≈` (approximate). The fallback is labeled, never silent.
+- If stats and the session rows disagree about a model, the card says so
+  instead of showing either number.
+- Stats totals exclude compaction usage. Session rows and the directory
+  fallback include it, so the two totals can differ.
+- Costs are list-price estimates from models.dev, not your bill, and models
+  that burn tokens at zero reported cost are undercounted.
 
-If you don't have opencode yet, install it with
-`curl -fsSL https://opencode.ai/install | bash` (more options at
-https://opencode.ai).
+## Quick start
 
-## Install
+Requires Node 22+ with npm, and a running opencode2 service from the
+compatible beta line. oc-dash only issues read-only GETs and never starts,
+stops, or restarts the service.
 
 ```sh
-npm install
+npx @webfueler/oc-dash
 ```
 
-## Develop
+Serves the dashboard on http://localhost:4021. Override the port with `PORT`,
+for example `PORT=4022 npx @webfueler/oc-dash`.
 
-```sh
-npm run dev
-```
+When no registered service answers the startup probe, oc-dash prints a short
+message and exits non-zero. Start the service with `opencode2 serve --service`.
 
-Starts two processes: the API server on port 4021 and the Vite dev server on
-port 5273 (http://localhost:5273). The dev server proxies `/api/*` to 4021.
+No opencode2 yet? Install the beta line with
+`npm install -g @opencode-ai/cli@beta`; it puts the `opencode2` command on
+your PATH. Exact money needs the stats route, which the beta line serves
+(`@latest` does not yet). To skip `npx`, `npm i -g @webfueler/oc-dash` puts
+`oc-dash` on your PATH.
 
-## Build
+## Using the dashboard
 
-```sh
-npm run build
-```
+Ranges sit in the top bar: Today, 7 days, 30 days, All. A range switch
+refetches and collapses the session tree.
 
-Typechecks the frontend (`tsc --noEmit`), bundles it with Vite into `dist/`,
-and compiles the server with `tsc` into `dist-server/`.
+The project and model filters sit above the tables, each with an All entry
+and live counts. Type to search: projects match their full path, models their
+display name and raw id. The model filter ignores reasoning variants; held
+values survive range switches with a truthful 0 when nothing matches.
 
-## Start (production)
+The filtered totals card appears whenever either filter is active. Its money
+comes from the stats engine when the exact cut can be served; otherwise it is
+the row sum, marked `≈`. A project filter on its own unlocks extra stats
+tiles (prompts, steps, activity, any positive compaction gap); a model filter
+hides them.
 
-```sh
-npm run build
-npm run start
-```
+Sessions nest under their parent, collapsed by default. Click a parent row or
+press Enter/Space to expand it; Expand all and Collapse all sit in the
+section head. Own cost is the session's own spend, Incl. subagents adds every
+descendant. The model chip shows the display name, with the raw
+`providerID/id · variant` on hover.
 
-Serves the built frontend and the API from a single process on port 4021
-(override with `PORT`). Open http://localhost:4021.
+If the stats endpoint is down, the hero carries a fallback badge and totals
+from the session rows, the filtered card labels its money approximate, and
+the Models table stays empty. The dashboard refreshes every 30 seconds while
+the tab is visible, and right away when it becomes visible again.
 
-## Test
+## Known limits
 
-```sh
-npm test        # or: npx vitest run
-```
+- The opencode2 API and client are beta; a service update can change
+  behavior. Exact money needs a service that serves `session.stats`.
+- The session walk stops after 50 pages of 100 rows. When it truncates, the
+  dashboard warns and a directory filter falls back to the approximate row sum.
+- The service endpoint is discovered once and cached. If the service comes
+  back on a new port, restart the dashboard.
+- Without a healthy service at startup, oc-dash exits. It never starts or
+  restarts one.
 
-Unit tests cover session-tree nesting, the recursive rollup math, unpriced
-model detection, and the client-side fallback totals.
+## Development
 
-## Lint
+Stack: Hono on Node 22 serves the API and built frontend from one process.
+Frontend: React + Vite + TypeScript, plain CSS, inline-SVG chart. Tests use
+vitest across the server routes, walk, and client logic; lint uses eslint.
 
 ```sh
-npm run lint
+npm install
+npm run dev     # API on 4021, Vite on 5273, /api proxied to 4021
+npm run build   # typecheck, bundle the frontend, compile the server
+npm run start   # serve the build on 4021
+npm test        # vitest
+npm run lint    # eslint
 ```
 
-## API surface (this app's own backend)
-
-| Endpoint | Purpose |
-| --- | --- |
-| `GET /api/health` | Dashboard health plus the opencode service URL and health |
-| `GET /api/summary?range=today\|7d\|30d\|all` | `session.stats` for the resolved window, with `tools="summary"` and the machine's local IANA timezone |
-| `GET /api/sessions?range=today\|7d\|30d\|all` | Cursor-paginated `GET /api/session` walk (limit 100, capped at 50 pages), windowed by `time.updated >= range start` |
-
-Range mapping: `today` starts at local midnight; `7d` and `30d` start now
-minus N×24h; `all` omits `from`/`to` so stats fall back to the earliest
-message. Nesting, filtering, and cost rollup happen in the frontend.
-
-If the stats endpoint is unavailable, `/api/summary` answers with
-`{ "degraded": true, "reason": ... }` instead of an error page, and the UI
-falls back to totals computed from the session list (marked as degraded).
+The backend talks to the service through `@opencode/client`, pinned to an
+exact beta build, and is discover-only. See
+[docs/API.md](https://github.com/webfueler/oc-dash/blob/main/docs/API.md) for
+the backend routes, the range mapping, and the project layout.
 
-## How it connects
+## License
 
-The backend uses `@opencode/client` (pinned to the `beta` dist-tag) and is
-discover-only: `Service.discover()` finds a healthy registered service and
-never starts, stops, or restarts one. If nothing healthy is registered when
-the dashboard starts, it prints a short message (start `opencode serve
---service`) and exits. If the service dies later, the UI shows its degraded
-state instead of crashing. Calls go through the typed client with a raw-fetch
-fallback (`Service.headers(endpoint)` auth attached).
-
-The discovered endpoint is cached for the life of the dashboard process, so
-if the opencode service comes back on a different port, restart the
-dashboard too.
-
-## Estimate caveats (read before quoting numbers)
-
-- Session costs and the stats totals are **list-price estimates** based on
-  models.dev pricing data, not your actual bill.
-- Providers without price data are **undercounted**: models flagged
-  `unpriced` in the Models table burn real tokens but report zero cost, so
-  real spend is higher than shown.
-- The stats endpoint adds **compaction usage** (not attributed to any
-  session) to the totals, so KPI totals can legitimately exceed the sum of
-  the session rollups in the table.
-- Subagent spend rolls up into the parent row; the opencode2 TUI does not
-  show this.
-
-## Project layout
-
-```
-server/          Hono backend (entry, service connection, range mapping)
-src/             React frontend (components, tree/rollup logic, formatting)
-src/*.test.ts    Unit tests (vitest)
-bin/oc-dash.js   npx launcher (runs the compiled server)
-dist/            Built frontend (gitignored)
-dist-server/     Compiled server (gitignored)
-```
+MIT. Source, issues, and releases: https://github.com/webfueler/oc-dash.