feat(web): catalog vs read-only session launch model + apply --header (#1481, #1483) (#1496)

* feat(web): catalog vs read-only session launch model + apply --header (#1481, #1483)

Per specification/v2_catalog_launch_config.md, `mcp-inspector --web` now selects
the backend's server-list source and a session-wide writability, instead of
seeding an inert `initialMcpConfig` the UI never read:

- `--catalog <path>` (and `MCP_CATALOG_PATH`) → active WRITABLE catalog
  (seed/CRUD/watch), like the default catalog.
- `--config <path>` → READ-ONLY session file: served in the UI but never
  written, seeded, or plaintext-secret-migrated — safe to point at a foreign
  config (e.g. claude_desktop_config.json).
- ad-hoc `--server-url`/command (+ `--header`) → one server held IN MEMORY
  (no file written); `--header` is lifted onto the entry so the seeded
  connection actually uses it (closes the #1483 warn-only no-op).
- nothing → default catalog (writable), unchanged.

Backend (`createRemoteApp`): new `writable` + `initialServers` options. GET
/api/servers branches three ways (in-memory / read-only file with no
seed+no migrate / writable catalog); the four mutating routes return 403 when
read-only; `/api/config` carries `writable`; the file watcher is skipped for
in-memory sessions. `--catalog`/`--config` are mutually exclusive and neither
combines with an ad-hoc target or `--header`; `--header` requires an ad-hoc
HTTP/SSE server (clear errors otherwise — no silent no-op).

UI: `useServerListWritable` reads `writable` from /api/config; the Servers
screen hides add/edit/clone/remove/reorder/settings and shows a read-only
banner when false. All new props default to writable=true (back-compatible).

Docs: spec gaps G2/G3/G4 updated; launcher README documents the flags.

Verified end-to-end against the built launcher: --config (writable:false,
file byte-stable, mutations 403), ad-hoc --header (in-memory, header lifted),
and --catalog (writable:true, POST persists).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(web): address review — Mantine <Code> in read-only banner, clarify watcher comment

- Replace raw <code> with Mantine <Code> in the read-only-session Alert
  (repo convention: prefer Mantine primitives over raw HTML).
- Add a comment near `watchable` clarifying that a read-only `--config` file
  is still watched on purpose (read-only blocks UI writes, not external
  observation; `writable` does not gate watching).

Deferred (per reviewer): consolidating useSandboxUrl + useServerListWritable
into one useConfig hook to avoid the duplicate /api/config fetch — optional
follow-up. The redundant ad-hoc header type-guard is kept as defensive.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

clients/web/src/test/core/react/useServerListWritable.test.tsx

@@ -0,0 +1,105 @@
+/**
+ * Tests for useServerListWritable — runs in happy-dom under the unit project.
+ * Uses a controlled fake `fetch` so each branch (writable / read-only / absent
+ * field / HTTP error / network throw) and the auth header are asserted directly.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { useServerListWritable } from "@inspector/core/react/useServerListWritable";
+
+function jsonResponse(body: unknown, ok = true): Response {
+  return {
+    ok,
+    status: ok ? 200 : 401,
+    json: async () => body,
+  } as unknown as Response;
+}
+
+describe("useServerListWritable", () => {
+  it("defaults to writable while loading, then keeps true for a writable session", async () => {
+    const fetchFn = vi.fn().mockResolvedValue(jsonResponse({ writable: true }));
+
+    const { result } = renderHook(() =>
+      useServerListWritable({ baseUrl: "http://test.local", fetchFn }),
+    );
+
+    expect(result.current.loading).toBe(true);
+    expect(result.current.writable).toBe(true);
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.writable).toBe(true);
+  });
+
+  it("resolves writable:false for a read-only session", async () => {
+    const fetchFn = vi
+      .fn()
+      .mockResolvedValue(jsonResponse({ writable: false }));
+
+    const { result } = renderHook(() =>
+      useServerListWritable({ baseUrl: "http://test.local", fetchFn }),
+    );
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.writable).toBe(false);
+  });
+
+  it("stays writable when the field is absent (legacy backend)", async () => {
+    const fetchFn = vi.fn().mockResolvedValue(jsonResponse({}));
+
+    const { result } = renderHook(() =>
+      useServerListWritable({ baseUrl: "http://test.local", fetchFn }),
+    );
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.writable).toBe(true);
+  });
+
+  it("sends the bearer auth header when a token is provided", async () => {
+    const fetchFn = vi
+      .fn()
+      .mockResolvedValue(jsonResponse({ writable: false }));
+
+    renderHook(() =>
+      useServerListWritable({
+        baseUrl: "http://test.local/",
+        authToken: "secret-token",
+        fetchFn,
+      }),
+    );
+
+    await waitFor(() => expect(fetchFn).toHaveBeenCalled());
+    const [url, init] = fetchFn.mock.calls[0] as [string, RequestInit];
+    // Trailing slash on baseUrl is trimmed.
+    expect(url).toBe("http://test.local/api/config");
+    expect((init.headers as Record<string, string>)["x-mcp-remote-auth"]).toBe(
+      "Bearer secret-token",
+    );
+  });
+
+  it("stays writable on an HTTP error", async () => {
+    const fetchFn = vi
+      .fn()
+      .mockResolvedValue(jsonResponse({ writable: false }, false));
+
+    const { result } = renderHook(() =>
+      useServerListWritable({ baseUrl: "http://test.local", fetchFn }),
+    );
+
+    // An !ok response is ignored (the body is never read), so the writable
+    // default survives even though loading still settles via `finally`.
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.writable).toBe(true);
+  });
+
+  it("stays writable when fetch throws", async () => {
+    const fetchFn = vi.fn().mockRejectedValue(new Error("network down"));
+
+    const { result } = renderHook(() =>
+      useServerListWritable({ baseUrl: "http://test.local", fetchFn }),
+    );
+
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.writable).toBe(true);
+  });
+});