feat(cli): read-only uploads staged view (#405)

[Zach Dunn (zachdunn)]

Summary

• New uploads staged [--branch <name>] [--repo <owner/name>] [--format json]: a read-only view of what's staged for a branch and whether it will auto-attach once a PR opens. One list call against the branch staging prefix (ghBranchKeyPrefix, never hand-built) plus the CLI: warn at stage time when the repo isn't bound (staged files won't auto-attach) #398 repo-binding check (files:read only, no new server surface).
• Human mode: one compact line per staged file (filename, size, gh.staged-at, public URL), a binding: <state> — <message> line, and once the PR exists: uploads attach --promote. Empty staging prints a single zero-state line.
• --format json / --json: always a valid document — { repo, branch, files, binding } — even with zero files (files: [], never empty stdout, unlike find --format json's known wart).
• Binding is folded into { state: self|other|none|unknown, autoAttach, message }. none/other reuse the exact CLI: warn at stage time when the repo isn't bound (staged files won't auto-attach) #398 stage-warning wording via a new shared stagingBindingAdvisory helper (the existing resolveStageBindingWarning now calls it too) — one source of truth, verified by test that both surfaces produce identical text for the same binding state.
• Local stdio MCP: new staged tool mirroring the CLI (shared resolveStaged core). Hosted MCP gets no new tool — it has no git context to default branch/repo from — documented as a list/find_files recipe in the skill instead.
• skills/uploads-cli/SKILL.md: documents the new command (flags, output, binding table, JSON shape), the hosted-MCP recipe, and a short video-size guidance line for PR embeds.
• Changeset: minor, @buildinternet/uploads only.

Test plan

• pnpm test — 204 files / 2567 tests pass (new test/commands-staged.test.ts, plus additions to test/mcp.test.ts and test/cli-completion.test.ts)
• pnpm --filter @buildinternet/uploads run build (tsc) and pnpm -r typecheck — clean
• pnpm run format:check — clean (oxfmt)
• Manual: uploads staged --help, uploads help --all lists staged
• Test matrix per the issue: branch/repo resolution (explicit flags, current-branch default via git rev-parse, detached-HEAD error), empty staging (human zero-state line + JSON files: [], both --json and --format json), all four binding states (self/other/none/unknown incl. network failure and older-server-without-route), JSON schema, and wording-reuse parity against attach --branch's CLI: warn at stage time when the repo isn't bound (staged files won't auto-attach) #398 warning

Closes #405

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (2)

• coderabbit:review
• review

🚫 Excluded labels (none allowed) (1)

• wip

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: bd8c3ee8-cf35-403c-8bdb-ecff16771272

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/405-staged-view

---

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	uploads-auth	3b249b9	Commit Preview URL Branch Preview URL	Jul 22 2026, 06:42 PM