npm - @lanes-sh/link - Versions diffs - 0.2.1 → 0.3.0 - Mend

@lanes-sh/link 0.2.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (139) hide show

package/README.md +21 -8
package/instructions/skills/lanes-link/SKILL.md +59 -14
package/package.json +1 -1
package/src/auth/index.ts +3 -1
package/src/auth/oauth/metadata.ts +83 -9
package/src/auth/oauth/redirects.ts +70 -0
package/src/auth/oauth/server.ts +49 -69
package/src/auth/oauth/store.ts +19 -5
package/src/cli/argv.ts +50 -0
package/src/cli/brand.ts +178 -0
package/src/cli/callback-page.ts +108 -128
package/src/cli/commands/connect/accounts.ts +5 -0
package/src/cli/commands/connect/assertion.ts +187 -0
package/src/cli/commands/connect/authorise.ts +61 -17
package/src/cli/commands/connect/client.ts +37 -9
package/src/cli/commands/connect/discover.ts +94 -0
package/src/cli/commands/connect/family.ts +72 -0
package/src/cli/commands/connect/index.ts +113 -115
package/src/cli/commands/connect/method.ts +237 -0
package/src/cli/commands/connect/outcome.ts +42 -1
package/src/cli/commands/connect/pasted-token.ts +66 -0
package/src/cli/commands/connect/requirements.ts +60 -8
package/src/cli/commands/connect/setup.ts +16 -5
package/src/cli/commands/connect/target-note.ts +34 -0
package/src/cli/commands/identity.ts +258 -0
package/src/cli/commands/knowledge/index.ts +390 -0
package/src/cli/commands/knowledge/migrate.ts +180 -0
package/src/cli/commands/knowledge/setup.ts +144 -0
package/src/cli/commands/knowledge.ts +10 -0
package/src/cli/commands/mcp/harnesses.ts +16 -2
package/src/cli/commands/mcp/register.ts +9 -1
package/src/cli/commands/mcp/stdio.ts +21 -0
package/src/cli/commands/operate/dashboard.ts +107 -0
package/src/cli/commands/operate/findings.ts +151 -0
package/src/cli/commands/operate/inspect.ts +56 -158
package/src/cli/commands/operate/outputs.ts +38 -11
package/src/cli/commands/operate/serve.ts +3 -0
package/src/cli/commands/operate/token.ts +1 -1
package/src/cli/commands/operate.ts +2 -0
package/src/cli/commands/profile/declare.ts +154 -0
package/src/cli/commands/profile/removal.ts +17 -0
package/src/cli/commands/profile.ts +83 -35
package/src/cli/commands/setup.ts +22 -6
package/src/cli/commands/target.ts +65 -83
package/src/cli/config-edit.ts +48 -144
package/src/cli/config-repair.ts +186 -0
package/src/cli/dashboard-page.ts +284 -0
package/src/cli/dashboard-shell.ts +125 -0
package/src/cli/identity.ts +12 -1
package/src/cli/main.ts +68 -4
package/src/cli/oauth-callback.ts +187 -0
package/src/cli/oauth-exchange.ts +57 -15
package/src/cli/oauth.ts +67 -177
package/src/cli/output.ts +21 -5
package/src/cli/provider-marks.ts +45 -0
package/src/cli/runtime/open.ts +67 -49
package/src/cli/runtime/registry.ts +60 -2
package/src/cli/runtime/select.ts +26 -13
package/src/cli/runtime/vault.ts +61 -0
package/src/cli/runtime.ts +2 -1
package/src/cli/selection.ts +357 -0
package/src/cli/usage.ts +32 -9
package/src/connectivity/auth/README.md +7 -1
package/src/connectivity/auth/basic/index.ts +1 -1
package/src/connectivity/auth/index.ts +14 -0
package/src/connectivity/auth/oauth-authcode/broker.ts +26 -0
package/src/connectivity/auth/oauth-authcode/index.ts +16 -2
package/src/connectivity/auth/oauth-authcode/provider.ts +1 -1
package/src/connectivity/auth/oauth-authcode/refresh.ts +3 -3
package/src/connectivity/auth/oauth-jwt/README.md +33 -0
package/src/connectivity/auth/oauth-jwt/index.ts +237 -0
package/src/connectivity/auth/oauth-jwt/key.ts +148 -0
package/src/connectivity/auth/resolve.ts +1 -1
package/src/connectivity/auth/token.ts +11 -0
package/src/connectivity/index.ts +2 -0
package/src/connectivity/manifest/auth.ts +99 -2
package/src/connectivity/manifest/identity.ts +12 -0
package/src/connectivity/manifest/index.ts +3 -1
package/src/connectivity/manifest/provider.ts +37 -8
package/src/connectivity/manifest/requirements.ts +109 -6
package/src/deployments/adapters/filesystem.ts +10 -1
package/src/deployments/adapters/github-api.ts +106 -0
package/src/deployments/adapters/github-commit.ts +103 -0
package/src/deployments/adapters/github-repo.ts +356 -0
package/src/deployments/adapters/github-testing.ts +258 -0
package/src/deployments/adapters/github.ts +125 -0
package/src/deployments/deploy.ts +48 -19
package/src/deployments/driver.ts +8 -1
package/src/deployments/gcp/driver.ts +9 -1
package/src/deployments/gcp/survey.ts +3 -0
package/src/deployments/knowledge.ts +119 -0
package/src/deployments/prepare.ts +2 -2
package/src/deployments/servable.ts +81 -0
package/src/deployments/target.ts +3 -2
package/src/deployments/upload.ts +2 -1
package/src/dispatch/dispatch.ts +1 -1
package/src/profile/authorization.ts +13 -4
package/src/profile/identity.ts +60 -0
package/src/profile/index.ts +15 -5
package/src/profile/knowledge.ts +124 -0
package/src/profile/load.ts +17 -5
package/src/profile/primitives.ts +24 -1
package/src/profile/schema.ts +72 -4
package/src/profile/targets.ts +74 -114
package/src/profile/workspace.ts +71 -84
package/src/providers/google/calendar/index.ts +2 -0
package/src/providers/google/contacts/index.ts +2 -0
package/src/providers/google/docs/index.ts +2 -0
package/src/providers/google/drive/index.ts +2 -0
package/src/providers/google/gmail/index.ts +2 -0
package/src/providers/google/gmail-imap/index.ts +125 -0
package/src/providers/google/index.ts +2 -1
package/src/providers/google/shared/oauth.ts +18 -6
package/src/providers/google/shared/service-account.ts +110 -0
package/src/providers/google/shared/setup.ts +5 -2
package/src/providers/google/sheets/index.ts +2 -0
package/src/providers/google/tasks/index.ts +2 -0
package/src/providers/identity/provider.ts +166 -0
package/src/providers/index.ts +3 -0
package/src/providers/owner.ts +10 -2
package/src/providers/scopes.ts +2 -0
package/src/providers/setup/plan.ts +31 -9
package/src/providers/setup/provider.ts +23 -0
package/src/providers/slack/index.ts +81 -33
package/src/providers/slack/oauth.ts +103 -0
package/src/providers/slack/scopes.ts +37 -0
package/src/server/container.ts +18 -1
package/src/server/cors.ts +252 -0
package/src/server/dashboard.ts +208 -0
package/src/server/endpoint.ts +57 -4
package/src/server/generation.ts +1 -0
package/src/server/generations.ts +13 -2
package/src/server/harness.ts +20 -3
package/src/server/index.ts +76 -12
package/src/server/mcp/build.ts +1 -1
package/src/server/mcp/index.ts +1 -0
package/src/server/mcp/instructions.ts +62 -5
package/src/server/mcp/visibility.ts +42 -0
package/src/stores/blobs/route.ts +123 -0

