#4 feat(4-install-script): one-command installer for yoke and its dependencies

[prineycom]

Summary

Adds a one-command installer for yoke on macOS, Linux, and Windows. install.sh bootstraps revdiff via brew / apt / dnf / yum / pacman / tarball, warns on missing gh, registers the github:yokeloop/yoke marketplace through claude plugin marketplace add, and verifies. install.ps1 mirrors the flow for Windows via winget → scoop. README and /hi advertise curl | bash and irm | iex entry points with a candor note about remote-script execution.

Closes #4

Attention

1. install.sh:193-218 sudo_prefix / sudo_prime — opportunistic TTY-gated sudo escalation. Critical for the curl | bash flow on Linux; post-review fix re-gates on [ -t 1 ] or warm sudo -n true and resolves once per step into $SUDO so a subshell exit 4 can't be swallowed.
2. install.sh:256-285 install_revdiff_tarball — least-privilege escape hatch with an XDG_BIN_HOME writability probe.
3. install.sh:297-302 brew tap probe — capture-then-filter pattern to dodge a pipefail false negative.
4. install.ps1:5-22 param block + $script:IsVerbose — custom [switch]$Verbose collides with [CmdletBinding()]; removed, and $script:IsVerbose = ($VerbosePreference -ne 'SilentlyContinue') -or $PSBoundParameters.ContainsKey('Verbose') is now the source of truth.
5. install.ps1:127-138 winget fallback — "already installed" / "no applicable update" exit codes re-probed against Get-Command revdiff.
6. install.ps1:183-190 Test-MarketplaceRegistered — multiline regex ([regex]::new('(?m)...')) over claude plugin marketplace list.
7. README.md / skills/hi/SKILL.md Installation blocks — byte-identical per Req 14, with the new candor note.

Design decisions

1. CLI subcommand correction (DD-1) — use claude plugin marketplace add/list/remove. The task file's claude marketplace add is not a real subcommand; verified against claude plugin marketplace --help. Slug github:yokeloop/yoke preserved.
2. Opportunistic sudo (DD-5, post-review) — gate on [ -t 1 ] or warm sudo -n true cache; resolve once per step into a $SUDO local; return non-zero instead of exit 4 so a subshell can't swallow the escalation failure.
3. Uninstall scope — remove the marketplace entry only; leave revdiff and gh binaries in place; print a manual-removal hint.
4. Monolithic installer (DD-9) — single ~507-line install.sh. No sourced modules — required for curl | bash.
5. Windows V1 scope (DD-10) — winget → scoop only. No choco, no zip-extract fallback.

Questions

1. Is the candor note in the Installation block assertive enough, or should the README recommend a pinned release tag (/releases/download/v0.1.0/install.sh) as the default install command?
2. Should --version on a release branch emit the git commit SHA alongside 0.1.0?
3. Is a scripts/test-install-docker.sh smoke harness worth landing in this PR, or deferred to a follow-up CI ticket?

Risks

• curl | bash on unknown hosts — the advertised one-liner fetches from main. Future main commits change the install surface for anyone piping the URL. Consider tagging releases.
• BSD vs GNU tool flags — tar --no-same-owner is GNU; the installer falls back on rejection. Confirm on older macOS (pre-10.15) if still in scope.
• PowerShell 5.1 Windows 10 stock — verified statically (no PS 7-only syntax); pwsh parse check deferred (not on the macOS host used here).
• Sudo fragility — if sudo is absent AND not root AND stderr has no TTY, the script exits 4. The right call, but documented only in the error message.

Test plan

Automated (already green):

• bash -n install.sh → rc=0
• pnpm run format:check → clean
• JSON manifest validation → OK
• Drift grep: claude marketplace add → 0 matches repo-wide
• ./install.sh --help, -h, --version → rc=0 before preflight
• PATH="/tmp/empty:$PATH" ./install.sh → rc=2 with Req-4 message

