diff --git a/TASKS.md b/TASKS.md new file mode 100644 index 0000000..19fa25e --- /dev/null +++ b/TASKS.md @@ -0,0 +1,101 @@ +# Implementation tasks + +The architecture is agreed as a starting point; implementation has not begun. +Complete the core CLI and manual workflow before optional automation or a TUI. + +## 1. Define manifests and command contracts + +- [ ] Define and document versioned JSON schemas for profiles and machines. +- [ ] Specify profile ordering, override precedence, disabled entries, duplicate + handling, and validation errors. +- [ ] Define package fields: ID, source, optional scope/version, and update policy. + Specify behavior for unavailable versions and already-newer installations. +- [ ] Define config fields: name, repository source, destination, copy mode, and + optional package dependency. +- [ ] Define supported path variables, source containment checks, and destination + collision handling. +- [ ] Add example base/development profiles and a machine manifest using clearly + documented sample choices. +- [ ] Specify command options, plan output, conflict handling, and exit codes. + +## 2. Build the CLI foundation + +- [ ] Add `cc.ps1`, module loading, and the `cc` launcher. +- [ ] Implement manifest loading, validation, and effective machine configuration. +- [ ] Implement `doctor` for Windows/PowerShell, WinGet, Git, repository access, + package sources, and required permissions. +- [ ] Implement a shared operation plan consumed by `plan` and `apply`. +- [ ] Add per-item logging, run summaries, atomic state writes, and a run lock. + +## 3. Implement repository synchronization + +- [ ] Persist local repository URL, branch, and selected machine outside Git. +- [ ] Implement fetch and commit resolution with actionable authentication and + network errors; reuse Git credential handling. +- [ ] Detect local edits and refuse destructive updates. +- [ ] Stage immutable commit snapshots and hand off execution without replacing + running scripts; record the revision used by each run. +- [ ] Implement `apply` without a fetch and `sync` as fetch followed by apply. + +## 4. Implement config deployment + +- [ ] Expand destination paths in the original user's context and validate paths. +- [ ] Compute file hashes and classify new, unchanged, changed, and conflicted files. +- [ ] Back up existing files and deploy replacements safely; record state only + after successful writes. +- [ ] Detect local edits using the last deployed hash, including local deletions. +- [ ] Add `--force-configs` with mandatory backup before replacement. +- [ ] Add `sync --configs-only` and config backup restoration. +- [ ] Implement `status` for config drift, conflicts, and last applied revision. + +## 5. Implement software management + +- [ ] Choose a reliable installed-package inventory strategy without depending on + localized terminal table parsing. +- [ ] Plan missing installs and policy-controlled upgrades of declared packages. +- [ ] Invoke WinGet with exact IDs, explicit sources, appropriate scope, silent + mode, and agreement/interactivity options. +- [ ] Handle package versions, unsupported scopes, unavailable packages, and + packages whose installed versions cannot be determined. +- [ ] Execute installs sequentially and interpret WinGet results, including + already-satisfied operations and reboot requirements. +- [ ] Preserve installer diagnostics and continue independent work after a failure; + skip dependent config operations and report them clearly. + +## 6. Implement elevation and first-machine setup + +- [ ] Implement a constrained elevated worker with validated inputs and structured + results, including cancellation and failure handling. +- [ ] Batch administrator operations while preserving the original user's paths + and keeping user operations in the user session. +- [ ] Secure machine-level state and elevated-worker inputs against unintended + modification; handle concurrent user sessions. +- [ ] Implement PowerShell 5.1 bootstrap to check or establish WinGet, Git, and + PowerShell 7, with explicit handling of missing WinGet registration. +- [ ] Clone the repository, save machine selection, install the launcher, and + perform the first apply. +- [ ] Verify bootstrap can resume after interrupted prerequisite installation. + +## 7. Validate and document the manual workflow + +- [ ] Add focused Pester tests for manifest validation and profile resolution. +- [ ] Test config backup, conflict, restore, and idempotent rerun behavior using + temporary directories. +- [ ] Test repository snapshot selection, dirty checkout handling, and fetch failure. +- [ ] Test package result handling and partial failure with mocked WinGet calls. +- [ ] Test fresh bootstrap and a second no-change apply on disposable Windows. +- [ ] Test elevation using both the same account and separate admin credentials. +- [ ] Test paths containing spaces/non-ASCII characters and interrupted runs. +- [ ] Test config-only updates and recovery after an installer requests a reboot. +- [ ] Write README instructions for onboarding a machine, editing profiles, + syncing, resolving conflicts, restoring configs, and finding logs. +- [ ] Document supported Windows versions, limitations, and which verification + requires Windows. + +## Later, only when useful + +- [ ] Add an optional numbered terminal menu using existing CLI commands. +- [ ] Add opt-in scheduled user-context sync with a defined policy for operations + requiring elevation. +- [ ] Add targeted application adapters or registry settings for concrete needs. +- [ ] Add explicit package removal or managed-file cleanup if requested.