npm - @korso/shepherd-ui - Versions diffs - 0.1.1 → 0.2.0 - Mend

@korso/shepherd-ui 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (100) hide show

package/README.md +47 -47
package/dist/ShepherdProvider.d.ts +12 -0
package/dist/ShepherdProvider.js +33 -0
package/dist/ShepherdProvider.test.d.ts +1 -0
package/dist/ShepherdProvider.test.js +47 -0
package/dist/ShepherdRoot.d.ts +9 -0
package/dist/ShepherdRoot.js +88 -0
package/dist/ShepherdRoot.routing.test.d.ts +1 -0
package/dist/ShepherdRoot.routing.test.js +61 -0
package/dist/ShepherdRoot.test.d.ts +1 -0
package/dist/ShepherdRoot.test.js +37 -0
package/dist/app/assets/index-CDOCIg6s.js +11 -0
package/dist/app/index.html +12 -0
package/dist/client.d.ts +107 -0
package/dist/client.js +238 -0
package/dist/client.test.d.ts +1 -0
package/dist/client.test.js +298 -0
package/dist/components/ActiveList.d.ts +22 -0
package/dist/components/ActiveList.js +59 -0
package/dist/components/Chat.d.ts +30 -0
package/dist/components/Chat.js +61 -0
package/dist/components/Composer.d.ts +37 -0
package/dist/components/Composer.js +146 -0
package/dist/components/Crew.d.ts +23 -0
package/dist/components/Crew.js +31 -0
package/dist/components/Dashboard.d.ts +34 -0
package/dist/components/Dashboard.js +209 -0
package/dist/components/DoneList.d.ts +29 -0
package/dist/components/DoneList.js +50 -0
package/dist/components/RepoSelect.d.ts +38 -0
package/dist/components/RepoSelect.js +56 -0
package/dist/components/Territory.d.ts +21 -0
package/dist/components/Territory.js +21 -0
package/dist/config/ConnectAgent.d.ts +10 -0
package/dist/config/ConnectAgent.js +119 -0
package/dist/config/ConnectAgent.test.d.ts +1 -0
package/dist/config/ConnectAgent.test.js +92 -0
package/dist/config/EmptyState.d.ts +12 -0
package/dist/config/EmptyState.js +4 -0
package/dist/config/EmptyState.test.d.ts +1 -0
package/dist/config/EmptyState.test.js +32 -0
package/dist/config/Members.d.ts +10 -0
package/dist/config/Members.js +83 -0
package/dist/config/Members.test.d.ts +1 -0
package/dist/config/Members.test.js +66 -0
package/dist/config/Workspaces.d.ts +12 -0
package/dist/config/Workspaces.js +96 -0
package/dist/config/Workspaces.test.d.ts +1 -0
package/dist/config/Workspaces.test.js +90 -0
package/dist/config/index.d.ts +8 -0
package/dist/config/index.js +6 -0
package/dist/context.d.ts +28 -0
package/dist/context.js +36 -0
package/dist/index.cjs +5289 -0
package/dist/index.cjs.map +1 -0
package/dist/index.d.cts +149 -0
package/dist/index.d.ts +18 -0
package/dist/index.js +15 -0
package/dist/index.js.map +1 -0
package/dist/lib/Dashboard-CG6KeFQ3.js +1214 -0
package/dist/lib/index.d.ts +438 -16
package/dist/lib/index.js +455 -6
package/dist/lib/selfhost.js +9 -9
package/dist/lib/styles.css +209 -182
package/dist/logic.d.ts +208 -0
package/dist/logic.js +372 -0
package/dist/main.d.ts +1 -0
package/dist/main.js +11 -0
package/dist/selfhost/assets/{index-tSyzirZa.css → index-BZmImfYZ.css} +1 -1
package/dist/selfhost/assets/index-CS268KSw.js +40 -0
package/dist/selfhost/index.html +13 -13
package/dist/selfhost.d.ts +22 -0
package/dist/selfhost.js +97 -0
package/dist/test/mockClient.d.ts +6 -0
package/dist/test/mockClient.js +45 -0
package/dist/test/setup.d.ts +1 -0
package/dist/test/setup.js +2 -0
package/dist/useLandscapePolling.d.ts +63 -0
package/dist/useLandscapePolling.js +129 -0
package/dist/views/Chat.d.ts +5 -0
package/dist/views/Chat.js +60 -0
package/dist/views/Chat.test.d.ts +1 -0
package/dist/views/Chat.test.js +92 -0
package/dist/views/Config.d.ts +12 -0
package/dist/views/Config.js +6 -0
package/dist/views/Tasks.d.ts +5 -0
package/dist/views/Tasks.js +75 -0
package/dist/views/Tasks.test.d.ts +1 -0
package/dist/views/Tasks.test.js +115 -0
package/dist/views/useLandscape.d.ts +14 -0
package/dist/views/useLandscape.js +74 -0
package/dist/views/useLandscape.test.d.ts +1 -0
package/dist/views/useLandscape.test.js +101 -0
package/dist/views/wallboard.d.ts +46 -0
package/dist/views/wallboard.js +209 -0
package/dist/views/wallboard.test.d.ts +1 -0
package/dist/views/wallboard.test.js +143 -0
package/package.json +67 -67
package/dist/lib/Dashboard-CB6SL-J2.js +0 -1064
package/dist/selfhost/assets/index-BBx3vo2Y.js +0 -40