Manual — please run before merge:

• Clean macOS with Homebrew → ./install.sh → exit 0; claude plugin marketplace list shows yoke; revdiff --version prints a version.
• Re-run on the same machine → exit 0; stderr contains revdiff already installed and yoke marketplace already registered; no network connects.
• ./install.sh --uninstall → exit 0; marketplace row gone; revdiff binary preserved; manual-removal hint printed.
• Debian 12 container via curl -fsSL file://.../install.sh | bash with sudo available → exit 0; .deb path fires; sudo escalation works via the [ -t 1 ] gate.
• Fedora 40 container with mocked claude → exit 0; .rpm path fires.
• Network blocked after marketplace registration → exit 6 with diagnostic naming the failing verify step.
• Windows 10 stock PS 5.1 → powershell -NoProfile -Command '. .\install.ps1 -Help' → exit 0; no reserved-parameter parse error.
• winget install returns "already installed" exit code → log demotes to debug; Scoop fallback not attempted.

Changes

File	Action	Description
install.sh	created	Monolithic bash installer, mode 100755, ~507 lines
install.ps1	created	PowerShell 5.1+ installer, ~257 lines; winget → scoop fallback
README.md	modified	Rewrote ## Installation as one-liner flow; trimmed revdiff ### Install; added candor note
skills/hi/SKILL.md	modified	Installation block synced word-for-word with README
docs/ai/4-install-script/4-install-script-task.md	created	Task artifact
docs/ai/4-install-script/4-install-script-plan.md	created	Plan artifact (5 tasks, sub-agents parallel mode)
docs/ai/4-install-script/4-install-script-report.md	created	Execution report
docs/ai/4-install-script/4-install-script-review.md	created	Review report (15 found, 14 fixed, 1 informational-skipped)

Stats: 8 files, +1443 / -5.

Commits

• 8f79707 Add one-command install and activation script for yoke and its dependencies #4 docs(4-install-script): add task definition
• a30524a Add one-command install and activation script for yoke and its dependencies #4 docs(4-install-script): add implementation plan
• a2ebc57 Add one-command install and activation script for yoke and its dependencies #4 feat(4-install-script): add install.ps1 installer for Windows
• aaaaacf Add one-command install and activation script for yoke and its dependencies #4 feat(4-install-script): add install.sh installer for macOS and Linux
• 23a3adf Add one-command install and activation script for yoke and its dependencies #4 fix(4-install-script): address spec-review feedback on install.ps1
• 62bbcca Add one-command install and activation script for yoke and its dependencies #4 docs(4-install-script): switch install docs to one-command flow
• 40be260 Add one-command install and activation script for yoke and its dependencies #4 refactor(4-install-script): simplify installer scripts
• 51a37cf Add one-command install and activation script for yoke and its dependencies #4 docs(4-install-script): add execution report
• a6259ab Add one-command install and activation script for yoke and its dependencies #4 fix(4-install-script): fix 14 review issues
• 9d9bd3f Add one-command install and activation script for yoke and its dependencies #4 docs(4-install-script): add review report

Validation

• pnpm run format:check ✅ clean
• bash -n install.sh ✅ rc=0
• JSON manifests ✅ OK
• head -1 skills/*/SKILL.md ✅ every SKILL.md starts with ---
• rg -F 'claude marketplace add' across repo ✅ 0 matches
• rg -F 'claude plugin marketplace add github:yokeloop/yoke' install.sh install.ps1 ✅ 2 matches
• rg -F '/plugin marketplace add umputun/revdiff' README.md ✅ 1 match (preserved)
• rg -F '/plugin install revdiff@umputun-revdiff' README.md ✅ 1 match (preserved)

Lint / type-check / test / build: N/A (markdown-only plugin; only format:check exists).

---

[prineycom]

Not sure about this implementation. It's better for the user to install everything by themselves, since the installation process is very dependent on device/os/configuration.