@getrefino/github 0.1.0-rc.4 → 0.1.0-rc.6

package/dist/adapter.d.ts

@@ -1,12 +1,14 @@
 /**
- * GitHub persistence through the REST Contents API
- * (GET/PUT /repos/{owner}/{repo}/contents/{path}).
+ * GitHub persistence for the copy file.
  *
  * Why the Contents API: it reads a file with its blob SHA and writes a new
  * version as a single commit only if the SHA still matches. That gives us
  * load, conflict detection, and an understandable commit without a custom
  * git implementation.
  *
+ * The HTTP itself lives in `file-store.ts`, which the article document
+ * service also uses, so copy and content commit through one code path.
+ *
  * Docs: https://docs.github.com/en/rest/repos/contents
  */
 import type { ContentAdapter } from "@getrefino/core";

package/dist/adapter.js

@@ -1,62 +1,16 @@
-import { ContentConflictError, ContentError, buildCommitMessage, parseCopy, planSave } from "@getrefino/core";
+import { ContentConflictError, ContentError, buildCommitMessage, isContentError, parseCopy, planSave, } from "@getrefino/core";
+import { createGitHubFileClient } from "./file-store.js";
 import { resolveOptions } from "./options.js";
-function encodePath(path) {
-    return path.split("/").map(encodeURIComponent).join("/");
-}
-function decodeBase64(text) {
-    return Buffer.from(text.replace(/\s/g, ""), "base64").toString("utf8");
-}
-function encodeBase64(text) {
-    return Buffer.from(text, "utf8").toString("base64");
-}
 export function createGitHubContentAdapter(options) {
     const resolved = resolveOptions(options);
-    const doFetch = resolved.fetch ?? ((...args) => globalThis.fetch(...args));
-    const fileUrl = `${resolved.apiBaseUrl}/repos/${encodeURIComponent(resolved.owner)}/${encodeURIComponent(resolved.repo)}/contents/${encodePath(resolved.path)}`;
-    const location = `${resolved.owner}/${resolved.repo}@${resolved.branch}:${resolved.path}`;
-    function headers(extra = {}) {
-        return {
-            accept: "application/vnd.github+json",
-            authorization: `Bearer ${resolved.token}`,
-            "x-github-api-version": resolved.apiVersion,
-            "user-agent": "refino-github-adapter",
-            ...extra,
-        };
-    }
-    /** Never let the token leak through an error message. */
-    function scrub(text) {
-        return text.split(resolved.token).join("[redacted]");
-    }
-    async function readError(response) {
-        try {
-            const body = (await response.json());
-            return scrub(body.message ?? `HTTP ${response.status}`);
-        }
-        catch {
-            return `HTTP ${response.status}`;
-        }
-    }
+    const client = createGitHubFileClient(resolved);
+    const location = client.location(resolved.path);
     async function readCurrent() {
-        const url = `${fileUrl}?ref=${encodeURIComponent(resolved.branch)}`;
-        const response = await doFetch(url, { method: "GET", headers: headers(), cache: "no-store" });
-        if (response.status === 404) {
+        const file = await client.readFile(resolved.path);
+        if (!file) {
             throw new ContentError("NOT_FOUND", `Copy file not found at ${location}. Check the repository, branch and path.`);
         }
-        if (response.status === 401 || response.status === 403) {
-            throw new ContentError("ADAPTER_ERROR", `GitHub rejected the token (HTTP ${response.status}). It needs Contents read/write on ${resolved.owner}/${resolved.repo}.`);
-        }
-        if (!response.ok) {
-            throw new ContentError("ADAPTER_ERROR", `GitHub read failed: ${await readError(response)}`);
-        }
-        const file = (await response.json());
-        if (file.type !== "file" || typeof file.sha !== "string") {
-            throw new ContentError("ADAPTER_ERROR", `${location} is not a file.`);
-        }
-        if (file.encoding !== "base64" || typeof file.content !== "string") {
-            throw new ContentError("ADAPTER_ERROR", `${location} is too large to edit through the Contents API (1 MB limit).`);
-        }
-        const text = decodeBase64(file.content);
-        return { text, content: parseCopy(text), revision: file.sha };
+        return { text: file.text, content: parseCopy(file.text), revision: file.revision };
     }
     return {
         name: "github",
@@ -73,43 +27,28 @@ export function createGitHubContentAdapter(options) {
             const message = resolved.commitMessage
                 ? resolved.commitMessage({ changedIds: plan.changedIds })
                 : buildCommitMessage(plan.changedIds);
-            const body = {
-                message,
-                content: encodeBase64(plan.text),
-                sha: current.revision,
-                branch: resolved.branch,
-            };
-            if (resolved.committer)
-                body.committer = resolved.committer;
-            if (resolved.author)
-                body.author = resolved.author;
-            const response = await doFetch(fileUrl, {
-                method: "PUT",
-                headers: headers({ "content-type": "application/json" }),
-                body: JSON.stringify(body),
-            });
-            if (response.status === 409) {
-                // GitHub compared the SHA we sent with the file and found it moved.
-                const latest = await readCurrent();
-                throw new ContentConflictError("The copy file changed in the repository while you were editing. Reload the latest copy and reapply your edits.", { content: latest.content, revision: latest.revision });
-            }
-            if (response.status === 401 || response.status === 403) {
-                throw new ContentError("ADAPTER_ERROR", `GitHub refused the commit (HTTP ${response.status}). The token needs Contents read/write on ${resolved.owner}/${resolved.repo}, and the branch must not block direct pushes.`);
+            let written;
+            try {
+                written = await client.writeFile({
+                    path: resolved.path,
+                    text: plan.text,
+                    baseRevision: current.revision,
+                    message,
+                });
             }
-            if (!response.ok) {
-                throw new ContentError("ADAPTER_ERROR", `GitHub commit failed: ${await readError(response)}`);
-            }
-            const result = (await response.json());
-            const newSha = result.content?.sha;
-            if (typeof newSha !== "string") {
-                throw new ContentError("ADAPTER_ERROR", "GitHub commit succeeded but returned no file SHA.");
+            catch (error) {
+                // GitHub compared the SHA we sent with the file and found it moved.
+                // The editor gets the latest copy back so it can rebase in place.
+                if (isContentError(error) && error.code === "CONFLICT") {
+                    const latest = await readCurrent();
+                    throw new ContentConflictError("The copy file changed in the repository while you were editing. Reload the latest copy and reapply your edits.", { content: latest.content, revision: latest.revision });
+                }
+                throw error;
             }
-            const commitSha = result.commit?.sha ?? "";
-            const commitUrl = result.commit?.html_url;
             return {
                 status: "saved",
-                snapshot: { content: plan.content, revision: newSha },
-                commit: commitUrl ? { sha: commitSha, message, url: commitUrl } : { sha: commitSha, message },
+                snapshot: { content: plan.content, revision: written.revision },
+                ...(written.commit ? { commit: written.commit } : {}),
             };
         },
     };

package/dist/file-store.d.ts

@@ -0,0 +1,29 @@
+import type { SourceFile, SourceFileStore, SourceFileWrite, SourceFileWriteResult } from "@getrefino/core/documents";
+import type { GitHubCommitIdentity } from "./options.js";
+export interface GitHubFileStoreOptions {
+    /** Fine-grained token with **Contents: Read and write** on this one repository. Server-side only. */
+    readonly token: string;
+    readonly owner: string;
+    readonly repo: string;
+    readonly branch: string;
+    readonly apiBaseUrl?: string;
+    readonly apiVersion?: string;
+    readonly fetch?: typeof fetch;
+    readonly committer?: GitHubCommitIdentity;
+    readonly author?: GitHubCommitIdentity;
+}
+/**
+ * The raw GitHub calls, shared by the copy adapter and the document store.
+ * `readFile` reports a missing file as `null` so each caller can say what a
+ * missing file means for it.
+ */
+export interface GitHubFileClient {
+    readonly location: (path: string) => string;
+    readFile(path: string): Promise<(SourceFile & {
+        readonly tooLarge?: false;
+    }) | null>;
+    writeFile(write: SourceFileWrite): Promise<SourceFileWriteResult>;
+}
+export declare function createGitHubFileClient(options: GitHubFileStoreOptions): GitHubFileClient;
+/** A `SourceFileStore` over one repository and branch. */
+export declare function createGitHubFileStore(options: GitHubFileStoreOptions): SourceFileStore;

package/dist/file-store.js

@@ -0,0 +1,113 @@
+import { ContentError } from "@getrefino/core";
+import { DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, validateRepoPath } from "./options.js";
+function encodePath(path) {
+    return path.split("/").map(encodeURIComponent).join("/");
+}
+function decodeBase64(text) {
+    return Buffer.from(text.replace(/\s/g, ""), "base64").toString("utf8");
+}
+function encodeBase64(text) {
+    return Buffer.from(text, "utf8").toString("base64");
+}
+export function createGitHubFileClient(options) {
+    const token = options.token;
+    const apiBaseUrl = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/+$/, "");
+    const apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
+    const doFetch = options.fetch ?? ((...args) => globalThis.fetch(...args));
+    const repoUrl = `${apiBaseUrl}/repos/${encodeURIComponent(options.owner)}/${encodeURIComponent(options.repo)}/contents`;
+    const location = (path) => `${options.owner}/${options.repo}@${options.branch}:${path}`;
+    function headers(extra = {}) {
+        return {
+            accept: "application/vnd.github+json",
+            authorization: `Bearer ${token}`,
+            "x-github-api-version": apiVersion,
+            "user-agent": "refino-github-adapter",
+            ...extra,
+        };
+    }
+    /** Never let the token leak through an error message. */
+    function scrub(text) {
+        return text.split(token).join("[redacted]");
+    }
+    async function readError(response) {
+        try {
+            const body = (await response.json());
+            return scrub(body.message ?? `HTTP ${response.status}`);
+        }
+        catch {
+            return `HTTP ${response.status}`;
+        }
+    }
+    function rejected(response) {
+        return new ContentError("ADAPTER_ERROR", `GitHub rejected the token (HTTP ${response.status}). It needs Contents read/write on ${options.owner}/${options.repo}.`);
+    }
+    return {
+        location,
+        async readFile(path) {
+            const safePath = validateRepoPath(path);
+            const url = `${repoUrl}/${encodePath(safePath)}?ref=${encodeURIComponent(options.branch)}`;
+            const response = await doFetch(url, { method: "GET", headers: headers(), cache: "no-store" });
+            if (response.status === 404)
+                return null;
+            if (response.status === 401 || response.status === 403)
+                throw rejected(response);
+            if (!response.ok) {
+                throw new ContentError("ADAPTER_ERROR", `GitHub read failed: ${await readError(response)}`);
+            }
+            const file = (await response.json());
+            if (file.type !== "file" || typeof file.sha !== "string") {
+                throw new ContentError("ADAPTER_ERROR", `${location(safePath)} is not a file.`);
+            }
+            if (file.encoding !== "base64" || typeof file.content !== "string") {
+                throw new ContentError("ADAPTER_ERROR", `${location(safePath)} is too large to edit through the Contents API (1 MB limit).`);
+            }
+            return { text: decodeBase64(file.content), revision: file.sha };
+        },
+        async writeFile(write) {
+            const safePath = validateRepoPath(write.path);
+            const body = {
+                message: write.message,
+                content: encodeBase64(write.text),
+                sha: write.baseRevision,
+                branch: options.branch,
+            };
+            if (options.committer)
+                body.committer = options.committer;
+            if (options.author)
+                body.author = options.author;
+            const response = await doFetch(`${repoUrl}/${encodePath(safePath)}`, {
+                method: "PUT",
+                headers: headers({ "content-type": "application/json" }),
+                body: JSON.stringify(body),
+            });
+            if (response.status === 409) {
+                throw new ContentError("CONFLICT", `${safePath} changed in the repository while you were editing. Reload the latest content and reapply your edits.`, { path: safePath });
+            }
+            if (response.status === 401 || response.status === 403) {
+                throw new ContentError("ADAPTER_ERROR", `GitHub refused the commit (HTTP ${response.status}). The token needs Contents read/write on ${options.owner}/${options.repo}, and the branch must not block direct pushes.`);
+            }
+            if (!response.ok) {
+                throw new ContentError("ADAPTER_ERROR", `GitHub commit failed: ${await readError(response)}`);
+            }
+            const result = (await response.json());
+            const newSha = result.content?.sha;
+            if (typeof newSha !== "string") {
+                throw new ContentError("ADAPTER_ERROR", "GitHub commit succeeded but returned no file SHA.");
+            }
+            const commitUrl = result.commit?.html_url;
+            const commit = commitUrl
+                ? { sha: result.commit?.sha ?? "", message: write.message, url: commitUrl }
+                : { sha: result.commit?.sha ?? "", message: write.message };
+            return { revision: newSha, commit };
+        },
+    };
+}
+/** A `SourceFileStore` over one repository and branch. */
+export function createGitHubFileStore(options) {
+    const client = createGitHubFileClient(options);
+    return {
+        name: "github",
+        readFile: (path) => client.readFile(path),
+        writeFile: (write) => client.writeFile(write),
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,7 @@
 export { createGitHubContentAdapter } from "./adapter.js";
+export { createGitHubFileClient, createGitHubFileStore } from "./file-store.js";
+export type { GitHubFileClient, GitHubFileStoreOptions } from "./file-store.js";
 export { DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, GITHUB_ENV, githubOptionsFromEnv, validateRepoPath, } from "./options.js";
 export type { GitHubCommitIdentity, GitHubContentAdapterOptions } from "./options.js";
+export { GitHubRepositoryError, MAX_BLOB_BYTES, createGitHubRepository, isGitHubRepositoryError } from "./repository.js";
+export type { CommitFile, CommitResult, GitHubRepository, GitHubRepositoryErrorCode, GitHubRepositoryOptions, RepositorySnapshot } from "./repository.js";

package/dist/index.js

@@ -1,2 +1,4 @@
 export { createGitHubContentAdapter } from "./adapter.js";
+export { createGitHubFileClient, createGitHubFileStore } from "./file-store.js";
 export { DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, GITHUB_ENV, githubOptionsFromEnv, validateRepoPath, } from "./options.js";
+export { GitHubRepositoryError, MAX_BLOB_BYTES, createGitHubRepository, isGitHubRepositoryError } from "./repository.js";

package/dist/repository.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Reading a branch at one commit and committing several files on top of it
+ * atomically, through the REST Git Database API.
+ *
+ * The content adapter commits one file with the Contents API, which is the
+ * right tool for the copy file. An integration update changes a handful of
+ * files together (package.json, the lockfile, generated modules), and they
+ * must land as one commit or not at all, so this module builds the tree and
+ * the commit itself and then moves the branch with `force: false`:
+ *
+ *   read:   ref → commit → recursive tree → blobs on demand
+ *   write:  tree (base_tree = the tree that was read) → commit (parent = the
+ *           commit that was read) → PATCH ref, fast-forward only
+ *
+ * If anyone pushed in between, GitHub refuses the fast-forward and nothing on
+ * the branch changes; the objects already created are unreferenced and
+ * harmless. The same token as the content adapter works: Contents read and
+ * write covers the Git Database API.
+ *
+ * Docs: https://docs.github.com/en/rest/git
+ */
+import type { GitHubCommitIdentity } from "./options.js";
+export interface GitHubRepositoryOptions {
+    /** Same token as the content adapter: Contents read and write on this repository. Server-side only. */
+    readonly token: string;
+    readonly owner: string;
+    readonly repo: string;
+    readonly branch: string;
+    readonly apiBaseUrl?: string;
+    readonly apiVersion?: string;
+    readonly fetch?: typeof fetch;
+    readonly committer?: GitHubCommitIdentity;
+    readonly author?: GitHubCommitIdentity;
+}
+export type GitHubRepositoryErrorCode = 
+/** The branch moved since it was read. Nothing was changed. */
+"CONFLICT"
+/** GitHub refused: the token lacks access, or the branch does not accept direct pushes. */
+ | "REFUSED" | "NOT_FOUND"
+/** The repository or a file is too large to read through the API. */
+ | "TOO_LARGE"
+/** GitHub could not be reached or answered with an error. Nothing was changed. */
+ | "UNAVAILABLE"
+/**
+ * The branch update was sent and its outcome could not be established:
+ * the commit may or may not be on the branch. The only code after which
+ * "nothing was changed" must not be said.
+ */
+ | "UNKNOWN";
+export declare class GitHubRepositoryError extends Error {
+    readonly code: GitHubRepositoryErrorCode;
+    constructor(code: GitHubRepositoryErrorCode, message: string);
+}
+export declare function isGitHubRepositoryError(error: unknown): error is GitHubRepositoryError;
+export interface CommitFile {
+    readonly path: string;
+    /** UTF-8 text. */
+    readonly content: string;
+}
+export interface CommitResult {
+    readonly sha: string;
+    readonly url?: string;
+}
+/** The branch as it was at one commit. */
+export interface RepositorySnapshot {
+    readonly commitSha: string;
+    /** Every file path (blobs only), repository-relative. */
+    readonly paths: readonly string[];
+    /** A file's text at this commit, or null when there is no such file. */
+    read(path: string): Promise<string | null>;
+    /**
+     * Commit `files` on top of this snapshot and move the branch to it, only if
+     * the branch still points at `commitSha`. Throws `CONFLICT` otherwise.
+     */
+    commit(input: {
+        readonly message: string;
+        readonly files: readonly CommitFile[];
+    }): Promise<CommitResult>;
+}
+export interface GitHubRepository {
+    snapshot(): Promise<RepositorySnapshot>;
+}
+/** A file larger than this is not read: nothing Refino updates comes close. */
+export declare const MAX_BLOB_BYTES: number;
+export declare function createGitHubRepository(options: GitHubRepositoryOptions): GitHubRepository;

package/dist/repository.js

@@ -0,0 +1,155 @@
+import { DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, validateRepoPath } from "./options.js";
+export class GitHubRepositoryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "GitHubRepositoryError";
+        this.code = code;
+    }
+}
+export function isGitHubRepositoryError(error) {
+    return error instanceof GitHubRepositoryError;
+}
+/** A file larger than this is not read: nothing Refino updates comes close. */
+export const MAX_BLOB_BYTES = 20 * 1024 * 1024;
+const OWNER_REPO = /^[A-Za-z0-9_.-]+$/;
+export function createGitHubRepository(options) {
+    const { token, owner, repo, branch } = options;
+    if (!token || !OWNER_REPO.test(owner) || !OWNER_REPO.test(repo) || !branch || branch.includes("..") || /\s/.test(branch)) {
+        throw new GitHubRepositoryError("NOT_FOUND", "GitHub repository: token, owner, repo and branch are required and must be valid.");
+    }
+    const apiBase = (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/+$/, "");
+    const apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
+    const doFetch = options.fetch ?? ((...args) => globalThis.fetch(...args));
+    const repoUrl = `${apiBase}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+    const refPath = `heads/${branch.split("/").map(encodeURIComponent).join("/")}`;
+    const scrub = (text) => text.split(token).join("[redacted]");
+    async function call(method, path, body) {
+        let response;
+        try {
+            response = await doFetch(`${repoUrl}${path}`, {
+                method,
+                cache: "no-store",
+                headers: {
+                    accept: "application/vnd.github+json",
+                    authorization: `Bearer ${token}`,
+                    "x-github-api-version": apiVersion,
+                    "user-agent": "refino-github-repository",
+                    ...(body === undefined ? {} : { "content-type": "application/json" }),
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            });
+        }
+        catch (error) {
+            throw new GitHubRepositoryError("UNAVAILABLE", `Could not reach GitHub: ${scrub(String(error))}`);
+        }
+        let parsed;
+        try {
+            parsed = await response.json();
+        }
+        catch {
+            parsed = null;
+        }
+        const message = scrub(typeof parsed?.message === "string" ? parsed.message : `HTTP ${response.status}`);
+        return { status: response.status, body: response.ok ? parsed : null, message };
+    }
+    function fail(step, status, message) {
+        if (status === 401 || status === 403)
+            throw new GitHubRepositoryError("REFUSED", `GitHub refused to ${step} (HTTP ${status}): ${message}`);
+        if (status === 404)
+            throw new GitHubRepositoryError("NOT_FOUND", `GitHub could not find what it needed to ${step}: ${message}`);
+        throw new GitHubRepositoryError("UNAVAILABLE", `GitHub could not ${step} (HTTP ${status}): ${message}`);
+    }
+    return {
+        async snapshot() {
+            const ref = await call("GET", `/git/ref/${refPath}`);
+            const commitSha = ref.body?.object?.sha;
+            if (!ref.body || typeof commitSha !== "string")
+                fail(`read branch ${branch}`, ref.status, ref.message);
+            const commit = await call("GET", `/git/commits/${commitSha}`);
+            const treeSha = commit.body?.tree?.sha;
+            if (!commit.body || typeof treeSha !== "string")
+                fail("read the latest commit", commit.status, commit.message);
+            const tree = await call("GET", `/git/trees/${treeSha}?recursive=1`);
+            if (!tree.body || !Array.isArray(tree.body.tree))
+                fail("list the repository", tree.status, tree.message);
+            if (tree.body.truncated)
+                throw new GitHubRepositoryError("TOO_LARGE", "The repository has too many files to list through the GitHub API.");
+            const entries = new Map(tree.body.tree.filter((entry) => entry.type === "blob").map((entry) => [entry.path, entry]));
+            const cache = new Map();
+            return {
+                commitSha,
+                paths: [...entries.keys()],
+                async read(path) {
+                    const entry = entries.get(path);
+                    if (!entry)
+                        return null;
+                    const cached = cache.get(path);
+                    if (cached !== undefined)
+                        return cached;
+                    if ((entry.size ?? 0) > MAX_BLOB_BYTES)
+                        throw new GitHubRepositoryError("TOO_LARGE", `${path} is too large to read.`);
+                    const blob = await call("GET", `/git/blobs/${entry.sha}`);
+                    if (!blob.body || typeof blob.body.content !== "string" || blob.body.encoding !== "base64")
+                        fail(`read ${path}`, blob.status, blob.message);
+                    const text = Buffer.from(blob.body.content.replace(/\s/g, ""), "base64").toString("utf8");
+                    cache.set(path, text);
+                    return text;
+                },
+                async commit({ message, files }) {
+                    if (files.length === 0)
+                        throw new GitHubRepositoryError("UNAVAILABLE", "Nothing to commit.");
+                    const tree = files.map((file) => {
+                        const path = validateRepoPath(file.path);
+                        const existing = entries.get(path);
+                        // Never write through a symlink or into a submodule; keep an executable bit if a file had one.
+                        if (existing && existing.mode !== "100644" && existing.mode !== "100755") {
+                            throw new GitHubRepositoryError("REFUSED", `${path} is not a regular file in the repository.`);
+                        }
+                        return { path, mode: existing?.mode ?? "100644", type: "blob", content: file.content };
+                    });
+                    const created = await call("POST", "/git/trees", { base_tree: treeSha, tree });
+                    if (!created.body?.sha)
+                        fail("prepare the commit", created.status, created.message);
+                    const commitBody = { message, tree: created.body.sha, parents: [commitSha] };
+                    if (options.author)
+                        commitBody.author = options.author;
+                    if (options.committer)
+                        commitBody.committer = options.committer;
+                    const made = await call("POST", "/git/commits", commitBody);
+                    if (!made.body?.sha)
+                        fail("create the commit", made.status, made.message);
+                    // The only step that changes the branch, and only as a fast-forward from what was read.
+                    const commitResult = made.body.html_url ? { sha: made.body.sha, url: made.body.html_url } : { sha: made.body.sha };
+                    let moved;
+                    try {
+                        moved = await call("PATCH", `/git/refs/${refPath}`, { sha: made.body.sha, force: false });
+                    }
+                    catch {
+                        moved = { status: 0, body: null, message: "no answer" };
+                    }
+                    if (!moved.body && (moved.status === 0 || moved.status >= 500)) {
+                        // The request may or may not have landed. Ask the branch rather than guess.
+                        const now = await call("GET", `/git/ref/${refPath}`).catch(() => null);
+                        const head = now?.body?.object?.sha;
+                        if (head === made.body.sha)
+                            return commitResult;
+                        if (typeof head === "string")
+                            throw new GitHubRepositoryError(head === commitSha ? "UNAVAILABLE" : "CONFLICT", `GitHub did not update ${branch}: ${moved.message}`);
+                        throw new GitHubRepositoryError("UNKNOWN", `GitHub did not confirm whether ${branch} was updated.`);
+                    }
+                    if (!moved.body) {
+                        if (moved.status === 422 && /fast.?forward/i.test(moved.message)) {
+                            throw new GitHubRepositoryError("CONFLICT", `${branch} changed while the update was being prepared.`);
+                        }
+                        if (moved.status === 422 || moved.status === 409) {
+                            throw new GitHubRepositoryError("REFUSED", `GitHub refused to update ${branch}: ${moved.message}`);
+                        }
+                        fail(`update ${branch}`, moved.status, moved.message);
+                    }
+                    return commitResult;
+                },
+            };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getrefino/github",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.6",
   "description": "GitHub persistence adapter for Refino: reads and commits the canonical copy file through the GitHub Contents API, so the repository stays the source of truth.",
   "keywords": [
     "refino",
@@ -36,7 +36,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@getrefino/core": "0.1.0-rc.4"
+    "@getrefino/core": "0.1.0-rc.6"
   },
   "devDependencies": {
     "@types/node": "22.20.2",