config-central/TASKS.md

14 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 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.
  • 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.
  • Capture live configs under Documents for review and upload without exporting Nextcloud credentials.
  • 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.

Simple web workflow

  • Add a one-command config-only updater using the saved machine and a fresh repository revision, with failure and cleanup tests.

  • Simplify the README around setup and web config updates; move detailed CLI workflows into an advanced guide.

  • Preserve signed WinGet HRESULT bits without UInt32 overflow and test diagnostic capture.

  • Rename the bundled default machine to beffroi-laptop and document switching existing setups.

  • Use PowerShell 7-compatible ACL application for elevation requests; add Windows-only permission regression tests (Windows execution pending).

  • Retry an upgrade with an install when WinGet reports no matching installed package, preserving scope and testing bounded retries.

  • Make web config updates force replacement with backups by default, with an explicit opt-out.

  • Apply the force-by-default policy during install/bootstrap too, with a preserve-local-configs opt-out.

  • Replace bootstrap exit-code exceptions with friendly partial-success, reboot, and busy summaries while preserving automation status.

  • Avoid null temporary-file cleanup after registry deployment or config adoption; preserve original per-item errors.

  • Report CLI exceptions concisely on stderr without throwing from the error handler; preserve exit code 2 and JSON errors.

  • Accept signed registry DWORD/QWORD exports and validate the complete MPC-HC declaration with mocked registry writes.

  • Color terminal item statuses while preserving plain redirected output and supporting NO_COLOR.

  • Preserve existing registry keys during MPC-HC apply and document registry-only storage and capture filtering.

  • Restore SSH firewall state using enum names, preserve retry state on cleanup failure, and show the elevated error without a wrapper stack trace.

  • Install MPC-HC through clsid2.mpc-hc and link its config to the package result.

  • Standardize entrypoint error summaries, status colors, plain redirected output, and automation exit codes across setup, updates, capture, CLI, and SSH.

  • Record the cross-script output and error-handling convention in AGENTS.md and the advanced guide.

  • 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.

  • Reduce Ontime countdown/message sizing by 30%, enlarge the clock, and bottom-align fullscreen messages; preview both layouts in Firefox.

  • Verify the shared MPC-HC x86/x64 registry target and block apply while either player is running to prevent settings being overwritten on exit.

  • Hide Ontime clock seconds and slow background blink to a three-second fade with a steady reduced-motion fallback.

  • Explain first-launch/registry-mode steps for missing MPC-HC capture settings and key-creation failures without suppressing the underlying error.

  • 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.

  • 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.

  • 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.

  • Enable the Windows sound/power defaults in desktop profiles and document the capture/update workflow.

  • Clarify when to use install versus the faster config-only update in the README.

Portable software

  • Document portable package identity, pinning, storage and recovery semantics.
  • Validate and resolve portable package declarations alongside WinGet (17 Linux Pester tests pass).
  • Implement portable ZIP planning, verified staging, launchers and recovery with Linux Pester tests; keep Windows acceptance below open.
  • 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, PDF handler registration/default selection, and running-app handling on disposable Windows x64.
  • 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).
  • Launch portable GUI packages directly from Start menu shortcuts with their embedded icons; repair legacy PowerShell-target shortcuts on the next apply (159 Linux Pester tests pass; Windows acceptance remains open above).
  • Run portable release updates before declared WinGet updates in update-software and document the complete workflow in the README.
  • Refresh Config Central from an immutable remote snapshot before update-software applies portable and declared WinGet updates (163 Linux Pester tests pass; 5 Windows-only skips).
  • Register PDF Presenter as a per-user .pdf handler and document the one-time supported Windows Default Apps selection (167 Linux Pester tests pass; Windows acceptance remains open above).
  • Remove superseded portable versions after successful activation while retaining the working version on failed updates and retrying interrupted cleanup (168 Linux Pester tests pass; 5 Windows-only skips).
  • Give PDF Presenter associations a dedicated branded PDF document icon that remains stable across portable updates (169 Linux Pester tests pass; 5 Windows-only skips).
  • Support explicit portable rename migrations that activate the successor before removing the verified old installation and handler registration, preserve local edits, and retry cleanup (189 Linux Pester tests pass; 5 Windows-only skips).
  • Replace the PDF Presenter declaration with verified Deckstride 0.1.96 from idle-org/Deckstride; keep the one-time Windows .pdf default selection in the Windows acceptance task (192 Linux Pester tests pass; 5 Windows-only skips).
  • Remove PDF Presenter's legacy self-registered Default Apps and Open With entries during the Deckstride migration.

PowerShell prerequisite reliability

  • Remove PowerShell from routine software updates and block runtime replacement in plans/workers, including missing inventory and stale plans (Linux mocked package tests pass).
  • Select the PowerShell MSI during bootstrap, probe runtime startup with retained diagnostics, and bind the launcher to the validated executable (Linux mocked bootstrap/output tests pass).
  • Verify MSI setup, broken .NET-tool/PATH recovery, and separate PowerShell updates on disposable Windows.

Requested Beffroi tools

  • Add verified PPTX Reporter 0.2.0 portable installation and update PDF Presenter to the stable 0.1.91 release.
  • Declare Pympress absent and remove it idempotently through its exact WinGet package ID.

Setup progress feedback

  • Show elapsed spinner feedback during the initial apply, keep redirected output plain, and replay child results and diagnostics after completion.
  • Show elapsed feedback during cc update-software, preserve plain/JSON output, and accept cc software-update as an alias (192 Linux Pester tests pass; 5 Windows-only skips).