From fecb892a2dff9fc0dd80ce22e2e47e358b34755a Mon Sep 17 00:00:00 2001 From: Kawa Date: Mon, 30 Mar 2026 09:06:13 +0200 Subject: [PATCH] docs: create milestone v1.1 roadmap (3 phases) --- .planning/REQUIREMENTS.md | 28 ++++----- .planning/ROADMAP.md | 49 ++++++++++++++++ .planning/STATE.md | 118 ++++++++++---------------------------- 3 files changed, 92 insertions(+), 103 deletions(-) diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index b6af4b7..42a323a 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -46,23 +46,23 @@ | Requirement | Phase | Status | |-------------|-------|--------| -| TECH-01 | — | Pending | -| TECH-02 | — | Pending | -| TECH-03 | — | Pending | -| TECH-04 | — | Pending | -| TECH-05 | — | Pending | -| BACK-01 | — | Pending | -| BACK-02 | — | Pending | -| BACK-03 | — | Pending | -| BACK-04 | — | Pending | -| VALID-01 | — | Pending | -| UX-01 | — | Pending | +| TECH-01 | Phase 5 | Pending | +| TECH-02 | Phase 5 | Pending | +| TECH-03 | Phase 5 | Pending | +| TECH-04 | Phase 5 | Pending | +| TECH-05 | Phase 5 | Pending | +| BACK-01 | Phase 6 | Pending | +| BACK-02 | Phase 6 | Pending | +| BACK-03 | Phase 6 | Pending | +| BACK-04 | Phase 6 | Pending | +| VALID-01 | Phase 7 | Pending | +| UX-01 | Phase 7 | Pending | **Coverage:** - v1.1 requirements: 11 total -- Mapped to phases: 0 -- Unmapped: 11 ⚠️ +- Mapped to phases: 11 +- Unmapped: 0 ✓ --- *Requirements defined: 2026-03-30* -*Last updated: 2026-03-30 after initial definition* +*Last updated: 2026-03-27 after roadmap creation — all 11 requirements mapped* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 1a4db7e..2fbbd8d 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -3,6 +3,7 @@ ## Milestones - ✅ **v1.0 MVP** — Phases 1–4 (shipped 2026-03-27) +- 🚧 **v1.1 Backlog & Tech Debt** — Phases 5–7 (in progress) ## Phases @@ -18,6 +19,51 @@ Full phase details: [.planning/milestones/v1.0-ROADMAP.md](milestones/v1.0-ROADM +### 🚧 v1.1 Backlog & Tech Debt (In Progress) + +**Milestone Goal:** Ship all deferred tech debt and backlog features from v1.0 — scriptTargets filtering, UX consistency fixes, registry-driven backend list, 4 new backends, field validation, and contextual tooltips. + +- [ ] **Phase 5: Tech Debt** - Fix all deferred v1.0 issues (scriptTargets filtering, Back button, registry-driven UI, dead export, test warnings) +- [ ] **Phase 6: New Backends** - Add OneDrive, SFTP, Google Cloud Storage, and Backblaze B2 to the backend registry and wizard +- [ ] **Phase 7: Validation & UX Polish** - Add field-level format validation and contextual tooltips across all backends + +## Phase Details + +### Phase 5: Tech Debt +**Goal**: The wizard behaves consistently and the codebase is clean — no visual noise from deselected script targets, ReviewStep has a Back button, BackendSelectionStep is driven by the registry, and dead code is removed +**Depends on**: Phase 4 (v1.0 complete) +**Requirements**: TECH-01, TECH-02, TECH-03, TECH-04, TECH-05 +**Success Criteria** (what must be TRUE): + 1. User who deselected RMM in DeploymentStep sees only the Intune output block in ReviewStep (and vice versa) + 2. User can click a Back button on ReviewStep to return to DeploymentStep without losing any form data + 3. Adding a new entry to BACKEND_REGISTRY automatically surfaces that backend in the BackendSelectionStep UI with no other code changes + 4. BackendSelectionStep test suite runs with zero `act()` warnings in the Vitest output + 5. `BackendFormValues` export is absent from `src/schemas/index.ts` and no TypeScript errors arise +**Plans**: TBD + +### Phase 6: New Backends +**Goal**: IT pros can configure OneDrive, SFTP, Google Cloud Storage, and Backblaze B2 remotes through the same wizard flow, with appropriate guidance for OAuth-based and key-based auth methods +**Depends on**: Phase 5 +**Requirements**: BACK-01, BACK-02, BACK-03, BACK-04 +**Success Criteria** (what must be TRUE): + 1. User can select OneDrive as a backend, paste a pre-obtained rclone OAuth token, and generate a valid rclone.conf containing `[type = onedrive]` with the token field + 2. User can select SFTP as a backend, choose between password and private-key authentication, fill the appropriate fields, and generate a valid rclone.conf + 3. User can select Google Cloud Storage as a backend, fill in the required fields, and generate a valid rclone.conf containing `[type = google cloud storage]` + 4. User can select Backblaze B2 as a backend, enter their application key credentials, and generate a valid rclone.conf containing `[type = b2]` + 5. All four new backends appear in the BackendSelectionStep list and each produces a downloadable config+scripts bundle +**Plans**: TBD + +### Phase 7: Validation & UX Polish +**Goal**: Users receive immediate inline feedback when they enter incorrectly formatted values, and can access plain-language explanations on confusing credential fields without leaving the wizard +**Depends on**: Phase 6 +**Requirements**: VALID-01, UX-01 +**Success Criteria** (what must be TRUE): + 1. User who enters an Azure storage account name shorter than 3 characters or containing uppercase letters sees an inline error message before they can advance + 2. User who enters an S3 region in an invalid format (e.g., spaces or uppercase) sees an inline error message + 3. User can hover or click a tooltip icon on sensitive fields (SAS token, access key, SFTP auth method, OneDrive token) and read a plain-language explanation without navigating away + 4. Tooltip content accurately distinguishes SAS token from storage account key in the Azure backend form +**Plans**: TBD + ## Progress | Phase | Milestone | Plans Complete | Status | Completed | @@ -26,3 +72,6 @@ Full phase details: [.planning/milestones/v1.0-ROADMAP.md](milestones/v1.0-ROADM | 2. Generators | v1.0 | 4/4 | Complete | 2026-03-26 | | 3. Wizard UI | v1.0 | 5/5 | Complete | 2026-03-27 | | 4. Review, Download & Security | v1.0 | 5/5 | Complete | 2026-03-27 | +| 5. Tech Debt | v1.1 | 0/TBD | Not started | - | +| 6. New Backends | v1.1 | 0/TBD | Not started | - | +| 7. Validation & UX Polish | v1.1 | 0/TBD | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 6328f9a..c3e6fc1 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,12 +2,12 @@ gsd_state_version: 1.0 milestone: v1.1 milestone_name: "Backlog & Tech Debt" -status: defining_requirements -stopped_at: Milestone v1.1 started — defining requirements +status: roadmap_ready +stopped_at: Roadmap created for v1.1 — 3 phases (5-7), 11 requirements mapped last_updated: "2026-03-27T00:00:00.000Z" -last_activity: 2026-03-27 — Milestone v1.1 started +last_activity: 2026-03-27 — v1.1 roadmap created, ready to plan Phase 5 progress: - total_phases: 0 + total_phases: 3 completed_phases: 0 total_plans: 0 completed_plans: 0 @@ -21,106 +21,45 @@ progress: See: .planning/PROJECT.md (updated 2026-03-27) **Core value:** An IT pro can go from zero to a deployable rclone setup in minutes — without needing to know rclone's config syntax or PowerShell deployment conventions. -**Current focus:** Planning next milestone (v1.1) +**Current focus:** Phase 5 — Tech Debt (ready to plan) ## Current Position -Phase: Not started (defining requirements) -Plan: — -Status: Defining requirements -Last activity: 2026-03-27 — Milestone v1.1 started +Phase: 5 of 7 (Tech Debt) +Plan: — (not yet planned) +Status: Ready to plan +Last activity: 2026-03-27 — v1.1 roadmap created, 11 requirements mapped across 3 phases -Progress: [█████░░░░░] 50% +Progress: [░░░░░░░░░░] 0% (v1.1) ## Performance Metrics -**Velocity:** -- Total plans completed: 2 -- Average duration: 3 min -- Total execution time: 6 min +**Velocity (v1.0 reference):** +- Total plans completed: 18 +- Average duration: ~3 min +- Total execution time: ~54 min -**By Phase:** +**v1.1 By Phase:** | Phase | Plans | Total | Avg/Plan | |-------|-------|-------|----------| -| 01-foundation | 2 | 6 min | 3 min | - -**Recent Trend:** -- Last 5 plans: 01-01 (4 min), 01-02 (2 min) -- Trend: On track +| 5. Tech Debt | TBD | - | - | +| 6. New Backends | TBD | - | - | +| 7. Validation & UX Polish | TBD | - | - | *Updated after each plan completion* -| Phase 01-foundation P03 | 1 | 1 tasks | 1 files | -| Phase 01-foundation P04 | 2min | 2 tasks | 4 files | -| Phase 02-generators P01 | 2min | 2 tasks | 5 files | -| Phase 02-generators P04 | 5min | 1 tasks | 1 files | -| Phase 02-generators P03 | resumed | 2 tasks | 3 files | -| Phase 03-wizard-ui P01 | 1min | 2 tasks | 5 files | -| Phase 03-wizard-ui P02 | 2min | 2 tasks | 4 files | -| Phase 03-wizard-ui P03 | 2min | 1 tasks | 2 files | -| Phase 03-wizard-ui P04 | 3min | 1 tasks | 3 files | -| Phase 03-wizard-ui P05 | 5min | 2 tasks | 5 files | -| Phase 03-wizard-ui P05 | 5min | 3 tasks | 5 files | -| Phase 04-review-download-security P01 | 2min | 2 tasks | 2 files | -| Phase 04-review-download-security P02 | 2min | 2 tasks | 5 files | -| Phase 04-review-download-security P03 | 4min | 1 tasks | 2 files | -| Phase 04-review-download-security P04 | 1min | 1 tasks | 2 files | -| Phase 04-review-download-security P05 | 1min | 1 tasks | 0 files | -| Phase 04-review-download-security P05 | 1min | 1 tasks | 0 files | ## Accumulated Context ### Decisions Decisions are logged in PROJECT.md Key Decisions table. -Recent decisions affecting current work: +Recent decisions affecting v1.1 work: -- Pure frontend (no backend): simpler hosting, no data retention risk with credentials -- Support all rclone backends: broader utility beyond Azure Blob -- Optional rclone install in scripts: different orgs have different baseline images -- [01-01] Tailwind v4 via @tailwindcss/vite plugin — no postcss.config.js, no tailwind.config.js -- [01-01] Zod v4 + @hookform/resolvers v5 required together (v5 resolvers required for Zod v4) -- [01-01] vitest passWithNoTests: true so CI passes before any tests are written -- [Phase 01-02]: BACKEND_REGISTRY as Record — typed map drives both form rendering (Phase 3) and config generation (Phase 2) -- [Phase 01-02]: Wave 0 TDD stubs (index.test.ts, reducer.test.ts) written before implementation — fail RED until Plans 03-04 -- [Phase 01-02]: All FieldDef.key values snake_case matching rclone config key names exactly — wrong keys would silently break generated .conf files -- [Phase 01-foundation]: buildZodSchema loops over BACKEND_REGISTRY — field names never hardcoded in Zod schemas, registry is single source of truth for validation shape -- [Phase 01-foundation]: BACKEND_SCHEMAS exported as const — TypeScript narrows to exact backend schema type at call sites -- [Phase 01-foundation]: useReducer + Context API chosen over external state library — zero dependencies, sufficient for 4-step wizard -- [Phase 01-foundation]: useWizard throws on missing provider — fail fast prevents silent undefined state propagation -- [Phase 01-foundation]: INITIAL_STATE.deployment.scriptTargets defaults to both ['intune','rmm'] — users deselect rather than discover -- [Phase 02-generators]: s3-compatible uses type = s3 with provider = Other — rclone does not have a separate s3-compatible backend type -- [Phase 02-generators]: Intune detection scripts must not use \ (STDERR contamination); RMM scripts must use \ = 'Stop' -- [Phase 02-generators]: Credentials embedded as literals in generated PowerShell — no PS variable interpolation inside config content blocks -- [Phase 02-generators]: buildRcloneConfContent duplicated inline in rmm-script.ts — keeps generators self-contained, avoids circular dep risk -- [Phase 02-generators]: RMM scripts use \ = 'Stop' — RMM platforms surface exit codes; not STDERR-based like Intune detection -- [Phase 02-generators]: PS here-string embeds config as literals — no PS variable interpolation, satisfies credential non-echo requirement -- [Phase 02-generators]: buildIntuneDetection omits ErrorActionPreference — STDERR contamination guard per Intune detection contract -- [Phase 02-generators]: CONFIG_DIR shared via ps-helpers.ts — single source of truth prevents path drift between install and detection scripts -- [Phase 03-wizard-ui]: jsdom environment added to vite.config.ts test block — no triple-slash vitest reference needed with vitest ^4.x -- [Phase 03-wizard-ui]: Wave 0 stubs use expect.fail('not yet implemented') for named RED failures rather than relying on import errors -- [Phase 03-wizard-ui]: Requirement IDs embedded in describe block names (WIZD-01, BACK-02, etc.) for direct test-to-requirement traceability -- [Phase 03-wizard-ui]: AzureAuthToggle uses CSS hidden class (not conditional rendering) to preserve both sas_url and key in react-hook-form state when toggling -- [Phase 03-wizard-ui]: FieldRenderer hides provider field for single-option selects and auto-registers via hidden input -- [Phase 03-wizard-ui]: [03-03] waitFor used in async validation tests — handleSubmit is async, React state updates need await -- [Phase 03-wizard-ui]: [03-03] pendingBackend useRef stores clicked backend type before handleSubmit fires — avoids closure staleness -- [Phase 03-wizard-ui]: [03-03] Dispatch order: SET_REMOTE_NAME -> SET_BACKEND_TYPE -> SET_REMOTE_PARAMS({}) -> SET_STEP(1) -- [Phase 03-wizard-ui]: [03-04] useEffect guard for null backendType instead of dispatch-in-render — prevents React hooks order violation -- [Phase 03-wizard-ui]: [03-04] Fallback schema (azureblob) used when backendType is null to keep useForm call unconditional -- [Phase 03-wizard-ui]: [03-05] StepIndicator dispatches SET_REMOTE_PARAMS({}) before SET_STEP(0) — clears remote params without RESET, preserving deployment options -- [Phase 03-wizard-ui]: [03-05] App.tsx clamps stepIndex to steps.length-1 — phase 4 can add step 3 without breaking current 3-step flow -- [Phase 03-wizard-ui]: [03-05] Human verification approved — full 3-step wizard flow confirmed working end-to-end -- [Phase 04-review-download-security]: [04-01] Wave 0 stubs use expect.fail — named RED baseline for all 10 ReviewStep requirements, consistent with Phase 3 pattern -- [Phase 04-review-download-security]: [04-01] SECU-03 assertion placed in reducer.test.ts — reducer is the state boundary that must never touch storage -- [Phase 04-review-download-security]: No src/utils/index.ts barrel — direct imports keep test mock paths predictable -- [Phase 04-review-download-security]: Do NOT install @types/jszip — JSZip 3.x ships own TypeScript declarations -- [Phase 04-review-download-security]: OutputBlock disabled prop gates both Copy and Download buttons — visual opacity-40 without hiding (SECU-01 gate) -- [Phase 04-review-download-security]: [04-03] Security checkbox must be clicked before testing action buttons — disabled buttons don't fire onClick in jsdom -- [Phase 04-review-download-security]: [04-03] vi.stubGlobal must come after vi.clearAllMocks in beforeEach — clear order matters for mock reliability -- [Phase 04-review-download-security]: [04-03] Native DOM .disabled/.checked properties used instead of jest-dom matchers — jest-dom not installed in this project -- [Phase 04-review-download-security]: [04-04] No logic changes needed in App.tsx — Math.min clamp already handled 4 steps correctly once ReviewStep added to array -- [Phase 04-review-download-security]: [04-05] Human verification checkpoint reached — browser verification of full Phase 4 feature set pending user approval -- [Phase 04-review-download-security]: [04-05] Human verification approved — Phase 4 full feature set confirmed working end-to-end in real browser +- [v1.0] BACKEND_REGISTRY as single source of truth — Phase 5 wires BackendSelectionStep to it +- [v1.0] scriptTargets defaults to both ['intune','rmm'] — Phase 5 adds filtering in ReviewStep +- [v1.0] AzureAuthToggle uses CSS hidden (not conditional render) — Phase 6 SFTP auth toggle should follow same pattern +- [v1.0] Wave 0 TDD stubs written before implementation — continue this pattern in v1.1 ### Pending Todos @@ -128,12 +67,13 @@ None yet. ### Blockers/Concerns -- Phase 2: Verify exact rclone backend field names against live rclone.org docs before implementing Schema Registry — wrong keys produce silently broken configs -- Phase 2: Verify Intune 32-bit/64-bit PS host defaults and script re-execution trigger against live Microsoft docs before writing script templates -- Phase 3: Confirm current `rclone authorize` token JSON structure for OneDrive before designing OAuth token input UX +- [Phase 6] OneDrive: confirm current `rclone authorize` token JSON structure before designing token input field — token format may differ from v1.0 research +- [Phase 6] SFTP: verify exact rclone SFTP field names (key_file vs key_pem, etc.) against live rclone.org docs before writing registry entry +- [Phase 6] GCS: rclone GCS backend uses `service_account_file` or `token` — confirm auth approach before implementation +- [Phase 7] VALID-01: S3 region validation regex must match AWS region format exactly — verify against current AWS region list ## Session Continuity -Last session: 2026-03-27T13:58:13.293Z -Stopped at: Completed 04-05-PLAN.md — Phase 4 human verification approved, all 18 checks passed +Last session: 2026-03-27T00:00:00.000Z +Stopped at: v1.1 roadmap created — Phases 5-7 defined, all 11 requirements mapped Resume file: None