Skip to content

Commit c77df99

Browse files
cliffhallclaude
andcommitted
docs: address review round 2 — stale customHeaders refs, rule wording (#1776)
Doc-only follow-up to the round-2 @claude review on PR #1784 (no code changed): 1. Stale paths (same class as round-1 item 1): the customHeaders move left three references to the deleted lib/types/customHeaders.ts path in specification/ (v2_ux_interfaces_phase_0_4_inventory.md, v2_ux_interfaces_plan.md ×2) — updated to utils/customHeaders.ts. 2. customHeaders anchor: note in AGENTS.md that its shape is staged for ServerSettingsForm (per v2_ux_interfaces_plan.md), so its zero-importer state reads as intentional rather than rot; kept as the no-types/-bucket illustration and led the anchor list with load-bearing modules. 3. Type-only-import clause: split the conflated clause — a type-only import (pendingReauth) and re-exporting core's pure functions/constants (oauthUx/oauthFlow) are distinct reasons to stay in utils; what makes a module lib is wrapping core's stateful runtime. Fixed in both AGENTS.md and the web README. Cosmetic: re-padded the v2_auth_mid_session.md table row to column width. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
1 parent 86fbdfc commit c77df99

5 files changed

Lines changed: 6 additions & 6 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -245,7 +245,7 @@ gh project item-edit --project-id PVT_kwDOCt2Azc4BJVxt --id "$ITEM_ID" --field-i
245245

246246
The web client keeps two grab-bag directories under `clients/web/src`, split by a real (now codified) rule — **`utils` = functions that compute; `lib` = things that instantiate, adapt, or touch the environment.** If it does I/O or wraps a subsystem, it's `lib`; if it's a pure transform, it's `utils`.
247247

248-
- **`src/utils/`** — pure, side-effect-free functions. Input → output, no DOM/browser/storage I/O, no subsystem ownership. Trivially unit-testable with no mocks. (Anchors: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `inspectorTabs`, `deepLink`, `sandbox-csp`, `customHeaders`.) This includes modules that are pure **shared domain types plus their pure constructors/transforms** (`customHeaders` — `CustomHeader` + `headersToRecord`/`migrateFromLegacyAuth`); there is no separate `types/` bucket. **Diagnostic logging (`console.warn`/`console.error`) does not count as a side effect** for this rule — a validator that warns on bad input is still "pure" here (`sandbox-csp`, `jsonUtils`, `schemaUtils` all warn). A module that only imports **types** from `@inspector/core` (or elsewhere) is likewise pure and belongs here — a type-only import is not a subsystem dependency (e.g. `pendingReauth` is pure type declarations, `oauthUx`/`oauthFlow` re-export core copy/predicates).
248+
- **`src/utils/`** — pure, side-effect-free functions. Input → output, no DOM/browser/storage I/O, no subsystem ownership. Trivially unit-testable with no mocks. (Anchors: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `inspectorTabs`, `deepLink`, `mcpNetworkHeaders`.) This includes modules that are pure **shared domain types plus their pure constructors/transforms** (`customHeaders` — `CustomHeader` + `headersToRecord`/`migrateFromLegacyAuth`, a shape staged for `ServerSettingsForm`, see `specification/v2_ux_interfaces_plan.md`, so it currently has no importer but its own test); there is no separate `types/` bucket. **Diagnostic logging (`console.warn`/`console.error`) does not count as a side effect** for this rule — a validator that warns on bad input is still "pure" here (`sandbox-csp`, `jsonUtils`, `schemaUtils` all warn). Two forms of importing from `@inspector/core` are also fine: a **type-only** import is not a subsystem dependency (`pendingReauth` is pure type declarations), and **re-exporting pure functions or constants** from core is not subsystem ownership either (`oauthUx`/`oauthFlow` re-export core copy/predicates) — what makes a module `lib` is wrapping core's *stateful runtime*, not merely importing from it.
249249
- **`src/lib/`** — infrastructure / integration / stateful adapters. Modules that instantiate or compose subsystems, wrap the `@inspector/core` **runtime** (not just its types), touch the DOM / `window` / `sessionStorage`, or otherwise produce side effects. (Anchors: `environmentFactory` composes `InspectorClientEnvironment`; `remoteOAuthStorage` is an adapter class over `core/auth`; `oauthResume` reads/writes `sessionStorage`; `browserTabVisibility` registers `visibilitychange` listeners; `clearServerOAuthState` drives the live `InspectorClient` / `OAuthStorage`; `downloadFile` triggers browser downloads.)
250250

251251
Cross-directory imports point **one way, `lib → utils`** (infra depends on pure helpers, never the reverse). Keep it that way: if a `utils/` module needs a type currently exported from a `lib/` module, declare the type in `utils/` and re-export it from `lib/` (as `pendingReauth` owns `OAuthResumeAuthKind` and `oauthResume` re-exports it), rather than importing "up" from `utils` into `lib`.

‎clients/web/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ Every screen and element has a `*.stories.tsx` (see [Storybook](#storybook)). St
5959

6060
Two grab-bag directories, split by one rule: **`utils` = functions that compute; `lib` = things that instantiate, adapt, or touch the environment.** If it does I/O or wraps a subsystem, it's `lib`; if it's a pure transform, it's `utils`.
6161

62-
- **`src/utils/`** — pure, side-effect-free functions (no DOM/`window`/`sessionStorage` I/O, no subsystem ownership), trivially unit-testable with no mocks. Diagnostic `console.warn`/`console.error` doesn't count as a side effect, and a type-only import from `@inspector/core` doesn't count as a subsystem dependency. Also home to pure shared domain types + their constructors (`customHeaders`) — no separate `types/` bucket. Examples: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `deepLink`, `sandbox-csp`, `customHeaders`.
62+
- **`src/utils/`** — pure, side-effect-free functions (no DOM/`window`/`sessionStorage` I/O, no subsystem ownership), trivially unit-testable with no mocks. Diagnostic `console.warn`/`console.error` doesn't count as a side effect; neither a type-only import from `@inspector/core` nor re-exporting core's pure functions/constants counts as a subsystem dependency (what makes a module `lib` is wrapping core's stateful runtime). Also home to pure shared domain types + their constructors (`customHeaders`) — no separate `types/` bucket. Examples: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `deepLink`, `sandbox-csp`, `customHeaders`.
6363
- **`src/lib/`** — infrastructure / stateful adapters: modules that compose subsystems, wrap the `@inspector/core` **runtime**, or produce side effects. Examples: `environmentFactory`, `remoteOAuthStorage`, `oauthResume` (sessionStorage), `browserTabVisibility` (DOM listeners), `clearServerOAuthState`, `downloadFile`.
6464

6565
Nothing keys off the boundary — it's a human-legible import-time signal. See [`AGENTS.md`](../../AGENTS.md) for the full rule.

‎specification/v2_auth_mid_session.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@ RemoteClientTransport StreamableHTTPClientTransport
139139
| EMA | `core/auth/ema/emaFlow.ts`, `core/auth/ema/resourceContext.ts` — see [v2_auth_ema.md](v2_auth_ema.md) |
140140
| Web remote backend | `core/mcp/remote/node/server.ts`, `remote-session.ts`, `core/mcp/node/authChallengeFetch.ts` |
141141
| Web remote client | `core/mcp/remote/remoteClientTransport.ts`, `core/mcp/inspectorClient.ts` |
142-
| Web app | `clients/web/src/App.tsx`, `lib/oauthResume.ts`, `utils/pendingReauth.ts`, `lib/browserTabVisibility.ts`, `components/groups/StepUpAuthModal/` |
142+
| Web app | `clients/web/src/App.tsx`, `lib/oauthResume.ts`, `utils/pendingReauth.ts`, `lib/browserTabVisibility.ts`, `components/groups/StepUpAuthModal/` |
143143
| TUI | `clients/tui/src/App.tsx`, `utils/tuiOAuth.ts` |
144144
| CLI | `clients/cli/src/cliOAuth.ts` |
145145
| Runner OAuth (TUI/CLI) | `core/auth/node/runner-interactive-oauth.ts`, `oauth-callback-server.ts` |

‎specification/v2_ux_interfaces_phase_0_4_inventory.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Phase 0 PR description and as a running checklist during the refactor.
2020
| `ResourceItem`, `TemplateListItem`, `SubscriptionItem` | `screens/ResourcesScreen/ResourcesScreen.tsx` | `groups/ResourceControls/ResourceControls.tsx`, `screens/ResourcesScreen/ResourcesScreen.stories.tsx` | SDK `Resource`, `ResourceTemplate`, wrapper `InspectorResourceSubscription` from `core/mcp/types.ts` |
2121
| `ToolListItemProps` (as a data shape) | `groups/ToolListItem/ToolListItem.tsx` | `groups/ToolControls/ToolControls.tsx`, `screens/ToolsScreen/ToolsScreen.tsx`, `screens/ToolsScreen/ToolsScreen.stories.tsx` | SDK `Tool` |
2222
| `RootEntry` | `groups/RootsTable/RootsTable.tsx` | — | SDK `Root` |
23-
| `KeyValuePair` | `groups/ServerSettingsForm/ServerSettingsForm.tsx`, `groups/ExperimentalFeaturesPanel/ExperimentalFeaturesPanel.tsx` | — | `CustomHeader` from `clients/web/src/lib/types/customHeaders.ts` when the form edits headers specifically; keep a local `KeyValuePair` only for generic key/value lists (e.g. metadata) |
23+
| `KeyValuePair` | `groups/ServerSettingsForm/ServerSettingsForm.tsx`, `groups/ExperimentalFeaturesPanel/ExperimentalFeaturesPanel.tsx` | — | `CustomHeader` from `clients/web/src/utils/customHeaders.ts` when the form edits headers specifically; keep a local `KeyValuePair` only for generic key/value lists (e.g. metadata) |
2424
| inline `"connected" \| "connecting" \| "disconnected" \| "failed"` | `elements/ServerStatusIndicator/ServerStatusIndicator.tsx:4`, `groups/ServerCard/ServerCard.tsx:15`, `views/ConnectedView/ConnectedView.tsx:7` | — | `ConnectionStatus` from `core/mcp/types.ts`. **Note**: reconcile `"failed"` → `"error"` (v1.5's canonical spelling) |
2525
| inline `"stdio" \| "http"` transport union | `elements/TransportBadge/TransportBadge.tsx:4`, `groups/ServerCard/ServerCard.tsx:12` plus story fixtures | — | `ServerType` (`"stdio" \| "sse" \| "streamable-http"`) from `core/mcp/types.ts` |
2626

‎specification/v2_ux_interfaces_plan.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ spec. After this work, every dumb component consumes either:
4848
`Tool[]`, `Prompt[]`, `Resource[]`, `ResourceTemplate[]`, `Task[]`.
4949
- `core/react/{useMessageLog,useStderrLog,useFetchRequestLog}.ts` — log
5050
wrapper consumers.
51-
- `clients/web/src/lib/types/customHeaders.ts` — `CustomHeader` /
51+
- `clients/web/src/utils/customHeaders.ts` — `CustomHeader` /
5252
`CustomHeaders` shape, used by `ServerSettingsForm`.
5353
- `clients/web/src/utils/schemaUtils.ts` + `clients/web/src/utils/jsonUtils.ts`
5454
— JSON Schema typing (`JsonValue`, `JsonSchemaType`, `JsonObject`) and
@@ -182,7 +182,7 @@ have no v1.5 equivalent):
182182
or transport concept. Place it under `clients/web/src/types/navigation.ts`
183183
rather than in `core/mcp/types.ts`. Everything else lives in `core/mcp/types.ts`.
184184

185-
**Custom headers**: copy `clients/web/src/lib/types/customHeaders.ts` from
185+
**Custom headers**: copy `clients/web/src/utils/customHeaders.ts` from
186186
v1.5 verbatim. It owns `CustomHeader` / `CustomHeaders` shape used by
187187
`ServerSettingsForm` and the experimental panel.
188188

0 commit comments

Comments
 (0)