cli: cell-routing foundation — client factory, generic repo→cell resolver, multi-cell fan-out

[Soph]

https://entire.io/gh/entireio/cli/trails/762

Stacked on #1592. Extracts the CLI's cell-routing plumbing into a shared foundation so multi-cell commands (code search, #1616, and anything after it) stop growing parallel copies of it. The backend model gives the CLI exactly three routing shapes, mirroring the entire.io BFF: repo-scoped → one cell, user-scoped /me → home cell, repo-set queries → fan out and merge client-side (no server-side aggregator exists). #1592 covers the second; this PR generalizes the first and builds the third.

Commits

• auth.CellClientFactory — NewEntireAPICellClient resolved the login subject (discovery + refresh) and ran the RFC 8693 exchange on every call. Identity tokens are per-jurisdiction, not per-cell, so a fan-out over N cells was about to pay N× all of it. The factory resolves the subject once and mints at most one token per jurisdiction; NewEntireAPICellClient stays as the single-cell wrapper, existing callers unchanged.
• cell_target.go — mechanical generalization of experts_cell_target.go (resolveRepoCellTarget, cellCoreClient, cellResolveTimeout): nothing in it was experts-specific, and it's the repo-scoped shape every cell-routed command needs. No behavior change.
• cell_fanout.go — the repo-set shape, extracted from what cli: add code search with multi-region fan-out (ENT-993) #1616 currently inlines into search_cmd.go:
  • groupReposByCell: repo index → per-cell groups, deterministic order.
  • resolveCellBaseURLs: cluster-catalog join on ClusterSlug↔Cluster.Slug. The catalog exposes no cell field — cli: add code search with multi-region fan-out (ENT-993) #1616's current join of the cell name against Slug only works when the two happen to coincide; a test pins the correct key.
  • fanOutCells: parallel per-cell calls under a per-cell timeout through one shared CellClientFactory; partial failures are isolated per result slot, merge semantics stay with the command.
• Documents the three routing shapes in CLAUDE.md.

Intended consumer

#1616 (code search) keeps its codesearch client, merge/sort/dedup semantics, and output rendering, and replaces its inline groupReposByCell/searchAllCells/searchCell orchestration with these helpers — fixing the slug join and the per-cell token minting along the way.

Testing

mise run test:ci green (unit + integration + both canary suites), -race on the fan-out tests. New tests: factory token reuse per jurisdiction, group determinism, slug-join pinning, per-cell failure isolation.

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches authentication (RFC 8693 exchange caching) and cross-region API routing; behavior is largely refactored with tests, but fan-out and factory concurrency affect how multi-cell commands authenticate and fail partially.

Overview
Introduces shared entire-api cell routing so multi-cell commands can reuse one plumbing layer instead of duplicating BFF-style routing.

Auth: NewEntireAPICellClient now delegates to CellClientFactory, which resolves the login subject once and caches one jurisdictional identity token per jurisdiction (not per cell). NewEntireAPICellClient remains the single-cell entry point; existing callers are unchanged.

Repo-scoped routing: Experts-style resolution is renamed and generalized to resolveRepoCellTarget (from resolveExpertsCellTarget), with shared cellCoreClient / cellResolveTimeout naming. Behavior is unchanged; NewAuthenticatedEntireAPICellClient calls the new resolver.

Repo-set routing: New cell_fanout.go provides groupReposByCell, resolveCellBaseURLs (catalog join on ClusterSlug ↔ Cluster.Slug, not cell name), and generic fanOutCells (parallel per-cell calls, per-cell timeout, isolated partial failures, one factory per operation).

Docs: CLAUDE.md documents the three routing shapes (repo-scoped, /me home cell, repo-set fan-out) and the per-jurisdiction token rule.

Minor: shared writeJSON test helper in corecmd_test.go; comment tweak in entireapi_client.go for timeout naming.

^{Reviewed by Cursor Bugbot for commit 73b1b2e. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 73b1b2e. Configure here.}

[Copilot]

Pull request overview

This PR extracts and generalizes the CLI’s entire-api cell-routing plumbing into shared helpers, enabling future multi-cell commands (e.g., code search) to fan out across cells without duplicating routing/auth logic. It introduces a reusable cell client factory to avoid repeated subject resolution and redundant identity-token exchanges during multi-cell operations, and adds a generic repo→cell resolver plus fan-out grouping/join logic aligned with the BFF routing model.

Changes:

• Introduces auth.CellClientFactory to build cell clients from one resolved subject and cache identity tokens per jurisdiction.
• Generalizes the repo-scoped routing resolver into resolveRepoCellTarget and adds multi-cell fan-out helpers (groupReposByCell, resolveCellBaseURLs, fanOutCells).
• Adds unit tests for token reuse, deterministic grouping/join behavior, and per-cell failure isolation; documents the three routing shapes in CLAUDE.md.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
cmd/entire/cli/entireapi_client.go	Updates timeout comment reference to the generalized cell resolver timeout.
cmd/entire/cli/corecmd_test.go	Adds shared writeJSON helper for corecmd test stub handlers.
cmd/entire/cli/cell_target.go	Renames/generalizes experts-specific repo→cell routing into shared resolver + interfaces.
cmd/entire/cli/cell_target_test.go	Updates resolver tests to the generalized names; shares test constants/stubs.
cmd/entire/cli/cell_fanout.go	Adds new multi-cell fan-out foundation: grouping, catalog join, parallel fan-out.
cmd/entire/cli/cell_fanout_test.go	Adds tests for grouping determinism, correct catalog join key, fan-out semantics.
cmd/entire/cli/auth/cell_data_api.go	Refactors NewEntireAPICellClient to use CellClientFactory; adds per-jurisdiction token caching.
cmd/entire/cli/auth/cell_data_api_test.go	Adds coverage pinning “one token per jurisdiction” reuse behavior via the factory.
cmd/entire/cli/api_client.go	Switches repo-scoped client construction to resolveRepoCellTarget.
CLAUDE.md	Documents the three cell-routing shapes and the per-jurisdiction token rule.

[Soph]

Reworked the temporary test-helper commit to match #1640's new shape: the corecmd stub handlers now route through printJSON (the #1606 deslop convention) instead of reintroducing the deleted writeJSON. Still falls out on rebase once #1640 merges.

[evisdren]

minor comment from claude, otherwise good:

  In tokenFor (cell_data_api.go), slot.mu.Lock() is held while exchangeJurisdictionToken makes an HTTP call. The comment on CellClientFactory.mu says "never
  held across I/O", but mintSlot.mu is held across I/O — that's the design (single-flight per jurisdiction). This is fine for correctness and the intent is
  correct (block concurrent callers for the same jurisdiction while one mints), but the comment on CellClientFactory.mu could mislead readers into thinking
  no mutex in the struct is held across I/O. Consider clarifying that the factory-level mu is never held across I/O, while slot-level mu intentionally is.

  File: cmd/entire/cli/auth/cell_data_api.go (around tokenFor)```

The base branch was changed.