161 lines
11 KiB
Markdown
161 lines
11 KiB
Markdown
# Implementation tasks
|
|
|
|
The core CLI and manual workflow are implemented. Windows-only validation remains
|
|
open until it is run on disposable machines with the required account setups.
|
|
|
|
## 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] Stage web bootstrap as a file and use absolute PowerShell paths for elevation.
|
|
- [x] Add a one-command installer with automatic machine selection and repair reruns.
|
|
- [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.
|
|
- [x] Test config-only updates and recovery after an installer requests a reboot.
|
|
- [x] Write README instructions for onboarding a machine, editing profiles,
|
|
syncing, resolving conflicts, restoring configs, and finding logs.
|
|
- [x] 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.
|
|
- [x] Add targeted application adapters or registry settings for concrete needs.
|
|
- [x] Document key-based remote administration from a Linux workstation.
|
|
- [x] Add reversible temporary SSH access for quick cross-platform debugging.
|
|
- [ ] Add explicit package removal or managed-file cleanup if requested.
|
|
|
|
## Requested desktop configuration
|
|
|
|
- [x] Show each managed config's repository source and resolved computer path.
|
|
- [x] Capture live configs under Documents for review and upload without exporting Nextcloud credentials.
|
|
- [x] Add the requested WinGet packages: XnView MP, Zoom, Nextcloud Desktop,
|
|
Notepad++, HandBrake, GIMP, Krita, LibreOffice, Waterfox, and Shotcut.
|
|
- [x] Add a safe registry-value adapter for MPC-HC settings.
|
|
- [x] Manage Ontime user settings without treating projects, uploads, or logs as config.
|
|
- [x] Manage XnView MP preferences without committing its catalog or thumbnails.
|
|
- [x] Add safe Nextcloud preconfiguration without committing account credentials.
|
|
- [x] Manage a marked block in the Windows hosts file through the elevated worker.
|
|
- [x] Document how to capture and customize the application-specific values.
|
|
|
|
## Simple web workflow
|
|
|
|
- [x] Add a one-command config-only updater using the saved machine and a fresh repository revision, with failure and cleanup tests.
|
|
- [x] Simplify the README around setup and web config updates; move detailed CLI workflows into an advanced guide.
|
|
|
|
- [x] Preserve signed WinGet HRESULT bits without UInt32 overflow and test diagnostic capture.
|
|
- [x] Rename the bundled default machine to beffroi-laptop and document switching existing setups.
|
|
- [x] Use PowerShell 7-compatible ACL application for elevation requests; add Windows-only permission regression tests (Windows execution pending).
|
|
- [x] Retry an upgrade with an install when WinGet reports no matching installed package, preserving scope and testing bounded retries.
|
|
- [x] Make web config updates force replacement with backups by default, with an explicit opt-out.
|
|
- [x] Apply the force-by-default policy during install/bootstrap too, with a preserve-local-configs opt-out.
|
|
- [x] Replace bootstrap exit-code exceptions with friendly partial-success, reboot, and busy summaries while preserving automation status.
|
|
- [x] Avoid null temporary-file cleanup after registry deployment or config adoption; preserve original per-item errors.
|
|
- [x] Report CLI exceptions concisely on stderr without throwing from the error handler; preserve exit code 2 and JSON errors.
|
|
- [x] Accept signed registry DWORD/QWORD exports and validate the complete MPC-HC declaration with mocked registry writes.
|
|
- [x] Color terminal item statuses while preserving plain redirected output and supporting NO_COLOR.
|
|
- [x] Preserve existing registry keys during MPC-HC apply and document registry-only storage and capture filtering.
|
|
- [x] Restore SSH firewall state using enum names, preserve retry state on cleanup failure, and show the elevated error without a wrapper stack trace.
|
|
- [x] Install MPC-HC through clsid2.mpc-hc and link its config to the package result.
|
|
- [x] Standardize entrypoint error summaries, status colors, plain redirected output, and automation exit codes across setup, updates, capture, CLI, and SSH.
|
|
- [x] Record the cross-script output and error-handling convention in AGENTS.md and the advanced guide.
|
|
- [x] Simplify the Ontime event timer: hide event cards, enlarge countdown and bottom message equally, and blink the background red; checked in a local Firefox fixture.
|
|
- [x] Reduce Ontime countdown/message sizing by 30%, enlarge the clock, and bottom-align fullscreen messages; preview both layouts in Firefox.
|
|
- [x] Verify the shared MPC-HC x86/x64 registry target and block apply while either player is running to prevent settings being overwritten on exit.
|
|
- [x] Hide Ontime clock seconds and slow background blink to a three-second fade with a steady reduced-motion fallback.
|
|
- [x] Explain first-launch/registry-mode steps for missing MPC-HC capture settings and key-creation failures without suppressing the underlying error.
|
|
- [x] Continue MPC-HC registry writes after individual failures, warn with key names on partial success, and fail only when no values were written; preserve diagnostics and retry state.
|
|
- [x] Back up registry value types and presence; restore failed writes or the full managed declaration on operation failure, and report incomplete rollback; verified with mocked rollback and state-failure tests.
|
|
|
|
- [x] Add capture/apply adapters for Windows sound-event assignments and the active plan's battery display timeout, with constrained declarations, backups, drift detection, and rollback; validate with Linux mocks.
|
|
- [x] Enable the Windows sound/power defaults in desktop profiles and document the capture/update workflow.
|
|
- [x] Clarify when to use install versus the faster config-only update in the README.
|
|
|
|
## Portable software
|
|
|
|
- [x] Document portable package identity, pinning, storage and recovery semantics.
|
|
- [x] Validate and resolve portable package declarations alongside WinGet (17 Linux Pester tests pass).
|
|
- [x] Implement portable ZIP planning, verified staging, launchers and recovery with Linux Pester tests; keep Windows acceptance below open.
|
|
- [x] Add the verified PDF Presenter 0.1.33 release to the desktop profile and document updates; validate archive/executable hashes and run the Linux suite (136 passed, 5 Windows-only skips).
|
|
- [ ] Validate portable installation, Start menu launch and running-app handling on disposable Windows x64.
|
|
- [x] Add `update-software` with checksum-verified Gitea release discovery and package-only execution; validate against the live PDF Presenter feed and run the Linux suite (155 passed, 5 Windows-only skips).
|