cli: consolidate pulp pr with shipyard pr + fix pulp upgrade 404

[danielraffel]

Found while shipping PR #350. Two related but distinct CLI gaps around the documented ship flow.

Context

CLAUDE.md and .agents/skills/ci/SKILL.md instruct agents to "run `pulp pr`" whenever the user says "ship this" / "push a PR" / etc. It's the documented single-orchestrator entry point.

Two things break that:

1. pulp pr is not in the installed binary

tools/cli/cmd_pr.cpp exists. tools/cli/pulp_cli.cpp:41 wires it into the dispatch table. But:

• Pinned release v0.14.0 (latest) predates pulp pr's landing in PR Versioning & skill-sync gates + pulp pr + auto-release on merge #144 on 2026-04-13. Looking at the source history, cmd_pr.cpp was first wired in 9ee9fce on 2026-04-13; the v0.14.0 binary was cut on 2026-04-16 but the installed binary at ~/.pulp/bin/pulp dates from April 7 — before the PR.
• pulp help on the installed binary does not list pr, so an agent reading CLAUDE.md and running pulp pr fails with "Unknown command: pr".
• Meanwhile, shipyard pr already exists and does the exact same thing. Its help text even says: "Mirrors pulp's `pulp pr` for parity with the ci skill's natural-language triggers." Same four steps: skill_sync_check → version_bump_check → commit → shipyard ship.

2. pulp upgrade 404s on release assets

Separately, pulp upgrade on the April 7 binary tries to download:

pulp-0.14.0-darwin-arm64.tar.gz

…which returns 404. The actual asset on gh release view v0.14.0 is:

pulp-darwin-arm64.tar.gz          (no version in the filename)

So even if an agent correctly runs pulp upgrade first, it silently fails and the user stays on a stale binary forever.

User impact

• Any agent following the documented "push a PR" flow hits "Unknown command: pr" unless their ~/.pulp/bin/pulp is newer than 2026-04-13.
• pulp upgrade doesn't unbreak them because the filename template is wrong.
• Net effect: agents silently fall through to running gh pr create + shipyard ship separately (exactly what CLAUDE.md forbids), or file-locally.

Proposed plan

Pick one for pulp pr:

• (A) Delete pulp pr, point docs at shipyard pr. shipyard pr is already the real implementation and its "mirrors pulp's" framing would be flipped. Remove tools/cli/cmd_pr.cpp and the dispatch entry. Update CLAUDE.md + .agents/skills/ci/SKILL.md + pr skill to call out shipyard pr as the entry point. Cleaner, one source of truth.
• (B) Make pulp pr a thin shim that execs shipyard pr. Preserves the natural-language trigger "pulp pr" but avoids code duplication. Requires fewer doc edits.

I recommend (A) — Shipyard is the primary CI tool per the ci skill, and the shim adds a second failure mode (shim-present-but-shipyard-missing).

pulp upgrade fix:

• Align the upgrade downloader's filename template with tools/install-shipyard.sh's style (<name>-<platform>-<arch>.tar.gz), or look up the asset list via the GitHub API rather than composing a URL.
• Add a CLI test that mocks the GitHub API response and asserts the resolved URL matches a real asset name.

Acceptance criteria

• One documented path (shipyard pr or pulp pr), no "Unknown command" surprise.
• pulp upgrade on v0.14.0 successfully resolves and downloads the latest release, verified with a mocked-http test.
• CLAUDE.md + ci skill + pr skill all agree on the entry command.
• No silent fall-through to separate gh pr create + shipyard ship calls (the ci skill's hard rule).

Related

• .agents/skills/ci/SKILL.md § "Shipping a PR: route through pulp pr"
• .agents/skills/pr/* (pulp plugin pr skill)
• PR Versioning & skill-sync gates + pulp pr + auto-release on merge #144 (original pulp pr landing)
• PR doctor + pulp pr: surface missing RELEASE_BOT_TOKEN secret #149 (RELEASE_BOT_TOKEN heads-up in pulp pr)
• tools/install-shipyard.sh (reference filename template)

[danielraffel]

Per follow-up discussion, preference is option (B) with graceful degradation:

• pulp pr becomes a thin shim:
  1. If shipyard is on PATH → exec shipyard pr "$@" (forward all flags).
  2. If not → print a concise install guide pointing at tools/install-shipyard.sh + how to add ~/.pulp/bin to PATH, then exit non-zero.
• Eventually dep-free; the existing in-CLI skill-sync/version-bump logic stays available but becomes a fallback path.

Rationale:

• Preserves the documented natural-language trigger "run pulp pr" — no doc churn required in CLAUDE.md or skills.
• Single real implementation (shipyard) stays the source of truth; no drift risk.
• Graceful degrade instead of "Unknown command" when shipyard isn't installed yet — critical for first-time contributors.

The pulp upgrade 404 fix stands as an independent sub-task in this same issue.