package/src/deployments/adapters/github-repo.ts ADDED Viewed

@@ -0,0 +1,356 @@
+import {
+  API,
+  GithubApiError,
+  base64,
+  encodePath,
+  failure,
+  githubHeaders,
+  type FetchLike,
+} from './github-api.ts';
+/**
+ * A GitHub repository, as something a `BlobStore` can be built on.
+ *
+ * This file knows GitHub — how a branch is read conditionally, what a tree
+ * looks like, how a write is a commit. `github.ts` knows `BlobStore`, and
+ * reaches all of it through here.
+ *
+ * **One of these per target, shared by every store built on it.** Memory and
+ * skills are two roots in one repository, so they share a head, a tree, and a
+ * blob cache — which means the endpoint's two-second skill poll also keeps
+ * memory's view current, at no additional cost. Two clients would each poll,
+ * each cache, and could disagree about which commit is current.
+ */
+/**
+ * How long a validated head is trusted before the next read re-checks it.
+ *
+ * Not a cache of content: blobs are content-addressed and a sha never means
+ * different bytes, so those are held for the life of the process without a
+ * freshness question. This bounds one thing only — how long we go on believing
+ * the branch still points where it did.
+ *
+ * Two seconds because that is already the staleness this system accepts.
+ * `Generation.SKILL_POLL_MS` is 2,000ms, so a skill added elsewhere is invisible
+ * to a running endpoint for up to two seconds wherever it is stored. Matching it
+ * means a repository is no staler than the filesystem was.
+ *
+ * The check is a conditional request and GitHub answers 304, which **does not
+ * count against the rate limit** — so what this bounds is round trips, not
+ * quota. Zero validates on every read.
+ */
+const DEFAULT_FRESHNESS_MS = 2_000;
+export interface GithubRepositoryOptions {
+  /** `owner/name`. */
+  readonly repo: string;
+  readonly token: string;
+  /** Defaults to the repository's own default branch, resolved on first use. */
+  readonly branch?: string | undefined;
+  readonly fetch?: FetchLike | undefined;
+  readonly now?: (() => number) | undefined;
+  readonly freshnessMs?: number | undefined;
+}
+/** One file in the tree, as a listing needs it. */
+export interface RepositoryEntry {
+  readonly path: string;
+  readonly sha: string;
+  readonly size: number;
+}
+/** What a repository looks like to somebody deciding whether to store here. */
+export interface RepositoryFacts {
+  readonly fullName: string;
+  readonly private: boolean;
+  readonly defaultBranch: string;
+  readonly canPush: boolean;
+  readonly empty: boolean;
+}
+export interface Head {
+  readonly commit: string;
+  readonly committedAt: Date;
+}
+export class GithubRepository {
+  readonly repo: string;
+  readonly #token: string;
+  readonly #fetch: FetchLike;
+  readonly #now: () => number;
+  readonly #freshnessMs: number;
+  #branch: string | undefined;
+  /** The branch tip, plus what GitHub gave us to re-ask about it cheaply. */
+  #head: Head | null = null;
+  #headEtag: string | undefined;
+  #headCheckedAt = 0;
+  #inFlight: Promise<Head | null> | undefined;
+  /** Keyed by the commit sha it was read at, so a stale one is never used. */
+  #tree: { commit: string; entries: Map<string, RepositoryEntry> } | undefined;
+  /** Content-addressed, so this needs no expiry. */
+  readonly #blobs = new Map<string, Uint8Array>();
+  constructor(options: GithubRepositoryOptions) {
+    this.repo = options.repo;
+    this.#token = options.token;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#now = options.now ?? Date.now;
+    this.#freshnessMs = options.freshnessMs ?? DEFAULT_FRESHNESS_MS;
+    this.#branch = options.branch;
+  }
+  request(path: string, init: RequestInit = {}): Promise<Response> {
+    return this.#fetch(`${API}${path}`, { ...init, headers: githubHeaders(this.#token, init) });
+  }
+  async json<T>(path: string, init: RequestInit = {}, what = path): Promise<T> {
+    const response = await this.request(path, init);
+    if (!response.ok) throw await failure(what, response);
+    return (await response.json()) as T;
+  }
+  /** The account the token belongs to. */
+  async viewer(): Promise<string> {
+    return (await this.json<{ login: string }>('/user', {}, 'identify the token')).login;
+  }
+  /** What this token can see and do here — the probe `knowledge use` runs. */
+  async facts(): Promise<RepositoryFacts> {
+    const repository = await this.#repository();
+    this.#branch ??= repository.default_branch;
+    return {
+      fullName: repository.full_name,
+      private: repository.private,
+      defaultBranch: repository.default_branch,
+      canPush: repository.permissions?.push === true,
+      empty: (await this.head(true)) === null,
+    };
+  }
+  async branch(): Promise<string> {
+    this.#branch ??= (await this.#repository()).default_branch;
+    return this.#branch;
+  }
+  #repository(): Promise<{
+    full_name: string;
+    private: boolean;
+    default_branch: string;
+    permissions?: { push?: boolean };
+  }> {
+    return this.json(`/repos/${this.repo}`, {}, `read ${this.repo}`);
+  }
+  /**
+   * The branch tip, or null when the branch has no commits yet.
+   *
+   * Null is an ordinary answer rather than an error: a repository created for
+   * this and not yet written to has no commits, which is exactly the state the
+   * first `lanes link knowledge use github` finds. Everything downstream reads
+   * it as "empty".
+   *
+   * Concurrent callers share one request. `allEntries` reads sixteen entries at
+   * a time and each of them asks; without this, one search would open sixteen
+   * connections to re-learn the same sha.
+   */
+  async head(force = false): Promise<Head | null> {
+    if (!force && this.#head && this.#now() - this.#headCheckedAt < this.#freshnessMs) {
+      return this.#head;
+    }
+    this.#inFlight ??= this.#readHead().finally(() => {
+      this.#inFlight = undefined;
+    });
+    return this.#inFlight;
+  }
+  async #readHead(): Promise<Head | null> {
+    const branch = await this.branch();
+    const response = await this.request(
+      `/repos/${this.repo}/branches/${encodeURIComponent(branch)}`,
+      this.#headEtag ? { headers: { 'if-none-match': this.#headEtag } } : {},
+    );
+    this.#headCheckedAt = this.#now();
+    // 304 is the answer this exists for: unchanged, free of rate limit, and the
+    // tree cached below is still current because it is keyed by the same sha.
+    if (response.status === 304) return this.#head;
+    if (response.status === 404) {
+      this.#head = null;
+      this.#headEtag = undefined;
+      return null;
+    }
+    if (!response.ok) throw await failure(`read branch "${branch}" of ${this.repo}`, response);
+    const body = (await response.json()) as {
+      commit: { sha: string; commit?: { committer?: { date?: string } } };
+    };
+    this.#headEtag = response.headers.get('etag') ?? undefined;
+    this.#head = {
+      commit: body.commit.sha,
+      committedAt: new Date(body.commit.commit?.committer?.date ?? 0),
+    };
+    return this.#head;
+  }
+  /**
+   * Every blob in the branch, by path.
+   *
+   * Keyed by the commit it was read at, so an unchanged head reuses it and a
+   * moved one refetches. One request per commit rather than one per listing is
+   * the whole reason `list` is affordable here.
+   */
+  async entries(): Promise<{ entries: Map<string, RepositoryEntry>; committedAt: Date }> {
+    const head = await this.head();
+    if (head === null) return { entries: new Map(), committedAt: new Date(0) };
+    if (this.#tree?.commit !== head.commit) {
+      const body = await this.json<{
+        tree: Array<{ path: string; type: string; sha: string; size?: number }>;
+        truncated?: boolean;
+      }>(`/repos/${this.repo}/git/trees/${head.commit}?recursive=1`, {}, `list ${this.repo}`);
+      // Refused rather than served short. GitHub truncates a recursive tree
+      // past roughly 100,000 entries, and a listing missing an arbitrary tail
+      // reads as "those entries do not exist" — which for memory is a search
+      // that quietly stops finding things.
+      if (body.truncated === true) {
+        throw new GithubApiError(
+          `${this.repo} is too large to list in one request — GitHub truncated the tree. Keep ` +
+            'memory and skills in a repository of their own, or under a "path" prefix in a smaller one.',
+          200,
+        );
+      }
+      const entries = new Map<string, RepositoryEntry>();
+      for (const item of body.tree) {
+        if (item.type !== 'blob') continue;
+        entries.set(item.path, { path: item.path, sha: item.sha, size: item.size ?? 0 });
+      }
+      this.#tree = { commit: head.commit, entries };
+    }
+    return { entries: this.#tree.entries, committedAt: head.committedAt };
+  }
+  /** One blob's bytes. Cached by sha, which is what a sha is for. */
+  async blob(sha: string): Promise<Uint8Array> {
+    const cached = this.#blobs.get(sha);
+    if (cached) return cached;
+    const response = await this.request(`/repos/${this.repo}/git/blobs/${sha}`, {
+      headers: { accept: 'application/vnd.github.raw' },
+    });
+    if (!response.ok) throw await failure(`read blob ${sha} of ${this.repo}`, response);
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    this.#blobs.set(sha, bytes);
+    return bytes;
+  }
+  /**
+   * Create or replace one file, as one commit.
+   *
+   * The Contents API refuses a write whose `sha` is not the one currently
+   * stored, which is how two writers on one branch are kept from silently
+   * overwriting each other. One retry against a re-read sha covers the ordinary
+   * race — a local command and a deployed endpoint touching the same entry —
+   * and a second conflict is a real fight, worth reporting rather than looping on.
+   */
+  async writeFile(path: string, data: Uint8Array, message: string): Promise<void> {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const current = await this.shaOf(path, attempt > 0);
+      const response = await this.request(`/repos/${this.repo}/contents/${encodePath(path)}`, {
+        method: 'PUT',
+        body: JSON.stringify({
+          message,
+          content: base64(data),
+          branch: await this.branch(),
+          ...(current ? { sha: current } : {}),
+        }),
+      });
+      // 422 is what GitHub answers when a `sha` is required and was not sent —
+      // the same staleness as a 409, reached from the other direction.
+      if (response.status === 409 || response.status === 422) continue;
+      if (!response.ok) throw await failure(`write "${path}" to ${this.repo}`, response);
+      this.absorb(await response.json(), path, data.byteLength);
+      return;
+    }
+    throw new GithubApiError(
+      `"${path}" in ${this.repo} changed while it was being written, twice. Something else is ` +
+        'writing this branch — check for a second endpoint on the same repository.',
+      409,
+    );
+  }
+  /** Remove one file. False when there was nothing to remove. */
+  async deleteFile(path: string, message: string): Promise<boolean> {
+    const sha = await this.shaOf(path, false);
+    if (!sha) return false;
+    const response = await this.request(`/repos/${this.repo}/contents/${encodePath(path)}`, {
+      method: 'DELETE',
+      body: JSON.stringify({ message, sha, branch: await this.branch() }),
+    });
+    // Gone already, or gone since we looked: absence is what the caller wanted.
+    if (response.status === 404 || response.status === 409) return false;
+    if (!response.ok) throw await failure(`delete "${path}" from ${this.repo}`, response);
+    this.absorb(await response.json(), path, null);
+    return true;
+  }
+  /** Forget the head and the tree. Blobs stay: a sha is still that content. */
+  invalidate(): void {
+    this.#head = null;
+    this.#headEtag = undefined;
+    this.#headCheckedAt = 0;
+    this.#tree = undefined;
+  }
+  /** The blob sha a path currently has, or undefined when it has none. */
+  async shaOf(path: string, force: boolean): Promise<string | undefined> {
+    if (force) this.invalidate();
+    return (await this.entries()).entries.get(path)?.sha;
+  }
+  /**
+   * Fold a Contents API response back into the cache.
+   *
+   * It carries both new shas — the commit's and the file's — so the next read
+   * needs no round trip to learn what the write just did. A response that is
+   * not the documented shape drops the cache instead of being guessed at; the
+   * cost of being wrong there is one refetch.
+   */
+  absorb(body: unknown, path: string, size: number | null): void {
+    const response = body as {
+      commit?: { sha?: string; committer?: { date?: string } };
+      content?: { sha?: string; size?: number };
+    };
+    const commit = response.commit?.sha;
+    if (!commit || !this.#tree) {
+      this.invalidate();
+      return;
+    }
+    const entries = new Map(this.#tree.entries);
+    if (size === null || !response.content?.sha) entries.delete(path);
+    else entries.set(path, { path, sha: response.content.sha, size: response.content.size ?? size });
+    this.#tree = { commit, entries };
+    this.#head = { commit, committedAt: new Date(response.commit?.committer?.date ?? this.#now()) };
+    // The ETag belonged to the previous tip, so the next conditional request
+    // must not present it — it would 304 against a branch that has moved.
+    this.#headEtag = undefined;
+    this.#headCheckedAt = this.#now();
+  }
+}

