From c6fe284e28700fe3b1de0366fd1ac2f88550b029 Mon Sep 17 00:00:00 2001 From: Kawa Date: Mon, 13 Apr 2026 10:49:47 +0200 Subject: [PATCH] docs(09-03): complete script-download-links plan - Add 09-03-SUMMARY.md documenting .ps1 routes + detail-page links - Update STATE.md with decisions and session info - Update ROADMAP.md phase 9 progress (1/3 summaries) - Mark UX-03 complete in REQUIREMENTS.md --- .planning/REQUIREMENTS.md | 4 +- .planning/ROADMAP.md | 2 +- .planning/STATE.md | 16 +-- .../09-ux-tech-debt-closure/09-03-SUMMARY.md | 107 ++++++++++++++++++ 4 files changed, 119 insertions(+), 10 deletions(-) create mode 100644 .planning/phases/09-ux-tech-debt-closure/09-03-SUMMARY.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 5284ecd..e656d27 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -20,7 +20,7 @@ - [ ] **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 -- [ ] **UX-03**: The printer detail page exposes direct download links for each generated script (install / uninstall / detect) in addition to the package export buttons +- [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) @@ -59,7 +59,7 @@ Carried forward from v1.0 Out of Scope — no change. | RTVAL-05 | Phase 10 | Pending | | UX-01 | Phase 9 | Pending | | UX-02 | Phase 9 | Pending | -| UX-03 | Phase 9 | Pending | +| UX-03 | Phase 9 | Complete | | NYQ-01 | Phase 8 | Pending | | NYQ-02 | Phase 8 | Pending | | NYQ-03 | Phase 8 | Pending | diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b6ed752..18de13f 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -89,6 +89,6 @@ Full details: [`milestones/v1.0-ROADMAP.md`](milestones/v1.0-ROADMAP.md) | 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 | v1.1 | 0/3 | Planned | — | +| 9. UX Tech Debt Closure | 1/3 | In Progress| | — | | 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 7c92f72..f430335 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: Phase 9 context gathered -last_updated: "2026-04-13T08:16:54.191Z" +stopped_at: Completed 09-ux-tech-debt-closure-09-03-PLAN.md +last_updated: "2026-04-13T08:49:37.022Z" last_activity: 2026-04-13 — v1.1 roadmap created, 15/15 requirements mapped across Phases 8–11 progress: total_phases: 4 completed_phases: 0 - total_plans: 0 - completed_plans: 0 + total_plans: 3 + completed_plans: 1 --- # Project State @@ -59,6 +59,8 @@ Last activity: 2026-04-13 — v1.1 roadmap created, 15/15 requirements mapped ac - **NYQ as dedicated phase:** Kept standalone (not absorbed) because it audits all 7 v1.0 phases and its evidence feeds defect triage into Phases 9/10. Full decision log in PROJECT.md Key Decisions table. Milestone v1.0 decisions archived in `milestones/v1.0-ROADMAP.md`. +- [Phase 09-ux-tech-debt-closure]: 09-03: .ps1 routes added as aliases (not renames) to preserve backward compatibility +- [Phase 09-ux-tech-debt-closure]: 09-03: Shared _*_response() helper pattern used for route aliases ### Pending Todos @@ -68,6 +70,6 @@ Full decision log in PROJECT.md Key Decisions table. Milestone v1.0 decisions ar ## Session Continuity -Last session: 2026-04-13T08:16:54.185Z -Stopped at: Phase 9 context gathered -Resume file: .planning/phases/09-ux-tech-debt-closure/09-CONTEXT.md +Last session: 2026-04-13T08:49:37.019Z +Stopped at: Completed 09-ux-tech-debt-closure-09-03-PLAN.md +Resume file: None diff --git a/.planning/phases/09-ux-tech-debt-closure/09-03-SUMMARY.md b/.planning/phases/09-ux-tech-debt-closure/09-03-SUMMARY.md new file mode 100644 index 0000000..1ebad59 --- /dev/null +++ b/.planning/phases/09-ux-tech-debt-closure/09-03-SUMMARY.md @@ -0,0 +1,107 @@ +--- +phase: 09-ux-tech-debt-closure +plan: 03 +subsystem: api, ui +tags: [fastapi, powershell, jinja2, routes, scripts] + +# Dependency graph +requires: [] +provides: + - ".ps1-suffixed route aliases for install, uninstall, detect scripts" + - "Scripts section in printer_detail.html with 3 direct download links" + - "Integration tests for the 3 new .ps1 routes and template links" +affects: [phase-10-rtval, phase-11-rollout] + +# Tech tracking +tech-stack: + added: [] + patterns: + - "Shared handler helpers (_install_response, _uninstall_response, _detect_response) to avoid logic duplication between extensionless and .ps1 route aliases" + +key-files: + created: + - tests/test_script_download.py + modified: + - imptune/api/scripts.py + - imptune/templates/printer_detail.html + - tests/test_packages.py + +key-decisions: + - "Added .ps1 routes as aliases (not renames) to preserve backward compatibility of existing extensionless routes" + - "Scripts section placed inside {% if has_driver %} guard, before Export section" + - "Shared _*_response() helper pattern to avoid code duplication across route aliases" + +patterns-established: + - "Route alias pattern: shared _*_response() helper called by both the extensionless and .ps1 route handlers" + +requirements-completed: [UX-03] + +# Metrics +duration: 18min +completed: 2026-04-13 +--- + +# Phase 9 Plan 03: Script Download Links Summary + +**Three .ps1 route aliases (install/uninstall/detect) + Scripts section on printer detail page, closing UX-03 with direct individual script downloads** + +## Performance + +- **Duration:** 18 min +- **Started:** 2026-04-13T08:46:27Z +- **Completed:** 2026-04-13T09:04:00Z +- **Tasks:** 2 (TDD: RED then GREEN) +- **Files modified:** 4 + +## Accomplishments + +- Added `.ps1`-suffixed route aliases for all three script endpoints via shared `_*_response()` helpers +- Added Scripts section to `printer_detail.html` inside the `{% if has_driver %}` guard with 3 direct download anchor links +- 6 new tests: 5 in `test_script_download.py` covering all .ps1 routes (200, 404, 422), 1 in `test_packages.py::TestCommandPreview` for template link presence +- Full non-e2e suite: 106/106 passing with no regressions + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Wave 0 — failing tests for .ps1 routes + detail page script links** - `d359001` (test) +2. **Task 2: Add .ps1 route aliases + printer_detail.html script links** - `68a2935` (feat) + +**Plan metadata:** (docs commit to follow) + +_Note: TDD tasks have two commits (test RED → feat GREEN)_ + +## Files Created/Modified + +- `tests/test_script_download.py` - 5 integration tests for the 3 new .ps1 routes (install/uninstall/detect, 404, 422) +- `tests/test_packages.py` - Added `test_detail_page_shows_script_links` to `TestCommandPreview` +- `imptune/api/scripts.py` - Refactored to shared helpers, added 3 `.ps1` route aliases +- `imptune/templates/printer_detail.html` - Added Scripts section with 3 download links before Export section + +## Decisions Made + +- `.ps1` routes implemented as aliases (not renames) to preserve backward compatibility — existing extensionless routes remain functional +- Scripts section inserted inside existing `{% if has_driver %}` guard per plan spec (no scripts without a driver) +- Shared `_install_response()`, `_uninstall_response()`, `_detect_response()` helpers avoid logic duplication between the two URL shapes + +## Deviations from Plan + +None — plan executed exactly as written. + +## Issues Encountered + +During a `git stash` probe to check a pre-existing test failure, a stash from a previous 09-01 session was inadvertently popped into `tests/test_driver_upload.py`. The file was restored to its committed state via `git checkout --` before committing. The pre-existing test failure (`test_upload_returns_oob_when_called_from_form`) is out-of-scope for 09-03 and belongs to the 09-01 plan scope. + +## User Setup Required + +None — no external service configuration required. + +## Next Phase Readiness + +- UX-03 closed: technician can download each script individually from the printer detail page +- Existing package export buttons untouched +- Ready for Phase 10 real-world runtime validation + +--- +*Phase: 09-ux-tech-debt-closure* +*Completed: 2026-04-13*