@exellix/jobs-ui 1.0.1 → 2.0.2

package/README.md

@@ -1,64 +1,71 @@
 # @exellix/jobs-ui
 
-Read-only **query + HTTP** layer over the Exellix job queue. Lists, groups, and counts **job runs** from [`@exellix/exellix-db`](../exellix-db/README.md). No execution rights — no `enqueue` / `claim` / `complete` / `fail`.
+**Jobs dashboard** — React operator SPA for the Exellix job queue. Queue overview, run detail, record-centric views, Source→Records workflow, and work-factory wizards (continuous work, batches, on-demand).
 
-> A **JobRun** is one graph run on one input. See [`temp/jobs/`](../temp/jobs/README.md) for the design. This package replaces the old `@exellix/exellix-matrix-read`.
+| Package | Role |
+|---------|------|
+| [`@exellix/jobs`](../jobs/README.md) | Jobs **manager** — queue runtime, worker loop, CLI |
+| [`@exellix/jobs-api`](../jobs-api/README.md) | Jobs **HTTP API** — REST server this UI talks to |
+| **`@exellix/jobs-ui`** (this) | Jobs **dashboard** — React SPA only |
+| [`@exellix/jobs-db`](../jobs-db/README.md) | Jobs **data tier** — Mongo persistence |
+
+> A **JobRun** is one graph run on one input. See [`temp/jobs/`](../temp/jobs/README.md) for the design.
+
+> **Migration from 1.x:** `@exellix/jobs-ui@1.x` bundled the HTTP API and dashboard in one package. **2.x is dashboard-only** — use [`@exellix/jobs-api`](../jobs-api/README.md) for the REST server and programmatic queries.
 
 ## Install
 
 ```bash
-npm install @exellix/jobs-ui @exellix/exellix-db
+npm install @exellix/jobs-ui
 ```
 
-## Queries
+The dashboard requires a running `@exellix/jobs-api` instance (or any host serving the same `/api/*` contract).
 
-```ts
-import { createJobRunStore } from '@exellix/exellix-db';
-import { listRuns, getRun, groupByItem, countByStatus, countRuns } from '@exellix/jobs-ui';
+## Quick start
 
-const { store } = await createJobRunStore({ mongoUri: process.env.MONGO_URI });
+```bash
+# terminal 1 — API backend (needs MONGO_URI)
+cd ../jobs-api && npm run serve
 
-await listRuns(store, { jobDefId, status: 'pending', page: 1, pageSize: 50 });
-await getRun(store, jobRunId);
-await groupByItem(store, itemId);          // all runs for one source item
-await countByStatus(store, jobDefId);      // { blocked, pending, running, done, failed }
-await countRuns(store, { graphId, status });
+# terminal 2 — UI with HMR
+npm run dev            # Vite on :5190, proxies /api → http://localhost:3099
 ```
 
-## HTTP server
-
-```bash
-# MONGO_URI must be set (or available in ../graph-engine/.env via the workspace)
-npm run ui:serve            # → jobs-ui listening on http://0.0.0.0:3099
-# or, after install:
-npx exellix-jobs-ui serve
-```
+Set `VITE_API_PROXY` to point at a remote API during dev. Set `VITE_DEV_PORT` to change the dev server port.
 
-Set `PORT` to override the default `3099`.
+### Combined deploy (single port)
 
-| Route | Returns |
-|-------|---------|
-| `GET /health` | liveness |
-| `GET /runs` | paged list (query: `jobDefId`, `status`, `itemId`, `graphId`, `page`, `pageSize`) |
-| `GET /runs/:id` | a single job run (404 if missing) |
-| `GET /items/:itemId/runs` | all job runs for one source item |
-| `GET /stats/by-status` | counts by status (optional `?jobDefId=`) |
+Build the UI, then let the API serve it:
 
 ```bash
-curl http://localhost:3099/health
-curl "http://localhost:3099/runs?status=pending&pageSize=20"
-curl http://localhost:3099/stats/by-status
+npm run build
+cd ../jobs-api && JOBS_UI_STATIC_DIR=../jobs-ui/dist npm run serve
 ```
 
-There is no bundled HTML dashboard; this package is the read API a frontend builds on.
+## Browser routes
+
+| Route | Page |
+|-------|------|
+| `/` | Queue Overview |
+| `/runs` | Runs list |
+| `/runs/:id` | Run detail |
+| `/sources` | Source picker |
+| `/records` | Records list |
+| `/records/:recordId` | Record detail |
+| `/items/:itemId` | Item timeline + DAG |
+| `/jobs/new` | Create / enqueue job |
+| `/job-defs` | Job definition list |
+| `/job-defs/:id` | Job definition detail |
+| `/settings` | App-wide queue execution settings |
+
+Work-factory routes: `/work`, `/work/:id`, `/batches/:id`, on-demand flows — see [`jobs-api` HTTP docs](../jobs-api/README.md).
 
 ## Scripts
 
 ```bash
-npm run build      # tsc → dist/
-npm test           # unit + live (live runs only when MONGO_URI is set)
-npm run test:live  # live Mongo integration tests only
-npm run ui:serve   # start the HTTP server
+npm run build       # vite build → dist/
+npm run dev         # Vite dev server + API proxy
+npm test            # build smoke test + graph-picker unit tests
 ```
 
 ## License