CLI: purge-expired dry-run + resource/verb command shape

[zachdunn]

Context

From the CLI-for-agents pass on the update-hint work (feat/cli-update-hint): a few agent affordances were deliberately deferred so the version-hint ship stayed small. This issue tracks them.

Goals

1. Dry-run for destructive / bulk maintenance

Agents need a safe preview before committing side effects.

Surface	Today	Desired
uploads delete <key>	--dry-run	Keep
uploads purge-expired	Always mutates when retention is set	--dry-run (or equivalent) that reports what would be deleted + freed bytes without writing
MCP purge_expired	Same as CLI	Mirror CLI dry-run flag
uploads reconcile	Always rewrites ledger totals from storage	Optional preview of current vs storage-derived totals if cheap

Notes

• Prefer implementing dry-run in the API (e.g. ?dryRun=1 or a dedicated preview response) so CLI, remote MCP, and stdio MCP stay consistent — not a client-only simulation that can drift from purge logic.
• Dry-run output should be machine-useful under --json ({ dryRun: true, wouldDelete, wouldFreeBytes, … }).
• Document in uploads purge-expired --help, package README, and skills/uploads-cli/SKILL.md (skill currently notes that purge has no dry-run).

2. Consistent resource + verb command shape

The CLI mixes flat verbs (put, list, delete) with nested resources (gallery create|add|…, config show|set|…, admin invite create). Agents pattern-match better when the grammar is predictable.

Non-goals for a first PR

• Do not break the existing top-level verbs agents and the skill already use (put, attach, list, delete, comment, …).
• Do not rename MCP tool names without a compatibility period.

Possible approaches (pick one in design)

1. Additive aliases only — e.g. uploads files list → list, uploads files delete → delete, keep current names primary.
2. Document a stable grammar for new commands only: uploads <resource> <verb>, and leave historical flat verbs as permanent aliases.
3. Longer migration — promote resource/verb, deprecate flat names with dual help and a major bump (high cost; likely not worth it).

Recommend (1) or (2): layered --help with examples under both spellings, skill and README list the preferred form first.

Acceptance criteria

• purge-expired (and MCP twin) supports dry-run / preview with stable JSON
• Help, package README, and skills/uploads-cli/SKILL.md document the preview path
• Decision recorded on resource/verb strategy (aliases vs new-only)
• If aliases land: examples in help for both shapes; no regression on existing agent invocations
• Tests cover dry-run no-mutation and alias routing

Related

• CLI-for-agents skill checklist: non-interactive first, layered help, dry-run for destructive actions, predictable structure
• Recent: version update hints, --version, usage errors → uploads <cmd> --help (this branch)