feat: progress counters, timing, and --dry-run for shll update and install

[sahil-noon]

Meta

ID	Type	Confidence	Plan	Review
6vuo	feat	3.8/5.0	13/13 tasks, 19/19 acceptance ✓	✓ 1 cycle

Pipeline: intake ✓ → apply ✓ → review ✓ → hydrate ✓ → ship → review-pr

Impact: +735/−99 code (excluding fab/, docs/) · +1547/−117 total

Summary

shll update and shll install are long, side-effectful, multi-tool runs the user starts and then watches. This change polishes the existing live-streaming model (no TUI, no capture-and-reframe, no new dependency) with progress signal, post-run timing, and a safe read-only preview — the biggest DX/anxiety-reduction lever being a --dry-run that shows exactly what would happen before committing to it.

Changes

Four additive features, applied to both update and install:

• Progress counters [N/M] in each per-tool header. The denominator M is computed up front (update: installed roster tools + 1 if shll itself is brew-installed; install: len(missing)). shll (self) counts as [1/M] and prints first, so the counter agrees with the summary tail's total.
• Section spacing — a blank line before each tool section after the first, and before the summary tail, so each tool's streamed output is visually separated from the next header / the tail.
• Wall-clock run duration appended to both summary-tail forms: success Done — N of M tools succeeded in 1m12s. and partial-failure X succeeded, Y failed in 1m12s — see above. (duration before the em-dash). Timing is driven by an injectable clock seam (clock.go, package-level nowFunc mirroring the proc.Runner injection pattern) so golden-string tests stay deterministic. Duration is a run fact, not an outcome claim — the existing honesty constraint (the tail never claims "updated" vs "up-to-date") is preserved.
• --dry-run flag on both commands. It previews exactly what would run — aligned-column per-tool argv built from the same dispatch upgradeTool uses — then exits with no side effects. Read-only probes still run (brew list, <tool> update --help); no brew update/brew upgrade/brew install and no <tool> update is executed. Only actionable tools are listed (update skips uninstalled tools, install skips already-installed ones); empty cases print the existing nothing-to-do messages.

ui.go (printToolHeader, printSummaryTail) is extended and gains the aligned-column preview helpers; clock.go is new.

Why this is constitution-safe

• Principle VII (Minimal Surface Area): no new top-level subcommand — --dry-run is a flag on two existing commands. The "could this be a flag?" test is satisfied.
• Principle I (Security First): no new subprocess patterns; all execution still routes through internal/proc. --dry-run strictly reduces execution. ui.go and clock.go stay presentation/seam-only (no subprocess calls).
• Principles III/IV (Wrap / Compose, don't reinvent): the live proc.RunForeground streaming model is preserved — shll still only frames around each sub-tool's output, never capturing or reframing it.
• Principle V (Graceful Degradation): the dry-run preview lists only actionable tools.

Test coverage

Full cmd/shll package is green, race-clean, and vet-clean. New/updated tests cover:

• [N/M] counters in both header forms and counter correctness for partial-install scenarios (update and install).
• Section spacing (blank lines between sections and before the tail) via updated golden strings; empty/short-circuit cases preserve their golden output exactly (no counter/spacing/duration).
• The clock seam: a deterministic clock asserts the exact in 1m12s in both tail forms; honesty assertions still pass.
• Dry-run previews: exact aligned-column stdout, the no-writes guarantee (read-only probes ARE recorded; brew update/brew upgrade/brew install/<tool> update are NOT), and the empty-case messages.

[Copilot]

Pull request overview

This PR improves the user experience for the long-running, streamed-output workflows of shll update and shll install by adding progress signaling, run timing, and a safe --dry-run preview mode, while preserving the existing “frame around subprocess output” model.

Changes:

• Add [N/M] progress counters and consistent blank-line section spacing between tool sections and before the summary tail.
• Append wall-clock elapsed time to the success and partial-failure summary tail lines via an injectable clock seam (nowFunc).
• Add --dry-run to both commands to preview the exact planned commands (aligned columns) while still performing only read-only probes and executing no writes.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/cmd/shll/update.go	Adds --dry-run, computes [N/M] upfront, adds section spacing, measures elapsed time with nowFunc, and centralizes per-tool argv building for live run + preview.
src/cmd/shll/update_test.go	Updates goldens for counters/spacing/duration and adds dry-run preview + no-writes coverage with deterministic clock injection.
src/cmd/shll/install.go	Adds --dry-run, prints [N/M] headers with spacing, measures elapsed time with nowFunc, and prints aligned install previews.
src/cmd/shll/install_test.go	Updates goldens for counters/spacing/duration and adds dry-run preview + no-writes + counter correctness tests with deterministic clock injection.
src/cmd/shll/ui.go	Extends header/tail helpers to include counters and elapsed duration; adds aligned preview-printing helpers shared by update/install.
src/cmd/shll/ui_test.go	Updates header/tail unit tests and adds unit tests for duration formatting and preview alignment.
src/cmd/shll/clock.go	Introduces a package-level injectable clock seam (nowFunc = time.Now).
src/cmd/shll/clock_test.go	Adds a deterministic clock test helper and sequencing test.
docs/memory/cli/update.md	Documents the new counters/spacing/duration behavior and the --dry-run contract for shll update.
docs/memory/cli/install.md	Documents the mirrored behavior and --dry-run contract for shll install.
docs/memory/cli/commands.md	Updates command/file-layout docs to reflect the extended UI helpers and new clock seam.
fab/changes/260604-6vuo-update-install-polish-dry-run/*	Adds the change’s intake/plan/status/history artifacts for traceability.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.