feat(miner-ui): read-only run-history table over the local run-state store

[reyanthony062001-ops]

Closes #4305

What

A read-only run-history table view in apps/gittensory-miner-ui/ — one row per repo from the local miner_run_state store (repository, state badge, last-updated) — plus the minimal local data-access layer the issue calls for so the browser app can read a node:sqlite file on disk.

Design, per the issue's guidance

• Data-access layer = a Vite dev/preview middleware (the issue's suggested shape): vite-run-state-api.ts serves GET /api/run-state by calling into packages/gittensory-miner/lib/run-state.js's EXISTING exports (resolveRunStateDbPath/listRunStates) — no SQL duplicated in the UI layer, wired into both configureServer and configurePreviewServer.
• Strictly read-only, including the fresh-install path: listRunStates() lazily initializes the default store, which would CREATE the SQLite file on a fresh install — a write a read-only dashboard must not perform. The handler therefore checks the resolved DB path for existence first and serves { rows: [] } without ever touching the store when no DB exists yet (asserted in tests: no listRunStates call happens on that path).
• The view (src/routes/run-history.tsx, mounted in the shell's nav) renders four states: loading, error (API unreachable/500 — an inline alert, never a crash), the fresh-install empty state, and the populated table. The fetch client (src/lib/run-history.ts) validates the payload shape field-by-field before it reaches the view.
• routeTree.gen.ts regenerated and committed via the router plugin (same as the scaffold).

Testing

14 cases across two suites: component tests for all four view states against fixture run-state rows plus the page-level injected-loader flow, fetch-client tests (happy path, non-2xx, three malformed-payload shapes, thrown fetch), and middleware-handler tests (rows served through the existing exports, the no-write fresh-install path, non-GET/other-path fall-through, store-failure → 500). Workspace test/typecheck/lint/build all green locally; the diff is confined to apps/gittensory-miner-ui/**.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-10 07:15:35 UTC}

8 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds a read-only run-history view to the miner UI: a Vite dev/preview middleware (`vite-run-state-api.ts`) that reads rows via the existing `run-state.js` exports without ever creating the SQLite file on a fresh install, a typed fetch client with field-by-field payload validation, and a route/table component with loading/error/empty/populated states. The read-only guard (check file existence before calling `listRunStates()`) is correctly implemented and directly tested (`run-state-api.test.ts` asserts `listed === false` on the fresh-install path), and the client rejects malformed payloads defensively rather than crashing. The one open question I can't verify from this diff is whether `packages/gittensory-miner/lib/run-state.js`'s actual `state` values are limited to the four literals (`idle/discovering/planning/preparing`) hardcoded in `run-history.ts`/`STATE_BADGE_CLASSES` — if the real store emits any other state, the client's `isRunStateRow` guard rejects the whole payload as malformed and the view shows an error instead of the table.

Nits — 5 non-blocking

• Verify `packages/gittensory-miner/lib/run-state.js`'s `state` column actually only ever contains `idle`/`discovering`/`planning`/`preparing` (apps/gittensory-miner-ui/src/lib/run-history.ts:9-25) — if the store has any other value, `fetchRunStates` will reject the whole response as malformed rather than degrading gracefully for just that row.
• apps/gittensory-miner-ui/vite-run-state-api.ts:43,45,48 — the raw status codes 200/200/500 could be named constants for readability, though this is purely stylistic.
• apps/gittensory-miner-ui/src/routes/run-history.tsx:78 and vite-run-state-api.ts:63 have somewhat deep nesting per the static-analysis pass; consider an early return to flatten, though it's not hurting readability much as written.
• routeTree.gen.ts's `as any` casts are generated boilerplate consistent with the file's existing pattern (unchanged lines already used the same style) — not something to fix by hand.
• Consider a unit test asserting that an unexpected `state` value (e.g. `"completed"`) from the API surfaces as the typed error state rather than silently failing, to document the current fail-closed behavior at apps/gittensory-miner-ui/src/lib/run-history.ts:16-25.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4305
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 26 registered-repo PR(s), 16 merged, 1 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	reyanthony062001-ops; Gittensor profile; 26 PR(s), 1 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The PR adds the read-only run-history table view (src/routes/run-history.tsx) rendering repo/state/last-updated from a fixture-driven fetch client, plus a Vite dev/preview middleware (vite-run-state-api.ts) that calls into run-state.js's existing resolveRunStateDbPath/listRunStates exports rather than duplicating SQL, explicitly avoids the lazy-init write on a fresh install by checking file existe

Review context

• Author: reyanthony062001-ops
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 26 PR(s), 1 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

Visual preview

Route	Viewport	Before (production)	After (this PR's preview)	Diff
/	desktop			—
/	mobile			—
/run-history	desktop			—
/run-history	mobile			—

Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.