Skip to content

Commit 3fecb5c

Browse files
cliffhallclaude
andcommitted
docs: address review round 4 — reconcile src/types/ claim with #1785 (#1776)
Doc-only follow-up to the round-4 @claude review on PR #1784 (no code changed): The round-3 scope fix overshot: it asserted src/types/ holds "not domain types at all", but the dead navigation.ts InspectorTab is a plain-.ts domain type still living there, and specification/v2_ux_interfaces_plan.md:181-182 actively prescribes placing InspectorTab there — so AGENTS.md and that spec doc gave opposite guidance about the same directory. - AGENTS.md + web README: softened to "not the place for new domain types" and added a parenthetical that the one lingering domain type (dead navigation.ts) is tracked for removal in #1785; until then a pure domain type belongs in utils/, not src/types/. - v2_ux_interfaces_plan.md:181: marked the tab-enum placement guidance as superseded by #1785 (live type is InspectorTabId in utils/inspectorTabs.ts). Self-heals on merge of #1785. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
1 parent ffcd657 commit 3fecb5c

3 files changed

Lines changed: 3 additions & 2 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`, `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 `types/` sub-bucket **inside** `lib`/`utils` (the removal of `lib/types/` is what the `customHeaders` move settles). This is distinct from the top-level `src/types/`, which is not a home for domain types at all — it holds ambient `.d.ts` module stubs (e.g. the `react-syntax-highlighter` shims wired through `tsconfig.app.json` `paths`). **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.
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 `types/` sub-bucket **inside** `lib`/`utils` (the removal of `lib/types/` is what the `customHeaders` move settles). This is distinct from the top-level `src/types/`, which is not the place for new domain types — it's essentially the home for ambient `.d.ts` module stubs (e.g. the `react-syntax-highlighter` shims wired through `tsconfig.app.json` `paths`). (One plain-`.ts` domain type still sits there, the dead `navigation.ts` `InspectorTab`, superseding [#1785](https://github.com/modelcontextprotocol/inspector/issues/1785) will remove it — until then a pure domain type belongs in `utils/`, not `src/types/`.) **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; 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`) — there is no `types/` sub-bucket inside `lib`/`utils` (the top-level `src/types/` is separate: ambient `.d.ts` module stubs, not domain types). Examples: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `inspectorTabs`, `deepLink`, `mcpNetworkHeaders`.
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`) — there is no `types/` sub-bucket inside `lib`/`utils` (the top-level `src/types/` is separate: ambient `.d.ts` module stubs, not the place for new domain types — the one that lingers there, dead `navigation.ts`, is tracked for removal in #1785). Examples: `jsonUtils`, `schemaUtils`, `toolUtils`, `maskSecrets`, `inspectorTabs`, `deepLink`, `mcpNetworkHeaders`.
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_ux_interfaces_plan.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,7 @@ have no v1.5 equivalent):
181181
**Tab enum placement**: `InspectorTab` is a UI-routing concept, not an MCP
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`.
184+
_(Superseded by [#1785](https://github.com/modelcontextprotocol/inspector/issues/1785): the live tab-id type is `InspectorTabId` in `clients/web/src/utils/inspectorTabs.ts`, and the `navigation.ts` `InspectorTab` here is dead and slated for removal — a pure UI domain type belongs in `utils/`, per the `src/lib` vs `src/utils` rule in AGENTS.md.)_
184185

185186
**Custom headers**: `clients/web/src/utils/customHeaders.ts` is a verbatim
186187
copy of the v1.5 module. It owns `CustomHeader` / `CustomHeaders` shape used by

0 commit comments

Comments
 (0)