@nimbus-dev/connectors 0.2.1 → 0.2.2

package/shared/cli-json-kit.ts

@@ -0,0 +1,150 @@
+/**
+ * cli-json-kit — the shared pieces of the CLI-backed connectors.
+ *
+ * Five connectors reach their service by spawning a cloud CLI and parsing its
+ * JSON (athena, cloudwatch and sagemaker through `aws`; cloud-logging and
+ * vertex-ai through `gcloud`), and each had written out the same three things:
+ *
+ *   - the `cliArg` Zod refinement that rejects an argument starting with `-`
+ *     (argv flag smuggling) or carrying control characters;
+ *   - a `runX` wrapper: spawn, trim, throw `"<label> <verb> failed: <stderr>"`
+ *     on a non-zero exit, otherwise `JSON.parse` the stdout;
+ *   - `isRecord` / `strField` / `asArray`, the untyped-payload readers used to
+ *     walk the parsed result.
+ *
+ * The argument guard is the reason this is worth sharing rather than tolerating:
+ * it is a security control, and a security control that exists in five
+ * hand-written copies is one that can be strengthened in four of them.
+ *
+ * The `gcloud` connectors (bigquery, cloud-logging, gcp, vertex-ai) also share
+ * how they hand gcloud its project and credentials: see {@link gcloudEnv} and
+ * {@link gcloudProjectArgs}.
+ */
+
+import { z } from "zod";
+import { optionalEnv } from "./env-json-api.ts";
+import { isSafeCliArg } from "./safe-cli-arg.ts";
+
+/** Body-snippet length in the thrown error. The value every connector used. */
+export const DEFAULT_STDERR_SNIPPET = 400;
+
+/**
+ * A value passed to a CLI as an argument.
+ *
+ * Rejected at the SCHEMA boundary, before the value can reach argv: a leading
+ * `-` would be read by the CLI as a flag rather than as the name it is meant to
+ * be, and control characters have no legitimate place in one.
+ */
+export const cliArg = z
+  .string()
+  .min(1)
+  .refine(isSafeCliArg, { message: 'must not start with "-" or contain control characters' });
+
+/** The spawn seam. Production passes `nimbusSpawn`; tests pass a fake. */
+export type SpawnFn = (
+  command: readonly string[],
+  env: Record<string, string | undefined>,
+) => Promise<{ code: number; stdout: string; stderr: string }>;
+
+export interface CliJsonRunnerConfig {
+  /**
+   * Builds the full argv for one call. Given the connector's own arguments, it
+   * returns the complete command — binary, subcommand, arguments and whatever
+   * output flag that CLI needs (`--output json` for aws, `--format json` for
+   * gcloud).
+   */
+  readonly argv: (args: readonly string[]) => readonly string[];
+  /** Prefix for the thrown error, e.g. `"aws athena"`. */
+  readonly label: string;
+  /**
+   * What empty stdout means. The `aws` connectors treat it as `{}` and the
+   * `gcloud` ones as `[]`, because that is the shape each CLI omits when there
+   * is nothing to report.
+   */
+  readonly emptyResult: unknown;
+  /** Extra environment for the spawn. Defaults to none — the CLI reads its own. */
+  readonly env?: () => Record<string, string | undefined>;
+  readonly snippetMax?: number;
+}
+
+/**
+ * A `(args) => Promise<unknown>` runner for one CLI.
+ *
+ * Throws `"<label> <first arg> failed: <stderr snippet>"` on a non-zero exit,
+ * so a caller sees which subcommand failed and why.
+ */
+export function createCliJsonRunner(
+  config: CliJsonRunnerConfig,
+  spawn: SpawnFn,
+): (args: readonly string[]) => Promise<unknown> {
+  const snippetMax = config.snippetMax ?? DEFAULT_STDERR_SNIPPET;
+  return async (args: readonly string[]): Promise<unknown> => {
+    const { code, stdout, stderr } = await spawn(config.argv(args), config.env?.() ?? {});
+    const out = stdout.trim();
+    if (code !== 0) {
+      throw new Error(
+        `${config.label} ${args[0] ?? ""} failed: ${stderr.trim().slice(0, snippetMax)}`,
+      );
+    }
+    return out === "" ? config.emptyResult : (JSON.parse(out) as unknown);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Untyped-payload readers
+//
+// External CLI output is `unknown` at the boundary (Non-Negotiable #5), and
+// these three are how every one of these connectors narrows it.
+// ---------------------------------------------------------------------------
+
+/** A non-null, non-array object. */
+export function isRecord(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/** `r[key]` when it is a string, else `""` — never `undefined`, never a throw. */
+export function strField(r: Record<string, unknown>, key: string): string {
+  const v = r[key];
+  return typeof v === "string" ? v : "";
+}
+
+/** `parsed[key]` when `parsed` is a record and the value is an array, else `[]`. */
+export function asArray(parsed: unknown, key: string): unknown[] {
+  if (!isRecord(parsed)) {
+    return [];
+  }
+  const arr = parsed[key];
+  return Array.isArray(arr) ? arr : [];
+}
+
+/** Case-insensitive substring match on one string field of an untyped entry. */
+export function fieldMatches(entry: unknown, key: string, query: string): boolean {
+  return isRecord(entry) && strField(entry, key).toLowerCase().includes(query.toLowerCase());
+}
+
+// ---------------------------------------------------------------------------
+// gcloud
+// ---------------------------------------------------------------------------
+
+/**
+ * `["--project", <id>]` when `GOOGLE_CLOUD_PROJECT` is set at spawn, else `[]`, which leaves
+ * gcloud on the project it is configured with.
+ */
+export function gcloudProjectArgs(): string[] {
+  const project = optionalEnv("GOOGLE_CLOUD_PROJECT", "");
+  return project === "" ? [] : ["--project", project];
+}
+
+/**
+ * The environment for a `gcloud` spawn: the process environment, with
+ * `GOOGLE_APPLICATION_CREDENTIALS` — the key file gcloud reads natively — re-set to its trimmed
+ * value when it is set.
+ */
+export function gcloudEnv(): Record<string, string | undefined> {
+  const env = { ...process.env } as Record<string, string | undefined>;
+  const credentials = process.env["GOOGLE_APPLICATION_CREDENTIALS"]?.trim();
+  if (credentials !== undefined && credentials !== "") {
+    env["GOOGLE_APPLICATION_CREDENTIALS"] = credentials;
+  }
+  return env;
+}

package/shared/collection-tool-kit.ts

@@ -0,0 +1,143 @@
+/**
+ * collection-tool-kit — the `<prefix>_list` / `<prefix>_get` / `<prefix>_search`
+ * triple that most read-only REST connectors expose over a single collection.
+ *
+ * Sonar reports the tail of this shape as duplicated across readwise, mercury,
+ * zoom, lever and intercom, but the flagged blocks understate it: the triple is
+ * written out by hand in roughly thirty connectors and is the same three tool
+ * bodies every time —
+ *
+ *   list   → `jsonResult(await get(PATH))`
+ *   get    → `jsonResult(await get(ITEM_PATH(encodeURIComponent(id))))`
+ *   search → `matchesResult(rows(await get(PATH)), filter, args)`
+ *
+ * — with only the paths, the envelope key and the descriptions differing. Those
+ * are the inputs here.
+ *
+ * What is NOT hidden: the descriptions. Each connector still writes its own,
+ * because they document that API's envelope shape and pagination and are the
+ * only thing the model sees when choosing a tool. A generated description would
+ * be a real regression in tool quality to save a line.
+ *
+ * Connectors whose tools do anything else — extra query parameters, a second
+ * request, a non-standard error, a POST — keep registering those directly on
+ * `reg`. This kit is for the plain triple, not a framework to force the rest
+ * into.
+ */
+
+import { z } from "zod";
+import { matchesResult, type SearchFilter, searchToolInputSchema } from "./mcp-search-tool.ts";
+import { mcpJsonResult } from "./mcp-tool-kit.ts";
+import type { ZodToolRegistrar } from "./run-read-only-mcp-connector.ts";
+
+/** The per-connector search cap every connector in this family uses. */
+export const DEFAULT_SEARCH_MAX = 100;
+
+/** A `(path) => Promise<unknown>` client, e.g. from `createJsonGetter`. */
+export type JsonGetter = (path: string) => Promise<unknown>;
+
+/**
+ * Read the row array out of a list response.
+ *
+ * Most APIs wrap the rows in a named key (`{ results }`, `{ data }`,
+ * `{ accounts }`, `{ conversations }`); a few return a bare array, which is
+ * {@link identityRows}.
+ */
+export type RowsAccessor = (root: unknown) => unknown;
+
+/** Rows under a single envelope key, e.g. `envelopeRows("results")`. */
+export function envelopeRows(key: string): RowsAccessor {
+  return (root: unknown): unknown => (root as Record<string, unknown> | null)?.[key];
+}
+
+/** The response IS the row array. */
+export const identityRows: RowsAccessor = (root: unknown): unknown => root;
+
+export interface CollectionListSpec {
+  /** Path appended to the getter's base. */
+  readonly path: string;
+  readonly description: string;
+  /** Tool name suffix. Defaults to `"list"`, giving `<prefix>_list`. */
+  readonly tool?: string;
+}
+
+export interface CollectionItemSpec {
+  /** Builds the path for one id. The id arrives already percent-encoded. */
+  readonly path: (encodedId: string) => string;
+  readonly description: string;
+  /** Tool name suffix. Defaults to `"get"`. */
+  readonly tool?: string;
+}
+
+export interface CollectionSearchSpec {
+  /** Path to search over. Defaults to the list path. */
+  readonly path?: string;
+  readonly description: string;
+  readonly rows: RowsAccessor;
+  readonly filter: SearchFilter;
+  /** Per-connector `limit` cap. Defaults to {@link DEFAULT_SEARCH_MAX}. */
+  readonly maxLimit?: number;
+  /** Tool name suffix. Defaults to `"search"`. */
+  readonly tool?: string;
+}
+
+export interface CollectionToolsConfig {
+  /** Tool-name prefix, e.g. `"mercury"` for `mercury_list`. */
+  readonly prefix: string;
+  readonly get: JsonGetter;
+  readonly list: CollectionListSpec;
+  readonly item?: CollectionItemSpec;
+  readonly search?: CollectionSearchSpec;
+}
+
+/** The names {@link registerCollectionTools} would register for `config`. */
+export function collectionToolNames(config: CollectionToolsConfig): string[] {
+  const names = [`${config.prefix}_${config.list.tool ?? "list"}`];
+  if (config.item !== undefined) {
+    names.push(`${config.prefix}_${config.item.tool ?? "get"}`);
+  }
+  if (config.search !== undefined) {
+    names.push(`${config.prefix}_${config.search.tool ?? "search"}`);
+  }
+  return names;
+}
+
+/**
+ * Register the list/get/search triple described by `config`.
+ *
+ * `item` and `search` are optional: a few collections are list-only, and a few
+ * have no id to fetch by.
+ */
+export function registerCollectionTools(
+  reg: ZodToolRegistrar,
+  config: CollectionToolsConfig,
+): void {
+  const { prefix, get, list, item, search } = config;
+
+  reg(`${prefix}_${list.tool ?? "list"}`, list.description, z.object({}), async () => {
+    return mcpJsonResult(await get(list.path));
+  });
+
+  if (item !== undefined) {
+    reg(
+      `${prefix}_${item.tool ?? "get"}`,
+      item.description,
+      z.object({ id: z.string().min(1) }),
+      async (p) => {
+        return mcpJsonResult(await get(item.path(encodeURIComponent(p.id))));
+      },
+    );
+  }
+
+  if (search !== undefined) {
+    reg(
+      `${prefix}_${search.tool ?? "search"}`,
+      search.description,
+      searchToolInputSchema(search.maxLimit ?? DEFAULT_SEARCH_MAX),
+      async (p) => {
+        const root = await get(search.path ?? list.path);
+        return matchesResult(search.rows(root), search.filter, p);
+      },
+    );
+  }
+}

package/shared/connector-mode.ts

@@ -45,8 +45,9 @@ export function getConnectorMode(): ConnectorMode {
 
 /**
  * TEST-ONLY: clear the lock between cases. Never called from production code — the
- * `audit:connector-consent` gate permits `setConnectorMode` only in the two sanctioned entrypoints,
- * and this function exists so tests never need to reach for it.
+ * `audit:connector-consent` gate lets no production file here but this one name `setConnectorMode`
+ * (its one production caller is the gateway's `run-bundled-connector.ts`), and this function
+ * exists so tests never need to reach for it.
  *
  * This matters more than it looks. `bun test` runs MANY TEST FILES IN ONE PROCESS — verified: two
  * files sharing a module observed the same pid, and state set by the first was visible to the

package/shared/cursor-list-tool.ts

@@ -0,0 +1,29 @@
+/**
+ * cursor-list-tool — the input contract of a paginated `<prefix>_list` tool.
+ *
+ * Six connectors (bigeye, looker, monte-carlo, powerbi, snowflake, tableau) page through a
+ * collection the same way: the caller passes back an opaque `cursor` — the previous page's
+ * `nextCursor`, or nothing / `null` for the first page — plus a `limit`, and receives
+ * `{ items, nextCursor }`. Each declared that input schema separately. What the cursor encodes (an
+ * offset, a page number, a relay token) and the default page size stay each connector's own.
+ */
+
+import { z } from "zod";
+import type { ZodObjectSchema } from "./mcp-tool-kit.ts";
+
+/** What a paginated `_list` tool is called with. */
+export interface CursorListOptions {
+  readonly cursor?: string | null | undefined;
+  readonly limit?: number | undefined;
+}
+
+/**
+ * The paginated `_list` input schema: an optional, nullable opaque `cursor` and an optional
+ * integer `limit` from 1 to `maxLimit`.
+ */
+export function cursorListInputSchema(maxLimit = 500): ZodObjectSchema<CursorListOptions> {
+  return z.object({
+    cursor: z.string().nullable().optional(),
+    limit: z.number().int().min(1).max(maxLimit).optional(),
+  });
+}

package/shared/env-json-api.ts

@@ -0,0 +1,209 @@
+/**
+ * env-json-api — the read-only JSON GET client that 31 connectors had each
+ * written out by hand.
+ *
+ * The shape below appeared, byte for byte, in every one of them:
+ *
+ * ```ts
+ * function apiToken(): string {
+ *   const t = process.env["X_TOKEN"]?.trim();
+ *   if (t === undefined || t === "") throw new Error("X_TOKEN is not set");
+ *   return t;
+ * }
+ * function authHeader(): Record<string, string> {
+ *   return { Authorization: `Bearer ${apiToken()}`, Accept: "application/json" };
+ * }
+ * async function xGet(path: string): Promise<unknown> {
+ *   const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
+ *   const text = await res.text();
+ *   if (!res.ok) throw new Error(`X ${String(res.status)}: ${text.slice(0, 400)}`);
+ *   return JSON.parse(text) as unknown;
+ * }
+ * ```
+ *
+ * Only four things ever varied: the base URL, the service label in the error,
+ * the auth header, and (never, in practice) the 400-character snippet cap. So
+ * those are the inputs and the rest is here once.
+ *
+ * This is deliberately NOT `rest-tool-kit`'s `makeRestFetcher`. That one returns
+ * `{ ok, status, json, text }` for callers that branch on status; these 31
+ * connectors all throw on a non-2xx and return parsed JSON, and rewriting their
+ * tool bodies to the other contract would have been a behaviour change rather
+ * than a deduplication. Both shapes are legitimate; this module owns the
+ * throwing one.
+ *
+ * Environment is read at CALL time, not at module load. That is not incidental:
+ * the connectors behaved that way (their `apiToken()` ran per request), tests
+ * depend on being able to set the variable after import, and a connector must
+ * fail with "X_TOKEN is not set" on the tool call rather than at startup.
+ */
+
+import { stripTrailingSlashes } from "./strip-trailing-slashes.ts";
+
+/** Body-snippet length in the thrown error. The value every connector used. */
+export const DEFAULT_SNIPPET_MAX = 400;
+
+/**
+ * `process.env[name]`, trimmed. Throws `"<name> is not set"` when the variable
+ * is absent, empty, or whitespace only.
+ *
+ * Distinct from `requireProcessEnv` in `mcp-tool-kit`, which does not trim: a
+ * variable set to a single space passes that check and then produces an
+ * `Authorization: Bearer ` header and a puzzling 401. Every one of the 31
+ * connectors trimmed, so trimming is the behaviour being preserved here.
+ */
+export function requiredEnv(name: string): string {
+  const raw = process.env[name]?.trim();
+  if (raw === undefined || raw === "") {
+    throw new Error(`${name} is not set`);
+  }
+  return raw;
+}
+
+/** `process.env[name]`, trimmed, or `fallback` when absent or empty. */
+export function optionalEnv(name: string, fallback: string): string {
+  const raw = process.env[name]?.trim();
+  return raw === undefined || raw === "" ? fallback : raw;
+}
+
+/**
+ * A required base URL from the environment, with trailing slashes stripped so
+ * `${base}${path}` cannot produce a double slash.
+ */
+export function requiredBaseUrl(name: string): string {
+  return stripTrailingSlashes(requiredEnv(name));
+}
+
+/** An optional base URL from the environment, trailing slashes stripped. */
+export function optionalBaseUrl(name: string, fallback: string): string {
+  return stripTrailingSlashes(optionalEnv(name, fallback));
+}
+
+/** Builds the request headers. Called per request, so it reads env at call time. */
+export type HeaderFactory = () => Record<string, string>;
+
+/**
+ * `{ [header]: "<scheme> <token>", Accept: "application/json", ...extra }` where
+ * `token` is the trimmed value of `env`.
+ *
+ * `scheme` is the RFC 7235 auth scheme — `"Bearer"` for most, but the tree also
+ * contains `"Token"` (Readwise, dbt, Flagsmith) and lowercase `"token"` (Snyk),
+ * which are what those APIs actually accept and so are not normalised. Pass
+ * `scheme: ""` for the APIs that want the bare credential with no scheme
+ * (Bitrise, LaunchDarkly), and `header` for the ones that use their own header
+ * instead of `Authorization` (Codemagic, Dependency-Track, Metabase, Zotero).
+ */
+export function envAuthHeaders(cfg: {
+  readonly env: string;
+  readonly scheme?: string;
+  readonly header?: string;
+  readonly extra?: Record<string, string>;
+}): HeaderFactory {
+  const header = cfg.header ?? "Authorization";
+  const scheme = cfg.scheme ?? "Bearer";
+  return (): Record<string, string> => {
+    const token = requiredEnv(cfg.env);
+    return {
+      [header]: scheme === "" ? token : `${scheme} ${token}`,
+      Accept: "application/json",
+      ...cfg.extra,
+    };
+  };
+}
+
+/**
+ * The fetch the getter and the poster use. Defaults to the global `fetch`.
+ *
+ * A seam because the connectors that reach a self-hosted control plane (argocd,
+ * flux, mlflow) use `fetchWithTimeout` instead: a server that stops answering
+ * should fail the tool call, not hang it. A timeout was the whole reason they
+ * had carried hand-written copies of this getter.
+ */
+export type JsonFetch = (url: string, init: RequestInit) => Promise<Response>;
+
+export interface JsonApiConfig {
+  /**
+   * Base URL the path is appended to. A function when the base itself comes
+   * from the environment, so it is resolved per request rather than at import.
+   */
+  readonly base: string | (() => string);
+  /** Service name that prefixes a failure, e.g. `"Stripe 404: ..."`. */
+  readonly label: string;
+  readonly headers: HeaderFactory;
+  /** Body-snippet length in the error. Defaults to {@link DEFAULT_SNIPPET_MAX}. */
+  readonly snippetMax?: number;
+  /** Overrides the global `fetch` — see {@link JsonFetch}. */
+  readonly fetch?: JsonFetch;
+}
+
+/**
+ * One request against `config`, shared by the getter and the poster: resolve the
+ * base, send what `init` builds from the request headers, and return the body
+ * text — throwing `"<errorPrefix> <status>: <body snippet>"` on any non-2xx.
+ *
+ * The base is resolved BEFORE the headers are built, so a connector missing both
+ * its URL and its credential names the URL first, as every hand-written copy did.
+ */
+function sendFor(
+  config: JsonApiConfig,
+): (
+  path: string,
+  init: (headers: Record<string, string>) => RequestInit,
+  errorPrefix: string,
+) => Promise<string> {
+  const { base, headers } = config;
+  const snippetMax = config.snippetMax ?? DEFAULT_SNIPPET_MAX;
+  const doFetch = config.fetch ?? ((url, init) => fetch(url, init));
+  return async (path, init, errorPrefix) => {
+    const root = typeof base === "string" ? base : base();
+    const res = await doFetch(`${root}${path}`, init(headers()));
+    const text = await res.text();
+    if (!res.ok) {
+      throw new Error(`${errorPrefix} ${String(res.status)}: ${text.slice(0, snippetMax)}`);
+    }
+    return text;
+  };
+}
+
+/**
+ * A `(path) => Promise<unknown>` GET client for `config`. Resolves to the parsed
+ * JSON body, and throws `"<label> <status>: <body snippet>"` on any non-2xx.
+ *
+ * `path` is appended to the base as given — callers build it, and must
+ * `encodeURIComponent` any user-supplied segment, exactly as before.
+ */
+export function createJsonGetter(config: JsonApiConfig): (path: string) => Promise<unknown> {
+  const { label } = config;
+  const send = sendFor(config);
+  return async (path: string): Promise<unknown> =>
+    JSON.parse(await send(path, (headers) => ({ headers }), label)) as unknown;
+}
+
+/**
+ * The mutating twin of {@link createJsonGetter}: a `(path, body) => Promise<unknown>`
+ * POST client that sends `body` as JSON (adding `Content-Type: application/json` to
+ * the request headers) and resolves to the parsed response — `{}` when the response
+ * body is empty, as a mutation's often is.
+ *
+ * Throws `"<label> <path> <status>: <body snippet>"` on any non-2xx: unlike the
+ * getter's, the message names the path, so a failed mutation says which endpoint
+ * refused it. The argocd and mlflow write tools each carried a copy of this.
+ */
+export function createJsonPoster(
+  config: JsonApiConfig,
+): (path: string, body: unknown) => Promise<unknown> {
+  const { label } = config;
+  const send = sendFor(config);
+  return async (path: string, body: unknown): Promise<unknown> => {
+    const text = await send(
+      path,
+      (headers) => ({
+        method: "POST",
+        headers: { ...headers, "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      }),
+      `${label} ${path}`,
+    );
+    return text === "" ? {} : (JSON.parse(text) as unknown);
+  };
+}

package/shared/fetch-json-text.ts

@@ -0,0 +1,27 @@
+/**
+ * fetch-json-text — send a JSON API request and hand back the raw response text.
+ *
+ * `atlassian-json-fetch.ts` (jira, confluence) and notion built this request the same way around
+ * different credentials: their own headers first, `Content-Type: application/json` only when the
+ * request has a body, and any header the caller passes in `init` overriding all of them. A non-2xx
+ * is reported rather than thrown, because these APIs put the useful diagnostic in the error body.
+ */
+export async function fetchJsonText(
+  url: string,
+  baseHeaders: Readonly<Record<string, string>>,
+  init?: RequestInit,
+): Promise<{ ok: boolean; status: number; text: string }> {
+  const headers: Record<string, string> = { ...baseHeaders };
+  if (init?.body !== undefined) {
+    headers["Content-Type"] = "application/json";
+  }
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      ...headers,
+      ...(init?.headers as Record<string, string> | undefined),
+    },
+  });
+  const text = await res.text();
+  return { ok: res.ok, status: res.status, text };
+}

package/shared/github-rest.ts

@@ -0,0 +1,62 @@
+/**
+ * github-rest — the GitHub REST client the `github` and `github-actions`
+ * connectors share.
+ *
+ * Both talk to the same API with the same token and had each written out its
+ * base URL, its default headers, the fetch built from them and the
+ * `/repos/<owner>/<repo>` path. The pinned `X-GitHub-Api-Version` lived in three
+ * places, so a bump had to find all three.
+ */
+
+import { makeRestFetcher, type RestFetchResult } from "./rest-tool-kit.ts";
+
+export const GH_API = "https://api.github.com";
+
+/** The media type GitHub documents for its REST API. */
+export const GH_ACCEPT = "application/vnd.github+json";
+
+/** The REST API version both connectors are written against. */
+export const GH_API_VERSION = "2022-11-28";
+
+/** Sent with every request, beside the Bearer token. */
+export const GH_HEADERS: Record<string, string> = {
+  Accept: GH_ACCEPT,
+  "X-GitHub-Api-Version": GH_API_VERSION,
+};
+
+/** A Bearer-authenticated JSON request against {@link GH_API} (a relative path or a same-origin URL). */
+export function ghFetch(token: string, path: string, init?: RequestInit): Promise<RestFetchResult> {
+  return makeRestFetcher({ apiBase: GH_API, token, defaultHeaders: GH_HEADERS })(path, init);
+}
+
+/** `/repos/<owner>/<repo>`, both segments URI-encoded. */
+export function ghRepoPath(owner: string, repo: string): string {
+  return `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+}
+
+/** The paging arguments every GitHub list tool accepts. */
+export interface GhPaging {
+  readonly perPage?: number | undefined;
+  readonly page?: number | undefined;
+}
+
+/**
+ * GitHub's paging parameters, in the order every list tool sends them: `per_page` (30 when not
+ * given — GitHub's own default), then `page` only when one was given.
+ */
+export function setGhPaging(params: URLSearchParams, paging: GhPaging): void {
+  params.set("per_page", String(paging.perPage ?? 30));
+  if (paging.page !== undefined) {
+    params.set("page", String(paging.page));
+  }
+}
+
+/**
+ * `path` plus the query string `setQuery` builds, as the relative path {@link ghFetch} takes. The
+ * parameters keep the order `setQuery` sets them in.
+ */
+export function ghQueryPath(path: string, setQuery: (params: URLSearchParams) => void): string {
+  const u = new URL(`${GH_API}${path}`);
+  setQuery(u.searchParams);
+  return `${u.pathname}${u.search}`;
+}