forges 0.0.0 → 0.1.0

package/dist/testing/index.d.mts

@@ -0,0 +1,123 @@
+import { Et as ForgeKind, n as FetchLike } from "../fetch-D4pSRvvA.mjs";
+//#region src/testing/index.d.ts
+/** One recorded or hand-authored request and its response. */
+export interface Fixture {
+  /** `true` when the fixture was written from documentation, not recorded. */
+  handAuthored?: boolean;
+  /** GraphQL requests share one URL, so they are matched on `operationName` and, when recorded, `variables` too. */
+  request: {
+    method: string;
+    url: string;
+    /** The GraphQL operation name, for a GraphQL request. */
+    operationName?: string;
+    /** The GraphQL variables, for a GraphQL request. */
+    variables?: Record<string, unknown>;
+    /** The JSON or text the request sent, when recorded with `requestBodies`. Replay does not match on it. */
+    body?: unknown;
+  };
+  /** A JSON body, the text of a response that is not JSON, or the base64 of one that is not text. */
+  response: {
+    status: number;
+    headers?: Record<string, string>;
+    /** The response body: parsed JSON, the text of a response that is not JSON, or base64 when `encoding` is set. */
+    body?: unknown;
+    /** Set when `body` holds the base64 of a binary response. */
+    encoding?: "base64";
+  };
+}
+/** A request that `fixtureFetch()` received. */
+export interface FixtureCall {
+  method: string;
+  url: string;
+  body?: string;
+  /** The GraphQL operation name, for a GraphQL request. */
+  operationName?: string;
+  /** The GraphQL variables, for a GraphQL request. */
+  variables?: Record<string, unknown>;
+  /** The `Authorization` header that the request carried. */
+  authorization?: string;
+  /** All the request headers. */
+  headers: Headers;
+  /** The fixture that answered, or `undefined` where an override did. */
+  fixture?: Fixture;
+}
+/** Options for {@link fixtureFetch}. */
+export interface FixtureFetchOptions {
+  /**
+   * Serve the fixtures that share a request in the order they were recorded,
+   * repeating the last, instead of always serving the last. Use it to replay
+   * a recording that reads the same URL before and after a write.
+   */
+  sequential?: boolean;
+}
+/** A `fetch` that answers from fixtures, and records the calls it received. */
+export interface FixtureFetch {
+  /** The `fetch` to pass to a provider. */
+  fetch: FetchLike;
+  /** Every request made, in order, including ones no fixture matched. */
+  calls: FixtureCall[];
+}
+/**
+ * A `fetch` that serves `fixtures` and records every call. Requests match on
+ * method, URL (query order ignored), GraphQL `operationName` and, where the
+ * fixture has them, `variables`. `overrides`
+ * replace or add responses, keyed `METHOD url [operationName]`. An unmatched
+ * request throws.
+ * @param fixtures The recorded or hand-written requests and responses to serve.
+ * @param overrides Responses that replace or add to the fixtures.
+ * @param options How to serve fixtures that share a request.
+ * @example
+ * ```ts
+ * import { github } from 'forges'
+ * import { fixtureFetch, loadFixtures } from 'forges/testing'
+ *
+ * const { fetch, calls } = fixtureFetch(await loadFixtures(new URL('./fixtures', import.meta.url)))
+ * const provider = github({ fetch }).create()
+ * ```
+ */
+export declare function fixtureFetch(fixtures: Iterable<Fixture>, overrides?: Record<string, Fixture["response"]>, options?: FixtureFetchOptions): FixtureFetch;
+/** A `fetch` that forwards to the real one and records every exchange as a fixture. */
+export interface RecordingFetch {
+  /** The `fetch` to pass to a provider. */
+  fetch: FetchLike;
+  /** One fixture per response, in order; pass them to {@link fixtureFetch} to replay. */
+  fixtures: Fixture[];
+}
+/** Options for {@link recordingFetch}. */
+export interface RecordingFetchOptions {
+  /**
+   * Record the body of each request that sends a string, parsed as JSON where
+   * it is JSON. A request body can hold a secret (a password, a webhook
+   * secret), so redact it too.
+   */
+  requestBodies?: boolean;
+}
+/**
+ * Wraps `fetch` (the global one by default) and records every response as a
+ * {@link Fixture}. Request headers are never recorded, but URLs and response
+ * bodies are, and either can hold a secret (an installation token, a query
+ * token). Use `redact` to rewrite each fixture before it is kept. A body that
+ * is not UTF-8 text is kept as base64.
+ * @param fetch The `fetch` to record. Defaults to the global one.
+ * @param redact Rewrites each fixture before it is kept, to remove secrets.
+ * @param options What else to record.
+ */
+export declare function recordingFetch(fetch?: FetchLike, redact?: (fixture: Fixture) => Fixture, options?: RecordingFetchOptions): RecordingFetch;
+/**
+ * Reads every `*.json` fixture in `directory`, skipping `manifest.json` and
+ * files without a `request`. Node, Bun and Deno only.
+ * @param directory The directory that holds the fixture JSON files.
+ */
+export declare function loadFixtures(directory: string | URL): Promise<Fixture[]>;
+/**
+ * Builds the headers a forge would sign `body` with, merged over `headers`
+ * (the event name and delivery id, which only the caller knows). `secret` is
+ * the webhook secret, or for Cursor Origin the base64 PKCS#8 Ed25519 private
+ * key matching the provider's verification key.
+ * @param forge The forge whose signature scheme to use.
+ * @param body The raw body of the delivery.
+ * @param secret The secret that signs it.
+ * @param headers Headers to add to the signed headers.
+ */
+export declare function signDelivery(forge: ForgeKind, body: string, secret: string, headers?: Record<string, string>): Promise<Record<string, string>>;
+//#endregion

