feat(cli): spike shared list behavior with legacy compatibility

[shrey150]

Browse list commands currently disagree about JSON envelopes, whether --limit applies to JSON, pagination, and available formatting flags. For example, cloud sessions list --limit 1 --json returns the whole API response, while secrets lists use --limit as a single-page request size.

This draft introduces a shared collection adapter behind --list-version 2. cloud sessions list --list-version 2 --limit 1 --json returns one record in { data, hasMore, nextCursor }. Existing invocations keep their behavior; version 1 remains the default.

Contract and scope

• Total --limit defaults to 20 in both table and JSON output. --all removes that limit and follows API cursors; combining it with an explicit limit is an error.
• Shared --format table|json, --json, --wide, TTY defaults, empty output, and continuation messages. Resource columns remain specific to the resource.
• Cursor-backed lists fetch only the remaining requested count, reject oversized pages and repeated/invalid cursors, and emit no partial collection if a later page fails.
• hasMore is true, false, or null for unknown completeness. A nextCursor is returned only when the backend can resume after the last emitted record. Sessions cannot claim a complete history from their unpaginated response.
• Adapters cover projects, sessions, locally saved context aliases, project secrets, Function secrets, and both skills/templates list and find (nine commands).
• Legacy JSON shapes, table-only limits, exact-match detail views, and single-page secrets behavior remain the default. New flags require version 2 where they were not previously supported.

The README documents the contract and migration. A browse minor changeset makes this suitable for the next minor release once the spike is accepted; it does not flip the default. Ranked cloud search, browser-driver tab list, logs, and artifact downloads are outside this initial adapter.

Validation

CLI build passed. Full CLI suite: 38 files / 494 tests passed, including the existing compatibility tests and 17 new pagination/collection tests. After the final cursor validation and help-text cleanup, the focused collection tests and build passed again. ESLint and changed-file formatting passed.

E2E Test Matrix

Built CLI against live APIs on 2026-09-24; existing environment credentials, synthetic secret values only.

Flow	Observed result	Scope
Projects and sessions with v2 --limit 1 --json	Common envelope, at most one record	Real project API; sessions retain unknown completeness
Skills list/find and templates list/find	Common envelope and limit	Live public catalogs
Project and Function secrets: --limit 1, resume with --cursor ... --all	All three synthetic IDs returned, no duplicate or missing IDs, final cursor null	Real deployed test function
Both secrets lists with --all --format table --wide	All three keys rendered	Real metadata only
Both secrets lists without v2	Original { data, limit, nextCursor } single-page shape	Backward compatibility
Local context aliases	Same envelope and limit	CLI contract test using a temporary local store
Short/empty API pages, API errors, cursor cycles, oversized pages	Correct continuation or failure with empty stdout	Controlled HTTP/unit contract tests; total limits above API page size covered
Cleanup	All three synthetic secrets detached and deleted	No new functions or schedules created

Related independent PRs: dotenv default transition #3038; bundled secrets skill #3037. The list contract does not depend on the Functions shared-core PR.

---

Summary by cubic

Adds an opt-in shared list contract behind --list-version 2 so project, session, context, secrets, skills, and templates list commands agree on JSON envelopes, total --limit, and formatting. Existing invocations keep their current behavior; version 1 remains the default.

Contract

• --limit is a total record limit (default 20) in every output format; --all removes it and cannot be combined with an explicit limit.
• JSON output is always { data, hasMore, nextCursor }; hasMore is false when the source is exhausted and null when completeness is unknown (sessions).
• The two secrets lists gain cursor continuation across API pages; oversized, repeated, or invalid cursors fail without printing a partial collection.

Scope

• Covers nine commands with 17 new collection tests; the full CLI suite (494 tests) passes.
• README documents the contract and migration; the browse minor changeset keeps it suitable for the next minor release without changing the default.

^{Written for commit 9606832. Summary will update on new commits.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 9606832

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
browse	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR