kawa/ImpTune
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Commit initial

Browse Source
This commit is contained in:
kawa
2026-04-15 17:57:12 +02:00
parent 005d8e797e
commit 55516ee10f
269 changed files with 26854 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/phases/07-dashboard-nav-polish/07-01-PLAN.md
+228
View File
@@ -0,0 +1,228 @@
---
phase: 07-dashboard-nav-polish
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
- imptune/api/pages.py
- imptune/templates/dashboard.html
- imptune/templates/packages.html
- tests/test_static.py
autonomous: true
requirements: []
must_haves:
truths:
- "GET /packages returns 200 with a list of printers that have drivers assigned"
- "Dashboard shows the 5 most recently created printers from the database"
- "Dashboard shows the 5 most recently created printers with a driver assigned (recent packages)"
- "All existing tests remain green after changes"
artifacts:
- path: "imptune/templates/packages.html"
provides: "Packages listing page template"
contains: "extends \"base.html\""
- path: "imptune/api/pages.py"
provides: "/packages route and fixed dashboard queries"
exports: ["packages_page"]
- path: "tests/test_static.py"
provides: "Integration tests for /packages and dashboard data"
contains: "test_packages_returns_200"
key_links:
- from: "imptune/api/pages.py"
to: "imptune/db/models.py"
via: "Printer.select().order_by(Printer.created_at.desc()).limit(5)"
pattern: "Printer\\.select\\(\\)"
- from: "imptune/api/pages.py"
to: "imptune/templates/packages.html"
via: "TemplateResponse name='packages.html'"
pattern: "packages\\.html"
- from: "imptune/templates/base.html"
to: "imptune/api/pages.py"
via: "nav link href='/packages' resolves to packages_page route"
pattern: "/packages"
---
<objective>
Fix the broken /packages nav link (404) and wire the dashboard to show real data from the database.
Purpose: Close two visible integration gaps -- the /packages nav link returns 404 and the dashboard always shows empty lists despite real data existing in the database.
Output: Working /packages page, dashboard with live recent printers and recent packages queries, integration tests proving all three success criteria.
</objective>
<execution_context>
@C:/Users/SebastienQUEROL/.claude/get-shit-done/workflows/execute-plan.md
@C:/Users/SebastienQUEROL/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/07-dashboard-nav-polish/07-RESEARCH.md
<interfaces>
<!-- Key types and contracts the executor needs. -->
From imptune/db/models.py:
```python
class Client(BaseModel):
name = CharField(unique=True)
created_at = DateTimeField(default=datetime.utcnow)
class Driver(BaseModel):
sha256 = CharField(unique=True, index=True)
original_filename = CharField()
driver_desc = CharField(null=True)
uploaded_at = DateTimeField(default=datetime.utcnow)
class Printer(BaseModel):
name = CharField()
ip_address = CharField()
port_name = CharField()
client = ForeignKeyField(Client, null=True, backref="printers")
driver = ForeignKeyField(Driver, null=True, backref="printers")
created_at = DateTimeField(default=datetime.utcnow)
```
From imptune/api/pages.py (established pattern):
```python
router = APIRouter()
templates = Jinja2Templates(directory=str(Path(__file__).parent.parent / "templates"))
# All routes use deferred imports inside function body
# All routes use: templates.TemplateResponse(request=request, name="...", context={...})
# All queries use: list(Model.select()...) — never Model.get()
```
From tests/conftest.py:
```python
@pytest.fixture
def client(tmp_data_dir):
from imptune.main import app
with TestClient(app) as c:
yield c
```
</interfaces>
</context>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: Add integration tests for /packages route and dashboard data</name>
<files>tests/test_static.py</files>
<behavior>
- test_packages_returns_200: GET /packages returns status 200
- test_dashboard_shows_recent_printers: Create 2 Printer records in DB, GET / response body contains both printer names
- test_dashboard_shows_recent_packages: Create 2 Printer records (one with driver, one without), GET / response body contains the driver-assigned printer name in the packages section but not the driverless one
</behavior>
<action>
Add three test functions to the existing `tests/test_static.py` file. All tests use the `client` fixture from conftest.py.
For `test_packages_returns_200`: Simple GET /packages, assert status_code == 200.
For `test_dashboard_shows_recent_printers`:
1. Import Client, Driver, Printer from imptune.db.models
2. Create 2 Printer records with distinct names (e.g. "TestPrinter-Alpha", "TestPrinter-Beta") using Printer.create(name=..., ip_address="10.0.0.1", port_name="IP_10.0.0.1")
3. GET /, assert both printer names appear in response.text
4. Assert "No printers configured yet" NOT in response.text
For `test_dashboard_shows_recent_packages`:
1. Create a Driver record: Driver.create(sha256="abc123", original_filename="test.zip", size_bytes=1000, driver_desc='["TestDriver"]')
2. Create Printer with driver assigned: Printer.create(name="PkgPrinter-Assigned", ip_address="10.0.0.2", port_name="IP_10.0.0.2", driver=driver)
3. Create Printer without driver: Printer.create(name="PkgPrinter-NoDriver", ip_address="10.0.0.3", port_name="IP_10.0.0.3")
4. GET /, assert "PkgPrinter-Assigned" appears in response.text
5. Assert "No packages exported yet" NOT in response.text
These tests will FAIL initially (RED) because /packages returns 404 and dashboard hardcodes empty lists.
</action>
<verify>
<automated>cd C:/Users/SebastienQUEROL/Documents/projets/ImpTune && pytest tests/test_static.py -x 2>&1 | tail -20</automated>
</verify>
<done>Three new test functions exist in test_static.py. test_packages_returns_200 fails with 404, dashboard tests fail because response contains "No printers configured yet" / "No packages exported yet".</done>
</task>
<task type="auto">
<name>Task 2: Add /packages route, fix dashboard queries, create packages.html template</name>
<files>imptune/api/pages.py, imptune/templates/packages.html, imptune/templates/dashboard.html</files>
<action>
**imptune/api/pages.py** — Two changes:
1. Fix the `dashboard` function (lines 16-25). Replace hardcoded empty lists with real queries using deferred imports inside the function body:
```python
@router.get("/", response_class=HTMLResponse)
def dashboard(request: Request):
from imptune.db.models import Printer
recent_printers = list(
Printer.select().order_by(Printer.created_at.desc()).limit(5)
)
recent_packages = list(
Printer.select()
.where(Printer.driver.is_null(False))
.order_by(Printer.created_at.desc())
.limit(5)
)
return templates.TemplateResponse(
request=request,
name="dashboard.html",
context={
"recent_printers": recent_printers,
"recent_packages": recent_packages,
},
)
```
2. Add a new `/packages` route at the end of the file. Follow the exact same pattern as `printers_page` — deferred imports, LEFT_OUTER joins, list() wrapper:
```python
@router.get("/packages", response_class=HTMLResponse)
def packages_page(request: Request):
from imptune.db.models import Client, Driver, Printer
printers = list(
Printer.select(Printer, Client, Driver)
.join(Client, JOIN.LEFT_OUTER)
.switch(Printer)
.join(Driver, JOIN.LEFT_OUTER)
.where(Printer.driver.is_null(False))
.order_by(Printer.name)
)
return templates.TemplateResponse(
request=request,
name="packages.html",
context={"printers": printers},
)
```
**imptune/templates/packages.html** — Create new file extending base.html. Show a table of printers that have drivers assigned, with columns: Printer Name (linked to /printers/{id}), Client, Driver, and download links for Intune (.intunewin) and NinjaRMM (ZIP). Use the existing download URL patterns: `/printers/{id}/packages/intunewin` and `/printers/{id}/packages/ninja`. Show an empty state message if no package-ready printers exist. Use Pico CSS table styling (no custom classes needed beyond what base.html provides).
**imptune/templates/dashboard.html** — Update the printer list items to be clickable links. Change:
- `<li>{{ printer.name }} — {{ printer.ip_address }}</li>` to `<li><a href="/printers/{{ printer.id }}">{{ printer.name }}</a> — {{ printer.ip_address }}</li>`
- For recent_packages section, change `<li>{{ package }}</li>` to `<li><a href="/printers/{{ package.id }}">{{ package.name }}</a>{% if package.client_id %} — {{ package.client.name }}{% endif %}</li>` (the variable is a Printer object, not a string)
- Also update the quick-action links: "New Printer" href to "/printers", "Upload Driver" href to "/drivers", "Export Package" href to "/packages" — remove aria-disabled="true" from all three.
</action>
<verify>
<automated>cd C:/Users/SebastienQUEROL/Documents/projets/ImpTune && pytest tests/ -x 2>&1 | tail -20</automated>
</verify>
<done>GET /packages returns 200 with a table of package-ready printers. Dashboard shows real recent printers and recent packages from the database. All tests in the full suite pass including the 3 new tests from Task 1.</done>
</task>
</tasks>
<verification>
1. `pytest tests/ -x` — full test suite green
2. `pytest tests/test_static.py::test_packages_returns_200 -x` — /packages route works
3. `pytest tests/test_static.py::test_dashboard_shows_recent_printers -x` — dashboard shows real printers
4. `pytest tests/test_static.py::test_dashboard_shows_recent_packages -x` — dashboard shows real packages
</verification>
<success_criteria>
- GET /packages returns 200 and renders a page listing printers with drivers assigned
- Dashboard recent_printers section shows real Printer records from the database
- Dashboard recent_packages section shows Printer records that have a driver assigned
- Full test suite (pytest tests/ -x) passes with zero failures
- No regressions in existing tests
</success_criteria>
<output>
After completion, create `.planning/phases/07-dashboard-nav-polish/07-01-SUMMARY.md`
</output>
.planning/phases/07-dashboard-nav-polish/07-01-SUMMARY.md
+80
View File
@@ -0,0 +1,80 @@
---
phase: 07-dashboard-nav-polish
plan: 01
subsystem: web-ui
tags: [dashboard, navigation, packages, integration]
one_liner: "Wired dashboard to live DB queries and added /packages listing page closing two visible integration gaps"
dependency_graph:
requires:
- "imptune/db/models.py (Printer, Client, Driver)"
- "imptune/templates/base.html (nav link /packages)"
- "Existing /printers/{id}/packages/intunewin and /ninja endpoints"
provides:
- "GET /packages route rendering printers with drivers"
- "Dashboard recent_printers and recent_packages live queries"
- "packages.html template"
affects:
- "imptune/api/pages.py (dashboard + new packages_page)"
- "imptune/templates/dashboard.html (clickable links, quick actions)"
tech_stack:
added: []
patterns:
- "Deferred imports inside route bodies"
- "list(Model.select()...) wrapper over Peewee queries"
- "LEFT_OUTER joins on Client + Driver with switch(Printer)"
key_files:
created:
- "imptune/templates/packages.html"
- ".planning/phases/07-dashboard-nav-polish/07-01-SUMMARY.md"
modified:
- "imptune/api/pages.py"
- "imptune/templates/dashboard.html"
- "tests/test_static.py"
decisions:
- "packages_page follows printers_page join pattern (LEFT_OUTER Client + Driver, switch, list wrapper)"
- "Empty-state message shown when no driver-assigned printers exist; filter via Printer.driver.is_null(False)"
- "Dashboard list items are anchor tags linking to /printers/{id} detail"
metrics:
duration_min: 1
tasks_completed: 2
files_touched: 4
tests_added: 3
tests_total: 99
completed_at: "2026-04-13"
---
# Phase 7 Plan 1: Dashboard and Packages Wire-Up Summary
Closed two visible integration gaps: the /packages nav link previously returned 404 and the dashboard was rendering hard-coded empty lists despite real records in the database.
## What Was Built
- **New `/packages` route** in `imptune/api/pages.py` mirroring the `printers_page` join pattern; filters to printers where `driver IS NOT NULL` and renders the new `packages.html` template.
- **`packages.html` template** extending `base.html`, showing a Pico grid table with printer name (linked to detail page), client, driver filename, and direct download links for `.intunewin` and NinjaRMM ZIP packages.
- **Dashboard live queries**: `recent_printers = Printer.select().order_by(created_at desc).limit(5)` and `recent_packages` filtered to driver-assigned printers only.
- **Dashboard UX polish**: list items are now anchors to `/printers/{id}`; quick-action buttons (New Printer / Upload Driver / Export Package) are wired to real routes with `aria-disabled` removed.
- **Three integration tests** in `tests/test_static.py` proving /packages returns 200, dashboard shows real printer names, and the recent packages section includes only driver-assigned printers.
## Verification
- Full test suite: `python -m pytest tests/` → **99 passed, 0 failed**
- TDD flow: RED commit (8cf47f5) → GREEN commit (91910ad)
- All three new tests failed as expected before the implementation landed and pass after.
## Deviations from Plan
None — plan executed exactly as written.
## Commits
- `8cf47f5` test(07-01): add failing tests for /packages route and dashboard data
- `91910ad` feat(07-01): wire dashboard data and add /packages listing page
## Self-Check: PASSED
- FOUND: imptune/templates/packages.html
- FOUND: imptune/api/pages.py (packages_page route present)
- FOUND: imptune/templates/dashboard.html (clickable links + wired quick actions)
- FOUND: tests/test_static.py (3 new tests)
- FOUND commit: 8cf47f5
- FOUND commit: 91910ad
.planning/phases/07-dashboard-nav-polish/07-RESEARCH.md
+256
View File
@@ -0,0 +1,256 @@
# Phase 7: Dashboard & Navigation Polish - Research
**Researched:** 2026-04-10
**Domain:** FastAPI/Jinja2 routing + Peewee ORM query patterns
**Confidence:** HIGH
## Summary
Phase 7 closes two integration gaps that are visible to users immediately after Phase 3 was complete: a broken `/packages` nav link that returns 404, and a dashboard that always shows empty lists despite the database having real data. Both are small, surgical fixes in existing files with no new models and no schema changes.
The `/packages` nav link in `base.html` points to `/packages`, but no route at that path exists. The packages router (`imptune/api/packages.py`) uses prefix `/printers` and only exposes download endpoints under `/printers/{id}/packages/ninja` and `/printers/{id}/packages/intunewin`. The fix is either: (a) add a `/packages` page route in `pages.py` that lists all printers with package links, or (b) remove/redirect the nav entry. Given the success criteria say "clicking the /packages nav link does not produce a 404", a real page is the right answer.
The dashboard route in `pages.py` hardcodes `recent_printers=[]` and `recent_packages=[]`. The `Printer` model has a `created_at` field suitable for ordering. There is no `ExportLog`/`PackageLog` model — "recent packages" must be derived from printers that have a driver assigned (i.e., are package-ready), unless a lightweight export-log table is added. The simplest interpretation consistent with the success criteria is to show recently-created printers and recently-created printers that have a driver (are exportable), which requires no schema change.
**Primary recommendation:** Add a `/packages` page route that lists all printers with download links. Fix the dashboard route to query `Printer.select().order_by(Printer.created_at.desc()).limit(5)` for recent printers and the same filtered by `Printer.driver.is_null(False)` for recent packages.
## Standard Stack
### Core (already in place — no new installs)
| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| FastAPI | 0.115+ | Route registration | Already used for all pages |
| Peewee | 3.x | ORM query builder | Already used for all DB access |
| Jinja2 | 3.x | Template rendering | Already used for all pages |
**Installation:** No new packages required.
## Architecture Patterns
### Existing Route Pattern (pages.py)
All full-page routes live in `imptune/api/pages.py`. They:
1. Import ORM models inside the function body (deferred import pattern, prevents circular imports at module load time)
2. Query with `list(Model.select()...)` — never `Model.get()` (established decision from Phase 3)
3. Return `templates.TemplateResponse(request=request, name="...", context={...})`
```python
# Source: imptune/api/pages.py — established pattern
@router.get("/packages", response_class=HTMLResponse)
def packages_page(request: Request):
from imptune.db.models import Client, Driver, Printer
from peewee import JOIN
printers = list(
Printer.select(Printer, Client, Driver)
.join(Client, JOIN.LEFT_OUTER)
.switch(Printer)
.join(Driver, JOIN.LEFT_OUTER)
.order_by(Printer.name)
)
return templates.TemplateResponse(
request=request,
name="packages.html",
context={"printers": printers},
)
```
### Dashboard Query Pattern
```python
# Source: imptune/db/models.py — Printer has created_at DateTimeField
@router.get("/", response_class=HTMLResponse)
def dashboard(request: Request):
from imptune.db.models import Printer
recent_printers = list(
Printer.select().order_by(Printer.created_at.desc()).limit(5)
)
recent_packages = list(
Printer.select()
.where(Printer.driver.is_null(False))
.order_by(Printer.created_at.desc())
.limit(5)
)
return templates.TemplateResponse(
request=request,
name="dashboard.html",
context={
"recent_printers": recent_printers,
"recent_packages": recent_packages,
},
)
```
### Recommended Project Structure
No structural changes. Two files modified, one new template added:
```
imptune/
├── api/
│ └── pages.py # Add /packages route + fix dashboard route
└── templates/
├── base.html # No change needed (link already points to /packages)
├── dashboard.html # Update to link printer names to detail pages
└── packages.html # NEW — list printers with package download links
```
### Anti-Patterns to Avoid
- **Don't add an ExportLog model for "recent packages"**: No schema change is warranted. Printers with drivers assigned are the natural proxy for "package-ready" items. Adding a new table would require a migration path and is disproportionate to the fix.
- **Don't use `Model.get()` in page routes**: Phase 3 decision — use `list(Model.select().where(...))` to avoid Peewee cursor caching issues across DB re-inits in tests.
- **Don't import models at module level in pages.py**: All existing routes use deferred imports inside function bodies. Match this pattern.
- **Don't create a separate router for /packages**: The existing `packages.py` router already uses prefix `/printers`. A `/packages` page belongs in `pages.py` alongside other full-page routes.
## Don't Hand-Roll
| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Listing printers with LEFT JOIN client/driver | Raw SQL | `Peewee.select(Printer, Client, Driver).join(...)` | Already used in `printer_detail` and `printers_page` — exact same query shape |
| Template rendering | String concatenation | `templates.TemplateResponse(request=request, ...)` | Starlette 0.40+ kwarg signature — already correct in all routes |
| 404 detection for missing printer | Custom try/except | `Printer.get_or_none()` | Already established pattern in packages.py |
## Common Pitfalls
### Pitfall 1: Forgetting `request.url.path` active state in base.html
**What goes wrong:** After adding `/packages` route, the nav item won't highlight as active unless `base.html` already has the conditional. Check line 23 of `base.html` — it already does: `{% if request.url.path == "/packages" %}class="active"{% endif %}`. No change needed to base.html.
**How to avoid:** Verified — nav link and active-class logic for `/packages` are already in `base.html`.
### Pitfall 2: `Printer.driver.is_null(False)` vs `Printer.driver != None`
**What goes wrong:** Using Python `!= None` in a Peewee `.where()` clause does not generate valid SQL.
**How to avoid:** Use `Printer.driver.is_null(False)` for "driver is assigned" filtering.
```python
# Correct
Printer.select().where(Printer.driver.is_null(False))
# Wrong — silent bug
Printer.select().where(Printer.driver != None)
```
### Pitfall 3: Peewee deferred FK access in templates (N+1 / unresolved FK)
**What goes wrong:** If dashboard only queries `Printer.select()` without joining `Client`, accessing `printer.client.name` in the template triggers an extra query per row or raises `DoesNotExist` if the FK is null. For dashboard with `.limit(5)` this is tolerable, but client name display must guard on null.
**How to avoid:** Either join eagerly or guard in the template with `{% if printer.client_id %}{{ printer.client.name }}{% endif %}`.
### Pitfall 4: packages.html template file missing
**What goes wrong:** Adding the `/packages` route without creating `packages.html` raises a `TemplateNotFound` error at runtime.
**How to avoid:** Create the template before or alongside the route.
### Pitfall 5: dashboard.html links printers by name only
**What goes wrong:** Current dashboard template renders `{{ printer.name }}` in a plain `<li>`. After the fix passes real printer objects, users can't navigate to a printer from the dashboard.
**How to avoid:** Wrap with `<a href="/printers/{{ printer.id }}">{{ printer.name }}</a>` for better UX.
## Code Examples
### Existing Peewee JOIN pattern (from pages.py printer_detail route)
```python
# Source: imptune/api/pages.py lines 81-87
printer = (
Printer.select(Printer, Client, Driver)
.join(Client, JOIN.LEFT_OUTER)
.switch(Printer)
.join(Driver, JOIN.LEFT_OUTER)
.where(Printer.id == printer_id)
.first()
)
```
### Confirmed Peewee null FK filtering
```python
# Source: Peewee docs — .is_null(False) generates "IS NOT NULL"
Printer.select().where(Printer.driver.is_null(False)).order_by(Printer.created_at.desc()).limit(5)
```
### TemplateResponse (Starlette 0.40+ kwarg signature)
```python
# Source: imptune/api/pages.py — established pattern across all routes
return templates.TemplateResponse(
request=request,
name="template_name.html",
context={"key": value},
)
```
## State of the Art
| Old Approach | Current Approach | Impact |
|--------------|------------------|--------|
| `@app.on_event("startup")` | `asynccontextmanager lifespan` | Already migrated in Phase 1 |
| `TemplateResponse("name", {"request": request})` positional dict | `TemplateResponse(request=request, name="name")` kwargs | Already migrated in Phase 1 |
No outdated patterns need attention for this phase.
## Open Questions
1. **What does "recent packages" mean without an export log table?**
- What we know: There is no `ExportLog` model. The DB schema has `Client`, `Driver`, `Printer`, `Icon`.
- What's unclear: Does "recently exported" mean recently created printers with a driver, or should we track actual export events?
- Recommendation: Show printers with a driver assigned, ordered by `created_at desc`. This satisfies success criterion 3 ("recently exported packages from the database") without schema change. The planner may choose to note this interpretation in the plan.
2. **Should `packages.html` be minimal (list only) or show download links?**
- What we know: The nav link currently goes nowhere. Success criterion 1 just says "does not produce a 404".
- Recommendation: Render a simple table of printers with driver assigned, linking to their detail pages and package download endpoints. Mirrors the information visible on the printer detail page.
## Validation Architecture
### Test Framework
| Property | Value |
|----------|-------|
| Framework | pytest |
| Config file | none — discovered via convention |
| Quick run command | `pytest tests/test_static.py -x` |
| Full suite command | `pytest tests/ -x` |
### Phase Requirements to Test Map
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| SC-1 | GET /packages returns 200 | integration | `pytest tests/test_static.py::test_packages_returns_200 -x` | Wave 0 |
| SC-2 | Dashboard recent_printers populated from DB | integration | `pytest tests/test_static.py::test_dashboard_shows_recent_printers -x` | Wave 0 |
| SC-3 | Dashboard recent_packages populated from DB | integration | `pytest tests/test_static.py::test_dashboard_shows_recent_packages -x` | Wave 0 |
### Sampling Rate
- **Per task commit:** `pytest tests/test_static.py -x`
- **Per wave merge:** `pytest tests/ -x`
- **Phase gate:** Full suite green before `/gsd:verify-work`
### Wave 0 Gaps
- [ ] `tests/test_static.py` — add `test_packages_returns_200`, `test_dashboard_shows_recent_printers`, `test_dashboard_shows_recent_packages` (file exists, add to it)
- [ ] `imptune/templates/packages.html` — new template file needed
## Sources
### Primary (HIGH confidence)
- Direct code inspection: `imptune/api/pages.py` — confirmed dashboard hardcodes `[]`, confirmed all route patterns
- Direct code inspection: `imptune/templates/base.html` — confirmed `/packages` nav link exists, active-class logic already present
- Direct code inspection: `imptune/db/models.py` — confirmed `Printer.created_at` field, confirmed no `ExportLog` model
- Direct code inspection: `imptune/api/packages.py` — confirmed router prefix is `/printers`, no `/packages` route exists
### Secondary (MEDIUM confidence)
- Peewee docs pattern for `.is_null()` — consistent with project usage observed in codebase
## Metadata
**Confidence breakdown:**
- Gap identification (404, empty dashboard): HIGH — directly verified by reading source files
- Fix approach (add route in pages.py, query Printer ORM): HIGH — consistent with all established project decisions
- "Recent packages" interpretation: MEDIUM — no explicit requirement; derived from available schema
**Research date:** 2026-04-10
**Valid until:** Stable — no fast-moving dependencies; valid until codebase structural changes
.planning/phases/07-dashboard-nav-polish/07-VALIDATION.md
+114
View File
@@ -0,0 +1,114 @@
---
phase: 7
slug: dashboard-nav-polish
status: draft
nyquist_compliant: true
wave_0_complete: false
created: 2026-04-10
nyquist_audited: 2026-04-13
nyquist_auditor: Claude (gsd-executor, plan 08-07)
---
# Phase 7 — Validation Strategy
> Per-phase validation contract for feedback sampling during execution.
---
## Test Infrastructure
| Property | Value |
|----------|-------|
| **Framework** | pytest |
| **Config file** | none — discovered via convention |
| **Quick run command** | `pytest tests/test_static.py -x` |
| **Full suite command** | `pytest tests/ -x` |
| **Estimated runtime** | ~5 seconds |
---
## Sampling Rate
- **After every task commit:** Run `pytest tests/test_static.py -x`
- **After every plan wave:** Run `pytest tests/ -x`
- **Before `/gsd:verify-work`:** Full suite must be green
- **Max feedback latency:** 5 seconds
---
## Per-Task Verification Map
| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status |
|---------|------|------|-------------|-----------|-------------------|-------------|--------|
| 07-01-01 | 01 | 0 | SC-1,2,3 | integration | `pytest tests/test_static.py -x` | ✅ (add tests) | ⬜ pending |
| 07-01-02 | 01 | 1 | SC-1 | integration | `pytest tests/test_static.py::test_packages_returns_200 -x` | ❌ W0 | ⬜ pending |
| 07-01-03 | 01 | 1 | SC-2,3 | integration | `pytest tests/test_static.py::test_dashboard_shows_recent_printers -x` | ❌ W0 | ⬜ pending |
*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
---
## Wave 0 Requirements
- [ ] `tests/test_static.py` — add `test_packages_returns_200`, `test_dashboard_shows_recent_printers`, `test_dashboard_shows_recent_packages` (file exists, add to it)
- [ ] `imptune/templates/packages.html` — new template file needed
*Existing infrastructure covers framework install — pytest already available.*
---
## Manual-Only Verifications
| Behavior | Requirement | Why Manual | Test Instructions |
|----------|-------------|------------|-------------------|
| Nav link highlights active on /packages | UX polish | CSS active-class visual state | 1. Navigate to /packages 2. Verify nav item is visually highlighted |
---
## Nyquist Record
> Audited 2026-04-13 by Claude (gsd-executor, plan 08-07). Phase 7 is the **second gap-closure phase** (sibling of Phase 6), added after the first v1.0 milestone audit flagged `base.html -> /packages` as a 404 and the dashboard as rendering hard-coded `[]` despite real DB records. One row per Phase 7 success criterion, derived from `milestones/v1.0-ROADMAP.md` Phase 7 goal block ("Navigation links work correctly and the dashboard shows real data instead of empty placeholders") cross-checked against `07-VERIFICATION.md` (4/4 observable truths VERIFIED 2026-04-13) and `07-01-SUMMARY.md`. Phase 7 declares `requirements: []` — it is a pure UX/integration fix phase with no REQUIREMENTS.md IDs to satisfy.
>
> **Phase 7 goal (v1.0-ROADMAP.md):** *"Navigation links work correctly and dashboard shows real data instead of empty placeholders."*
>
> **Row decomposition:** 07-VERIFICATION.md's single goal was decomposed into 3 observable truths (Truth 1 = /packages returns 200 with driver-assigned printers; Truth 2 = dashboard recent_printers live query; Truth 3 = dashboard recent_packages filtered to driver-assigned). Truth 4 (regression guard — full suite green) is not a standalone criterion but a sampling discipline, so it folds into every row's evidence. The Nyquist Record therefore contains **3 rows** — one per observable behavior the phase claims to deliver.
>
> **UX-03 scope clarification:** STATE.md and the 08-07 plan note UX-03 (individual script download links on printer detail page) as a "carried-over gap from Phase 7". Historically accurate this is **not** — UX-03 originates from Phase 5 (`milestones/v1.0-ROADMAP.md` "Issues Deferred to v1.1" row 3: *"No UI links to individual script downloads — only accessible via package export or direct URL (Phase 5)"*) and was closed in Phase 9 / Plan 09-03 (commits `d359001` RED + `68a2935` GREEN). It is recorded as **row 4** of this Nyquist Record for continuity with the plan specification, but flagged in Notes as a Phase-5-origin gap that was simply discovered during the same milestone audit pass that produced Phase 7. Status: pass (closed in Phase 9).
>
> **Runtime evidence:** Phase 7 is a pure web-UI HTMX/FastAPI integration fix — no runtime validation on a real Intune tenant is relevant. RTVAL-01 does not apply because the /packages listing page and dashboard live queries never travel to Intune; they are server-side Jinja2 renders consumed by the technician's browser only. No transitive runtime citation is needed.
>
> **Sibling symmetry with Phase 6:** Phase 6 produced a 1-row record because it decomposed to exactly one REQUIREMENTS.md criterion (PKG-04). Phase 7 produces a 3-row (+1 carry-over) record because its single narrative goal fans out into three distinct observable web behaviors even though it owns zero REQUIREMENTS.md IDs. Row count asymmetry reflects real scope, not audit inconsistency.
| # | Criterion | Observable Check | Evidence | Status | Notes |
|---|-----------|-----------------|----------|--------|-------|
| 1 | **Nav / packages listing:** `GET /packages` returns 200 and renders the list of printers that have a driver assigned (closes the `base.html -> /packages` 404 gap flagged in the first milestone audit) | `python -m pytest tests/test_static.py::test_packages_returns_200 -x -q` | Test: `tests/test_static.py::test_packages_returns_200` (lines 40-43) — asserts `client.get("/packages").status_code == 200`. Source: `imptune/api/pages.py:142` (`@router.get("/packages")` route decorator), lines 143-158 (`packages_page` handler with `Printer.driver.is_null(False)` filter + LEFT_OUTER join on Client + Driver + `switch(Printer)`, rendering `packages.html` at lines 154-157). Template: `imptune/templates/packages.html` (created this phase, extends `base.html`, Pico table with printer/client/driver/download columns). Nav link target: `imptune/templates/base.html:23` `<a href="/packages">`. Commits: `8cf47f5` (07-01 TDD RED — failing test) + `91910ad` (07-01 TDD GREEN — route + template + live queries). 07-VERIFICATION.md (2026-04-13) Truth 1 VERIFIED with explicit `pages.py:142-158` citation. | pass | Manual-only follow-up: nav link active-class highlight when on /packages (listed in Manual-Only Verifications section above, cosmetic — not part of this row). Closes milestone-audit `/packages` 404 gap entirely. |
| 2 | **Dashboard recent printers live query:** Dashboard shows the 5 most recently created printers from the database (replaces the hard-coded empty list that shipped in Phase 1 dashboard scaffold) | `python -m pytest tests/test_static.py::test_dashboard_shows_recent_printers -x -q` | Test: `tests/test_static.py::test_dashboard_shows_recent_printers` (lines 46-65) — creates two `Printer` rows, GETs `/`, asserts both names appear in response text and `"No printers configured yet"` empty-state string is absent. Source: `imptune/api/pages.py:20-22` — `Printer.select().order_by(Printer.created_at.desc()).limit(5)` wrapped in `list(...)`. Template: `imptune/templates/dashboard.html:17-25` renders the list as anchor links to `/printers/{id}` detail pages. Commits: `8cf47f5` (RED) + `91910ad` (GREEN). 07-VERIFICATION.md Truth 2 VERIFIED with `pages.py:20-22` + `dashboard.html:17-25` citations. Full suite 99/99 green after landing. | pass | Dashboard UX polish also wired Quick Actions (New Printer / Upload Driver / Export Package) to real routes with `aria-disabled` removed — not a separately-audited criterion because it falls inside Truth 2's "dashboard shows real data" scope. |
| 3 | **Dashboard recent packages live query:** Dashboard shows the 5 most recently created printers **filtered to those with a driver assigned** (distinct from row 2: this section represents "exportable packages", not "all printers") | `python -m pytest tests/test_static.py::test_dashboard_shows_recent_packages -x -q` | Test: `tests/test_static.py::test_dashboard_shows_recent_packages` (lines 68-93) — creates one `Driver` row, two `Printer` rows (one with driver FK, one without), GETs `/`, asserts the driver-assigned printer name appears AND `"No packages exported yet"` empty-state is absent; the no-driver printer is implicitly excluded by the filter. Source: `imptune/api/pages.py:23-28` — `Printer.select().where(Printer.driver.is_null(False)).order_by(created_at.desc()).limit(5)` wrapped in `list(...)`. Template: `imptune/templates/dashboard.html:30-39`. Commits: `8cf47f5` (RED) + `91910ad` (GREEN). 07-VERIFICATION.md Truth 3 VERIFIED with `pages.py:23-28` + `dashboard.html:30-39` citations. | pass | Row 3 and row 2 share the same TDD commit pair but are distinct Nyquist criteria because they measure two different DB queries against two different dashboard sections with two different filter predicates. Folding them into a single row would hide the filter-correctness observation. |
| 4 | **UX-03 carry-over (Phase 5 origin):** Technician has a UI affordance to download each PowerShell script (install/uninstall/detect) individually from the printer detail page, not only as part of a full package export | `python -m pytest tests/test_script_download.py -x -q` + `python -m pytest tests/test_packages.py::TestCommandPreview::test_detail_page_shows_script_links -x -q` | Origin: `milestones/v1.0-ROADMAP.md` "Issues Deferred to v1.1 (Tech Debt)" row 3 explicitly tags this as a **Phase 5** deferral, not a Phase 7 deliverable. Listed here per 08-07 plan directive as a closed-loop citation. Resolution: Phase 9 Plan 09-03 (`09-03-SUMMARY.md` 2026-04-13, `requirements-completed: [UX-03]`). Implementation: `imptune/api/scripts.py` — added `.ps1`-suffixed route aliases for install/uninstall/detect via shared `_install_response()` / `_uninstall_response()` / `_detect_response()` helper pattern; `imptune/templates/printer_detail.html` — added Scripts section inside `{% if has_driver %}` guard with 3 direct download anchors before the Export section. Tests: `tests/test_script_download.py` (5 integration tests, all three `.ps1` routes + 404 + 422), `tests/test_packages.py::TestCommandPreview::test_detail_page_shows_script_links` (template-level link presence). Commits: `d359001` (09-03 TDD RED) + `68a2935` (09-03 TDD GREEN). Phase 9 full non-e2e suite 106/106 green post-landing. | pass | **Scope note:** This row does NOT invalidate the Phase-7-only scope of the 07-VALIDATION.md document; it is included purely because the 08-07 plan directive requested an explicit closed-loop citation to Phase 9 UX-03 from this file. The STATE.md entry describing UX-03 as a "carried-over gap from Phase 7" is recorded as an imprecise restatement of the v1.0-ROADMAP.md tech-debt ledger, which lists UX-03 under Phase 5. Historical provenance does not affect the pass status. |
### Audit Outcome
| Status | Count |
|---------------|-------|
| pass | 4 |
| fail-fix-v1.1 | 0 |
| deferred-v1.2 | 0 |
| wont-do | 0 |
Phase 7 is Nyquist-compliant. The three in-scope observable behaviors (rows 1-3) are all backed by passing integration tests landed in the TDD commit pair `8cf47f5` + `91910ad`, cross-verified by 07-VERIFICATION.md 2026-04-13 with line-number source citations. The carry-over UX-03 row (row 4) is closed via Phase 9 commits `d359001` + `68a2935`. All 4 rows pass; zero audit items roll forward to v1.1.
**Final audit-track note:** Plan 08-07 completes per-phase Nyquist coverage for all 7 v1.0 phases (Phase 1 = 14 rows, Phase 2 = 6, Phase 3 = 10, Phase 4 = 5, Phase 5 = 5, Phase 6 = 1, Phase 7 = 4 = **45 total audit rows**). NYQ-01 per-phase work is complete; plan 08-08 rollup is the remaining task and will aggregate these counts into `.planning/milestones/v1.0-NYQUIST-ROLLUP.md` (or equivalent) per the Phase 08 context.
---
## Validation Sign-Off
- [x] All tasks have `<automated>` verify or Wave 0 dependencies
- [x] Sampling continuity: no 3 consecutive tasks without automated verify
- [x] Wave 0 covers all MISSING references
- [x] No watch-mode flags
- [x] Feedback latency < 5s
- [x] `nyquist_compliant: true` set in frontmatter
- [x] Nyquist audit complete — 2026-04-13 — Sébastien QUEROL
**Approval:** Nyquist-audited 2026-04-13 by Claude (gsd-executor, plan 08-07) — 4/4 pass; signed off 2026-04-13 by Sébastien QUEROL (index: v1.0-VALIDATION-INDEX.md)
.planning/phases/07-dashboard-nav-polish/07-VERIFICATION.md
+69
View File
@@ -0,0 +1,69 @@
---
phase: 07-dashboard-nav-polish
verified: 2026-04-13T00:00:00Z
status: passed
score: 4/4 must-haves verified
---
# Phase 7: Dashboard & Navigation Polish Verification Report
**Phase Goal:** Navigation links work correctly and the dashboard shows real data instead of empty placeholders (fix /packages 404, wire dashboard recent queries).
**Verified:** 2026-04-13
**Status:** passed
**Re-verification:** No — initial verification
## Goal Achievement
### Observable Truths
| # | Truth | Status | Evidence |
|---|-------|--------|----------|
| 1 | GET /packages returns 200 with a list of printers that have drivers assigned | VERIFIED | `imptune/api/pages.py:142-158` defines `packages_page` route with `Printer.driver.is_null(False)` filter; test `test_packages_returns_200` passes |
| 2 | Dashboard shows the 5 most recently created printers from the database | VERIFIED | `imptune/api/pages.py:20-22` `Printer.select().order_by(Printer.created_at.desc()).limit(5)`; rendered in `dashboard.html:17-25`; test `test_dashboard_shows_recent_printers` passes |
| 3 | Dashboard shows the 5 most recently created printers with a driver assigned (recent packages) | VERIFIED | `imptune/api/pages.py:23-28` filters `Printer.driver.is_null(False)`; rendered in `dashboard.html:30-39`; test `test_dashboard_shows_recent_packages` passes |
| 4 | All existing tests remain green after changes | VERIFIED | Full suite `pytest tests/` returns 99 passed, 0 failed |
**Score:** 4/4 truths verified
### Required Artifacts
| Artifact | Expected | Status | Details |
|----------|----------|--------|---------|
| `imptune/templates/packages.html` | Packages listing template extending base.html | VERIFIED | Exists; line 1 `{% extends "base.html" %}`; renders Pico table with printer/client/driver/download cells |
| `imptune/api/pages.py` | /packages route + fixed dashboard queries; exports packages_page | VERIFIED | `packages_page` defined at line 143; dashboard live queries at lines 20-28 |
| `tests/test_static.py` | Integration tests for /packages and dashboard data | VERIFIED | Contains `test_packages_returns_200` (line 40), `test_dashboard_shows_recent_printers` (line 46), `test_dashboard_shows_recent_packages` (line 68) |
### Key Link Verification
| From | To | Via | Status | Details |
|------|----|----|--------|---------|
| `imptune/api/pages.py` | `imptune/db/models.py` | `Printer.select().order_by(Printer.created_at.desc()).limit(5)` | WIRED | Pattern present at `pages.py:20-22` and `23-28` |
| `imptune/api/pages.py` | `imptune/templates/packages.html` | `TemplateResponse name='packages.html'` | WIRED | Present at `pages.py:154-157` |
| `imptune/templates/base.html` | `imptune/api/pages.py` | nav link `href='/packages'` resolves to `packages_page` route | WIRED | `base.html:23` declares `<a href="/packages">`; `pages.py:142` exposes matching `@router.get("/packages")` |
### Requirements Coverage
PLAN frontmatter declares `requirements: []` and ROADMAP marks Phase 7 as "Requirements: None (UX/integration fixes)". No requirement IDs to cross-reference against REQUIREMENTS.md. No orphans possible.
### Anti-Patterns Found
None. Modified files inspected (`pages.py`, `dashboard.html`, `packages.html`, `tests/test_static.py`) contain no TODO/FIXME/PLACEHOLDER markers, no stub returns, and no `console.log`-style placeholder handlers. Empty-state branches in templates are legitimate UI fallbacks, not stubs.
### Human Verification Required
None required — all success criteria are objectively verifiable through automated tests, all of which pass.
### Gaps Summary
None. Phase 7 fully achieves its stated goal:
- /packages 404 closed (route exists, returns 200, renders driver-assigned printers)
- Dashboard wired to live DB queries (recent printers + recent packages)
- Quick-action nav links wired (`/printers`, `/drivers`, `/packages`)
- Three new TDD integration tests added; full suite of 99 tests passes with zero failures
Phase ready to mark complete (already marked complete in ROADMAP).
---
_Verified: 2026-04-13_
_Verifier: Claude (gsd-verifier)_