package/dist/testing/index.mjs

@@ -0,0 +1,242 @@
+import { a as sha256Hex, i as hmacSha256Hex, l as toBase64 } from "../crypto-CQNEyYHD.mjs";
+//#region src/testing/index.ts
+function fixtureKey(method, url, operationName, variables) {
+	const parsed = new URL(url);
+	parsed.searchParams.sort();
+	const base = `${method.toUpperCase()} ${parsed.origin}${parsed.pathname}${parsed.search}`;
+	const operation = operationName ? `${base} ${operationName}` : base;
+	return variables ? `${operation} ${JSON.stringify(variables, Object.keys(variables).sort())}` : operation;
+}
+function operationOf(url, body) {
+	if (!body || !url.endsWith("/graphql")) return {};
+	try {
+		const { operationName, variables } = JSON.parse(body);
+		return {
+			operationName,
+			variables
+		};
+	} catch {
+		return {};
+	}
+}
+function callOf(input, init) {
+	const body = typeof init?.body === "string" ? init.body : void 0;
+	const headers = new Headers(init?.headers);
+	return {
+		method: (init?.method ?? "GET").toUpperCase(),
+		url: input,
+		body,
+		...operationOf(input, body),
+		authorization: headers.get("authorization") ?? void 0,
+		headers
+	};
+}
+/**
+* A `fetch` that serves `fixtures` and records every call. Requests match on
+* method, URL (query order ignored), GraphQL `operationName` and, where the
+* fixture has them, `variables`. `overrides`
+* replace or add responses, keyed `METHOD url [operationName]`. An unmatched
+* request throws.
+* @param fixtures The recorded or hand-written requests and responses to serve.
+* @param overrides Responses that replace or add to the fixtures.
+* @param options How to serve fixtures that share a request.
+* @example
+* ```ts
+* import { github } from 'forges'
+* import { fixtureFetch, loadFixtures } from 'forges/testing'
+*
+* const { fetch, calls } = fixtureFetch(await loadFixtures(new URL('./fixtures', import.meta.url)))
+* const provider = github({ fetch }).create()
+* ```
+*/
+function fixtureFetch(fixtures, overrides = {}, options = {}) {
+	const responses = /* @__PURE__ */ new Map();
+	for (const fixture of fixtures) {
+		const key = fixtureKey(fixture.request.method, fixture.request.url, fixture.request.operationName, fixture.request.variables);
+		const queue = options.sequential ? responses.get(key) : void 0;
+		if (queue) queue.push({
+			response: fixture.response,
+			fixture
+		});
+		else responses.set(key, [{
+			response: fixture.response,
+			fixture
+		}]);
+	}
+	for (const [override, response] of Object.entries(overrides)) {
+		const [method = "GET", url = "", operationName] = override.split(" ");
+		responses.set(fixtureKey(method, url, operationName), [{ response }]);
+	}
+	const served = /* @__PURE__ */ new Map();
+	const take = (key) => {
+		const queue = responses.get(key);
+		if (!queue) return;
+		const index = served.get(key) ?? 0;
+		served.set(key, index + 1);
+		return queue[Math.min(index, queue.length - 1)];
+	};
+	const calls = [];
+	const fetch = async (input, init) => {
+		const call = callOf(input, init);
+		calls.push(call);
+		const match = take(fixtureKey(call.method, input, call.operationName, call.variables)) ?? take(fixtureKey(call.method, input, call.operationName));
+		if (!match) throw new Error(`No fixture for ${call.method} ${input}${call.operationName ? ` (${call.operationName})` : ""}`);
+		const { response } = match;
+		call.fixture = match.fixture;
+		const headers = new Headers(response.headers);
+		const binary = response.encoding === "base64" && typeof response.body === "string";
+		const body = response.body === void 0 ? null : binary ? Uint8Array.from(atob(response.body), (char) => char.charCodeAt(0)) : typeof response.body === "string" ? response.body : JSON.stringify(response.body);
+		if (body !== null && !headers.has("content-type")) headers.set("content-type", binary ? "application/octet-stream" : typeof response.body === "string" ? "text/plain" : "application/json");
+		const result = new Response(body, {
+			status: response.status,
+			headers
+		});
+		Object.defineProperty(result, "url", { value: input });
+		return result;
+	};
+	return {
+		fetch,
+		calls
+	};
+}
+const RECORDED_HEADERS = [
+	"link",
+	"etag",
+	"location",
+	"retry-after",
+	"x-ratelimit-limit",
+	"ratelimit-limit",
+	"x-ratelimit-remaining",
+	"x-ratelimit-reset",
+	"ratelimit-remaining",
+	"ratelimit-reset",
+	"x-total",
+	"x-total-count",
+	"x-total-pages",
+	"x-next-page",
+	"x-page",
+	"x-per-page",
+	"total_page",
+	"total_count"
+];
+/** Parsed JSON, or the text as is where it is not JSON or parsing would round an integer beyond `Number.MAX_SAFE_INTEGER`. */
+function parsed(text) {
+	try {
+		let lossy = false;
+		const value = JSON.parse(text, (_key, item) => {
+			lossy ||= typeof item === "number" && Number.isInteger(item) && !Number.isSafeInteger(item);
+			return item;
+		});
+		return lossy ? text : value;
+	} catch {
+		return text;
+	}
+}
+function utf8(bytes) {
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		return;
+	}
+}
+/**
+* Wraps `fetch` (the global one by default) and records every response as a
+* {@link Fixture}. Request headers are never recorded, but URLs and response
+* bodies are, and either can hold a secret (an installation token, a query
+* token). Use `redact` to rewrite each fixture before it is kept. A body that
+* is not UTF-8 text is kept as base64.
+* @param fetch The `fetch` to record. Defaults to the global one.
+* @param redact Rewrites each fixture before it is kept, to remove secrets.
+* @param options What else to record.
+*/
+function recordingFetch(fetch = globalThis.fetch, redact = (fixture) => fixture, options = {}) {
+	const fixtures = [];
+	const recording = async (input, init) => {
+		const call = callOf(input, init);
+		const sent = options.requestBodies && call.body !== void 0 ? parsed(call.body) : void 0;
+		const response = await fetch(input, init);
+		const bytes = new Uint8Array(await response.clone().arrayBuffer());
+		const text = utf8(bytes);
+		const body = text ? parsed(text) : void 0;
+		const headers = Object.fromEntries(RECORDED_HEADERS.flatMap((name) => response.headers.has(name) ? [[name, response.headers.get(name)]] : []));
+		fixtures.push(redact({
+			request: {
+				method: call.method,
+				url: input,
+				...call.operationName ? {
+					operationName: call.operationName,
+					variables: call.variables
+				} : {},
+				...sent === void 0 ? {} : { body: sent }
+			},
+			response: {
+				status: response.status,
+				headers,
+				...text === void 0 ? {
+					body: toBase64(bytes),
+					encoding: "base64"
+				} : body === void 0 ? {} : { body }
+			}
+		}));
+		return response;
+	};
+	return {
+		fetch: recording,
+		fixtures
+	};
+}
+/**
+* Reads every `*.json` fixture in `directory`, skipping `manifest.json` and
+* files without a `request`. Node, Bun and Deno only.
+* @param directory The directory that holds the fixture JSON files.
+*/
+async function loadFixtures(directory) {
+	const { readdir, readFile } = await import("node:fs/promises");
+	const base = typeof directory === "string" ? directory.replace(/\/?$/, "/") : new URL(directory.href.replace(/\/?$/, "/"));
+	const files = (await readdir(base)).filter((file) => file.endsWith(".json") && file !== "manifest.json").sort();
+	return (await Promise.all(files.map(async (file) => JSON.parse(await readFile(typeof base === "string" ? `${base}${file}` : new URL(file, base), "utf8"))))).filter((fixture) => fixture.request !== void 0);
+}
+async function signStandardWebhook(id, body, privateKeyBase64) {
+	const timestamp = String(Math.floor(Date.now() / 1e3));
+	const digest = await sha256Hex(`${id}.${timestamp}.${body}`);
+	const der = Uint8Array.from(atob(privateKeyBase64), (char) => char.charCodeAt(0));
+	const key = await crypto.subtle.importKey("pkcs8", der, { name: "Ed25519" }, false, ["sign"]);
+	const signature = new Uint8Array(await crypto.subtle.sign("Ed25519", key, new TextEncoder().encode(digest)));
+	return {
+		"webhook-id": id,
+		"webhook-timestamp": timestamp,
+		"webhook-signature": `v1ed,${toBase64(signature)}`
+	};
+}
+const SIGNERS = {
+	"github": async (body, secret) => ({ "x-hub-signature-256": `sha256=${await hmacSha256Hex(secret, body)}` }),
+	"gitlab": async (_body, secret) => ({ "x-gitlab-token": secret }),
+	"forgejo": async (body, secret) => ({ "x-forgejo-signature": await hmacSha256Hex(secret, body) }),
+	"gitea": async (body, secret) => ({ "x-gitea-signature": await hmacSha256Hex(secret, body) }),
+	"bitbucket": async (body, secret) => ({ "x-hub-signature": `sha256=${await hmacSha256Hex(secret, body)}` }),
+	"tangled": async (body, secret) => ({ "x-tangled-signature-256": `sha256=${await hmacSha256Hex(secret, body)}` }),
+	"gitee": async (_body, secret) => ({ "x-gitee-token": secret }),
+	"azure-devops": async (_body, secret) => ({ authorization: `Basic ${btoa(secret)}` }),
+	"cursor-origin": (body, secret) => signStandardWebhook(crypto.randomUUID(), body, secret),
+	"fake": async (body, secret) => ({ "x-fake-signature": await hmacSha256Hex(secret, body) })
+};
+/**
+* Builds the headers a forge would sign `body` with, merged over `headers`
+* (the event name and delivery id, which only the caller knows). `secret` is
+* the webhook secret, or for Cursor Origin the base64 PKCS#8 Ed25519 private
+* key matching the provider's verification key.
+* @param forge The forge whose signature scheme to use.
+* @param body The raw body of the delivery.
+* @param secret The secret that signs it.
+* @param headers Headers to add to the signed headers.
+*/
+async function signDelivery(forge, body, secret, headers = {}) {
+	const sign = SIGNERS[forge];
+	if (!sign) throw new Error(`No webhook signer for ${forge}`);
+	return {
+		...headers,
+		...await sign(body, secret)
+	};
+}
+//#endregion
+export { fixtureFetch, loadFixtures, recordingFetch, signDelivery };

