@wirecat/cli-template 0.14.0 → 0.16.0

package/src/mcp.test.ts

@@ -1,88 +1,83 @@
-import { Client } from "@modelcontextprotocol/client"
-import { InMemoryTransport } from "@modelcontextprotocol/server"
-import { describeProgram } from "@wirecat/cli-base/commands"
-import { changesAuthorityAt } from "@wirecat/cli-core/cli"
-import { afterEach, expect, it } from "vitest"
-import { configuration } from "./config.js"
-import { createMcpServer, serveMcp } from "./mcp.js"
-import { createProgram, run } from "./program.js"
+import { mkdirSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import type { RunOptions } from "@wirecat/cli-core/cli"
+import { mcpOverStdio } from "@wirecat/cli-core/testing"
+import { expect, it } from "vitest"
+import type { ServiceEnvironment } from "./context.js"
+import { IDENTITY } from "./identity.js"
+import { run } from "./program.js"
+import { fakeComments } from "./testing/fake-comments.js"
+import { runCli, signedIn } from "./testing/harness.js"
 
-const clients: Client[] = []
-afterEach(async () => {
-  for (const client of clients.splice(0)) await client.close()
+it("mcp serve offers search, read and write, and runs a command through the CLI", async () => {
+  const mcp = await mcpOverStdio((streams) => run(["personal", "mcp", "serve"], { tty: false, ...streams }))
+  try {
+    expect((await mcp.tools()).sort()).toEqual(["clidev_read", "clidev_tools_search", "clidev_write"])
+    const doctor = await mcp.call("clidev_read", { command: "doctor" })
+    expect(doctor.body).toMatchObject({ item: { version: IDENTITY.version } })
+  } finally {
+    expect(await mcp.close()).toBe(0)
+  }
 })
 
-const connect = async () => {
-  const program = createProgram()
-  const server = createMcpServer({
-    profile: "personal",
-    commands: describeProgram(program),
-    levels: () => configuration.resolveSettings({ profile: "personal" }).permissions,
-    authority: changesAuthorityAt(program),
-    run,
-  })
-  const [clientSide, serverSide] = InMemoryTransport.createLinkedPair()
-  await server.connect(serverSide)
-  const client = new Client({ name: "test", version: "1.0.0" })
-  await client.connect(clientSide)
-  clients.push(client)
-  return client
-}
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value)
-const structured = (result: unknown) => {
-  if (!isRecord(result) || !isRecord(result.structuredContent))
-    throw new Error("the tool answered without structured content")
-  return result.structuredContent
-}
-
-it("offers search, read and write", async () => {
-  const client = await connect()
-  const { tools } = await client.listTools()
-  expect(tools.map((tool) => tool.name).sort()).toEqual(["clidev_read", "clidev_tools_search", "clidev_write"])
+it("mcp serve refuses a --permission that names no command, and a --profiles this computer lacks", async () => {
+  const unknown = await runCli(["personal", "mcp", "serve", "--permission", "comments.nope=deny"])
+  expect(unknown.code).toBe(2)
+  expect(unknown.err).toContain("comments.nope")
+  const missing = await runCli(["mcp", "serve", "--profiles", "nope"])
+  expect(missing.code).toBe(2)
+  expect(missing.err).toContain("nope")
 })
 
-it("finds writes as well as reads", async () => {
-  const client = await connect()
-  const found = structured(await client.callTool({ name: "clidev_tools_search", arguments: {} }))
-  expect(found.items).toContainEqual(expect.objectContaining({ writes: true }))
-  expect(found.items).not.toContainEqual(expect.objectContaining({ command: expect.stringMatching(/^mcp\b/) }))
+it("mcp config prints an entry that serves the named profile, or every profile only when told", async () => {
+  const one = await runCli(["personal", "mcp", "config", "--permission", "comments.create=deny", "--json"])
+  const entry = one.json().item as { config: { mcpServers: Record<string, { args: string[] }> } }
+  expect(entry.config.mcpServers["clidev-personal"]?.args.slice(-5)).toEqual([
+    "personal",
+    "mcp",
+    "serve",
+    "--permission",
+    "comments.create=deny",
+  ])
+  const all = await runCli(["mcp", "config", "--profiles", "all", "--json"])
+  expect(JSON.stringify(all.json())).toContain('"--profiles","all"')
 })
 
-it("runs a command through the CLI and answers with its result", async () => {
-  const client = await connect()
-  const answer = structured(await client.callTool({ name: "clidev_read", arguments: { command: "doctor" } }))
-  expect(answer.item).toMatchObject({ version: expect.any(String), profiles: [] })
+it("mcp revoke answers for the profile it names", async () => {
+  const revoked = await runCli(["personal", "mcp", "revoke", "--json"])
+  expect(revoked.code).toBe(0)
+  expect(revoked.json().item).toMatchObject({ profile: "personal" })
 })
 
-it("serves until the command is stopped", async () => {
-  const program = createProgram()
-  const [clientSide, serverSide] = InMemoryTransport.createLinkedPair()
-  const stop = new AbortController()
-  const serving = serveMcp({
-    profile: "personal",
-    commands: describeProgram(program),
-    levels: () => ({}),
-    authority: () => false,
-    run,
-    signal: stop.signal,
-    transport: serverSide,
-  })
-  const client = new Client({ name: "test", version: "1.0.0" })
-  await client.connect(clientSide)
-  expect((await client.listTools()).tools).toHaveLength(3)
-  stop.abort()
-  await expect(serving).resolves.toBeUndefined()
+it("doctor --online answers even when npm cannot be reached", async () => {
+  const online = await runCli(["doctor", "--online", "--json"])
+  expect(online.code).toBe(0)
+  expect(online.json().item).toMatchObject({ version: IDENTITY.version, online: expect.any(Object) })
 })
 
-it("clidev <profile> mcp serve starts the server and ends on a signal", async () => {
-  const stop = new AbortController()
-  const serving = run(["personal", "mcp", "serve"], {
-    signal: stop.signal,
-    tty: false,
-    streams: { data: () => {}, diagnostic: () => {} },
-  })
-  stop.abort()
-  expect(await serving).toBe(0)
+it("a denied command is offered as unavailable and refused before any request (WC-PERM-23)", async () => {
+  const file = join(process.env.CLIDEV_CONFIG_DIR ?? "", "config.json")
+  mkdirSync(join(file, ".."), { recursive: true })
+  writeFileSync(file, JSON.stringify({ profiles: { personal: { permissions: { "comments.list": "deny" } } } }))
+  const service = fakeComments()
+  const options: RunOptions & ServiceEnvironment = { tty: false, keyring: signedIn(), fetch: service.fetch }
+  const mcp = await mcpOverStdio((streams) => run(["personal", "mcp", "serve"], { ...options, ...streams }))
+  try {
+    const found = await mcp.call("clidev_tools_search", { query: "comments list" })
+    expect(found.body).toMatchObject({
+      items: expect.arrayContaining([
+        expect.objectContaining({
+          command: "comments list",
+          availability: expect.objectContaining({ available: false }),
+        }),
+      ]),
+    })
+    const listed = await mcp.call("clidev_read", { command: "comments list" })
+    expect(listed.isError).toBe(true)
+    expect(JSON.stringify(listed.body)).toContain("permission_error")
+    expect(service.calls).toEqual([])
+  } finally {
+    expect(await mcp.close()).toBe(0)
+    rmSync(file, { force: true })
+  }
 })

package/src/program.test.ts

@@ -1,10 +1,11 @@
 import { chmodSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
 import { join } from "node:path"
-import { expect, it, vi } from "vitest"
-import { doctorReport } from "./commands/doctor.js"
-import { configuration } from "./config.js"
+import { annotate } from "@wirecat/cli-base/commands"
+import { REMOTE_READ, run as runShared } from "@wirecat/cli-core/cli"
+import { Command } from "commander"
+import { expect, it } from "vitest"
 import { IDENTITY } from "./identity.js"
-import { run } from "./program.js"
+import { definition, run } from "./program.js"
 
 const ran = async (argv: string[]) => {
   const out: string[] = []
@@ -66,20 +67,15 @@ it("doctor reports an unknown setting with the command that removes it", async (
   )
 })
 
-it("doctor reports settings an environment variable breaks, and still answers", () => {
-  const { report } = doctorReport({ ...process.env, CLIDEV_EMBEDDING_DIMS: "many" })
-  expect(report).toMatchObject({ config: { issues: [] }, settings: { error: expect.any(String) }, profiles: null })
-})
-
-it("doctor answers when reading the settings fails with an unexpected error", () => {
-  const spy = vi.spyOn(configuration, "resolveSettings").mockImplementation(() => {
-    throw new TypeError("boom")
+it("doctor reports settings an environment variable breaks, and still answers", async () => {
+  const out: string[] = []
+  const code = await run(["doctor", "--json"], {
+    streams: { data: (text) => out.push(text), diagnostic: () => {} },
+    tty: false,
+    env: { ...process.env, CLIDEV_EMBEDDING_DIMS: "many" },
   })
-  try {
-    expect(doctorReport(process.env).report).toMatchObject({ settings: { error: "boom" }, profiles: null })
-  } finally {
-    spy.mockRestore()
-  }
+  expect(code).toBe(0)
+  expect(json(out.join("")).item).toMatchObject({ config: { issues: [] }, version: IDENTITY.version })
 })
 
 it.skipIf(process.platform === "win32")(
@@ -233,3 +229,29 @@ it("config repair --dry-run changes nothing, and config repair fixes the JSON wi
     if (backup) rmSync(backup)
   }
 })
+
+it("a deny in the profile stops a read command before its action runs", async () => {
+  const reached: string[] = []
+  const probe = annotate(new Command("probe"), { effects: REMOTE_READ, offline: false }).action(() => {
+    reached.push("probe")
+  })
+  const withProbe = { ...definition(), commands: () => [...definition().commands(), probe] }
+  const dir = process.env.CLIDEV_CONFIG_DIR ?? ""
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(
+    join(dir, "config.json"),
+    JSON.stringify({ profiles: { personal: { permissions: { probe: "deny" } } } }),
+  )
+  const err: string[] = []
+  try {
+    const code = await runShared(["personal", "probe", "--json"], withProbe, {
+      streams: { data: () => {}, diagnostic: (text) => err.push(text) },
+      tty: false,
+    })
+    expect(code).not.toBe(0)
+    expect(err.join("\n")).toContain("permission_error")
+    expect(reached).toEqual([])
+  } finally {
+    rmSync(join(dir, "config.json"))
+  }
+})

package/src/program.ts

@@ -1,9 +1,12 @@
 import { join } from "node:path"
-import { resolvePaths } from "@wirecat/cli-base"
+import { type KeyringStore, resolvePaths } from "@wirecat/cli-base"
 import {
+  appDoctorCommand,
+  appMcpCommand,
   commandsCommand,
   configCommand,
   createProgram as createSharedProgram,
+  environmentOf,
   outputFor,
   type ProgramDefinition,
   type ProgramOptions,
@@ -15,10 +18,12 @@ import {
 } from "@wirecat/cli-core/cli"
 import { appUpdate } from "@wirecat/cli-core/update"
 import type { Command } from "commander"
-import { doctorCommand } from "./commands/doctor.js"
-import { mcpCommand } from "./commands/mcp.js"
+import { commentsCommand } from "./commands/comments.js"
+import { sessionCommand } from "./commands/session.js"
 import { configuration } from "./config.js"
 import { IDENTITY, PACKAGE, SKILL } from "./identity.js"
+import { SERVICE } from "./sample/transport.js"
+import { holdsToken } from "./token.js"
 
 const update = appUpdate({
   packageName: PACKAGE,
@@ -31,12 +36,32 @@ const update = appUpdate({
   offVariables: [`${IDENTITY.envPrefix}_NO_UPDATE_CHECK`],
 })
 
+const mcpCommand = () => {
+  // cli-core asks `signedIn` with no keyring; the run's own one, a test's `memoryKeyring()`, is taken here. Each
+  // program builds its own `mcp`, so a tool call run beside it never swaps the server's keyring (WC-ARCH-22).
+  let keyring: KeyringStore | undefined
+  const mcp = appMcpCommand(IDENTITY, configuration, {
+    name: SERVICE,
+    // SAMPLE: name the kinds of text other people wrote that your answers carry (WC-MCP-11).
+    untrusted: ["comment text", "author names"],
+    permissionExample: "comments.create=deny",
+    skill: SKILL,
+    signedIn: (profile, env) => holdsToken(env, profile, keyring),
+  })
+  return mcp.hook("preAction", (_mcp, action) => {
+    keyring = environmentOf(action).keyring
+  })
+}
+
 export const definition = (): ProgramDefinition => ({
   app: IDENTITY,
-  configuration: { resolveSettings: configuration.resolveSettings },
+  // The whole object: cli-core refuses a command by its key only when it gets the permission table too.
+  configuration,
   commands: () => [
     commandsCommand(IDENTITY),
-    doctorCommand(),
+    sessionCommand(),
+    commentsCommand(),
+    appDoctorCommand(IDENTITY, configuration, { packageName: PACKAGE }),
     skillCommand(IDENTITY, SKILL),
     mcpCommand(),
     upgradeCommand(IDENTITY, PACKAGE, (command) => ({

package/src/sample/comments.ts

@@ -0,0 +1,51 @@
+import * as v from "valibot"
+import type { Transport } from "./transport.js"
+
+// SAMPLE: replace these shapes with your service's. Each wire name comes from the service's docs or a captured answer,
+// never from memory; the strict fake in src/testing/fake-comments.ts refuses any other.
+const wireComment = v.object({
+  id: v.string(),
+  body: v.string(),
+  authorName: v.string(),
+  createdAt: v.string(),
+})
+const wirePage = v.object({ comments: v.array(wireComment), hasMore: v.boolean() })
+const wireUser = v.object({ id: v.string(), name: v.string() })
+
+/**
+ * The answer's own shape, in snake_case (WC-OUT-12). `answerEntity` publishes it, so `--json=id,text` and the MCP
+ * schema both come from here (WC-CMD-19). No wire type leaves this file (WC-ARCH-3).
+ */
+export const commentSchema = v.strictObject({
+  id: v.string(),
+  text: v.string(),
+  author: v.string(),
+  created_at: v.string(),
+})
+export type Comment = v.InferOutput<typeof commentSchema>
+
+export const commentOf = (wire: v.InferOutput<typeof wireComment>): Comment => ({
+  id: wire.id,
+  text: wire.body,
+  author: wire.authorName,
+  created_at: wire.createdAt,
+})
+
+/** Every call the sample makes: a method, a path template and only the fields the service documents. */
+export const commentsService = (api: Transport) => ({
+  me: () => api.send({ method: "GET", path: "me" }, wireUser),
+  list: async ({ limit, offset, author }: { limit: number; offset: number; author?: string | undefined }) => {
+    const page = await api.send({ method: "GET", path: "comments", query: { limit, offset, by: author } }, wirePage)
+    return { items: page.comments.map(commentOf), has_more: page.hasMore }
+  },
+  show: async (id: string) =>
+    commentOf(await api.send({ method: "GET", path: "comments/{id}", ids: { id } }, wireComment)),
+  create: async (text: string) =>
+    commentOf(await api.send({ method: "POST", path: "comments", body: { body: text } }, wireComment)),
+  update: async (id: string, text: string) =>
+    commentOf(
+      await api.send({ method: "PATCH", path: "comments/{id}", ids: { id }, body: { body: text } }, wireComment),
+    ),
+})
+
+export type CommentsService = ReturnType<typeof commentsService>

package/src/sample/transport.test.ts

@@ -0,0 +1,117 @@
+import type { Pacer } from "@wirecat/cli-core/sends"
+import * as v from "valibot"
+import { expect, it } from "vitest"
+import { FAKE_TOKEN, fakeComments } from "../testing/fake-comments.js"
+import { commentOf, commentsService } from "./comments.js"
+import { failureOf, transport } from "./transport.js"
+
+const anything = v.unknown()
+const failing = (error: unknown) => async () => Promise.reject(error)
+const timedOut = () => new DOMException("timed out", "TimeoutError")
+
+it("maps the wire shape to the answer's own", () => {
+  expect(commentOf({ id: "c1", body: "Hi", authorName: "Test Person", createdAt: "2026-01-02T03:04:05Z" })).toEqual({
+    id: "c1",
+    text: "Hi",
+    author: "Test Person",
+    created_at: "2026-01-02T03:04:05Z",
+  })
+})
+
+it.each([
+  [401, false, "authentication_error"],
+  [404, false, "not_found"],
+  [429, true, "rate_limited"],
+  [503, false, "provider_unavailable"],
+  [503, true, "outcome_unknown"],
+  [400, true, "validation_error"],
+])("HTTP %i (a write: %s) is %s", (status, writes, code) => {
+  expect(failureOf(status, writes).code).toBe(code)
+})
+
+it("a write that failed on the service is never marked safe to retry", () => {
+  expect(failureOf(500, true).details).toMatchObject({ retryable: false })
+  expect(failureOf(429, false, 2000).details).toMatchObject({ retryable: true, retry_after_ms: 2000 })
+})
+
+it("sends the token in the Authorization header only, and refuses a redirect", async () => {
+  const service = fakeComments()
+  const sent: RequestInit[] = []
+  await commentsService(
+    transport({
+      token: FAKE_TOKEN,
+      fetch: (input, init = {}) => {
+        sent.push(init)
+        return service.fetch(input, init)
+      },
+    }),
+  ).me()
+  expect(service.calls[0]?.url).not.toContain(FAKE_TOKEN)
+  expect(service.calls[0]?.headers.authorization).toBe(`Bearer ${FAKE_TOKEN}`)
+  expect(sent[0]?.redirect).toBe("error")
+})
+
+it('refuses an id of "." or ".." before any request, since it would reach another endpoint', async () => {
+  const service = fakeComments()
+  const comments = commentsService(transport({ token: FAKE_TOKEN, fetch: service.fetch }))
+  await expect(comments.show("..")).rejects.toMatchObject({ code: "validation_error" })
+  expect(service.calls).toEqual([])
+})
+
+it("a read that got no answer is a retryable timeout or network error; a write is outcome_unknown", async () => {
+  const send = (error: unknown, method: "GET" | "POST") =>
+    transport({ token: FAKE_TOKEN, fetch: failing(error) }).send({ method, path: "comments", body: {} }, anything)
+  await expect(send(timedOut(), "GET")).rejects.toMatchObject({ code: "timeout", details: { retryable: true } })
+  await expect(send(new TypeError("fetch failed"), "GET")).rejects.toMatchObject({ code: "network_error" })
+  await expect(send(timedOut(), "POST")).rejects.toMatchObject({
+    code: "outcome_unknown",
+    details: { retryable: false },
+  })
+})
+
+it("a stop during a read cancels it; during a write it stays outcome_unknown", async () => {
+  const stop = new AbortController()
+  stop.abort()
+  const send = (method: "GET" | "PATCH") =>
+    transport({ token: FAKE_TOKEN, fetch: failing(new Error("aborted")), signal: stop.signal }).send(
+      { method, path: "comments" },
+      anything,
+    )
+  await expect(send("GET")).rejects.toMatchObject({ code: "cancelled" })
+  await expect(send("PATCH")).rejects.toMatchObject({ code: "outcome_unknown" })
+})
+
+it("an answer that is not JSON is invalid_response", async () => {
+  const fetch = async () => new Response("<html>", { status: 200 })
+  await expect(commentsService(transport({ token: FAKE_TOKEN, fetch })).me()).rejects.toMatchObject({
+    code: "invalid_response",
+  })
+})
+
+it("an answer in another shape is invalid_response", async () => {
+  const fetch = async () => new Response(JSON.stringify({ unexpected: true }), { status: 200 })
+  await expect(commentsService(transport({ token: FAKE_TOKEN, fetch })).me()).rejects.toMatchObject({
+    code: "invalid_response",
+  })
+})
+
+it("waits its turn under the profile's pace, and ends the run instead of a long wait", async () => {
+  const service = fakeComments()
+  const waits: number[] = []
+  const paced = (at: number) =>
+    commentsService(
+      transport({
+        token: FAKE_TOKEN,
+        fetch: service.fetch,
+        now: () => 1_000,
+        pacer: { reserve: async () => at } as unknown as Pacer,
+        sleep: async (ms) => {
+          waits.push(ms)
+        },
+      }),
+    ).me()
+  await paced(1_500)
+  expect(waits).toEqual([500])
+  await expect(paced(1_000 + 120_000)).rejects.toMatchObject({ code: "rate_limited" })
+  expect(service.calls).toHaveLength(1)
+})

package/src/sample/transport.ts

@@ -0,0 +1,184 @@
+import { CliError, isCliError, realSleep, type SleepLike, wallClock } from "@wirecat/cli-base"
+import { providerWaitMs, readJsonResponse, statusToCode } from "@wirecat/cli-base/http"
+import { type EventSink, providerRequest } from "@wirecat/cli-core/cli"
+import type { Pacer } from "@wirecat/cli-core/sends"
+import * as v from "valibot"
+
+// SAMPLE: the Example Comments service does not exist; `.invalid` never resolves, so a real run reaches nothing.
+// Replace the address, the paths and the answer shapes with your service's, each from its docs or a captured answer.
+export const SERVICE_URL = "https://comments.example.invalid/v1/"
+export const SERVICE = "Example Comments"
+
+const TIMEOUT_MS = 30_000
+const LARGEST_ANSWER = 8 * 1024 * 1024
+/** A pace wait longer than this ends the run with `rate_limited` instead of sitting in it. */
+const LONGEST_PACE_WAIT_MS = 60_000
+
+export interface Request {
+  method: "GET" | "POST" | "PATCH"
+  /** The path as a template, `comments/{id}`: the run record keeps the template, never an id. */
+  path: string
+  ids?: Record<string, string>
+  query?: Record<string, string | number | undefined>
+  body?: Record<string, unknown>
+}
+
+export interface TransportOptions {
+  token: string
+  fetch?: typeof fetch
+  signal?: AbortSignal | undefined
+  /** The run's sink from `baseContext(...).run(events => …)`, so each request lands in the run record (WC-LIFE-15). */
+  events?: EventSink
+  /** cli-core's per-profile pace, shared by every process of the profile through a file. */
+  pacer?: Pacer
+  sleep?: SleepLike
+  now?: () => number
+  timeoutMs?: number
+}
+
+/** `new URL` folds a `.` or `..` segment into its parent, so such an id would reach another endpoint. */
+const segment = (name: string, value: string) => {
+  if (value === "" || value === "." || value === "..")
+    throw new CliError("validation_error", `${name} must name one item; an empty, "." or ".." id is refused`)
+  return encodeURIComponent(value)
+}
+
+const urlOf = ({ path, ids = {}, query = {} }: Request) => {
+  const url = new URL(
+    path.replace(/\{(\w+)\}/g, (_, name: string) => segment(name, ids[name] ?? "")),
+    SERVICE_URL,
+  )
+  for (const [key, value] of Object.entries(query)) if (value !== undefined) url.searchParams.set(key, String(value))
+  return url
+}
+
+/**
+ * A refusal as a CliError with cli-base's code for its status. The service's own message is never repeated: it can
+ * quote what was sent (WC-SECR-6). A write that failed on the service's side may have happened, so it is
+ * `outcome_unknown` and never retryable (WC-OUT-20, WC-LIFE-9).
+ */
+export const failureOf = (status: number, writes: boolean, retryAfterMs?: number): CliError => {
+  if (status === 401)
+    return new CliError("authentication_error", `${SERVICE} refused the token; sign in again with session start`, {
+      status,
+    })
+  if (status === 429)
+    return new CliError("rate_limited", `${SERVICE} asked to slow down; retry the command later`, {
+      status,
+      retryable: true,
+      ...(retryAfterMs === undefined ? {} : { retry_after_ms: retryAfterMs }),
+    })
+  if (status >= 500 && writes)
+    return new CliError("outcome_unknown", `${SERVICE} failed during a write; check it before repeating the write`, {
+      status,
+      retryable: false,
+    })
+  if (status === 404) return new CliError("not_found", `${SERVICE} has no such item, or this token cannot see it`)
+  return new CliError(statusToCode(status), `${SERVICE} refused the request (HTTP ${status})`, {
+    status,
+    retryable: status >= 500,
+  })
+}
+
+/**
+ * The only code that holds the token: it goes in the Authorization header, never in an address, an error or a run
+ * record (WC-SECR-7). Nothing here retries. A read the caller may run again; a write is never sent twice, since the
+ * first may have landed (WC-OUT-20).
+ */
+export const transport = (options: TransportOptions) => {
+  const fetchOf = options.fetch ?? fetch
+  const sleep = options.sleep ?? realSleep
+  const now = options.now ?? Date.now
+
+  const turn = async () => {
+    if (!options.pacer) return
+    const wait = (await options.pacer.reserve()) - now()
+    if (wait <= 0) return
+    if (wait > LONGEST_PACE_WAIT_MS)
+      throw new CliError("rate_limited", `this profile must wait ${Math.ceil(wait / 1000)} s before its next request`, {
+        retry_after_ms: wait,
+      })
+    await sleep(wait, options.signal, "retry")
+  }
+
+  const unanswered = (writes: boolean, error: unknown): CliError => {
+    // Before the stop check: a write stopped in flight may still have landed (WC-LIFE-9).
+    if (writes)
+      return new CliError("outcome_unknown", `${SERVICE} did not answer a write; check it before repeating the write`, {
+        retryable: false,
+      })
+    if (options.signal?.aborted) return new CliError("cancelled", `the ${SERVICE} request was stopped`)
+    const timedOut = (error as { name?: string } | undefined)?.name === "TimeoutError"
+    return timedOut
+      ? new CliError("timeout", `${SERVICE} did not answer in time`, { retryable: true })
+      : new CliError("network_error", `${SERVICE} could not be reached`, { retryable: true })
+  }
+
+  const send = async <T>(request: Request, answer: v.GenericSchema<unknown, T>): Promise<T> => {
+    const writes = request.method !== "GET"
+    const url = urlOf(request)
+    await turn()
+    // Not AbortSignal.timeout: its timer keeps the run's async context alive until it fires.
+    const deadline = new AbortController()
+    const timer = setTimeout(
+      () => deadline.abort(new DOMException("timed out", "TimeoutError")),
+      options.timeoutMs ?? TIMEOUT_MS,
+    )
+    timer.unref()
+    const signal = options.signal ? AbortSignal.any([options.signal, deadline.signal]) : deadline.signal
+    const end = providerRequest(`${request.method} /${request.path}`, options.events, {
+      method: request.method,
+      transport: "http",
+    })
+    try {
+      let response: Response
+      try {
+        response = await fetchOf(url, {
+          method: request.method,
+          headers: {
+            authorization: `Bearer ${options.token}`,
+            accept: "application/json",
+            ...(request.body ? { "content-type": "application/json" } : {}),
+          },
+          ...(request.body ? { body: JSON.stringify(request.body) } : {}),
+          // A redirect would carry the Authorization header to an address we did not choose.
+          redirect: "error",
+          signal,
+        })
+      } catch (error) {
+        const failure = unanswered(writes, deadline.signal.reason ?? error)
+        end({ errorCode: failure.code })
+        throw failure
+      }
+      if (!response.ok) {
+        const failure = failureOf(response.status, writes, providerWaitMs(response.headers, wallClock))
+        end({ status: response.status, errorCode: failure.code })
+        throw failure
+      }
+      let body: unknown
+      try {
+        body = await readJsonResponse(response, { maxBytes: LARGEST_ANSWER, signal })
+      } catch (error) {
+        const failure =
+          isCliError(error) && error.code !== "invalid_response"
+            ? error
+            : new CliError("invalid_response", `${SERVICE} answered with something other than bounded JSON`)
+        end({ status: response.status, errorCode: failure.code })
+        throw failure
+      }
+      const parsed = v.safeParse(answer, body)
+      if (!parsed.success) {
+        end({ status: response.status, errorCode: "invalid_response" })
+        throw new CliError("invalid_response", `${SERVICE}'s answer does not have the documented shape`)
+      }
+      end({ status: response.status })
+      return parsed.output
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  return { send }
+}
+
+export type Transport = ReturnType<typeof transport>