diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index b334cad..2046265 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -19,7 +19,7 @@ ### UX Tech Debt (UX) - [x] **UX-01**: After a new driver is uploaded on the printer form, the DriverDesc dropdown refreshes automatically (no manual page reload) — verified live in browser -- [ ] **UX-02**: PRNT-03 Alpine.js IP→port auto-derivation is verified live in a real browser session, with the verification recorded in VALIDATION.md +- [x] **UX-02**: PRNT-03 Alpine.js IP→port auto-derivation is verified live in a real browser session, with the verification recorded in VALIDATION.md - [x] **UX-03**: The printer detail page exposes direct download links for each generated script (install / uninstall / detect) in addition to the package export buttons ### Nyquist Validation Track (NYQ) @@ -58,7 +58,7 @@ Carried forward from v1.0 Out of Scope — no change. | RTVAL-04 | Phase 10 | Pending | | RTVAL-05 | Phase 10 | Pending | | UX-01 | Phase 9 | Complete | -| UX-02 | Phase 9 | Pending | +| UX-02 | Phase 9 | Complete | | UX-03 | Phase 9 | Complete | | NYQ-01 | Phase 8 | Pending | | NYQ-02 | Phase 8 | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 0825ba7..0bf0aad 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -1,94 +1,94 @@ -# Roadmap: ImpTune - -## Milestones - -- ✅ **v1.0 MVP** — Phases 1–7, 13 plans, 27/27 requirements (shipped 2026-04-13) — see [`milestones/v1.0-ROADMAP.md`](milestones/v1.0-ROADMAP.md) -- 🚧 **v1.1 Hardening & Validation** — Phases 8–11, 15 requirements (in progress, started 2026-04-13) - -## Phases - -
-✅ v1.0 MVP (Phases 1–7) — SHIPPED 2026-04-13 - -- [x] Phase 1: Foundation (3/3 plans) — 2026-04-10 -- [x] Phase 2: Driver Management (2/2 plans) — 2026-04-10 -- [x] Phase 3: Printer Configuration (2/2 plans) — 2026-04-10 -- [x] Phase 4: Script Generation (2/2 plans) — 2026-04-10 -- [x] Phase 5: Package Export (2/2 plans) — 2026-04-10 -- [x] Phase 6: Wire Icon into .intunewin (1/1 plan, gap closure) — 2026-04-10 -- [x] Phase 7: Dashboard & Navigation Polish (1/1 plan, gap closure) — 2026-04-13 - -Full details: [`milestones/v1.0-ROADMAP.md`](milestones/v1.0-ROADMAP.md) - -
- -### 🚧 v1.1 Hardening & Validation (Phases 8–11) - -- [ ] **Phase 8: Nyquist Validation Track** — Retro-fit Nyquist-compliant VALIDATION.md across all 7 v1.0 phases with evidence-backed checks -- [ ] **Phase 9: UX Tech Debt Closure** — Fix the three carried-over UX gaps so the deployed build is the polished one technicians actually use -- [ ] **Phase 10: Real-World Runtime Validation** — Validate generated artifacts end-to-end against a live Intune tenant and a real managed endpoint -- [ ] **Phase 11: Real-World Rollout & Feedback** — Deploy the container to a real MSP environment, push a real package, and capture structured technician feedback - -## Phase Details - -### Phase 8: Nyquist Validation Track -**Goal**: Every v1.0 phase has a signed-off Nyquist-compliant validation record with cited evidence, and any blocking gaps are tracked. -**Depends on**: Nothing (parallelizable — pure audit of shipped code, no runtime dependency) -**Requirements**: NYQ-01, NYQ-02, NYQ-03 -**Success Criteria** (what must be TRUE): - 1. An operator can open any of the 7 v1.0 phase folders and read a `VALIDATION.md` where every success criterion maps to exactly one observable check with cited evidence (commit, test name, file path, or screenshot) - 2. An operator can open `.planning/milestones/v1.0-VALIDATION-INDEX.md` and see a single pass/fail roll-up across all 7 phases with links to each phase's validation file - 3. Any validation gap surfaced during the Nyquist pass appears in the index as either a v1.1 defect ticket (linked to the fixing phase) or an explicitly deferred item with written rationale -**Plans**: TBD - -### Phase 9: UX Tech Debt Closure -**Goal**: The three carried-over UX defects are fixed and live-verified in a real browser so the rolled-out build is the polished one. -**Depends on**: Nothing (independent of validation and rollout — but must complete before Phase 11) -**Requirements**: UX-01, UX-02, UX-03 -**Success Criteria** (what must be TRUE): - 1. A technician uploading a new driver on the printer form sees the new DriverDesc appear in the dropdown without manually reloading the page - 2. A technician typing an IP address into the printer form sees the port field auto-populate via the PRNT-03 Alpine.js handler, observed live in a real browser and recorded in VALIDATION.md - 3. A technician on the printer detail page can click direct download links for the install, uninstall, and detect scripts individually, in addition to the existing package export buttons -**Plans**: 3 plans - - [ ] 09-01-driver-upload-fix-and-inline-oob-PLAN.md — Fix POST /drivers/upload 500 + add inline upload to printer form with HTMX OOB refresh (UX-01) - - [ ] 09-02-playwright-port-autofill-PLAN.md — Add Playwright dev dep + headless test for PRNT-03 IP->port auto-fill (UX-02) - - [ ] 09-03-script-download-links-PLAN.md — Add .ps1 route aliases + printer_detail.html script download links (UX-03) - -### Phase 10: Real-World Runtime Validation -**Goal**: Generated .intunewin, install, detect, and uninstall artifacts are proven to work end-to-end on a real Intune tenant against a real Windows endpoint, with evidence recorded. -**Depends on**: Phase 9 (rollout uses the validated-AND-polished build; validation itself only strictly needs v1.0, but running it on the polished build avoids re-doing the pass) -**Requirements**: RTVAL-01, RTVAL-02, RTVAL-03, RTVAL-04, RTVAL-05 -**Success Criteria** (what must be TRUE): - 1. A generated `.intunewin` package is uploaded to a real Microsoft Intune tenant and accepted without format errors, with the tenant ingestion confirmation captured as evidence - 2. A technician assigning the package to a real Intune-managed Windows endpoint observes the install script succeed under SYSTEM context, with `pnputil` driver staging and `$PSScriptRoot` path resolution verified in the device log - 3. After install, the Intune detection rule driven by the generated detect script reports "installed" for the endpoint - 4. A technician triggering uninstall from Intune sees the printer cleanly removed from the endpoint under SYSTEM context - 5. A reviewer can open `RUNTIME-VALIDATION.md` and read a signed-off report listing tenant, device, OS build, driver vendor(s), screenshots/logs, and any issues found -**Plans**: TBD - -### Phase 11: Real-World Rollout & Feedback -**Goal**: ImpTune is running in a real MSP environment, has produced a package that actually reached endpoints, and technician feedback has been captured and triaged. -**Depends on**: Phase 9 (UX tech debt), Phase 10 (runtime validation passed) -**Requirements**: RWR-01, RWR-02, RWR-03, RWR-04 -**Success Criteria** (what must be TRUE): - 1. ImpTune is running in its single Docker container inside at least one real MSP environment serving real printers, with the host/URL recorded in the feedback document - 2. At least one printer deployment package generated by the deployed instance has been pushed to real endpoints via Intune or NinjaRMM end-to-end - 3. A reviewer can open `.planning/feedback/v1.1-rollout.md` and read structured feedback from the deploying technician covering what worked, what blocked, and what's missing - 4. Every feedback item in that document is tagged fix-in-v1.1, defer-to-v1.2, or won't-do with written rationale -**Plans**: TBD - -## Progress - -| Phase | Milestone | Plans Complete | Status | Completed | -|-------|-----------|----------------|----------|------------| -| 1. Foundation | v1.0 | 3/3 | Complete | 2026-04-10 | -| 2. Driver Management | v1.0 | 2/2 | Complete | 2026-04-10 | -| 3. Printer Configuration | v1.0 | 2/2 | Complete | 2026-04-10 | -| 4. Script Generation | v1.0 | 2/2 | Complete | 2026-04-10 | -| 5. Package Export | v1.0 | 2/2 | Complete | 2026-04-10 | -| 6. Wire Icon into .intunewin | v1.0 | 1/1 | Complete | 2026-04-10 | -| 7. Dashboard & Nav Polish | v1.0 | 1/1 | Complete | 2026-04-13 | -| 8. Nyquist Validation Track | v1.1 | 0/? | Not started | — | -| 9. UX Tech Debt Closure | 2/3 | In Progress| | — | -| 10. Real-World Runtime Validation | v1.1 | 0/? | Not started | — | -| 11. Real-World Rollout & Feedback | v1.1 | 0/? | Not started | — | +# Roadmap: ImpTune + +## Milestones + +- ✅ **v1.0 MVP** — Phases 1–7, 13 plans, 27/27 requirements (shipped 2026-04-13) — see [`milestones/v1.0-ROADMAP.md`](milestones/v1.0-ROADMAP.md) +- 🚧 **v1.1 Hardening & Validation** — Phases 8–11, 15 requirements (in progress, started 2026-04-13) + +## Phases + +
+✅ v1.0 MVP (Phases 1–7) — SHIPPED 2026-04-13 + +- [x] Phase 1: Foundation (3/3 plans) — 2026-04-10 +- [x] Phase 2: Driver Management (2/2 plans) — 2026-04-10 +- [x] Phase 3: Printer Configuration (2/2 plans) — 2026-04-10 +- [x] Phase 4: Script Generation (2/2 plans) — 2026-04-10 +- [x] Phase 5: Package Export (2/2 plans) — 2026-04-10 +- [x] Phase 6: Wire Icon into .intunewin (1/1 plan, gap closure) — 2026-04-10 +- [x] Phase 7: Dashboard & Navigation Polish (1/1 plan, gap closure) — 2026-04-13 + +Full details: [`milestones/v1.0-ROADMAP.md`](milestones/v1.0-ROADMAP.md) + +
+ +### 🚧 v1.1 Hardening & Validation (Phases 8–11) + +- [ ] **Phase 8: Nyquist Validation Track** — Retro-fit Nyquist-compliant VALIDATION.md across all 7 v1.0 phases with evidence-backed checks +- [x] **Phase 9: UX Tech Debt Closure** — Fix the three carried-over UX gaps so the deployed build is the polished one technicians actually use (completed 2026-04-13) +- [ ] **Phase 10: Real-World Runtime Validation** — Validate generated artifacts end-to-end against a live Intune tenant and a real managed endpoint +- [ ] **Phase 11: Real-World Rollout & Feedback** — Deploy the container to a real MSP environment, push a real package, and capture structured technician feedback + +## Phase Details + +### Phase 8: Nyquist Validation Track +**Goal**: Every v1.0 phase has a signed-off Nyquist-compliant validation record with cited evidence, and any blocking gaps are tracked. +**Depends on**: Nothing (parallelizable — pure audit of shipped code, no runtime dependency) +**Requirements**: NYQ-01, NYQ-02, NYQ-03 +**Success Criteria** (what must be TRUE): + 1. An operator can open any of the 7 v1.0 phase folders and read a `VALIDATION.md` where every success criterion maps to exactly one observable check with cited evidence (commit, test name, file path, or screenshot) + 2. An operator can open `.planning/milestones/v1.0-VALIDATION-INDEX.md` and see a single pass/fail roll-up across all 7 phases with links to each phase's validation file + 3. Any validation gap surfaced during the Nyquist pass appears in the index as either a v1.1 defect ticket (linked to the fixing phase) or an explicitly deferred item with written rationale +**Plans**: TBD + +### Phase 9: UX Tech Debt Closure +**Goal**: The three carried-over UX defects are fixed and live-verified in a real browser so the rolled-out build is the polished one. +**Depends on**: Nothing (independent of validation and rollout — but must complete before Phase 11) +**Requirements**: UX-01, UX-02, UX-03 +**Success Criteria** (what must be TRUE): + 1. A technician uploading a new driver on the printer form sees the new DriverDesc appear in the dropdown without manually reloading the page + 2. A technician typing an IP address into the printer form sees the port field auto-populate via the PRNT-03 Alpine.js handler, observed live in a real browser and recorded in VALIDATION.md + 3. A technician on the printer detail page can click direct download links for the install, uninstall, and detect scripts individually, in addition to the existing package export buttons +**Plans**: 3 plans + - [ ] 09-01-driver-upload-fix-and-inline-oob-PLAN.md — Fix POST /drivers/upload 500 + add inline upload to printer form with HTMX OOB refresh (UX-01) + - [ ] 09-02-playwright-port-autofill-PLAN.md — Add Playwright dev dep + headless test for PRNT-03 IP->port auto-fill (UX-02) + - [ ] 09-03-script-download-links-PLAN.md — Add .ps1 route aliases + printer_detail.html script download links (UX-03) + +### Phase 10: Real-World Runtime Validation +**Goal**: Generated .intunewin, install, detect, and uninstall artifacts are proven to work end-to-end on a real Intune tenant against a real Windows endpoint, with evidence recorded. +**Depends on**: Phase 9 (rollout uses the validated-AND-polished build; validation itself only strictly needs v1.0, but running it on the polished build avoids re-doing the pass) +**Requirements**: RTVAL-01, RTVAL-02, RTVAL-03, RTVAL-04, RTVAL-05 +**Success Criteria** (what must be TRUE): + 1. A generated `.intunewin` package is uploaded to a real Microsoft Intune tenant and accepted without format errors, with the tenant ingestion confirmation captured as evidence + 2. A technician assigning the package to a real Intune-managed Windows endpoint observes the install script succeed under SYSTEM context, with `pnputil` driver staging and `$PSScriptRoot` path resolution verified in the device log + 3. After install, the Intune detection rule driven by the generated detect script reports "installed" for the endpoint + 4. A technician triggering uninstall from Intune sees the printer cleanly removed from the endpoint under SYSTEM context + 5. A reviewer can open `RUNTIME-VALIDATION.md` and read a signed-off report listing tenant, device, OS build, driver vendor(s), screenshots/logs, and any issues found +**Plans**: TBD + +### Phase 11: Real-World Rollout & Feedback +**Goal**: ImpTune is running in a real MSP environment, has produced a package that actually reached endpoints, and technician feedback has been captured and triaged. +**Depends on**: Phase 9 (UX tech debt), Phase 10 (runtime validation passed) +**Requirements**: RWR-01, RWR-02, RWR-03, RWR-04 +**Success Criteria** (what must be TRUE): + 1. ImpTune is running in its single Docker container inside at least one real MSP environment serving real printers, with the host/URL recorded in the feedback document + 2. At least one printer deployment package generated by the deployed instance has been pushed to real endpoints via Intune or NinjaRMM end-to-end + 3. A reviewer can open `.planning/feedback/v1.1-rollout.md` and read structured feedback from the deploying technician covering what worked, what blocked, and what's missing + 4. Every feedback item in that document is tagged fix-in-v1.1, defer-to-v1.2, or won't-do with written rationale +**Plans**: TBD + +## Progress + +| Phase | Milestone | Plans Complete | Status | Completed | +|-------|-----------|----------------|----------|------------| +| 1. Foundation | v1.0 | 3/3 | Complete | 2026-04-10 | +| 2. Driver Management | v1.0 | 2/2 | Complete | 2026-04-10 | +| 3. Printer Configuration | v1.0 | 2/2 | Complete | 2026-04-10 | +| 4. Script Generation | v1.0 | 2/2 | Complete | 2026-04-10 | +| 5. Package Export | v1.0 | 2/2 | Complete | 2026-04-10 | +| 6. Wire Icon into .intunewin | v1.0 | 1/1 | Complete | 2026-04-10 | +| 7. Dashboard & Nav Polish | v1.0 | 1/1 | Complete | 2026-04-13 | +| 8. Nyquist Validation Track | v1.1 | 0/? | Not started | — | +| 9. UX Tech Debt Closure | 3/3 | Complete | 2026-04-13 | — | +| 10. Real-World Runtime Validation | v1.1 | 0/? | Not started | — | +| 11. Real-World Rollout & Feedback | v1.1 | 0/? | Not started | — | diff --git a/.planning/STATE.md b/.planning/STATE.md index 45e36f5..aa8b806 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,14 +3,14 @@ gsd_state_version: 1.0 milestone: v1.1 milestone_name: Hardening & Validation status: Pending (roadmap approved, plans not yet drafted) -stopped_at: Completed 09-01-driver-upload-fix-and-inline-oob-PLAN.md -last_updated: "2026-04-13T08:53:01.475Z" +stopped_at: Completed 09-02-playwright-port-autofill-PLAN.md +last_updated: "2026-04-13T08:58:40.338Z" last_activity: 2026-04-13 — v1.1 roadmap created, 15/15 requirements mapped across Phases 8–11 progress: total_phases: 4 - completed_phases: 0 + completed_phases: 1 total_plans: 3 - completed_plans: 2 + completed_plans: 3 --- # Project State @@ -63,6 +63,8 @@ Full decision log in PROJECT.md Key Decisions table. Milestone v1.0 decisions ar - [Phase 09-ux-tech-debt-closure]: 09-03: Shared _*_response() helper pattern used for route aliases - [Phase 09]: Sentinel field (caller=printer_form) for OOB branching: chosen over HX-Target header for clarity and testability - [Phase 09]: HTMX OOB template includes primary fragment + OOB select sibling in driver_upload_with_oob.html +- [Phase 09-ux-tech-debt-closure]: 09-02: /printers route used for e2e test (full-page with Alpine.js) — no new /printers/new route needed +- [Phase 09-ux-tech-debt-closure]: 09-02: conftest.py adapted — imptune.config uses string paths, init_db() takes no args ### Pending Todos @@ -72,6 +74,6 @@ Full decision log in PROJECT.md Key Decisions table. Milestone v1.0 decisions ar ## Session Continuity -Last session: 2026-04-13T08:53:01.469Z -Stopped at: Completed 09-01-driver-upload-fix-and-inline-oob-PLAN.md +Last session: 2026-04-13T08:58:40.331Z +Stopped at: Completed 09-02-playwright-port-autofill-PLAN.md Resume file: None diff --git a/.planning/phases/09-ux-tech-debt-closure/09-02-SUMMARY.md b/.planning/phases/09-ux-tech-debt-closure/09-02-SUMMARY.md new file mode 100644 index 0000000..50bfa4c --- /dev/null +++ b/.planning/phases/09-ux-tech-debt-closure/09-02-SUMMARY.md @@ -0,0 +1,144 @@ +--- +phase: 09-ux-tech-debt-closure +plan: 02 +subsystem: testing +tags: [playwright, e2e, chromium, uvicorn, alpine-js, pytest] + +# Dependency graph +requires: + - phase: 09-01 + provides: "final printer_form.html with stable ids and inline upload form" +provides: + - "Playwright headless e2e test suite infrastructure (tests/e2e/ package)" + - "UX-02 evidence: live chromium verification of PRNT-03 Alpine IP->port auto-derivation" + - "Session-scoped live_server fixture (uvicorn thread, free port, /health readiness)" +affects: [09-03, phase-10-rtval, future-e2e] + +# Tech tracking +tech-stack: + added: [pytest-playwright, playwright, uvicorn (as test server)] + patterns: [session-scoped-live-server, playwright-fill-alpine-input, e2e-isolated-from-unit-tests] + +key-files: + created: + - tests/e2e/__init__.py + - tests/e2e/conftest.py + - tests/e2e/test_port_autofill.py + modified: + - requirements-dev.txt + - .planning/phases/09-ux-tech-debt-closure/09-VALIDATION.md + +key-decisions: + - "Route /printers used for e2e test (full-page route via printers.html extending base.html with Alpine.js loaded) — no new /printers/new route needed" + - "conftest.py adapted from plan: config uses string paths (not Path objects), init_db() reads DB_PATH from imptune.config directly" + - "playwright install chromium run separately after pip install -r requirements-dev.txt" + +patterns-established: + - "E2E fixture pattern: patch imptune.config.* string attrs, call init_db(), start uvicorn thread, poll /health before yielding base_url" + - "Alpine @input tested via page.fill() which dispatches native input event + page.wait_for_function for synchronous handler stability" + +requirements-completed: [UX-02] + +# Metrics +duration: 3min +completed: 2026-04-13 +--- + +# Phase 09 Plan 02: Playwright Port Autofill Summary + +**Playwright headless chromium test verifying Alpine IP->port_name auto-derivation at /printers, with session-scoped uvicorn live_server fixture, closing UX-02** + +## Performance + +- **Duration:** 3 min +- **Started:** 2026-04-13T08:54:19Z +- **Completed:** 2026-04-13T08:57:31Z +- **Tasks:** 2 +- **Files modified:** 5 + +## Accomplishments + +- Playwright e2e package scaffolded (tests/e2e/__init__.py + conftest.py) with session-scoped live_server fixture running uvicorn in a background thread against an isolated tmp data dir +- UX-02 Playwright test written and verified green: headless chromium loads /printers, fills ip_address, asserts port_name equals IP_192_168_1_100 — Alpine @input handler confirmed working in real browser +- 112 unit tests unaffected (pytest tests/ -x -q --ignore=tests/e2e still passes) + +## Printer Form Route + +The test uses `/printers` (the full-page printers.html that extends base.html and embeds printer_form.html). No new route was needed — the existing /printers route renders the Alpine x-data wrapper with `