6.5 KiB
6.5 KiB
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
- 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 thecclauncher. - Implement manifest loading, validation, and effective machine configuration.
- Implement
doctorfor Windows/PowerShell, WinGet, Git, repository access, package sources, and required permissions. - Implement a shared operation plan consumed by
planandapply. - 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
applywithout a fetch andsyncas 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-configswith mandatory backup before replacement. - Add
sync --configs-onlyand config backup restoration. - Implement
statusfor 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.
- Stage web bootstrap as a file and use absolute PowerShell paths for elevation.
- Add a one-command installer with automatic machine selection and repair reruns.
- 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.
- Document key-based remote administration from a Linux workstation.
- Add reversible temporary SSH access for quick cross-platform debugging.
- Add explicit package removal or managed-file cleanup if requested.
Requested desktop configuration
- Show each managed config's repository source and resolved computer path.
- Add the requested WinGet packages: XnView MP, Zoom, Nextcloud Desktop, Notepad++, HandBrake, GIMP, Krita, LibreOffice, Waterfox, and Shotcut.
- Add a safe registry-value adapter for MPC-HC settings.
- Manage Ontime user settings without treating projects, uploads, or logs as config.
- Manage XnView MP preferences without committing its catalog or thumbnails.
- Add safe Nextcloud preconfiguration without committing account credentials.
- Manage a marked block in the Windows hosts file through the elevated worker.
- Document how to capture and customize the application-specific values.