feat: add page version listing and purge commands

[stevenhan2]

Description

Three new commands and matching client methods for managing Confluence page version history:

• versions <pageId> — list historical versions (read-only)
• version-delete <pageId> <versionNumber> — delete a single non-current version
• versions-purge <pageId> — convenience: delete every non-current version, keeping only current

The list and delete calls fall back transparently to the /rest/experimental/ endpoint on a 404 or 405 from the configured /rest/api/ path. Confluence Server/Data Center exposes content versions only at the experimental path; Cloud accepts both. The fallback is sticky for paginated listVersions so long histories don't double their round-trip count.

versions-purge accepts --throttle <seconds> to space the version-delete calls inside one page, useful when the underlying instance has aggressive rate limits.

Type of Change

• New feature (non-breaking change which adds functionality)

Testing

• Tests pass locally with my changes (648/648)
• I have added tests that prove my feature works
• New and existing unit tests pass locally with my changes

12 new test cases cover:

• pagination of listVersions
• 404 and 405 fallback on both list and delete
• empty results array (no infinite loop)
• 404 propagation when both modern and experimental return 404 (page-not-found)
• end-to-end purge through both fallbacks
• descending-order delete (some Confluence builds renumber when an earlier version is removed)
• partial-failure tolerance (continues the loop, collects errors)

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas (path-strategy explanation in listVersions, descending-order rationale in purgeNonCurrentVersions)
• I have made corresponding changes to the documentation (3 new rows in the Commands table)
• My changes generate no new warnings

Additional Context

• The viaExperimental flag returned by deleteVersion and yielded from purgeNonCurrentVersions's onProgress callback is intended as a debugging signal so a user can see when their instance routed via the fallback path. Happy to drop or rename if you'd prefer it stay implementation-detail.
• Possible follow-ups (intentionally not in this PR to keep it focused):
  • --dry-run on versions-purge
  • Move the throttle from the CLI's onProgress callback into purgeNonCurrentVersions itself so library consumers can pace without a custom callback
  • CLI-layer validation of versionNumber for friendlier error UX

[pchuri]

Thanks for the thoughtful PR — really appreciate the level of care here. The 12 new test cases, the path-strategy comment in listVersions, and the descending-order rationale in purgeNonCurrentVersions made this very easy to review.

A few things I particularly liked:

• Sticky fallback in listVersions — flipping useExperimental once and reusing it across paginated requests avoids doubling round-trips on long histories. Nice touch.
• Descending-order delete with the renumber rationale — exactly the kind of subtlety that bites you in production; glad it's both implemented and documented inline.
• Partial-failure tolerance — collecting errors and continuing the loop (with a covering test) is the right behavior for a bulk-cleanup tool.
• Consistent assertWritable usage on both mutating commands.

A few minor suggestions (none blocking — happy to land as-is and address as follow-ups):

1. Double listVersions call in versions-purge CLI — bin/confluence.js calls listVersions for the early-exit checks, then purgeNonCurrentVersions calls it again internally. For pages with long histories this doubles the listing cost. Could pass pre-fetched versions in via options, or move the early-exit logic into the library.
2. --throttle input validation — parseFloat('abc') returns NaN, which silently disables throttling (NaN > 0 is false). A Number.isFinite() guard with a friendly error would catch typos.
3. versionNumber validation in CLI — currently happens inside deleteVersion, so running version-delete 123 abc shows the prompt as Delete vNaN of page 123? before the validation rejects. Validating in the CLI before the prompt is a small UX win.
4. README vs. CLI argument names — README documents versions <pageId_or_url> but the CLI registers versions <pageId> (similar for the other two). The behavior is correct since extractPageId accepts both, but --help output won't tell users URLs are accepted. Existing delete <pageIdOrUrl> is the precedent.
5. viaExperimental in the public API — you flagged this in the PR description; agree it's a nice debugging signal but worth documenting as @unstable or similar so future removal isn't a breaking change for library consumers.
6. Hardcoded limit: 200 — other paginated methods (e.g. getSpaces) accept a pageSize option via parsePositiveInt. Worth aligning for consistency, though not urgent.

CI note

The failing security check is unrelated to this PR — it's the recent batch of axios advisories (validateStatus prototype pollution, etc.) tripping npm audit --audit-level moderate. The same job fails on main at the latest commit, and this PR doesn't touch package.json or package-lock.json. A separate axios bump PR is needed; please don't let it block this one.

Approving. Thanks again!

[github-actions]

🎉 This PR is included in version 2.5.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