feat(ui): the Health screen, and a tab that stops being dimmed

`SCREENS.health`, `PdSidebar`'s `NOT_YET` down to `['security']`, and a screen that owns the
folder, the run, the progress and the errors while `PdHealthReport` owns the tabs.

**A bug found by opening the screen, not by any test.** With a folder remembered and no run
yet, it said *no issues found* — nothing had run, so there was nothing to have found. That
is the identical lie a tab keyed on `ran` alone tells about a failed tool, one level up and
in code written by someone who had just spent a commit preventing it. It now says *not
checked yet · Press Run to check this folder*, which is a state rather than a claim.

Driven against a stubbed bridge in a real browser, which is how the above surfaced and how
the rest was confirmed rather than assumed:

* `Ctrl+6` reaches Health and the `<h1>` takes focus, so the next Tab resumes in the new
  screen.
* The remembered folder arrives on `EnvRow.healthProject` — the button reads *Change
  folder…* rather than *Choose folder…* on a first visit, which is the whole read path
  end to end.
* `plugin:event|listen` crosses the bridge **before** `health_run`, so the tools-venv
  bootstrap is not emitted into nothing.
* The three tab counts are 4/3/6 against a fixture carrying 4/3/6. Nothing is recomputed.
* `requests` — unused *and* installed — offers *Review in Uninstall…*; `httpx`, unused and
  not installed here, does not; `yaml`, a DEP001, does not either.
* On the partial report: the ruff tab reads *did not finish*, vulture reads *not run*,
  deptry still reports its four findings, `PdErrorRow` carries `PD-HLT-001` with its
  localized one-liner above the tabs, and the status line reads `⚠ 1`.

`useEnvPackages` rather than a fourth copy of that effect, and rather than the `loadPackages`
-only variant an earlier draft of the plan called for: the hook's own doc comment explains
that `loadedFor` is one flag covering two calls, so a screen loading only `pkg_list` would
set it and leave every row's badge permanently `unknown`. One networked `pkg_outdated` this
screen does not use is the price of not reintroducing that.

`asError` converts a `ToolProblem` for `PdErrorRow`. The two are the same shape by design but
not the same type: `exactOptionalPropertyTypes` is on and the generator emits `?: T | null`,
so an absent `stderrTail` and a null one are different and neither is `string`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-13 18:49:59 +07:00
1 parent 1b909deb33
commit aa839545c2
5 files changed
+221 -1

No files matched your search

