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

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { createGitHubContentAdapter } from "./adapter.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,3 @@
 export { createGitHubContentAdapter } from "./adapter.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.5",
   "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.5"
   },
   "devDependencies": {
     "@types/node": "22.20.2",