config-central/TASKS.md

102 lines
5.4 KiB
Markdown

# 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
- [x] Define and document versioned JSON schemas for profiles and machines.
- [x] Specify profile ordering, override precedence, disabled entries, duplicate
handling, and validation errors.
- [x] Define package fields: ID, source, optional scope/version, and update policy.
Specify behavior for unavailable versions and already-newer installations.
- [x] Define config fields: name, repository source, destination, copy mode, and
optional package dependency.
- [x] Define supported path variables, source containment checks, and destination
collision handling.
- [x] Add example base/development profiles and a machine manifest using clearly
documented sample choices.
- [x] Specify command options, plan output, conflict handling, and exit codes.
## 2. Build the CLI foundation
- [x] Add `cc.ps1`, module loading, and the `cc` launcher.
- [x] Implement manifest loading, validation, and effective machine configuration.
- [x] Implement `doctor` for Windows/PowerShell, WinGet, Git, repository access,
package sources, and required permissions.
- [x] Implement a shared operation plan consumed by `plan` and `apply`.
- [x] Add per-item logging, run summaries, atomic state writes, and a run lock.
## 3. Implement repository synchronization
- [x] Persist local repository URL, branch, and selected machine outside Git.
- [x] Implement fetch and commit resolution with actionable authentication and
network errors; reuse Git credential handling.
- [x] Detect local edits and refuse destructive updates.
- [x] Stage immutable commit snapshots and hand off execution without replacing
running scripts; record the revision used by each run.
- [x] Implement `apply` without a fetch and `sync` as fetch followed by apply.
## 4. Implement config deployment
- [x] Expand destination paths in the original user's context and validate paths.
- [x] Compute file hashes and classify new, unchanged, changed, and conflicted files.
- [x] Back up existing files and deploy replacements safely; record state only
after successful writes.
- [x] Detect local edits using the last deployed hash, including local deletions.
- [x] Add `--force-configs` with mandatory backup before replacement.
- [x] Add `sync --configs-only` and config backup restoration.
- [x] Implement `status` for config drift, conflicts, and last applied revision.
## 5. Implement software management
- [x] Choose a reliable installed-package inventory strategy without depending on
localized terminal table parsing.
- [x] Plan missing installs and policy-controlled upgrades of declared packages.
- [x] Invoke WinGet with exact IDs, explicit sources, appropriate scope, silent
mode, and agreement/interactivity options.
- [x] Handle package versions, unsupported scopes, unavailable packages, and
packages whose installed versions cannot be determined.
- [x] Execute installs sequentially and interpret WinGet results, including
already-satisfied operations and reboot requirements.
- [x] 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
- [x] Implement a constrained elevated worker with validated inputs and structured
results, including cancellation and failure handling.
- [x] Batch administrator operations while preserving the original user's paths
and keeping user operations in the user session.
- [x] Secure machine-level state and elevated-worker inputs against unintended
modification; handle concurrent user sessions.
- [x] Implement PowerShell 5.1 bootstrap to check or establish WinGet, Git, and
PowerShell 7, with explicit handling of missing WinGet registration.
- [x] 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
- [x] Add focused Pester tests for manifest validation and profile resolution.
- [x] Test config backup, conflict, restore, and idempotent rerun behavior using
temporary directories.
- [x] Test repository snapshot selection, dirty checkout handling, and fetch failure.
- [x] 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.
- [x] 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
- [x] Add an optional numbered terminal menu using existing CLI commands.
- [x] 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.