@stigmer/cli 3.35.0 → 3.36.0

package/src/resources/connect/connect.integration.test.ts

@@ -1,383 +0,0 @@
-// In-process integration test for `connect mcp-server` orchestration.
-//
-// Stands up a Connect backend serving the McpServer query + command controllers,
-// points an SDK node client at it, and drives connectMcpServer end to end: the
-// push path (asserts ConnectInput fields + rendered capabilities), the OAuth
-// guidance gate, and the dry-run path (local discovery, no Connect RPC).
-
-import { create } from "@bufbuild/protobuf";
-import { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
-import { connectNodeAdapter } from "@connectrpc/connect-node";
-import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
-import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
-import {
-  type ConnectInput,
-  GetOAuthGrantStatusOutputSchema,
-} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
-import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
-import { McpServerAuthSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
-import type { Stigmer } from "@stigmer/sdk";
-import { createNodeClient, normalizeEndpoint } from "@stigmer/sdk/node";
-import {
-  createServer as createHttp2Server,
-  type Http2Server,
-  type ServerHttp2Session,
-} from "node:http2";
-import type { AddressInfo } from "node:net";
-import { fileURLToPath } from "node:url";
-import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
-import { UsageError } from "../../errors/index.js";
-import { connectMcpServer } from "./connect.js";
-import { renderConnectResult } from "./display.js";
-
-const FIXTURE = fileURLToPath(
-  new URL("./__fixtures__/stdio-server.mjs", import.meta.url),
-);
-
-let backend: Http2Server;
-let client: Stigmer;
-const openSessions = new Set<ServerHttp2Session>();
-
-let connectCalls: ConnectInput[] = [];
-let grantConnected = false;
-// Delay before the mock Connect RPC answers; lets the --timeout tests
-// simulate a long-running server-side connect. The timer is unref'd so a
-// still-pending delayed response can never hold the test process open.
-let connectDelayMs = 0;
-// The server returned by getByReference; mutated per test for auth scenarios.
-let servedSpec: ReturnType<typeof create<typeof McpServerSchema>>;
-
-beforeEach(() => {
-  connectCalls = [];
-  grantConnected = false;
-  connectDelayMs = 0;
-  servedSpec = create(McpServerSchema, {
-    metadata: { id: "mcp_1", name: "github", slug: "github", org: "acme" },
-    spec: {
-      serverType: {
-        case: "stdio",
-        value: { command: process.execPath, args: [FIXTURE] },
-      },
-      env: { GITHUB_TOKEN: { isSecret: true } },
-    },
-  });
-});
-
-// The updated server the Connect RPC returns, carrying discovered capabilities.
-const updatedServer = create(McpServerSchema, {
-  metadata: { id: "mcp_1", name: "github", slug: "github", org: "acme" },
-  spec: { serverType: { case: "stdio", value: { command: "github-mcp" } } },
-  status: {
-    discoveredCapabilities: {
-      tools: [{ name: "search_issues", description: "search issues" }],
-      resourceTemplates: [
-        { name: "issue", uriTemplate: "github:///issues/{id}" },
-      ],
-    },
-  },
-});
-
-beforeAll(async () => {
-  const routes = (router: ConnectRouter) => {
-    router.service(McpServerQueryController, {
-      getByReference: () => servedSpec,
-      get: () => servedSpec,
-      getOAuthGrantStatus: () =>
-        create(GetOAuthGrantStatusOutputSchema, { connected: grantConnected }),
-    });
-    router.service(McpServerCommandController, {
-      // Mirror the backend's protovalidate rule (org min_len=1): reject an empty
-      // org so a regression that drops org fails loudly here instead of silently
-      // passing (the mock adapter does not run protovalidate on its own).
-      connect: async (req) => {
-        if (req.org === "")
-          throw new ConnectError(
-            "org – value length must be at least 1 characters",
-            Code.InvalidArgument,
-          );
-        if (connectDelayMs > 0) {
-          await new Promise((resolve) =>
-            setTimeout(resolve, connectDelayMs).unref(),
-          );
-        }
-        connectCalls.push(req);
-        return updatedServer;
-      },
-    });
-  };
-
-  backend = createHttp2Server(connectNodeAdapter({ routes }));
-  backend.on("session", (session) => {
-    openSessions.add(session);
-    session.on("close", () => openSessions.delete(session));
-  });
-  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
-  const port = (backend.address() as AddressInfo).port;
-  client = createNodeClient({
-    baseUrl: normalizeEndpoint(`127.0.0.1:${port}`),
-  });
-});
-
-afterAll(async () => {
-  for (const session of openSessions) session.destroy();
-  await new Promise<void>((resolve) => backend.close(() => resolve()));
-});
-
-describe("connect push path", () => {
-  it("sends ConnectInput with merged runtime env and returns discovered capabilities", async () => {
-    const result = await connectMcpServer(client, {
-      reference: "github",
-      org: "acme",
-      timeoutMs: 30_000,
-      dryRun: false,
-      envOverrides: ["GITHUB_TOKEN=ghp-override"],
-      consoleURL: "https://app.stigmer.ai",
-      probeLocalConsole: false,
-      interactive: false,
-    });
-
-    expect(connectCalls).toHaveLength(1);
-    expect(connectCalls[0].mcpServerId).toBe("mcp_1");
-    // The org resolved by the command must ride along on ConnectInput — the
-    // backend requires it (issue #140: the CLI used to drop it entirely).
-    expect(connectCalls[0].org).toBe("acme");
-    expect(connectCalls[0].runtimeEnv.GITHUB_TOKEN.value).toBe("ghp-override");
-    expect(connectCalls[0].runtimeEnv.GITHUB_TOKEN.isSecret).toBe(true);
-
-    expect(result.updated?.metadata?.id).toBe("mcp_1");
-    expect(result.capabilities?.tools.map((t) => t.name)).toEqual([
-      "search_issues",
-    ]);
-  });
-});
-
-describe("--timeout bounds the server-side connect (issue #239)", () => {
-  it("stops waiting with actionable guidance when pushTimeoutMs elapses", async () => {
-    connectDelayMs = 5_000;
-    await expect(
-      connectMcpServer(client, {
-        reference: "github",
-        org: "acme",
-        timeoutMs: 30_000,
-        pushTimeoutMs: 150,
-        dryRun: false,
-        envOverrides: ["GITHUB_TOKEN=ghp-x"],
-        consoleURL: "https://app.stigmer.ai",
-        probeLocalConsole: false,
-        interactive: false,
-      }),
-    ).rejects.toThrow(
-      /Stopped waiting for the connect of MCP server 'github' after 0\.15s/,
-    );
-  });
-
-  it("does not bound the wait when pushTimeoutMs is unset (default --timeout)", async () => {
-    // The flag's 30s default is sized for --dry-run local discovery; a real
-    // connect legitimately outlives it, so only an explicit --timeout bounds
-    // the push. 200ms of server delay stands in for "longer than the bound
-    // would have been".
-    connectDelayMs = 200;
-    const result = await connectMcpServer(client, {
-      reference: "github",
-      org: "acme",
-      timeoutMs: 100,
-      dryRun: false,
-      envOverrides: ["GITHUB_TOKEN=ghp-x"],
-      consoleURL: "https://app.stigmer.ai",
-      probeLocalConsole: false,
-      interactive: false,
-    });
-    expect(result.updated?.metadata?.id).toBe("mcp_1");
-  });
-});
-
-describe("OAuth guidance gate", () => {
-  beforeEach(() => {
-    servedSpec.spec!.auth = create(McpServerAuthSchema, {
-      targetEnvVar: "GITHUB_TOKEN",
-    });
-  });
-
-  it("stops with actionable guidance when auth is required off an interactive terminal", async () => {
-    await expect(
-      connectMcpServer(client, {
-        reference: "github",
-        org: "acme",
-        timeoutMs: 30_000,
-        dryRun: false,
-        envOverrides: [],
-        consoleURL: "https://app.stigmer.ai",
-        probeLocalConsole: false,
-        interactive: false,
-      }),
-    ).rejects.toThrow(UsageError);
-    expect(connectCalls).toHaveLength(0);
-  });
-
-  it("proceeds when an OAuth grant already exists", async () => {
-    grantConnected = true;
-    await connectMcpServer(client, {
-      reference: "github",
-      org: "acme",
-      timeoutMs: 30_000,
-      dryRun: false,
-      envOverrides: [],
-      consoleURL: "https://app.stigmer.ai",
-      probeLocalConsole: false,
-      interactive: false,
-    });
-    expect(connectCalls).toHaveLength(1);
-  });
-
-  it("proceeds when --env credentials are supplied (bypassing OAuth)", async () => {
-    await connectMcpServer(client, {
-      reference: "github",
-      org: "acme",
-      timeoutMs: 30_000,
-      dryRun: false,
-      envOverrides: ["GITHUB_TOKEN=ghp-x"],
-      consoleURL: "https://app.stigmer.ai",
-      probeLocalConsole: false,
-      interactive: false,
-    });
-    expect(connectCalls).toHaveLength(1);
-  });
-});
-
-describe("oauth_only servers reject the manual-token routes", () => {
-  beforeEach(() => {
-    servedSpec.spec!.auth = create(McpServerAuthSchema, {
-      targetEnvVar: "GITHUB_TOKEN",
-      oauthOnly: true,
-    });
-  });
-
-  it("rejects --env (which cannot satisfy an OAuth-only endpoint) instead of pushing a doomed token", async () => {
-    const err = await connectMcpServer(client, {
-      reference: "github",
-      org: "acme",
-      timeoutMs: 30_000,
-      dryRun: false,
-      envOverrides: ["GITHUB_TOKEN=ghp-x"],
-      consoleURL: "https://app.stigmer.ai",
-      probeLocalConsole: false,
-      interactive: false,
-    }).catch((e: unknown) => e);
-
-    expect(err).toBeInstanceOf(UsageError);
-    expect((err as UsageError).message).toMatch(/requires OAuth/i);
-    // The guidance must NOT recommend the manual-token route for an oauth_only server.
-    expect((err as UsageError).message).not.toContain("--env TOKEN=");
-    expect(connectCalls).toHaveLength(0);
-  });
-
-  it("omits the --env suggestion from the non-interactive OAuth guidance", async () => {
-    const err = await connectMcpServer(client, {
-      reference: "github",
-      org: "acme",
-      timeoutMs: 30_000,
-      dryRun: false,
-      envOverrides: [],
-      consoleURL: "https://app.stigmer.ai",
-      probeLocalConsole: false,
-      interactive: false,
-    }).catch((e: unknown) => e);
-
-    expect(err).toBeInstanceOf(UsageError);
-    expect((err as UsageError).message).not.toContain("--env TOKEN=");
-    expect(connectCalls).toHaveLength(0);
-  });
-
-  it("refuses --dry-run local discovery (no locally-obtainable OAuth token) with a clear message", async () => {
-    const err = await connectMcpServer(client, {
-      reference: "github",
-      org: "acme",
-      timeoutMs: 10_000,
-      dryRun: true,
-      envOverrides: [],
-      consoleURL: "https://app.stigmer.ai",
-      probeLocalConsole: false,
-      interactive: false,
-    }).catch((e: unknown) => e);
-
-    expect(err).toBeInstanceOf(UsageError);
-    expect((err as UsageError).message).toMatch(/requires OAuth/i);
-    expect((err as UsageError).message).toContain("--dry-run");
-    expect(connectCalls).toHaveLength(0);
-  });
-});
-
-describe("dry-run path", () => {
-  it("discovers locally and never calls the Connect RPC", async () => {
-    const result = await connectMcpServer(client, {
-      reference: "github",
-      org: "acme",
-      timeoutMs: 10_000,
-      dryRun: true,
-      envOverrides: [],
-      consoleURL: "https://app.stigmer.ai",
-      probeLocalConsole: false,
-      interactive: false,
-    });
-
-    expect(connectCalls).toHaveLength(0);
-    expect(result.updated).toBeUndefined();
-    expect(result.capabilities?.tools.map((t) => t.name)).toEqual([
-      "echo",
-      "noop",
-    ]);
-
-    const lines: string[] = [];
-    renderConnectResult(result, (l) => lines.push(l), false);
-    const text = lines.join("\n");
-    expect(text).toContain("MCP Server: acme/github");
-    expect(text).toContain("Transport:  stdio");
-    expect(text).toContain("Tools (2):");
-    expect(text).toContain("Dry run — results not saved");
-  }, 15_000);
-
-  it("maps an unresolved ${VAR} arg to actionable guidance and never calls Connect", async () => {
-    // Server references a declared env var in its args, but it is not set.
-    delete process.env.NEEDED_DIR;
-    servedSpec = create(McpServerSchema, {
-      metadata: {
-        id: "mcp_1",
-        name: "filesystem",
-        slug: "filesystem",
-        org: "acme",
-      },
-      spec: {
-        serverType: {
-          case: "stdio",
-          value: {
-            command: process.execPath,
-            args: [FIXTURE, "${NEEDED_DIR}"],
-          },
-        },
-        env: {
-          NEEDED_DIR: {
-            isSecret: false,
-            description: "Root directory the server may access",
-          },
-        },
-      },
-    });
-
-    const err = await connectMcpServer(client, {
-      reference: "filesystem",
-      org: "acme",
-      timeoutMs: 10_000,
-      dryRun: true,
-      envOverrides: [],
-      consoleURL: "https://app.stigmer.ai",
-      probeLocalConsole: false,
-      interactive: false,
-    }).catch((e: unknown) => e);
-
-    expect(err).toBeInstanceOf(UsageError);
-    const message = (err as UsageError).message;
-    expect(message).toContain("NEEDED_DIR");
-    expect(message).toContain("--env");
-    expect(connectCalls).toHaveLength(0);
-  }, 15_000);
-});

package/src/resources/connect/discover.test.ts

@@ -1,84 +0,0 @@
-// Local discovery tests over a real stdio MCP subprocess fixture.
-//
-// Spawns the fixture server (node __fixtures__/stdio-server.mjs), connects via
-// the MCP SDK, and asserts the discovered tools + resource templates convert to
-// the DiscoveredCapabilities proto and render correctly. Also asserts a crashing
-// subprocess surfaces its stderr instead of hanging.
-
-import { create } from "@bufbuild/protobuf";
-import { McpServerSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
-import { fileURLToPath } from "node:url";
-import { afterEach, describe, expect, it } from "vitest";
-import { localDiscover } from "./discover.js";
-import { PlaceholderResolutionError } from "../mcp/placeholder-resolver.js";
-
-const FIXTURE = fileURLToPath(new URL("./__fixtures__/stdio-server.mjs", import.meta.url));
-const CRASH_FIXTURE = fileURLToPath(new URL("./__fixtures__/stdio-crash.mjs", import.meta.url));
-
-function stdioSpec(scriptPath: string) {
-  return create(McpServerSpecSchema, {
-    serverType: { case: "stdio", value: { command: process.execPath, args: [scriptPath] } },
-  });
-}
-
-// A spec whose args reference ${ALLOWED_DIR}, declared under spec.env — the shape
-// a filesystem MCP server declares its root with (issue #141).
-function stdioSpecWithPlaceholderArg(scriptPath: string) {
-  return create(McpServerSpecSchema, {
-    serverType: { case: "stdio", value: { command: process.execPath, args: [scriptPath, "${ALLOWED_DIR}"] } },
-    env: { ALLOWED_DIR: { isSecret: false, description: "Directory the server may access" } },
-  });
-}
-
-describe("localDiscover (stdio subprocess)", () => {
-  it("discovers tools and resource templates and converts them to proto", async () => {
-    const caps = await localDiscover(stdioSpec(FIXTURE), [], 10_000);
-
-    expect(caps.tools.map((t) => t.name)).toEqual(["echo", "noop"]);
-    expect(caps.tools[0].description).toContain("token=unset");
-    expect(caps.tools[0].inputSchema).toBeDefined();
-
-    expect(caps.resourceTemplates).toHaveLength(1);
-    expect(caps.resourceTemplates[0].uriTemplate).toBe("file:///{path}");
-    expect(caps.resourceTemplates[0].name).toBe("local-file");
-    expect(caps.resourceTemplates[0].mimeType).toBe("text/plain");
-  }, 15_000);
-
-  it("propagates --env overrides into the spawned subprocess", async () => {
-    const caps = await localDiscover(stdioSpec(FIXTURE), ["FIXTURE_TOKEN=secret-123"], 10_000);
-    expect(caps.tools[0].description).toContain("token=secret-123");
-  }, 15_000);
-
-  it("surfaces subprocess stderr when the server crashes on startup", async () => {
-    await expect(localDiscover(stdioSpec(CRASH_FIXTURE), [], 10_000)).rejects.toThrow(/fixture boom: missing CONFIG/);
-  }, 15_000);
-});
-
-describe("localDiscover (${VAR} argument expansion — issue #141)", () => {
-  const original = process.env;
-  afterEach(() => {
-    process.env = original;
-  });
-
-  it("expands a declared ${VAR} arg from --env into the spawned subprocess", async () => {
-    const caps = await localDiscover(stdioSpecWithPlaceholderArg(FIXTURE), ["ALLOWED_DIR=/tmp/allowed"], 10_000);
-    // The fixture echoes the argv it actually received; the resolved value must
-    // reach the subprocess, never the literal placeholder.
-    expect(caps.tools[0].description).toContain('args=["/tmp/allowed"]');
-    expect(caps.tools[0].description).not.toContain("${ALLOWED_DIR}");
-  }, 15_000);
-
-  it("expands a declared ${VAR} arg from the exported shell environment", async () => {
-    process.env = { ...original, ALLOWED_DIR: "/tmp/from-shell" };
-    const caps = await localDiscover(stdioSpecWithPlaceholderArg(FIXTURE), [], 10_000);
-    expect(caps.tools[0].description).toContain('args=["/tmp/from-shell"]');
-  }, 15_000);
-
-  it("rejects with a placeholder error before spawning when the declared var is unset", async () => {
-    process.env = { ...original };
-    delete process.env.ALLOWED_DIR;
-    await expect(localDiscover(stdioSpecWithPlaceholderArg(FIXTURE), [], 10_000)).rejects.toBeInstanceOf(
-      PlaceholderResolutionError,
-    );
-  }, 15_000);
-});

package/src/resources/connect/oauth.test.ts

@@ -1,158 +0,0 @@
-import { create } from "@bufbuild/protobuf";
-import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
-import type { Stigmer } from "@stigmer/sdk";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { UsageError } from "../../errors/index.js";
-import {
-  browserCommand,
-  runOAuthFlow,
-  waitForOAuthGrant,
-  type OAuthFlowDeps,
-} from "./oauth.js";
-
-const server = create(McpServerSchema, {
-  metadata: { id: "mcp_1", slug: "github", name: "GitHub" },
-});
-
-// A fake client whose getOAuthGrantStatus reports `connected` once the call
-// count reaches `connectOnCall` (1 = first poll). Records the call count.
-function fakeClient(connectOnCall: number): {
-  client: Stigmer;
-  calls: () => number;
-} {
-  let calls = 0;
-  const client = {
-    mcpServer: {
-      getOAuthGrantStatus: async () => {
-        calls += 1;
-        return { connected: calls >= connectOnCall };
-      },
-    },
-  } as unknown as Stigmer;
-  return { client, calls: () => calls };
-}
-
-const noopSleep = async (): Promise<void> => {};
-
-describe("browserCommand", () => {
-  it("maps each supported platform to its opener", () => {
-    expect(browserCommand("darwin", "https://x")).toEqual([
-      "open",
-      ["https://x"],
-    ]);
-    expect(browserCommand("linux", "https://x")).toEqual([
-      "xdg-open",
-      ["https://x"],
-    ]);
-    expect(browserCommand("win32", "https://x")).toEqual([
-      "rundll32",
-      ["url.dll,FileProtocolHandler", "https://x"],
-    ]);
-  });
-
-  it("returns no command for unsupported platforms", () => {
-    expect(browserCommand("aix", "https://x")[0]).toBeUndefined();
-  });
-});
-
-describe("waitForOAuthGrant", () => {
-  it("resolves once the grant connects on a later poll", async () => {
-    const { client, calls } = fakeClient(3);
-    const deps: OAuthFlowDeps = {
-      client,
-      server,
-      org: "acme",
-      consoleURL: "https://app.stigmer.ai",
-      probeLocalConsole: false,
-      now: () => 0,
-      sleep: noopSleep,
-      log: () => {},
-    };
-    await expect(waitForOAuthGrant(deps)).resolves.toBeUndefined();
-    expect(calls()).toBe(3);
-  });
-
-  it("throws a UsageError when the poll window elapses", async () => {
-    const { client, calls } = fakeClient(Number.POSITIVE_INFINITY);
-    // First now() seeds the deadline; the next jumps past it to force a timeout
-    // before any grant check runs.
-    const clock = [0, 10 * 60 * 1000];
-    const deps: OAuthFlowDeps = {
-      client,
-      server,
-      org: "acme",
-      consoleURL: "https://app.stigmer.ai",
-      probeLocalConsole: false,
-      now: () => clock.shift() ?? 10 * 60 * 1000,
-      sleep: noopSleep,
-      log: () => {},
-    };
-    await expect(waitForOAuthGrant(deps)).rejects.toThrow(UsageError);
-    expect(calls()).toBe(0);
-  });
-});
-
-describe("runOAuthFlow", () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it("opens the org's MCP-server page then waits for the grant", async () => {
-    const { client } = fakeClient(1);
-    const openBrowser = vi.fn(async () => {});
-    await runOAuthFlow({
-      client,
-      server,
-      org: "acme",
-      consoleURL: "https://app.stigmer.ai",
-      probeLocalConsole: false,
-      openBrowser,
-      now: () => 0,
-      sleep: noopSleep,
-      log: () => {},
-    });
-    expect(openBrowser).toHaveBeenCalledWith(
-      "https://app.stigmer.ai/library/mcp-servers/acme/github",
-    );
-  });
-
-  it("aborts before opening the browser when the local console is unreachable", async () => {
-    const { client } = fakeClient(1);
-    const openBrowser = vi.fn(async () => {});
-    await expect(
-      runOAuthFlow({
-        client,
-        server,
-        org: "acme",
-        consoleURL: "http://localhost:7234",
-        probeLocalConsole: true,
-        probeConsole: async () => false,
-        openBrowser,
-        now: () => 0,
-        sleep: noopSleep,
-        log: () => {},
-      }),
-    ).rejects.toThrow(UsageError);
-    expect(openBrowser).not.toHaveBeenCalled();
-  });
-
-  it("opens the local console page when the probe succeeds", async () => {
-    const { client } = fakeClient(1);
-    const openBrowser = vi.fn(async () => {});
-    await runOAuthFlow({
-      client,
-      server,
-      org: "acme",
-      consoleURL: "http://localhost:7234",
-      probeLocalConsole: true,
-      probeConsole: async () => true,
-      openBrowser,
-      now: () => 0,
-      sleep: noopSleep,
-      log: () => {},
-    });
-    expect(openBrowser).toHaveBeenCalledWith(
-      "http://localhost:7234/library/mcp-servers/acme/github",
-    );
-  });
-});

package/src/resources/cursor-pages.test.ts

@@ -1,55 +0,0 @@
-// Pins readCursorPages, the walk behind `list session` and `list executions`:
-// a --limit above the server's page cap takes several reads, a short page
-// that still carries a token is followed, each read asks only for what is
-// missing, and a limit of zero is one whole-list request.
-import { describe, expect, it } from "vitest";
-import { type CursorPage, readCursorPages } from "./cursor-pages.js";
-
-const SERVER_CAP = 100;
-
-// A server over `total` rows that caps pages and answers `short` rows on
-// the page whose token is listed there (a scope refusing most of a batch).
-function fakeServer(total: number, short: ReadonlyMap<string, number> = new Map()) {
-  const asked: Array<{ pageSize: number; pageToken: string }> = [];
-  const read = async (pageSize: number, pageToken: string): Promise<CursorPage<number>> => {
-    asked.push({ pageSize, pageToken });
-    const start = pageToken === "" ? 0 : Number(pageToken);
-    if (pageSize === 0) return { entries: range(start, total), nextPageToken: "" };
-    const size = Math.min(pageSize, SERVER_CAP, short.get(pageToken) ?? Number.POSITIVE_INFINITY);
-    const end = Math.min(start + size, total);
-    return { entries: range(start, end), nextPageToken: end < total ? String(end) : "" };
-  };
-  return { read, asked };
-}
-
-function range(from: number, to: number): number[] {
-  return Array.from({ length: Math.max(0, to - from) }, (_, i) => from + i);
-}
-
-describe("readCursorPages", () => {
-  it("reads past the server's page cap until the limit is met", async () => {
-    const server = fakeServer(500);
-    const rows = await readCursorPages(250, server.read);
-    expect(rows).toEqual(range(0, 250));
-    expect(server.asked.map((a) => a.pageSize)).toEqual([250, 150, 50]);
-  });
-
-  it("follows a short page that carries a token", async () => {
-    const server = fakeServer(30, new Map([["", 0], ["0", 4]]));
-    const rows = await readCursorPages(10, server.read);
-    expect(rows).toEqual(range(0, 10));
-    expect(server.asked).toHaveLength(3);
-  });
-
-  it("stops when the list ends before the limit", async () => {
-    const server = fakeServer(7);
-    expect(await readCursorPages(50, server.read)).toEqual(range(0, 7));
-    expect(server.asked).toHaveLength(1);
-  });
-
-  it("sends one page_size 0 request for a limit of zero", async () => {
-    const server = fakeServer(150);
-    expect(await readCursorPages(0, server.read)).toHaveLength(150);
-    expect(server.asked).toEqual([{ pageSize: 0, pageToken: "" }]);
-  });
-});