package/dist/app/index.html ADDED Viewed

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Shepherd</title>
+    <script type="module" crossorigin src="/assets/index-CDOCIg6s.js"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/dist/client.d.ts ADDED Viewed

@@ -0,0 +1,107 @@
+import type { ListWorkspacesResponseT, CreateWorkspaceRequestT, CreateWorkspaceResponseT, MintTokenRequestT, MintTokenResponseT, ListTokensResponseT, CreateInviteRequestT, InviteResponseT, RedeemInviteResponseT, ListMembersResponseT, WorkspaceLandscapeResponseT, WorkspaceAnnounceRequestT, WorkspaceAnnounceResponseT } from "@shepherd/shared";
+/**
+ * The single error type surfaced by the client. A missing `status` means a
+ * transport failure (network error or request timeout); a present `status` is
+ * the upstream HTTP status of a non-2xx response. One class — distinguished by
+ * the optional `status` — keeps callers from having to branch on two error
+ * types just to tell "couldn't reach the hub" from "the hub said no".
+ */
+export declare class ShepherdClientError extends Error {
+    /** Upstream HTTP status for a non-2xx response; absent for transport errors. */
+    readonly status?: number;
+    /**
+     * @param message - Human-readable failure description.
+     * @param status - Upstream HTTP status, omitted for network/abort failures.
+     */
+    constructor(message: string, status?: number);
+}
+/**
+ * Maps any thrown value into a short, human-friendly message for the view layer.
+ * A {@link ShepherdClientError} (and any other `Error`) surfaces its own
+ * `message` — which already carries the hub's detail for non-2xx responses and a
+ * transport description otherwise — while a non-Error value degrades to a
+ * generic line rather than stringifying something unprintable.
+ *
+ * @param err - The caught value (typically from a client method rejection).
+ * @returns A display-ready message string.
+ */
+export declare function describeError(err: unknown): string;
+/**
+ * The typed Shepherd hub surface. The plural, workspace-scoped methods use the
+ * `/workspaces/:id/...` form (which works in both deployments: a bearer token
+ * resolves its own workspace and ignores `:id`, while a browser session
+ * validates membership of `:id`). The singular `getLandscape()`/`announce()`
+ * pair are the self-host aliases against the implicit single-workspace routes.
+ * Every response with a dedicated schema is Zod-parsed at the boundary so a
+ * contract drift throws `Invalid response schema` rather than flowing a
+ * malformed object into the view layer.
+ */
+export interface ShepherdClient {
+    /** The normalised (trailing-slash-stripped) hub base URL the client targets. */
+    readonly baseUrl: string;
+    /** GET the caller's workspaces, each tagged with the caller's role. */
+    listWorkspaces(): Promise<ListWorkspacesResponseT>;
+    /** POST a new workspace; the caller becomes its admin. */
+    createWorkspace(body: CreateWorkspaceRequestT): Promise<CreateWorkspaceResponseT>;
+    /** POST a new agent token; the raw `shp_` value is returned exactly once. */
+    mintToken(workspaceId: string, body: MintTokenRequestT): Promise<MintTokenResponseT>;
+    /** GET the workspace's token metadata (never the raw token). */
+    listTokens(workspaceId: string): Promise<ListTokensResponseT>;
+    /** DELETE (revoke) a token by id. */
+    revokeToken(workspaceId: string, tokenId: string): Promise<void>;
+    /** POST a new invite code for the workspace (admin only). */
+    createInvite(workspaceId: string, body: CreateInviteRequestT): Promise<InviteResponseT>;
+    /** POST to revoke an invite code (admin only). */
+    revokeInvite(workspaceId: string, code: string): Promise<void>;
+    /** POST to redeem an invite code, joining its workspace as a member. */
+    redeemInvite(code: string): Promise<RedeemInviteResponseT>;
+    /** GET the workspace's member roster. */
+    listMembers(workspaceId: string): Promise<ListMembersResponseT>;
+    /** DELETE (remove) a member by account id (admin only). */
+    removeMember(workspaceId: string, accountId: string): Promise<void>;
+    /** POST to leave the workspace. */
+    leave(workspaceId: string): Promise<void>;
+    /** GET a specific workspace's landscape (agents, tasks, announcements). */
+    landscape(workspaceId: string): Promise<WorkspaceLandscapeResponseT>;
+    /** POST an operator announcement to a specific workspace. */
+    announceTo(workspaceId: string, body: WorkspaceAnnounceRequestT): Promise<WorkspaceAnnounceResponseT>;
+    /** GET the unfiltered whole-workspace view (agents, tasks, announcements). */
+    getLandscape(): Promise<WorkspaceLandscapeResponseT>;
+    /** POST an operator announcement (broadcast or @targeted) to the workspace. */
+    announce(req: WorkspaceAnnounceRequestT): Promise<WorkspaceAnnounceResponseT>;
+}
+/**
+ * Construction options for {@link createShepherdClient}. Auth is supplied
+ * externally via `getAuthHeader` so the core client stays auth-agnostic — it
+ * never reads tokens, localStorage, or a BFF; it only merges whatever the host
+ * injects and notifies the host on a 401 via `onUnauthorized`.
+ */
+export interface ShepherdClientConfig {
+    /** Hub origin; a trailing slash is tolerated and normalised away. "" = same-origin. */
+    baseUrl: string;
+    /**
+     * Returns the credential for the next request, as either:
+     *   - a string  → sent as the `Authorization` header value (e.g. "Bearer …"),
+     *   - a header map → merged verbatim over the JSON content-type base, or
+     *   - undefined  → no auth header added (same-origin BFF supplies the cookie).
+     * May be sync or async (e.g. refreshing a short-lived token). Omit entirely
+     * for an unauthenticated/same-origin deployment.
+     */
+    getAuthHeader?: () => string | Record<string, string> | undefined | Promise<string | Record<string, string> | undefined>;
+    /** Invoked once when the hub responds 401, before the error is thrown. */
+    onUnauthorized?: () => void;
+    /** Per-request abort timeout in ms; defaults to {@link DEFAULT_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/**
+ * Builds a browser fetch client for the Shepherd hub. Each call wires up an
+ * AbortController timeout (cleared in `finally`), merges the injected auth
+ * headers over a JSON content-type base, and Zod-parses ONLY the response at
+ * the boundary — the request body is forwarded verbatim because the caller owns
+ * its input shape. void-returning methods (revoke/remove/leave) await the
+ * request and parse nothing.
+ *
+ * @param config - Base URL, optional injected auth, 401 hook, and timeout.
+ * @returns A {@link ShepherdClient}.
+ */
+export declare function createShepherdClient(config: ShepherdClientConfig): ShepherdClient;

package/dist/client.js ADDED Viewed

@@ -0,0 +1,238 @@
+import { ListWorkspacesResponse, CreateWorkspaceResponse, MintTokenResponse, ListTokensResponse, InviteResponse, RedeemInviteResponse, ListMembersResponse, WorkspaceLandscapeResponse, WorkspaceAnnounceResponse, } from "@shepherd/shared";
+/** Per-request abort fires after this many ms when no timeoutMs is configured. */
+const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * The single error type surfaced by the client. A missing `status` means a
+ * transport failure (network error or request timeout); a present `status` is
+ * the upstream HTTP status of a non-2xx response. One class — distinguished by
+ * the optional `status` — keeps callers from having to branch on two error
+ * types just to tell "couldn't reach the hub" from "the hub said no".
+ */
+export class ShepherdClientError extends Error {
+    /** Upstream HTTP status for a non-2xx response; absent for transport errors. */
+    status;
+    /**
+     * @param message - Human-readable failure description.
+     * @param status - Upstream HTTP status, omitted for network/abort failures.
+     */
+    constructor(message, status) {
+        super(message);
+        this.name = "ShepherdClientError";
+        if (status !== undefined) {
+            this.status = status;
+        }
+    }
+}
+/**
+ * Maps any thrown value into a short, human-friendly message for the view layer.
+ * A {@link ShepherdClientError} (and any other `Error`) surfaces its own
+ * `message` — which already carries the hub's detail for non-2xx responses and a
+ * transport description otherwise — while a non-Error value degrades to a
+ * generic line rather than stringifying something unprintable.
+ *
+ * @param err - The caught value (typically from a client method rejection).
+ * @returns A display-ready message string.
+ */
+export function describeError(err) {
+    return err instanceof Error ? err.message : "Something went wrong.";
+}
+/**
+ * Reads a best-effort `{ error: string }` message from a non-2xx response body
+ * so the thrown error carries the hub's own explanation. A non-JSON or bodyless
+ * response degrades to an empty string — the status code is still informative.
+ *
+ * @param res - The non-2xx response to inspect.
+ * @returns The upstream error string, or "" when none could be read.
+ */
+async function readErrorDetail(res) {
+    try {
+        const data = await res.json();
+        if (data !== null &&
+            typeof data === "object" &&
+            "error" in data &&
+            typeof data.error === "string") {
+            return data.error;
+        }
+    }
+    catch {
+        // Body wasn't JSON; the status code alone remains informative.
+    }
+    return "";
+}
+/**
+ * Builds a browser fetch client for the Shepherd hub. Each call wires up an
+ * AbortController timeout (cleared in `finally`), merges the injected auth
+ * headers over a JSON content-type base, and Zod-parses ONLY the response at
+ * the boundary — the request body is forwarded verbatim because the caller owns
+ * its input shape. void-returning methods (revoke/remove/leave) await the
+ * request and parse nothing.
+ *
+ * @param config - Base URL, optional injected auth, 401 hook, and timeout.
+ * @returns A {@link ShepherdClient}.
+ */
+export function createShepherdClient(config) {
+    // Strip a trailing slash so `${baseUrl}/workspace/...` never yields a double
+    // slash regardless of how the host configured the origin. An empty baseUrl
+    // stays "" so paths resolve root-relative (same-origin).
+    const baseUrl = config.baseUrl.replace(/\/$/, "");
+    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const enc = encodeURIComponent;
+    /**
+     * Performs one request, mapping transport failures to a status-less error,
+     * 401s to `onUnauthorized` + a 401 error, other non-2xx to a status error,
+     * and a 2xx body either through the supplied Zod schema or — when no schema
+     * is given (void endpoints) — to `undefined`.
+     */
+    async function request(method, path, opts = {}) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let res;
+        try {
+            const baseHeaders = {
+                "Content-Type": "application/json",
+            };
+            // Resolve getAuthHeader (sync or async) into a header record: a string is
+            // the Authorization value, a map merges verbatim, undefined adds nothing.
+            // Injected auth wins over the base, so a host may even override the
+            // content-type if it ever needs to. Built INSIDE the try so a rejecting
+            // (async) getAuthHeader is funneled through the catch and the finally
+            // still clears the abort timer — no leaked timer on an auth failure.
+            const resolved = await config.getAuthHeader?.();
+            const authHeaders = typeof resolved === "string"
+                ? { Authorization: resolved }
+                : resolved ?? {};
+            const init = {
+                method,
+                headers: { ...baseHeaders, ...authHeaders },
+                signal: controller.signal,
+            };
+            if (opts.body !== undefined) {
+                init.body = JSON.stringify(opts.body);
+            }
+            res = await fetch(`${baseUrl}${path}`, init);
+        }
+        catch (err) {
+            // Network error or abort/timeout: no HTTP status exists, so the error is
+            // thrown WITHOUT one to mark it a transport failure.
+            throw new ShepherdClientError(err instanceof Error ? err.message : String(err));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (res.status === 401) {
+            config.onUnauthorized?.();
+            throw new ShepherdClientError("Unauthorized", 401);
+        }
+        if (!res.ok) {
+            const detail = await readErrorDetail(res);
+            throw new ShepherdClientError(detail !== ""
+                ? `HTTP ${res.status}: ${detail}`
+                : `HTTP ${res.status}`, res.status);
+        }
+        if (!opts.schema) {
+            // void endpoint: no dedicated response schema. Drain any body and resolve
+            // undefined — callers of these methods don't depend on the payload.
+            try {
+                await res.json();
+            }
+            catch {
+                // empty / non-JSON body is fine for a void endpoint.
+            }
+            // void endpoints are called as request<void>(...); the undefined resolve
+            // is the intended value, asserted to T since the no-schema branch is only
+            // reached for the void-typed callers.
+            return undefined;
+        }
+        const parsed = opts.schema.safeParse(await res.json());
+        if (!parsed.success) {
+            throw new ShepherdClientError("Invalid response schema");
+        }
+        return parsed.data;
+    }
+    return {
+        baseUrl,
+        // --- multi-workspace management surface ---------------------------------
+        listWorkspaces() {
+            return request("GET", "/workspaces", {
+                schema: ListWorkspacesResponse,
+            });
+        },
+        createWorkspace(body) {
+            return request("POST", "/workspaces", {
+                body,
+                schema: CreateWorkspaceResponse,
+            });
+        },
+        mintToken(workspaceId, body) {
+            return request("POST", `/workspaces/${enc(workspaceId)}/tokens`, {
+                body,
+                schema: MintTokenResponse,
+            });
+        },
+        listTokens(workspaceId) {
+            return request("GET", `/workspaces/${enc(workspaceId)}/tokens`, {
+                schema: ListTokensResponse,
+            });
+        },
+        revokeToken(workspaceId, tokenId) {
+            return request("DELETE", `/workspaces/${enc(workspaceId)}/tokens/${enc(tokenId)}`);
+        },
+        createInvite(workspaceId, body) {
+            return request("POST", `/workspaces/${enc(workspaceId)}/invites`, {
+                body,
+                schema: InviteResponse,
+            });
+        },
+        revokeInvite(workspaceId, code) {
+            return request("POST", `/workspaces/${enc(workspaceId)}/invites/${enc(code)}/revoke`);
+        },
+        redeemInvite(code) {
+            return request("POST", `/invites/${enc(code)}/redeem`, {
+                schema: RedeemInviteResponse,
+            });
+        },
+        listMembers(workspaceId) {
+            return request("GET", `/workspaces/${enc(workspaceId)}/members`, {
+                schema: ListMembersResponse,
+            });
+        },
+        removeMember(workspaceId, accountId) {
+            return request("DELETE", `/workspaces/${enc(workspaceId)}/members/${enc(accountId)}`);
+        },
+        leave(workspaceId) {
+            return request("POST", `/workspaces/${enc(workspaceId)}/leave`);
+        },
+        landscape(workspaceId) {
+            // WorkspaceLandscapeResponse's inferred type widens the announcement
+            // admin flags to optional, so it doesn't structurally match the declared
+            // ...ResponseT alias; an explicit cast is kept for just this schema.
+            return request("GET", `/workspaces/${enc(workspaceId)}/landscape`, {
+                schema: WorkspaceLandscapeResponse,
+            });
+        },
+        announceTo(workspaceId, body) {
+            // The request body is NOT validated here — the caller owns input shape;
+            // only the RESPONSE is parsed at the boundary.
+            return request("POST", `/workspaces/${enc(workspaceId)}/announce`, {
+                body,
+                schema: WorkspaceAnnounceResponse,
+            });
+        },
+        // --- self-host singular aliases (implicit single workspace) -------------
+        getLandscape() {
+            // See landscape() above: this schema's inferred type doesn't structurally
+            // match the ...ResponseT alias, so its explicit cast is kept.
+            return request("GET", "/workspace/landscape", {
+                schema: WorkspaceLandscapeResponse,
+            });
+        },
+        announce(req) {
+            // The request body is NOT validated here — the caller owns input shape;
+            // only the RESPONSE is parsed at the boundary.
+            return request("POST", "/workspace/announce", {
+                body: req,
+                schema: WorkspaceAnnounceResponse,
+            });
+        },
+    };
+}

package/dist/client.test.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export {};

package/dist/client.test.js ADDED Viewed

@@ -0,0 +1,298 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createShepherdClient, ShepherdHttpError } from "./client.js";
+// ---------------------------------------------------------------------------
+// ShepherdClient — fetch-mock unit tests (DB-free; mocks global `fetch`).
+//
+// Each method asserts: the request URL (baseUrl + exact encoded path), the HTTP
+// method, that auth headers from getAuthHeader are merged (Bearer-string, header-
+// map, and undefined/no-op cases), Content-Type + body JSON on bodied requests,
+// and that the response is validated by the @shepherd/shared zod schema. A
+// malformed 2xx body throws; a non-2xx rejects with a typed ShepherdHttpError.
+// ---------------------------------------------------------------------------
+const BASE = "https://hub.example.com";
+/** Build a Response-like object for a mocked fetch resolution. */
+function jsonResponse(body, init) {
+    const status = init?.status ?? 200;
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        statusText: init?.statusText ?? "OK",
+        json: async () => body,
+        text: async () => JSON.stringify(body),
+    };
+}
+let fetchMock;
+beforeEach(() => {
+    fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+});
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+});
+/** The single call recorded on the fetch mock: [url, init]. */
+function lastCall() {
+    const call = fetchMock.mock.calls[0];
+    return [call[0], call[1]];
+}
+/** Read a header from a recorded RequestInit (headers stored as a plain record). */
+function header(init, name) {
+    const h = init.headers;
+    if (!h)
+        return undefined;
+    const key = Object.keys(h).find((k) => k.toLowerCase() === name.toLowerCase());
+    return key ? h[key] : undefined;
+}
+// --- fixtures matching the @shepherd/shared schemas ------------------------
+const WORKSPACE_SUMMARY = { id: "ws_1", slug: "acme", name: "Acme", role: "admin" };
+const LANDSCAPE = {
+    agents: [],
+    tasks: [],
+    announcements: [],
+    serverTime: "2026-06-29T00:00:00.000Z",
+};
+describe("createShepherdClient", () => {
+    let client;
+    beforeEach(() => {
+        client = createShepherdClient({ baseUrl: BASE });
+    });
+    describe("listWorkspaces", () => {
+        it("GETs /workspaces and returns the validated body", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse({ workspaces: [WORKSPACE_SUMMARY] }));
+            const out = await client.listWorkspaces();
+            const [url, init] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces`);
+            expect(init.method).toBe("GET");
+            expect(out).toEqual({ workspaces: [WORKSPACE_SUMMARY] });
+        });
+        it("throws when the response body fails schema validation", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse({ workspaces: [{ id: "x" }] }));
+            await expect(client.listWorkspaces()).rejects.toThrow();
+        });
+        it("rejects with a typed ShepherdHttpError carrying the status on non-2xx", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse({ error: "nope" }, { status: 401, statusText: "Unauthorized" }));
+            await expect(client.listWorkspaces()).rejects.toBeInstanceOf(ShepherdHttpError);
+            fetchMock.mockResolvedValueOnce(jsonResponse({ error: "nope" }, { status: 500, statusText: "Server Error" }));
+            await expect(client.listWorkspaces()).rejects.toMatchObject({ status: 500 });
+        });
+    });
+    describe("createWorkspace", () => {
+        it("POSTs /workspaces with a JSON body and returns the WorkspaceSummary", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse(WORKSPACE_SUMMARY));
+            const out = await client.createWorkspace({ name: "Acme" });
+            const [url, init] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces`);
+            expect(init.method).toBe("POST");
+            expect(header(init, "Content-Type")).toBe("application/json");
+            expect(JSON.parse(init.body)).toEqual({ name: "Acme" });
+            expect(out).toEqual(WORKSPACE_SUMMARY);
+        });
+    });
+    describe("mintToken", () => {
+        it("POSTs /workspaces/:id/tokens and returns the MintTokenResponse", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse({ token: "shp_abc", id: "tok_1" }));
+            const out = await client.mintToken("ws_1", { name: "ci" });
+            const [url, init] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces/ws_1/tokens`);
+            expect(init.method).toBe("POST");
+            expect(JSON.parse(init.body)).toEqual({ name: "ci" });
+            expect(out).toEqual({ token: "shp_abc", id: "tok_1" });
+        });
+    });
+    describe("listTokens", () => {
+        it("GETs /workspaces/:id/tokens and returns the ListTokensResponse", async () => {
+            const token = {
+                id: "tok_1",
+                name: "ci",
+                lastUsedAt: null,
+                createdAt: "2026-06-29T00:00:00.000Z",
+                revokedAt: null,
+            };
+            fetchMock.mockResolvedValueOnce(jsonResponse({ tokens: [token] }));
+            const out = await client.listTokens("ws_1");
+            const [url, init] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces/ws_1/tokens`);
+            expect(init.method).toBe("GET");
+            expect(out).toEqual({ tokens: [token] });
+        });
+    });
+    describe("revokeToken", () => {
+        it("DELETEs /workspaces/:id/tokens/:tokenId (no schema validation)", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse({ ok: true }));
+            await client.revokeToken("ws_1", "tok_1");
+            const [url, init] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces/ws_1/tokens/tok_1`);
+            expect(init.method).toBe("DELETE");
+        });
+    });
+    describe("createInvite", () => {
+        it("POSTs /workspaces/:id/invites and returns the InviteResponse", async () => {
+            const invite = { code: "inv_abc", expiresAt: null, maxUses: 5, useCount: 0 };
+            fetchMock.mockResolvedValueOnce(jsonResponse(invite));
+            const out = await client.createInvite("ws_1", { maxUses: 5 });
+            const [url, init] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces/ws_1/invites`);
+            expect(init.method).toBe("POST");
+            expect(JSON.parse(init.body)).toEqual({ maxUses: 5 });
+            expect(out).toEqual(invite);
+        });
+    });
+    describe("revokeInvite", () => {
+        it("POSTs /workspaces/:id/invites/:code/revoke (encodes the code)", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse({ ok: true }));
+            await client.revokeInvite("ws_1", "a/b code");
+            const [url, init] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces/ws_1/invites/a%2Fb%20code/revoke`);
+            expect(init.method).toBe("POST");
+        });
+    });
+    describe("redeemInvite", () => {
+        it("POSTs /invites/:code/redeem and returns the RedeemInviteResponse", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse({ workspace: WORKSPACE_SUMMARY }));
+            const out = await client.redeemInvite("inv_abc");
+            const [url, init] = lastCall();
+            expect(url).toBe(`${BASE}/invites/inv_abc/redeem`);
+            expect(init.method).toBe("POST");
+            expect(out).toEqual({ workspace: WORKSPACE_SUMMARY });
+        });
+    });
+    describe("listMembers", () => {
+        it("GETs /workspaces/:id/members and returns the ListMembersResponse", async () => {
+            const member = {
+                accountId: "acc_1",
+                displayName: "Dana",
+                githubLogin: "dana",
+                avatarUrl: null,
+                role: "member",
+            };
+            fetchMock.mockResolvedValueOnce(jsonResponse({ members: [member] }));
+            const out = await client.listMembers("ws_1");
+            const [url, init] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces/ws_1/members`);
+            expect(init.method).toBe("GET");
+            expect(out).toEqual({ members: [member] });
+        });
+    });
+    describe("removeMember", () => {
+        it("DELETEs /workspaces/:id/members/:accountId (encodes the accountId)", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse({ ok: true }));
+            await client.removeMember("ws_1", "acc/1");
+            const [url, init] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces/ws_1/members/acc%2F1`);
+            expect(init.method).toBe("DELETE");
+        });
+    });
+    describe("leave", () => {
+        it("POSTs /workspaces/:id/leave", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse({ ok: true }));
+            await client.leave("ws_1");
+            const [url, init] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces/ws_1/leave`);
+            expect(init.method).toBe("POST");
+        });
+    });
+    describe("landscape", () => {
+        it("GETs /workspaces/:id/landscape and returns the WorkspaceLandscapeResponse", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse(LANDSCAPE));
+            const out = await client.landscape("ws_1");
+            const [url, init] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces/ws_1/landscape`);
+            expect(init.method).toBe("GET");
+            expect(out).toEqual(LANDSCAPE);
+        });
+    });
+    describe("announce", () => {
+        it("POSTs /workspaces/:id/announce and returns the WorkspaceAnnounceResponse", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse({ ok: true, announcementIds: [1, 2] }));
+            const out = await client.announce("ws_1", { body: "hello", repo: "r" });
+            const [url, init] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces/ws_1/announce`);
+            expect(init.method).toBe("POST");
+            expect(header(init, "Content-Type")).toBe("application/json");
+            expect(JSON.parse(init.body)).toEqual({ body: "hello", repo: "r" });
+            expect(out).toEqual({ ok: true, announcementIds: [1, 2] });
+        });
+    });
+    // --- encodeURIComponent on path params ----------------------------------
+    describe("path-param encoding", () => {
+        it("encodes the workspaceId segment", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse(LANDSCAPE));
+            await client.landscape("ws/1 special");
+            const [url] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces/ws%2F1%20special/landscape`);
+        });
+        it("encodes a tokenId with a special char", async () => {
+            fetchMock.mockResolvedValueOnce(jsonResponse({ ok: true }));
+            await client.revokeToken("ws_1", "tok/1");
+            const [url] = lastCall();
+            expect(url).toBe(`${BASE}/workspaces/ws_1/tokens/tok%2F1`);
+        });
+    });
+});
+// --- baseUrl joining --------------------------------------------------------
+describe("baseUrl joining", () => {
+    it("does not double-slash when baseUrl has a trailing slash", async () => {
+        const fm = vi.fn().mockResolvedValueOnce(jsonResponse({ workspaces: [] }));
+        vi.stubGlobal("fetch", fm);
+        const client = createShepherdClient({ baseUrl: `${BASE}/` });
+        await client.listWorkspaces();
+        expect(fm.mock.calls[0][0]).toBe(`${BASE}/workspaces`);
+        vi.unstubAllGlobals();
+    });
+    it("supports same-origin ('') baseUrl producing a root-relative path", async () => {
+        const fm = vi.fn().mockResolvedValueOnce(jsonResponse({ workspaces: [] }));
+        vi.stubGlobal("fetch", fm);
+        const client = createShepherdClient({ baseUrl: "" });
+        await client.listWorkspaces();
+        expect(fm.mock.calls[0][0]).toBe("/workspaces");
+        vi.unstubAllGlobals();
+    });
+});
+// --- getAuthHeader resolution: all three return shapes, sync + async --------
+describe("getAuthHeader injection", () => {
+    beforeEach(() => {
+        fetchMock = vi.fn().mockResolvedValue(jsonResponse({ workspaces: [] }));
+        vi.stubGlobal("fetch", fetchMock);
+    });
+    afterEach(() => vi.unstubAllGlobals());
+    it("merges a Bearer string into the Authorization header (sync)", async () => {
+        const client = createShepherdClient({
+            baseUrl: BASE,
+            getAuthHeader: () => "Bearer team_tok",
+        });
+        await client.listWorkspaces();
+        const [, init] = lastCall();
+        expect(header(init, "Authorization")).toBe("Bearer team_tok");
+    });
+    it("merges a Bearer string returned asynchronously", async () => {
+        const client = createShepherdClient({
+            baseUrl: BASE,
+            getAuthHeader: async () => "Bearer async_tok",
+        });
+        await client.listWorkspaces();
+        const [, init] = lastCall();
+        expect(header(init, "Authorization")).toBe("Bearer async_tok");
+    });
+    it("merges a header-map return", async () => {
+        const client = createShepherdClient({
+            baseUrl: BASE,
+            getAuthHeader: () => ({ Authorization: "Bearer map_tok", "X-Extra": "1" }),
+        });
+        await client.listWorkspaces();
+        const [, init] = lastCall();
+        expect(header(init, "Authorization")).toBe("Bearer map_tok");
+        expect(header(init, "X-Extra")).toBe("1");
+    });
+    it("sends no auth header when getAuthHeader is omitted (same-origin BFF)", async () => {
+        const client = createShepherdClient({ baseUrl: BASE });
+        await client.listWorkspaces();
+        const [, init] = lastCall();
+        expect(header(init, "Authorization")).toBeUndefined();
+    });
+    it("sends no auth header when getAuthHeader resolves to undefined", async () => {
+        const client = createShepherdClient({ baseUrl: BASE, getAuthHeader: () => undefined });
+        await client.listWorkspaces();
+        const [, init] = lastCall();
+        expect(header(init, "Authorization")).toBeUndefined();
+    });
+});