feat: add list_custom_shards tool using v1 API

[lorcan]

Why?

The get_infrastructure tool is the only tool in this codebase that uses the /internal PlanetScale API. The /internal API has a more restrictive authentication mechanism than /v1, and failures present as opaque 404s rather than clear auth errors. As a v1 endpoint, custom-shards uses the same authentication as every other tool in this codebase.

The v1 endpoint also has better ergonomics for the shard-sizing use case:

• Returns all shards in a paginated list (~2 API calls for 128 shards) vs the current tool's 1-call-per-shard approach
• A has_override flag explicitly marks shards resized from the keyspace default, rather than inferring this from the most common size
• An active_resize flag per shard, vs only a keyspace-level resizing boolean

How?

Adds a new list_custom_shards tool that calls the v1 endpoint /v1/.../keyspaces/{ks}/custom-shards to list per-shard cluster sizes. The tool has two modes: a default summary mode that auto-paginates and returns size distribution, override shards, and active resizes; and a raw paginated mode when page/per_page are provided. Tool descriptions on get_infrastructure, get_branch_keyspaces, and list_resizes are updated to cross-reference the new tool.

Decisions

• Retaining get_infrastructure for now: The /internal endpoint returns VTGate info and per-tablet AZ placement that no v1 endpoint currently provides. The old tool is retained until we're certain this data is no longer valuable or we find a v1 replacement. The preference is to retire it.
• Summary mode as default: The most common question is "what size are my shards?" — auto-paginating and computing the size distribution answers this in one call instead of requiring the caller to paginate manually.

Risks

The v1 /custom-shards endpoint does not provide:

• VTGate information (name, size, availability zone distribution)
• Per-tablet AZ placement (which AZ each primary/replica is in)
• Primary/replica distinction (only the effective cluster size per shard)

If downstream consumers rely on this data, they must continue using get_infrastructure. The updated tool descriptions steer callers to list_custom_shards for shard sizing and preserve get_infrastructure for VTGate/AZ detail.

Note: The other /internal-based tool, get_metrics, does not currently have a v1 equivalent — the /v1/.../metrics path returns 404 with both service tokens and OAuth. Migrating get_metrics away from /internal will require PlanetScale to expose a v1 metrics endpoint.

Implementation Plan

Implementation

Step 1: Add CustomShard interface and listCustomShards() to planetscale-api.ts

New interface matching the v1 response shape, and a new function using the existing apiRequest helper and PaginatedResponse<T> type.

Step 2: Create src/tools/list-custom-shards.ts

New tool following existing patterns (get-branch-keyspaces.ts, list-resizes.ts).

Input: organization, database, branch, keyspace (all required), page/per_page (optional)

Output — two modes:

1. Summary mode (default): auto-paginate all shards, return shard_count, size_distribution, default_size, override_shards, active_resizes
2. Paginated mode: raw paginated results when page/per_page provided

Step 3: Register in gram.ts

Existing get_infrastructure tool

Left unchanged. It still works when OAuth is available and provides VTGate/AZ info that list_custom_shards doesn't.

Verification

• Type check passes
• Tested summary mode and paginated mode against a 128-shard production keyspace using a service token

_{Generated with Claude Code}