hngr 0.1.0 → 0.2.0

package/dist/mcp-DeWHHgQK.mjs

@@ -0,0 +1,610 @@
+import { S as HngrError, b as writeFileAtomically, g as resolveConnection, s as redactSensitive, t as apiFetch } from "./http-2HWxLIOq.mjs";
+import { _ as resolveCapabilityVersion, a as failedResult, c as stringValues, f as downloadContent, g as resolveCapability, h as parseCapabilityPath, i as errorBody, l as AGENTS, n as readPublishFlags, o as positionalPaths, p as MCP_KIND, r as runPublish, s as runBatch, t as explicitName, u as findAgentDefinition } from "./publish-D7zaQl9x.mjs";
+import { constants } from "node:fs";
+import { access, readFile, stat } from "node:fs/promises";
+import { basename, delimiter, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { spawn } from "node:child_process";
+// src/mcp/claude-cli.ts
+const EXECUTABLE = "claude";
+function childEnvironment(env) {
+	const merged = {
+		...process.env,
+		...env
+	};
+	for (const [key, value] of Object.entries(merged)) if (value === void 0) delete merged[key];
+	return merged;
+}
+/** Finds an executable on the PATH from `env` (falling back to this process). */
+async function findExecutable(name, env) {
+	const searchPath = env.PATH ?? process.env.PATH ?? "";
+	for (const dir of searchPath.split(delimiter)) {
+		if (dir === "") continue;
+		const candidate = join(dir, name);
+		try {
+			if (!(await stat(candidate)).isFile()) continue;
+			await access(candidate, constants.X_OK);
+			return candidate;
+		} catch {}
+	}
+}
+function run(executable, args, env) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(executable, args, {
+			env: childEnvironment(env),
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout.on("data", (chunk) => {
+			stdout += chunk.toString("utf8");
+		});
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk.toString("utf8");
+		});
+		child.on("error", (err) => {
+			reject(new HngrError({
+				type: "io",
+				title: "Could not run the Claude Code CLI",
+				detail: err.message
+			}));
+		});
+		child.on("close", (code) => {
+			resolve({
+				code: code ?? -1,
+				stdout,
+				stderr
+			});
+		});
+	});
+}
+function commandFailed(command, label, result) {
+	return new HngrError({
+		type: "io",
+		title: `claude ${command} failed for ${JSON.stringify(label)}`,
+		detail: result.stderr.trim() || result.stdout.trim() || `claude exited with code ${result.code === -1 ? "unknown" : result.code}.`
+	});
+}
+async function runChecked(executable, args, env, label) {
+	const result = await run(executable, args, env);
+	if (result.code !== 0) throw commandFailed(args.slice(0, 2).join(" "), label, result);
+}
+/**
+* Whether Claude Code already has a server at user scope. `claude mcp get`
+* reports the winning scope for a name; anything other than "User config" is
+* indeterminate for user scope, so it fails rather than guessing.
+*/
+async function userServerState(executable, name, env) {
+	const result = await run(executable, [
+		"mcp",
+		"get",
+		name
+	], env);
+	const output = `${result.stdout}\n${result.stderr}`;
+	if (result.code !== 0) {
+		if (/No MCP server named/i.test(output)) return "absent";
+		throw commandFailed("mcp get", name, result);
+	}
+	if (/Scope:\s*User config/i.test(output)) return "present";
+	throw new HngrError({
+		type: "io",
+		title: `Could not determine whether ${JSON.stringify(name)} is installed at user scope`,
+		detail: `\`claude mcp get\` reported a non-user scope, so hngr will not overwrite it. Run \`claude mcp get ${name}\` to inspect it, or install at project scope (without --global).`
+	});
+}
+/**
+* Installs one user-scope server through Claude Code itself.
+* `~/.claude.json` is never edited directly: Claude Code owns that file and may
+* hold live session state. A conflicting user-scope server fails without
+* `force`; with `force` it is removed through the CLI before the new entry is
+* added, so every write still goes through Claude Code.
+*/
+async function addJsonWithClaude(env, name, config, force) {
+	const executable = await findExecutable(EXECUTABLE, env);
+	if (!executable) throw new HngrError({
+		type: "config",
+		title: "Claude Code CLI not found",
+		detail: "`claude` must be on PATH to install user-level MCP servers; install Claude Code or use project-level (no --global) installation."
+	});
+	if (await userServerState(executable, name, env) === "present") {
+		if (!force) throw new HngrError({
+			type: "io",
+			title: `MCP server ${JSON.stringify(name)} already exists in Claude Code's user config`,
+			detail: "Pass --force to replace it."
+		});
+		await runChecked(executable, [
+			"mcp",
+			"remove",
+			"--scope",
+			"user",
+			name
+		], env, name);
+	}
+	await runChecked(executable, [
+		"mcp",
+		"add-json",
+		"--scope",
+		"user",
+		name,
+		JSON.stringify(config)
+	], env, name);
+}
+// src/mcp/content.ts
+/** Server names Claude Code accepts as `mcpServers` keys. */
+const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+const EXPECTED_SHAPE = "Expected an object shaped {\"mcpServers\": {\"<server-name>\": {\"command\": \"...\", \"args\": [...]}}}.";
+function invalid(title, detail = EXPECTED_SHAPE) {
+	return new HngrError({
+		type: "api",
+		title,
+		detail
+	});
+}
+function isPlainObject$1(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* Validates the snapshot shape. `mcpServers` must be an object and every
+* server name must match `[A-Za-z0-9_-]+`; other top-level keys are ignored.
+*/
+function validateSnapshot(body) {
+	if (!isPlainObject$1(body)) throw invalid("The MCP snapshot is not a JSON object");
+	if (!("mcpServers" in body)) throw invalid("The MCP snapshot is missing \"mcpServers\"");
+	const servers = body.mcpServers;
+	if (!isPlainObject$1(servers)) throw invalid("The MCP snapshot's \"mcpServers\" is not an object");
+	for (const name of Object.keys(servers)) if (!SERVER_NAME_PATTERN.test(name)) throw invalid(`Invalid MCP server name ${JSON.stringify(name)}`, "Server names must match [A-Za-z0-9_-]+.");
+	return {
+		servers,
+		ignoredKeys: Object.keys(body).filter((key) => key !== "mcpServers")
+	};
+}
+/**
+* Downloads an MCP snapshot as `application/json` and validates its shape.
+*/
+async function downloadMcpSnapshot(connection, capabilityId, version, signal) {
+	const download = await downloadContent(connection, capabilityId, version, "application/json", signal);
+	let body;
+	try {
+		body = JSON.parse(download.bytes.toString("utf8"));
+	} catch (err) {
+		throw invalid("The MCP snapshot is not valid JSON", err instanceof Error ? err.message : String(err));
+	}
+	return {
+		...validateSnapshot(body),
+		etag: download.etag
+	};
+}
+// src/mcp/merge.ts
+function ioError(title, detail) {
+	return new HngrError({
+		type: "io",
+		title,
+		detail
+	});
+}
+/**
+* Parses an existing target document. A missing file is an empty document;
+* malformed JSON or a non-object root is an error rather than silent replacement.
+*/
+function readTargetDocument(raw, label) {
+	if (raw === void 0) return {};
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		throw ioError(`Could not parse ${label}`, err instanceof Error ? err.message : String(err));
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw ioError(`${label} is not a JSON object`, "The target file must contain a JSON object.");
+	return parsed;
+}
+/**
+* Merges the incoming servers into the document's `mcpServers`. Existing
+* servers and other top-level keys survive. A name collision fails unless
+* `force`, which replaces only the colliding entries.
+*/
+function mergeSnapshot(document, incoming, options) {
+	const existing = document.mcpServers;
+	if (existing !== void 0) {
+		if (existing === null || typeof existing !== "object" || Array.isArray(existing)) throw ioError(`"mcpServers" in ${options.label} is not an object`, "Fix the target file before installing MCP servers.");
+	}
+	const servers = { ...existing ?? {} };
+	const conflicts = [];
+	const added = [];
+	const replaced = [];
+	for (const [name, entry] of Object.entries(incoming)) if (Object.hasOwn(servers, name)) {
+		if (!options.force) {
+			conflicts.push(name);
+			continue;
+		}
+		servers[name] = entry;
+		replaced.push(name);
+	} else {
+		servers[name] = entry;
+		added.push(name);
+	}
+	if (conflicts.length > 0) throw ioError(`MCP ${conflicts.length === 1 ? "server" : "servers"} already configured in ${options.label}: ${conflicts.join(", ")}`, "Pass --force to replace only the conflicting entries.");
+	return {
+		document: {
+			...document,
+			mcpServers: servers
+		},
+		added,
+		replaced
+	};
+}
+/** Two-space indentation plus a trailing newline. */
+function serializeTargetDocument(document) {
+	return `${JSON.stringify(document, null, 2)}\n`;
+}
+// src/mcp/resolve.ts
+/** Parses `<name>` or `<namespace>/<name>`, with an optional `@YYYY.MM.DD.N`. */
+function parseMcpPath(raw) {
+	return parseCapabilityPath(raw, MCP_KIND);
+}
+function resolveMcp(connection, parsed, signal) {
+	return resolveCapability(connection, parsed, MCP_KIND, signal);
+}
+/** The pinned version, or the capability's Current Version. */
+function resolveMcpVersion(capability, parsed) {
+	return resolveCapabilityVersion(capability, parsed, MCP_KIND);
+}
+// src/mcp/targets.ts
+/** Ids accepted by `--agent`: agents with a JSON or Claude Code CLI adapter. */
+const MCP_AGENT_IDS = AGENTS.filter((agent) => agent.mcp.kind === "json" || agent.mcp.kind === "claude-cli").map((agent) => agent.id);
+function usage$1(title, detail) {
+	return new HngrError({
+		type: "usage",
+		title,
+		detail
+	});
+}
+function displayPath(path, cwd) {
+	const rel = relative(cwd, path);
+	if (rel !== "" && !rel.startsWith("..") && !isAbsolute(rel)) return rel.split(sep).join("/");
+	return path;
+}
+/** The reason an agent's MCP format is unsupported, or undefined. */
+function unsupportedReason(agent) {
+	const support = findAgentDefinition(agent)?.mcp;
+	return support?.kind === "unsupported" ? support.reason : void 0;
+}
+/** The adapter for one agent at one scope, or null when none exists. */
+function adapterFor(agent, scope, cwd, env) {
+	const support = findAgentDefinition(agent)?.mcp;
+	if (!support) return null;
+	if (support.kind === "claude-cli") {
+		if (scope === "project") {
+			const filePath = join(cwd, ".mcp.json");
+			return {
+				agent,
+				kind: "json",
+				path: displayPath(filePath, cwd),
+				filePath
+			};
+		}
+		return {
+			agent,
+			kind: "claude-cli",
+			path: support.configPath(env),
+			filePath: null
+		};
+	}
+	if (support.kind !== "json") return null;
+	if (scope === "project") {
+		if (support.project === null) return null;
+		const filePath = join(cwd, support.project);
+		return {
+			agent,
+			kind: "json",
+			path: displayPath(filePath, cwd),
+			filePath
+		};
+	}
+	if (support.global === null) return null;
+	const filePath = support.global(env);
+	return {
+		agent,
+		kind: "json",
+		path: filePath,
+		filePath
+	};
+}
+function unimplemented(agent, scope) {
+	if (agent === "devin" && scope === "project") return usage$1("Devin does not support project-level MCP configuration", "Devin's project-level MCP config is not documented; only the user-level ~/.config/devin/mcp_config.json is supported. Use --global.");
+	return usage$1(`MCP installation for ${agent} is not supported`, `Supported MCP targets: ${MCP_AGENT_IDS.join(", ")}.`);
+}
+function unsupportedFormatError(agents) {
+	const reasons = agents.map((agent) => `${agent}: ${unsupportedReason(agent) ?? ""}`);
+	return usage$1(`MCP installation for ${agents.join(", ")} is not supported`, `${reasons.join(" ")} Supported MCP targets: ${MCP_AGENT_IDS.join(", ")}.`);
+}
+/**
+* Resolves `--agent` / `--all` into concrete targets. `--all` selects every
+* agent that has an adapter for the requested scope, so project scope skips
+* Devin. Unknown ids, known formats with another shape, and documented-but-
+* unsupported scopes are usage errors and nothing is written.
+*/
+function selectMcpTargets(requested, all, scope, cwd, env) {
+	if (requested.length > 0) {
+		const unsupported = [...new Set(requested)].filter((id) => unsupportedReason(id) !== void 0);
+		if (unsupported.length > 0) throw unsupportedFormatError(unsupported);
+		const known = new Set(MCP_AGENT_IDS);
+		const unknown = requested.filter((id) => !known.has(id));
+		if (unknown.length > 0) throw usage$1(`Unknown agent target: ${unknown.join(", ")}`, `Known targets: ${MCP_AGENT_IDS.join(", ")}.`);
+		return [...new Set(requested)].map((id) => {
+			const adapter = adapterFor(id, scope, cwd, env);
+			if (!adapter) throw unimplemented(id, scope);
+			return adapter;
+		});
+	}
+	if (all) {
+		const plans = [];
+		for (const id of MCP_AGENT_IDS) {
+			const adapter = adapterFor(id, scope, cwd, env);
+			if (adapter) plans.push(adapter);
+		}
+		if (plans.length === 0) throw usage$1("No MCP target is available for this scope");
+		return plans;
+	}
+	throw usage$1("No agent target selected", "Pass --agent <id> (repeatable) or --all. For example: hngr mcp add pdf --agent claude-code");
+}
+// src/commands/mcp.ts
+function usage(title, detail) {
+	return new HngrError({
+		type: "usage",
+		title,
+		detail
+	});
+}
+function failureResult(parsed, err, version) {
+	return {
+		servers: [],
+		...failedResult(parsed, err, version)
+	};
+}
+async function readExisting(path, label) {
+	try {
+		return await readFile(path, "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") return;
+		throw new HngrError({
+			type: "io",
+			title: `Could not read ${label}`,
+			detail: err instanceof Error ? err.message : String(err)
+		});
+	}
+}
+/**
+* Dry-run output goes to stderr, so credentials inside server entries are
+* redacted. The file is never written by dry-run, so this only affects the
+* preview.
+*/
+function previewJsonTarget(plan, existing, servers, force) {
+	const merged = mergeSnapshot(readTargetDocument(existing, plan.path), servers, {
+		force,
+		label: plan.path
+	});
+	return serializeTargetDocument(redactSensitive(merged.document));
+}
+/** Reports one target's failure without aborting the remaining targets. */
+function reportTargetFailure(ctx, plan, err) {
+	const body = errorBody(err);
+	ctx.summary(`error: ${plan.agent} ${plan.path}: ${body.title}`);
+}
+async function installJsonTarget(plan, servers, force) {
+	const filePath = plan.filePath;
+	if (!filePath) throw new HngrError({
+		type: "io",
+		title: `No file path configured for ${plan.agent}`
+	});
+	const merged = mergeSnapshot(readTargetDocument(await readExisting(filePath, plan.path), plan.path), servers, {
+		force,
+		label: plan.path
+	});
+	await writeFileAtomically(filePath, serializeTargetDocument(merged.document), { label: plan.path });
+}
+async function addOne(ctx, connection, parsed, targets, state) {
+	const capability = await resolveMcp(connection, parsed);
+	const version = resolveMcpVersion(capability, parsed);
+	state.version = version;
+	const snapshot = await downloadMcpSnapshot(connection, capability.id, version);
+	if (snapshot.ignoredKeys.length > 0) ctx.summary(`warning: ignoring unsupported top-level keys in the MCP snapshot: ${snapshot.ignoredKeys.join(", ")}`);
+	const serverNames = Object.keys(snapshot.servers);
+	const etag = snapshot.etag ? ` (ETag ${snapshot.etag})` : "";
+	ctx.summary(`resolved ${parsed.namespace}/${parsed.name} to version ${version}${etag}`);
+	if (ctx.flags.dryRun) {
+		const dryTargets = [];
+		let failure = null;
+		for (const plan of targets) try {
+			if (plan.kind === "json") {
+				const preview = previewJsonTarget(plan, plan.filePath ? await readExisting(plan.filePath, plan.path) : void 0, snapshot.servers, ctx.flags.force);
+				ctx.detail(`dry-run: would write ${plan.path}\n${preview}`);
+			} else for (const [name, entry] of Object.entries(snapshot.servers)) ctx.detail(`dry-run: claude mcp add-json --scope user ${name} ${JSON.stringify(redactSensitive(entry))}`);
+			dryTargets.push({
+				agent: plan.agent,
+				path: plan.path,
+				status: "dry-run"
+			});
+		} catch (err) {
+			failure ??= err;
+			dryTargets.push({
+				agent: plan.agent,
+				path: plan.path,
+				status: "failed"
+			});
+			reportTargetFailure(ctx, plan, err);
+		}
+		return {
+			name: capability.name,
+			namespace: capability.namespace,
+			version,
+			status: failure ? "failed" : "dry-run",
+			servers: serverNames,
+			targets: dryTargets,
+			error: failure ? errorBody(failure) : null
+		};
+	}
+	const installedTargets = [];
+	let failure = null;
+	for (const plan of targets) try {
+		if (plan.kind === "json") await installJsonTarget(plan, snapshot.servers, ctx.flags.force);
+		else for (const [name, entry] of Object.entries(snapshot.servers)) await addJsonWithClaude(ctx.env, name, entry, ctx.flags.force);
+		installedTargets.push({
+			agent: plan.agent,
+			path: plan.path,
+			status: "installed"
+		});
+	} catch (err) {
+		failure ??= err;
+		installedTargets.push({
+			agent: plan.agent,
+			path: plan.path,
+			status: "failed"
+		});
+		reportTargetFailure(ctx, plan, err);
+	}
+	const verb = failure ? "partially installed" : "installed";
+	ctx.progress(`${verb} ${capability.namespace}/${capability.name}@${version} (${serverNames.join(", ")})`);
+	for (const target of installedTargets) ctx.progress(target.status === "failed" ? `  failed ${target.agent} ${target.path}` : `  ${target.agent} ${target.path}`);
+	return {
+		name: capability.name,
+		namespace: capability.namespace,
+		version,
+		status: failure ? "failed" : "installed",
+		servers: serverNames,
+		targets: installedTargets,
+		error: failure ? errorBody(failure) : null
+	};
+}
+const CAPABILITIES_PATH = "/api/v1/capabilities";
+const SNAPSHOT_SHAPE = "Expected an object shaped {\"mcpServers\": {\"<server-name>\": {\"command\": \"...\", \"args\": [...]}}}.";
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Reads and shape-checks a local snapshot; the whole object becomes `config`. */
+async function readSnapshot(file) {
+	let raw;
+	try {
+		raw = await readFile(resolve(file), "utf8");
+	} catch (err) {
+		throw new HngrError({
+			type: "io",
+			title: `Could not read ${file}`,
+			detail: err instanceof Error ? err.message : String(err)
+		});
+	}
+	let body;
+	try {
+		body = JSON.parse(raw);
+	} catch (err) {
+		throw usage("The MCP snapshot is not valid JSON", err instanceof Error ? err.message : String(err));
+	}
+	if (!isPlainObject(body)) throw usage("The MCP snapshot is not a JSON object", SNAPSHOT_SHAPE);
+	if (!("mcpServers" in body)) throw usage("The MCP snapshot is missing \"mcpServers\"", SNAPSHOT_SHAPE);
+	if (!isPlainObject(body.mcpServers)) throw usage("The MCP snapshot's \"mcpServers\" is not an object", SNAPSHOT_SHAPE);
+	return body;
+}
+/** The MCP server that `mcp publish` sends as the JSON `config` field. */
+function mcpPrepared(config, metadata) {
+	const serverCount = Object.keys(config.mcpServers).length;
+	const createBody = () => {
+		const body = {
+			namespace: metadata.namespace,
+			name: metadata.name,
+			description: metadata.description ?? "",
+			visibility: metadata.visibility
+		};
+		if (metadata.readme !== void 0) body.readme = metadata.readme;
+		if (metadata.tags.length > 0) body.tags = metadata.tags;
+		body.config = config;
+		return body;
+	};
+	const versionBody = () => {
+		const body = {};
+		if (metadata.readme !== void 0) body.readme = metadata.readme;
+		body.config = config;
+		return body;
+	};
+	return {
+		preview() {
+			const preview = {
+				namespace: metadata.namespace,
+				name: metadata.name
+			};
+			if (metadata.description !== void 0) preview.description = metadata.description;
+			preview.visibility = metadata.visibility;
+			if (metadata.readme !== void 0) preview.readme = metadata.readme;
+			if (metadata.tags.length > 0) preview.tags = metadata.tags;
+			preview.config = `<${serverCount} server${serverCount === 1 ? "" : "s"}>`;
+			return preview;
+		},
+		async create(connection) {
+			return (await apiFetch(connection, {
+				method: "POST",
+				path: CAPABILITIES_PATH,
+				body: createBody()
+			})).json();
+		},
+		async version(connection, capabilityId) {
+			const path = `${CAPABILITIES_PATH}/${encodeURIComponent(capabilityId)}/versions`;
+			return (await apiFetch(connection, {
+				method: "POST",
+				path,
+				body: versionBody()
+			})).json();
+		}
+	};
+}
+function defaultMcpName(file) {
+	const base = basename(resolve(file));
+	return base.toLowerCase().endsWith(".json") ? base.slice(0, -5) : base;
+}
+/**
+* Publishes MCP snapshots. A file that is not valid JSON, or lacks an
+* `mcpServers` object, fails before the capability lookup; an existing
+* capability receives a new version unless --new is set.
+*/
+async function publish(ctx, argv) {
+	const rawPaths = positionalPaths(argv.paths);
+	if (rawPaths.length === 0) throw usage("No MCP snapshot given", "Pass one or more JSON snapshot files.");
+	const flags = await readPublishFlags(argv, "mcp");
+	const forcedName = explicitName(argv, rawPaths.length);
+	const items = rawPaths.map((file) => ({
+		name: forcedName ?? defaultMcpName(file),
+		prepare: async (metadata) => mcpPrepared(await readSnapshot(file), metadata)
+	}));
+	return runPublish({
+		ctx,
+		kind: "mcp",
+		info: MCP_KIND,
+		...flags,
+		items
+	});
+}
+async function add(ctx, argv) {
+	const rawPaths = positionalPaths(argv.paths);
+	if (rawPaths.length === 0) throw usage("No capability path given", "Pass one or more `<name>` or `<namespace>/<name>` arguments.");
+	const parsedPaths = rawPaths.map(parseMcpPath);
+	const scope = argv.global === true ? "global" : "project";
+	const targets = selectMcpTargets(stringValues(argv.agent), argv.all === true, scope, process.cwd(), ctx.env);
+	const connection = await resolveConnection(ctx.flags, ctx.env);
+	let approvalHintShown = false;
+	const { results, failed } = await runBatch({
+		ctx,
+		paths: parsedPaths,
+		run: (parsed, state) => addOne(ctx, connection, parsed, targets, state),
+		failure: failureResult,
+		onResult: (result) => {
+			if (approvalHintShown) return;
+			if (result.targets.some((target) => target.agent === "claude-code" && target.status === "installed") && scope === "project") {
+				ctx.summary("note: Claude Code will ask you to approve these MCP servers on first interactive use.");
+				approvalHintShown = true;
+			}
+		}
+	});
+	ctx.writePayload({ results });
+	return failed ? 1 : 0;
+}
+export { add, publish };

package/dist/pagination-BbKLKSw3.mjs

@@ -0,0 +1,32 @@
+import { S as HngrError } from "./http-2HWxLIOq.mjs";
+// src/pagination.ts
+function asCursorPage(body, path) {
+	if (body === null || typeof body !== "object" || !Array.isArray(body.items) || !("next_cursor" in body)) throw new HngrError({
+		type: "api",
+		title: "The server returned an unexpected response shape",
+		detail: `Expected {items: [...], next_cursor: ...} from GET ${path}.`
+	});
+	return body;
+}
+/**
+* Reads a cursor-paginated collection to the end and returns every item in
+* server order. `fetchPage` receives the cursor to send (`undefined` for the
+* first page); a server that repeats a cursor would loop forever, so it is an
+* error instead.
+*/
+async function collectPages(path, fetchPage) {
+	const items = [];
+	let cursor;
+	for (;;) {
+		const page = asCursorPage(await fetchPage(cursor), path);
+		items.push(...page.items);
+		if (page.next_cursor === null) return items;
+		if (page.next_cursor === cursor) throw new HngrError({
+			type: "api",
+			title: "Pagination did not advance",
+			detail: `GET ${path} returned the same next_cursor twice.`
+		});
+		cursor = page.next_cursor;
+	}
+}
+export { collectPages as t };