package/dist/webhooks-rn9-8lxT.mjs

@@ -0,0 +1,70 @@
+import { c as timingSafeEqual, i as hmacSha256Hex, n as headerValue } from "./crypto-CQNEyYHD.mjs";
+//#region src/webhooks.ts
+/** The first of `names` the delivery carries a non-empty value for. */
+function firstHeader(delivery, names) {
+	for (const name of typeof names === "string" ? [names] : names) {
+		const value = headerValue(delivery.headers, name);
+		if (value) return value;
+	}
+}
+/**
+* Checks a hex HMAC-SHA256 of the raw body, sent in the first of `header`
+* present, after an optional `prefix` such as `sha256=`. The delivery's own
+* `secret` takes precedence over the provider's.
+*/
+async function verifyHmacSignature(delivery, secret, { header, prefix = "" }) {
+	const signature = firstHeader(delivery, header);
+	const key = delivery.secret ?? secret;
+	if (!key || !signature) return false;
+	return timingSafeEqual(signature.toLowerCase(), `${prefix}${await hmacSha256Hex(key, delivery.body)}`);
+}
+/** Checks a secret sent verbatim in `header`. */
+function verifySharedToken(delivery, secret, header) {
+	const token = headerValue(delivery.headers, header);
+	const key = delivery.secret ?? secret;
+	return Boolean(key && token && timingSafeEqual(token, key));
+}
+/** The kind, detail and summary of one ref update in a push: a deletion, a creation, or new commits. */
+function refEvent(who, change) {
+	const name = change.ref.replace(/^refs\/(?:heads|tags)\//, "");
+	const refType = change.refType ?? (change.ref.startsWith("refs/tags/") ? "tag" : "branch");
+	if (change.deleted || change.created) return {
+		kind: "ref",
+		action: change.deleted ? "deleted" : "created",
+		detail: {
+			type: "ref",
+			ref: change.ref,
+			refType
+		},
+		summary: `${who} ${change.deleted ? "deleted" : "created"} ${name}`
+	};
+	const commits = change.commits ?? [];
+	const count = change.commitCount ?? commits.length;
+	return {
+		kind: "push",
+		detail: {
+			type: "push",
+			ref: change.ref,
+			before: change.before,
+			after: change.after,
+			commitCount: count,
+			forced: change.forced ?? false,
+			commits
+		},
+		summary: `${who} pushed ${count} commit(s) to ${name}`
+	};
+}
+/** The forge's own event names for `events`, plus any `nativeEvents` passed through unchanged. */
+function nativeEventsFor(map, events, nativeEvents) {
+	const names = new Set(nativeEvents ?? []);
+	for (const kind of events ?? []) for (const name of map[kind] ?? []) names.add(name);
+	return [...names];
+}
+/** The normalised kinds a subscription to `nativeEvents` covers. */
+function eventKindsOf(map, nativeEvents) {
+	const kinds = /* @__PURE__ */ new Set();
+	for (const [kind, names] of Object.entries(map)) if (nativeEvents.includes("*") || names.some((name) => nativeEvents.includes(name))) kinds.add(kind);
+	return [...kinds];
+}
+//#endregion
+export { verifyHmacSignature as a, refEvent as i, firstHeader as n, verifySharedToken as o, nativeEventsFor as r, eventKindsOf as t };

package/package.json

@@ -1,8 +1,120 @@
 {
   "name": "forges",
-  "version": "0.0.0",
+  "type": "module",
+  "version": "0.1.0",
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": "24.21.0",
+      "onFail": "download"
+    },
+    "packageManager": {
+      "name": "pnpm",
+      "version": "12.11.2",
+      "onFail": "download"
+    }
+  },
+  "description": "One client, every forge: issues, pull requests, notifications, checks and webhooks",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danielroe/forges.git"
+  },
+  "keywords": [
+    "forge",
+    "git",
+    "github",
+    "gitlab",
+    "bitbucket",
+    "forgejo",
+    "codeberg",
+    "gitea",
+    "gitee",
+    "azure-devops",
+    "tangled",
+    "atproto",
+    "issues",
+    "pull-requests",
+    "notifications",
+    "webhooks"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./azure-devops": "./dist/azure-devops/index.mjs",
+    "./bitbucket": "./dist/bitbucket/index.mjs",
+    "./cursor-origin": "./dist/cursor-origin/index.mjs",
+    "./env": "./dist/env.mjs",
+    "./fake": "./dist/fake/index.mjs",
+    "./forgejo": "./dist/forgejo/index.mjs",
+    "./gitea": "./dist/gitea/index.mjs",
+    "./gitee": "./dist/gitee/index.mjs",
+    "./github": "./dist/github/index.mjs",
+    "./gitlab": "./dist/gitlab/index.mjs",
+    "./kit": "./dist/kit.mjs",
+    "./pushin": "./dist/pushin/index.mjs",
+    "./schema": "./dist/schema/index.mjs",
+    "./tangled": "./dist/tangled/index.mjs",
+    "./testing": "./dist/testing/index.mjs",
+    "./package.json": "./package.json",
+    "./schema/*.json": "./dist/schema/*.json"
+  },
+  "types": "./dist/index.d.mts",
   "files": [
     "dist"
   ],