package/src/deployments/adapters/github-testing.ts ADDED Viewed

@@ -0,0 +1,258 @@
+import type { FetchLike } from './github-api.ts';
+/**
+ * A GitHub repository, in memory, for the adapter's tests.
+ *
+ * Test-only, behind the `-testing` suffix the blob and state stores already use
+ * for the same purpose, so application code does not reach it by habit. It is not
+ * a general GitHub simulator: it implements exactly the eight requests
+ * `github-repo.ts` and `github-commit.ts` make, and answers anything else with
+ * a 501 so an untested code path fails loudly rather than silently.
+ *
+ * What it does model faithfully, because the adapter's correctness rests on it:
+ * blob shas are content hashes (so "same sha, same bytes" is true, which is
+ * what makes the blob cache sound), commits snapshot the tree, the branch read
+ * answers 304 to a matching `If-None-Match`, and a Contents write with a stale
+ * `sha` answers 409.
+ */
+export interface FakeGithubOptions {
+  readonly repo?: string;
+  readonly private?: boolean;
+  readonly defaultBranch?: string;
+  readonly canPush?: boolean;
+  /** Start with commits already in place, rather than an empty repository. */
+  readonly files?: Readonly<Record<string, string>>;
+}
+export interface FakeGithub {
+  readonly fetch: FetchLike;
+  /** Every request, as `METHOD /path`, in order. */
+  readonly calls: string[];
+  /** The files at the branch tip. */
+  files(): Record<string, string>;
+  commitCount(): number;
+  /** Answer the next matching request with this instead. */
+  failNext(match: string, response: Response): void;
+  /**
+   * Answer every matching request this way, from now on.
+   *
+   * The shape a token that has expired actually has: not one bad response, but
+   * every response, until somebody replaces it. `failNext` models a race;
+   * this models a state.
+   */
+  failEvery(match: string, make: () => Response): void;
+  /** Change a file behind the adapter's back, as another writer would. */
+  writeBehind(path: string, text: string): void;
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/** Content-addressed, so the adapter's blob cache is exercised honestly. */
+function blobSha(data: Uint8Array): string {
+  const hasher = new Bun.CryptoHasher('sha1');
+  hasher.update(data);
+  return hasher.digest('hex');
+}
+function decodeBase64(value: string): Uint8Array {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+  return bytes;
+}
+function json(body: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(body), {
+    ...init,
+    headers: { 'content-type': 'application/json', ...(init.headers ?? {}) },
+  });
+}
+export function createFakeGithub(options: FakeGithubOptions = {}): FakeGithub {
+  const repo = options.repo ?? 'my-org/my-notes';
+  const branch = options.defaultBranch ?? 'main';
+  const calls: string[] = [];
+  const overrides: Array<{ match: string; response: Response }> = [];
+  const standing: Array<{ match: string; make: () => Response }> = [];
+  /** Path → bytes, at the tip. */
+  let files = new Map<string, Uint8Array>();
+  /** Commit sha → the tree it points at. Trees are addressed by commit here. */
+  const commits = new Map<string, Map<string, Uint8Array>>();
+  /** Loose objects created by the Git Data API before a commit references them. */
+  const loose = new Map<string, Uint8Array>();
+  const trees = new Map<string, Map<string, Uint8Array>>();
+  let head: string | null = null;
+  let counter = 0;
+  const snapshot = (): string => {
+    counter += 1;
+    const sha = `commit${counter}`;
+    commits.set(sha, new Map(files));
+    head = sha;
+    return sha;
+  };
+  if (options.files) {
+    for (const [path, text] of Object.entries(options.files)) {
+      files.set(path, encoder.encode(text));
+    }
+    snapshot();
+  }
+  const treeOf = (sha: string): Map<string, Uint8Array> => commits.get(sha) ?? new Map();
+  const fetch: FetchLike = async (input, init = {}) => {
+    const url = new URL(String(input));
+    const method = init.method ?? 'GET';
+    const path = url.pathname;
+    calls.push(`${method} ${path}`);
+    const override = overrides.findIndex((entry) => `${method} ${path}`.includes(entry.match));
+    if (override !== -1) return overrides.splice(override, 1)[0]!.response;
+    const always = standing.find((entry) => `${method} ${path}`.includes(entry.match));
+    if (always) return always.make();
+    const body = init.body === undefined ? undefined : (JSON.parse(String(init.body)) as Record<string, unknown>);
+    const headers = (init.headers ?? {}) as Record<string, string>;
+    if (method === 'GET' && path === `/repos/${repo}`) {
+      return json({
+        full_name: repo,
+        private: options.private ?? true,
+        default_branch: branch,
+        permissions: { push: options.canPush ?? true },
+      });
+    }
+    if (method === 'GET' && path === '/user') return json({ login: 'an-owner' });
+    if (method === 'GET' && path === `/repos/${repo}/branches/${branch}`) {
+      if (head === null) return json({ message: 'Branch not found' }, { status: 404 });
+      const etag = `"${head}"`;
+      if (headers['if-none-match'] === etag) return new Response(null, { status: 304 });
+      return json(
+        { commit: { sha: head, commit: { committer: { date: '2026-01-02T03:04:05Z' } } } },
+        { headers: { etag } },
+      );
+    }
+    if (method === 'GET' && path.startsWith(`/repos/${repo}/git/trees/`)) {
+      const sha = path.slice(`/repos/${repo}/git/trees/`.length);
+      const tree = commits.has(sha) ? treeOf(sha) : (trees.get(sha) ?? new Map());
+      return json({
+        sha,
+        tree: [...tree].map(([entry, data]) => ({
+          path: entry,
+          mode: '100644',
+          type: 'blob',
+          sha: blobSha(data),
+          size: data.byteLength,
+        })),
+        truncated: false,
+      });
+    }
+    if (method === 'GET' && path.startsWith(`/repos/${repo}/git/blobs/`)) {
+      const sha = path.slice(`/repos/${repo}/git/blobs/`.length);
+      for (const data of [...files.values(), ...loose.values()]) {
+        if (blobSha(data) === sha) return new Response(data);
+      }
+      for (const tree of commits.values()) {
+        for (const data of tree.values()) if (blobSha(data) === sha) return new Response(data);
+      }
+      return json({ message: 'Not Found' }, { status: 404 });
+    }
+    if (path.startsWith(`/repos/${repo}/contents/`)) {
+      const target = decodeURIComponent(path.slice(`/repos/${repo}/contents/`.length));
+      const existing = files.get(target);
+      const given = body?.['sha'] as string | undefined;
+      if (existing && given !== blobSha(existing)) {
+        return json({ message: 'does not match' }, { status: 409 });
+      }
+      if (!existing && given) return json({ message: 'not found' }, { status: 404 });
+      if (method === 'PUT') {
+        const data = decodeBase64(String(body?.['content'] ?? ''));
+        files.set(target, data);
+        const sha = snapshot();
+        return json({
+          content: { sha: blobSha(data), size: data.byteLength },
+          commit: { sha, committer: { date: '2026-01-02T03:04:05Z' } },
+        });
+      }
+      if (method === 'DELETE') {
+        if (!existing) return json({ message: 'Not Found' }, { status: 404 });
+        files.delete(target);
+        const sha = snapshot();
+        return json({ commit: { sha, committer: { date: '2026-01-02T03:04:05Z' } } });
+      }
+    }
+    if (method === 'POST' && path === `/repos/${repo}/git/blobs`) {
+      const data = decodeBase64(String(body?.['content'] ?? ''));
+      const sha = blobSha(data);
+      loose.set(sha, data);
+      return json({ sha });
+    }
+    if (method === 'POST' && path === `/repos/${repo}/git/trees`) {
+      const base = body?.['base_tree'] as string | undefined;
+      const tree = new Map(base ? treeOf(base) : []);
+      for (const entry of (body?.['tree'] ?? []) as Array<{ path: string; sha: string | null }>) {
+        if (entry.sha === null) tree.delete(entry.path);
+        else {
+          const data = loose.get(entry.sha);
+          if (data) tree.set(entry.path, data);
+        }
+      }
+      counter += 1;
+      const sha = `tree${counter}`;
+      trees.set(sha, tree);
+      return json({ sha });
+    }
+    if (method === 'POST' && path === `/repos/${repo}/git/commits`) {
+      counter += 1;
+      const sha = `commit${counter}`;
+      commits.set(sha, new Map(trees.get(String(body?.['tree'])) ?? new Map()));
+      return json({ sha });
+    }
+    // Creating the first ref, or moving an existing one. Both land the commit.
+    if (
+      (method === 'POST' && path === `/repos/${repo}/git/refs`) ||
+      (method === 'PATCH' && path === `/repos/${repo}/git/refs/heads/${branch}`)
+    ) {
+      const sha = String(body?.['sha']);
+      if (!commits.has(sha)) return json({ message: 'no such commit' }, { status: 422 });
+      head = sha;
+      files = new Map(treeOf(sha));
+      return json({ ref: `refs/heads/${branch}`, object: { sha } });
+    }
+    return json({ message: `the fake does not implement ${method} ${path}` }, { status: 501 });
+  };
+  return {
+    fetch,
+    calls,
+    files: () => Object.fromEntries([...files].map(([path, data]) => [path, decoder.decode(data)])),
+    commitCount: () => commits.size,
+    failNext: (match, response) => overrides.push({ match, response }),
+    failEvery: (match, make) => standing.push({ match, make }),
+    writeBehind: (path, text) => {
+      files.set(path, encoder.encode(text));
+      snapshot();
+    },
+  };
+}