+2
View File
@@ -9,6 +9,7 @@ import { PdStatusLine } from '@/components/PdStatusLine'
import { PdUninstallDialog } from '@/components/PdUninstallDialog'
import type { NavKey } from '@/components/nav'
import { PdEnvironments } from '@/screens/PdEnvironments'
import { PdHealth } from '@/screens/PdHealth'
import { PdPackages } from '@/screens/PdPackages'
import { PdPins } from '@/screens/PdPins'
import { PdPlanPanel } from '@/screens/PdPlanPanel'
@@ -28,6 +29,7 @@ const SCREENS: Partial<Record<NavKey, React.ReactNode>> = {
updates: <PdPackages mode="updates" />,
search: <PdSearch />,
pins: <PdPins />,
health: <PdHealth />,
settings: <PdSettings />,
}
+1 -1
View File
@@ -4,7 +4,7 @@ import { NAV_KEYS, type NavKey } from '@/components/nav'
import { useEnvStore, useUiStore } from '@/stores'
/** Tabs whose screens land in a later milestone. Kept in place, not hidden. */
const NOT_YET: readonly NavKey[] = ['health', 'security']
const NOT_YET: readonly NavKey[] = ['security']
/**
* The sidebar — UI-SPEC §3 and §8.
+2
View File
@@ -221,6 +221,8 @@
"failed": "did not finish",
"failedHint": "See the problem reported above.",
"clean": "no issues found",
"notRunYet": "not checked yet",
"notRunYetHint": "Press Run to check this folder.",
"notebooks": "Jupyter notebooks (.ipynb) are excluded from every report.",
"tabLabel": {
"deptry_one": "Dependencies, {{count}} finding",
+2
View File
@@ -207,6 +207,8 @@
"failed": "không hoàn tất",
"failedHint": "Xem lỗi được báo ở trên.",
"clean": "không phát hiện vấn đề nào",
"notRunYet": "chưa kiểm tra",
"notRunYetHint": "Nhấn Chạy để kiểm tra thư mục này.",
"notebooks": "Jupyter notebook (.ipynb) được loại khỏi mọi báo cáo.",
"tabLabel": {
"deptry_other": "Phụ thuộc, {{count}} phát hiện",
+214
View File
@@ -0,0 +1,214 @@
/**
* Code Health — UI-SPEC §4's one sentence, CODE-HEALTH-SPEC §5's run header and tabs.
*
* The screen owns the folder, the run, the progress and the errors; `PdHealthReport` owns the
* three tabs and is given a report. The division is the one `PdPlanPanel`/`PdPreviewDiff` uses,
* and it is what lets the tabs be tested against a fixture with no store at all.
*
* **The folder is remembered per environment, and it arrives on the row.** `EnvRow.healthProject`
* is filled by `env_scan` and `env_probe` from the same `health_projects` table the CLI writes,
* so the second run in a project costs one click fewer than the first — which is the difference
* between UI-SPEC §5's budget of 3 and the 4 a first run actually takes.
*/
import { useEffect } from 'react'
import { useTranslation } from 'react-i18next'
import { PdConsoleDrawer } from '@/components/PdConsoleDrawer'
import { PdEmptyState } from '@/components/PdEmptyState'
import { PdErrorRow } from '@/components/PdErrorRow'
import { PdHealthReport } from '@/components/PdHealthReport'
import { pickProjectFolder } from '@/ipc'
import type { PdError, ToolProblem } from '@/ipc'
import { useEnvPackages } from '@/screens/useEnvPackages'
import { freshReport, useEnvStore, useHealthStore, usePlanStore } from '@/stores'
/**
* A failed tool as an error row.
*
* `ToolProblem` is `PdError`-shaped on purpose, but not identically typed: `exactOptionalPropertyTypes`
* is on and the generator emits `?: T | null` for every `Option<T>`, so an absent `stderrTail` and
* a null one are different types and neither is `string`. Same conditional spread
* `PdSummarySheet` uses.
*/
function asError(problem: ToolProblem): PdError {
return {
code: problem.code,
message: problem.message,
...(problem.stderrTail == null ? {} : { stderrTail: problem.stderrTail }),
}
}
export function PdHealth() {
const { t } = useTranslation()
const selected = useEnvStore((s) => s.selected)
const rows = useEnvStore((s) => s.rows)
const dists = useEnvStore((s) => s.dists)
const startUninstall = usePlanStore((s) => s.startUninstall)
// Per-field selectors throughout, for `PdPackages`' reason: destructuring the store re-renders
// a report of several hundred rows on every unrelated field change, including each progress tick.
const folder = useHealthStore((s) => s.folder)
const report = useHealthStore((s) => s.report)
const reportFor = useHealthStore((s) => s.reportFor)
const ruffByFile = useHealthStore((s) => s.ruffByFile)
const tab = useHealthStore((s) => s.tab)
const phase = useHealthStore((s) => s.phase)
const error = useHealthStore((s) => s.error)
const consoleLines = useHealthStore((s) => s.console)
const done = useHealthStore((s) => s.done)
const total = useHealthStore((s) => s.total)
const consoleOpen = useHealthStore((s) => s.consoleOpen)
const setFolder = useHealthStore((s) => s.setFolder)
const setTab = useHealthStore((s) => s.setTab)
const setConsoleOpen = useHealthStore((s) => s.setConsoleOpen)
const run = useHealthStore((s) => s.run)
const row = rows.find((r) => r.interpreter === selected)
// Hoisted, for `PdPackages`' reason: a narrowing that has to be re-derived inside a closure is
// one the compiler cannot carry, and `row?.env` is exactly that shape.
const env = row?.env
// `dists` belongs to the package slice and is only filled once the user has visited Installed
// or Updates. Without this the deptry handoff's button would appear or vanish depending on
// which tab they happened to open first — "never render a state you have not loaded", in
// reverse. The hook guards on `loadedFor` and does not refetch.
useEnvPackages()
// The remembered folder, taken from the row the moment one is known. Not a fallback inside the
// render: `setFolder` resets the report when the folder actually changes, and calling it during
// render would reset on every pass.
useEffect(() => {
if (row?.healthProject !== undefined && folder === null) setFolder(row.healthProject)
}, [row?.healthProject, folder, setFolder])
const running = phase === 'running'
// Only when it describes *this* environment and folder. A plain `report` read would show one
// environment's findings after the user switched to another.
const shown = row === undefined ? null : freshReport({ report, reportFor, folder }, row.envHash)
const choose = () => {
void pickProjectFolder(t('health.pickerTitle'), folder ?? undefined).then((chosen) => {
if (chosen !== null) setFolder(chosen)
})
}
return (
<section aria-labelledby="health-title" className="flex h-full min-h-0 flex-col p-6">
<h1 id="health-title" className="shrink-0 text-accent">
{t('health.title')}
</h1>
{row === undefined ? (
<PdEmptyState
message={t('health.noEnvironment')}
hint={t('health.noEnvironmentHint')}
/>
) : (
<>
<div className="mt-4 flex shrink-0 flex-wrap items-center gap-3">
{/* A path is data and is never localized (I18N §2). */}
<code className="min-w-0 flex-1 truncate font-mono text-data text-text-dim">
{folder ?? t('health.noFolder')}
</code>
<button
type="button"
className="rounded-pd border border-border px-2 py-1 text-data hover:bg-surface-2"
disabled={running}
onClick={choose}
>
{folder === null ? t('health.chooseFolder') : t('health.changeFolder')}
</button>
<button
type="button"
data-action="run-health"
className="rounded-pd bg-accent px-3 py-1 text-data text-bg disabled:opacity-50"
disabled={running || folder === null || env === undefined}
onClick={() => {
if (env !== undefined) void run(env, row.envHash)
}}
>
{running ? t('health.running') : t('health.run')}
</button>
<button
type="button"
className="rounded-pd border border-border px-2 py-1 text-data text-text-dim hover:bg-surface-2"
onClick={() => {
setConsoleOpen(!consoleOpen)
}}
>
{t('health.log')}
</button>
</div>
{/* One live region for the screen, announcing the same `done/total` the drawer shows. */}
<p aria-live="polite" className="mt-2 shrink-0 text-data text-text-dim">
{running && total > 0 ? t('plan.progress', { done, total }) : ''}
</p>
{/* A run that failed outright — distinct from a *tool* that failed, which is below. */}
{error !== null ? (
<div className="mt-2 shrink-0">
<PdErrorRow error={error} />
</div>
) : null}
{/* Above the tabs, and counted into `⚠ n`. A failed tool is a problem currently on
screen, and there are at most three of them — this is not `PdSummarySheet`'s
one-row-per-package case. Above rather than inside a tab, because the explanation
must not be reachable only from the tab it explains. */}
{(shown?.problems ?? []).map((problem) => (
<div key={problem.tool} className="mt-2 shrink-0">
<PdErrorRow error={asError(problem)} />
</div>
))}
{shown === null ? (
// **Never "no issues found" here.** No run has happened, so there is nothing to have
// found — saying otherwise is the same lie a tab keyed on `ran` alone tells about a
// failed tool, one level up. Found by opening the screen with a remembered folder and
// reading what it said before anything ran.
<PdEmptyState
message={folder === null ? t('health.noFolder') : t('health.notRunYet')}
hint={folder === null ? t('health.noFolderHint') : t('health.notRunYetHint')}
/>
) : (
<div className="mt-4 flex min-h-0 flex-1 flex-col">
<p className="shrink-0 text-data text-text-dim">
{t('health.checkedAt', { when: shown.ranAt })}
</p>
<PdHealthReport
report={shown}
ruffByFile={ruffByFile}
tab={tab}
onTab={setTab}
installed={dists.map((d) => d.name)}
onUninstall={
env === undefined
? undefined
: (distribution) => {
// `PdUninstallDialog` is mounted outside `<main>`, so this opens over
// Health with no navigation. On confirm the plan panel takes the content
// area; the report survives because it lives in the store.
void startUninstall(env, [distribution])
}
}
/>
</div>
)}
</>
)}
<PdConsoleDrawer
lines={consoleLines}
open={consoleOpen}
done={done}
total={total}
onClose={() => {
setConsoleOpen(false)
}}
/>
</section>
)
}