-  "author": "Daniel Roe <daniel@roe.dev>"
-}
+  "engines": {
+    "node": ">=22.18"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "9.5.1",
+    "@arethetypeswrong/core": "0.18.5",
+    "@octokit/openapi-webhooks-types": "12.2.0",
+    "@octokit/rest": "22.0.1",
+    "@types/node": "24.19.2",
+    "@vitest/coverage-v8": "5.0.3",
+    "eslint": "10.12.0",
+    "installed-check": "11.0.0",
+    "knip": "6.39.0",
+    "nano-staged": "1.0.2",
+    "pkg-pr-new": "0.0.91",
+    "publint": "0.3.25",
+    "rolldown": "1.2.13",
+    "simple-git-hooks": "2.14.0",
+    "ts-json-schema-generator": "2.9.0",
+    "tsdown": "0.23.0",
+    "typescript": "6.0.3",
+    "vitest": "5.0.3"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm nano-staged"
+  },
+  "nano-staged": {
+    "*.{js,ts,mjs,cjs,vue,json,yml,yaml,md,.*rc}": [
+      "pnpm eslint --fix"
+    ]
+  },
+  "scripts": {
+    "build": "tsdown",
+    "build:docs": "pnpm --filter forges-docs build",
+    "check:all": "pnpm lint && pnpm test && pnpm test:versions && pnpm build && pnpm test:size",
+    "dev": "vitest dev",
+    "lint": "eslint --cache .",
+    "lint:fix": "eslint --cache --fix .",
+    "test": "pnpm test:unit && pnpm test:capabilities && pnpm test:types && pnpm test:knip",
+    "test:unit": "vitest run --project unit",
+    "test:docs": "vitest run --project docs",
+    "test:capabilities": "node scripts/check-capabilities.ts",
+    "test:knip": "knip",
+    "test:links": "lychee --config lychee.toml --remap \"https://github\\.com/danielroe/forges/(?:blob|tree)/main/(.*) file://$PWD/\\$1\" --include-fragments docs/.output/public README.md CONTRIBUTING.md CODE_OF_CONDUCT.md docs/README.md docs/content examples test/fixtures",
+    "test:versions": "installed-check -d --no-workspaces",
+    "test:types": "tsc --noEmit",
+    "dev:docs": "pnpm --filter forges-docs dev",
+    "dev:playground": "pnpm --filter playground dev",
+    "record-fixtures": "node --env-file-if-exists=.env scripts/record-fixtures.ts",
+    "capability-matrix": "node scripts/capability-matrix.ts",
+    "recorded-coverage": "node scripts/recorded-coverage.ts",
+    "docs:api": "node scripts/docs-api.ts",
+    "test:size": "node scripts/bundle-size.ts"
+  }
+}