[ Feature - Dashboard ] Topology Grouping schema + assignment endpoints

[mitulgarg]

Phase 2 — Grouping schema + assignment endpoints

 Backend

 src/env_doctor/server/models.py — add to Machine:

 group_name = Column(String(64), nullable=True, index=True)

 Base.metadata.create_all() auto-adds the column on next startup for new DBs. For existing DBs SQLite will not
 retroactively add columns — add a one-shot migration in database.py:init_db() that runs ALTER TABLE machines ADD
 COLUMN group_name VARCHAR(64) inside a try/except OperationalError (idempotent: the OperationalError on second run
 means the column already exists).

 src/env_doctor/server/routes.py — add two endpoints:

 - PATCH /api/machines/{id} — body MachineUpdate(group_name: str | None). Pydantic model with group_name:
 Optional[str] = Field(None, max_length=64). Empty string → None (ungroup). Sanitise: strip whitespace, reject names
 containing / or control chars.
 - GET /api/groups — returns [{name, machine_count, status_breakdown: {pass, warning, fail}}]. Single SQL: SELECT
 group_name, COUNT(*), SUM(CASE WHEN latest_status='pass'...) GROUP BY group_name. Treat NULL as the synthetic group
 "ungrouped" in the response.

 POST /report ingest (routes.py ~line 100): if the inbound payload includes machine.group_name, persist it. Optional —
  keeps CLI ↔ dashboard symmetric so a machine can self-tag at registration time. Don't require it.

 Frontend types — web/src/types.ts

 - Add group_name: string | null to both MachineListItem and MachineDetail.
 - Add interface MachineGroup { name: string; machine_count: number; status_breakdown: { pass: number; warning:
 number; fail: number } }.

 Frontend API — web/src/api.ts

 - updateMachineGroup(id: string, group_name: string | null): Promise<MachineDetail> → PATCH wrapper.
 - getGroups(): Promise<MachineGroup[]>.

 MachineDetail inline-edit (web/src/pages/MachineDetail.tsx)

 Add a "Group" row in the summary cards block (~line 114-127). Display: current group name or "—". Click to edit →
 small inline <GroupPicker> (see component below). On save → updateMachineGroup() → optimistic update + refetch. This
 is the first inline-edit pattern in the app — keep it minimal: no modal, just an in-place swap between label and
 picker.

 New shared component — web/src/components/GroupPicker.tsx

 Compact combobox (no library — <input list> won't style well in dark theme):
 - Text input with a dropdown showing existing groups (from getGroups()).
 - Free typing creates a new group on submit (no separate "create" step — the group exists implicitly once a machine
 is assigned to it).
 - Empty submit → ungroup.
 - Props: { value: string | null, onChange: (next: string | null) => void, groups: MachineGroup[] }.
 - Reused by MachineDetail (inline) and by Topology's floating action bar (Phase 3) and Fleet's filter chip (Phase 3).

[mitulgarg]

---

Technical implementation Plan

Phase 2 — Steps

Step 1 · Backend schema + migration

src/env_doctor/server/models.py

• Add group_name = Column(String(64), nullable=True, index=True) to Machine
• Add group_name to Machine.to_dict() so it flows out of every existing /api/machines* endpoint

src/env_doctor/server/database.py

• In init_db(), after create_all(), run an idempotent ALTER TABLE machines ADD COLUMN group_name VARCHAR(64) wrapped in
  try/except OperationalError (no-op when column already exists)
• Idempotent CREATE INDEX IF NOT EXISTS ix_machines_group_name ON machines(group_name)

Step 2 · Backend endpoints

src/env_doctor/server/routes.py

• New MachineUpdate Pydantic model: group_name: Optional[str] = Field(None, max_length=64)
• PATCH /api/machines/{machine_id}:
  • 404 if machine missing
  • Strip whitespace; reject names containing / or any control character (return 400 with reason)
  • Empty / whitespace-only → set NULL (ungroup)
  • Persist + return full updated machine dict (same shape as GET /api/machines/{id})
• GET /api/groups:
  • Single SQL: GROUP BY group_name with COUNT(*) and conditional sums for pass/warning/fail
  • NULL → synthetic "ungrouped" group, listed last
  • Returns [{name, machine_count, status_breakdown: {pass, warning, fail}}], real groups sorted alphabetically
• POST /api/report upsert: optionally read machine.group_name from payload (allows CLI self-tagging via env-doctor check
  --report-to ... --group later); add group_name field to MachineInfo Pydantic model

Step 3 · Frontend types + API

web/src/types.ts

• group_name: string | null on MachineListItem (auto-inherited by MachineDetail)
• New MachineGroup interface

web/src/api.ts

• updateMachineGroup(id, group_name): Promise — PATCH wrapper
• getGroups(): Promise<MachineGroup[]>

Step 4 · GroupPicker component (reusable across phases)

web/src/components/GroupPicker.tsx (new)

A compact combobox built on a single + dropdown — no library:

• Props: { value, onChange, groups, autoFocus?, onClose? }
• Dropdown lists existing groups, filtered live as you type
• If the typed text doesn't exact-match any group, prepend a + Create "" option
• Keyboard: ↑/↓ navigates, Enter commits, Esc closes
• "Clear / Ungroup" affordance for explicit removal
• Click-outside closes (via useEffect listener on document)

This component is built once and reused in Phase 3 (Topology action bar) and Fleet filter, so it has to be solid.

Step 5 · MachineDetail inline edit

web/src/pages/MachineDetail.tsx

• Add a Group card as the first card in the summary row (line 114-127), so the row becomes [Group | GPU | Driver | CUDA
  | PyTorch | Issues]
• Default state: shows current group name or — with a hover-only "edit" affordance
• Click → swap card content for inline
• On commit: optimistic UI update (immediate setMachine) + updateMachineGroup() API call; on error, revert and surface
  error inline
• Esc / click-outside cancels without saving

Step 6 · Verification

1. python -m pytest tests/unit/server/ -q — all 18 existing tests still green
2. npx tsc --noEmit — no type errors
3. Smoke test via httpx (the same harness used in Phase 1):
   - PATCH /api/machines/ with valid name → 200 + group_name set
   - PATCH with {"group_name": "bad/name"} → 400
   - PATCH with {"group_name": ""} → ungroups
   - GET /api/groups → counts match reality, ungrouped listed last
4. UI hand-test (you'll do this): build + open dashboard, edit group on a machine, confirm it sticks across refresh

---

Out of scope this phase (deferred to Phase 3)

• Group filter chip on Fleet table
• Group column on Fleet table
• Topology canvas changes (toolbar, multi-select, group bubbles)

These all consume the same getGroups() + updateMachineGroup() plumbing I'll add now, so Phase 3 stays focused on UX
rather than backend.

---

[mitulgarg]

completed in #129