@getrefino/github 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Refino contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# @getrefino/github
+
+GitHub persistence adapter for **Refino**. Reads and commits the canonical copy
+file through the GitHub Contents API with a fine-grained token (Contents
+read/write on one repository), so an edit made in the browser becomes a commit
+in the website's own repository.
+
+Installed for you by `npx @getrefino/cli init` in self-hosted mode. Sites
+connected to hosted Refino do not need this package: Refino commits on their
+behalf and the site holds no credentials.
+
+```ts
+createGitHubContentAdapter(githubOptionsFromEnv(process.env))
+```
+
+Environment: `COPY_GITHUB_TOKEN`, `COPY_GITHUB_REPO` (owner/name),
+`COPY_GITHUB_BRANCH`, `COPY_FILE_PATH`. **Server-side only** — never import this
+package from client code.
+
+<https://refino.dev>

package/dist/adapter.d.ts

@@ -0,0 +1,14 @@
+/**
+ * GitHub persistence through the REST Contents API
+ * (GET/PUT /repos/{owner}/{repo}/contents/{path}).
+ *
+ * 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.
+ *
+ * Docs: https://docs.github.com/en/rest/repos/contents
+ */
+import type { ContentAdapter } from "@getrefino/core";
+import type { GitHubContentAdapterOptions } from "./options.js";
+export declare function createGitHubContentAdapter(options: GitHubContentAdapterOptions): ContentAdapter;

package/dist/adapter.js

@@ -0,0 +1,116 @@
+import { ContentConflictError, ContentError, buildCommitMessage, parseCopy, planSave } from "@getrefino/core";
+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}`;
+        }
+    }
+    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) {
+            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 {
+        name: "github",
+        async load() {
+            const { content, revision } = await readCurrent();
+            return { content, revision };
+        },
+        async save(request) {
+            const current = await readCurrent();
+            const plan = planSave(current, request);
+            if (plan.kind === "unchanged") {
+                return { status: "unchanged", snapshot: { content: current.content, revision: current.revision } };
+            }
+            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.`);
+            }
+            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 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 },
+            };
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+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";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createGitHubContentAdapter } from "./adapter.js";
+export { DEFAULT_API_BASE_URL, DEFAULT_API_VERSION, GITHUB_ENV, githubOptionsFromEnv, validateRepoPath, } from "./options.js";

package/dist/options.d.ts

@@ -0,0 +1,54 @@
+export interface GitHubCommitIdentity {
+    readonly name: string;
+    readonly email: string;
+}
+export interface GitHubContentAdapterOptions {
+    /**
+     * Fine-grained personal access token (or GitHub App installation token)
+     * with **Contents: Read and write** on this one repository and nothing else.
+     * Server-side only. Never ship it to the browser.
+     */
+    readonly token: string;
+    readonly owner: string;
+    readonly repo: string;
+    /** Branch to read from and commit to, e.g. "main". Explicit on purpose. */
+    readonly branch: string;
+    /** Repository-relative path of the copy file, e.g. "content/copy.json". */
+    readonly path: string;
+    /** Defaults to https://api.github.com. Set for GitHub Enterprise Server. */
+    readonly apiBaseUrl?: string;
+    /** X-GitHub-Api-Version header. Defaults to the current documented version. */
+    readonly apiVersion?: string;
+    /** Injectable for tests. Defaults to global fetch. */
+    readonly fetch?: typeof fetch;
+    /** Override the commit message. Receives the IDs that actually changed. */
+    readonly commitMessage?: (context: {
+        readonly changedIds: readonly string[];
+    }) => string;
+    readonly committer?: GitHubCommitIdentity;
+    readonly author?: GitHubCommitIdentity;
+}
+export declare const DEFAULT_API_BASE_URL = "https://api.github.com";
+export declare const DEFAULT_API_VERSION = "2026-03-10";
+/** Validate a repository-relative file path. Rejects traversal and absolute paths. */
+export declare function validateRepoPath(path: string): string;
+export interface ResolvedGitHubOptions extends GitHubContentAdapterOptions {
+    readonly apiBaseUrl: string;
+    readonly apiVersion: string;
+}
+export declare function resolveOptions(options: GitHubContentAdapterOptions): ResolvedGitHubOptions;
+/**
+ * Environment variable names used by `githubOptionsFromEnv`.
+ *
+ *   COPY_GITHUB_TOKEN   fine-grained PAT, Contents read/write on one repo
+ *   COPY_GITHUB_REPO    "owner/name"
+ *   COPY_GITHUB_BRANCH  branch to commit to (default "main")
+ *   COPY_FILE_PATH      repository path of the copy file (default "content/copy.json")
+ */
+export declare const GITHUB_ENV: {
+    readonly token: "COPY_GITHUB_TOKEN";
+    readonly repo: "COPY_GITHUB_REPO";
+    readonly branch: "COPY_GITHUB_BRANCH";
+    readonly path: "COPY_FILE_PATH";
+};
+export declare function githubOptionsFromEnv(env: Readonly<Record<string, string | undefined>>): GitHubContentAdapterOptions;

package/dist/options.js

@@ -0,0 +1,79 @@
+import { ContentError } from "@getrefino/core";
+export const DEFAULT_API_BASE_URL = "https://api.github.com";
+export const DEFAULT_API_VERSION = "2026-03-10";
+const NAME_PATTERN = /^[A-Za-z0-9_.-]+$/;
+function requireString(value, label) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new ContentError("NOT_CONFIGURED", `GitHub adapter: ${label} is required.`);
+    }
+    return value.trim();
+}
+/** Validate a repository-relative file path. Rejects traversal and absolute paths. */
+export function validateRepoPath(path) {
+    const trimmed = requireString(path, "path");
+    if (trimmed.startsWith("/") || trimmed.includes("\\") || trimmed.includes("\0")) {
+        throw new ContentError("NOT_CONFIGURED", "GitHub adapter: path must be repository-relative.");
+    }
+    const segments = trimmed.split("/");
+    if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw new ContentError("NOT_CONFIGURED", "GitHub adapter: path contains invalid segments.");
+    }
+    return trimmed;
+}
+export function resolveOptions(options) {
+    const token = requireString(options.token, "token");
+    const owner = requireString(options.owner, "owner");
+    const repo = requireString(options.repo, "repo");
+    const branch = requireString(options.branch, "branch");
+    if (!NAME_PATTERN.test(owner) || !NAME_PATTERN.test(repo)) {
+        throw new ContentError("NOT_CONFIGURED", "GitHub adapter: owner and repo contain invalid characters.");
+    }
+    if (branch.includes("..") || /\s/.test(branch)) {
+        throw new ContentError("NOT_CONFIGURED", "GitHub adapter: branch name is invalid.");
+    }
+    return {
+        ...options,
+        token,
+        owner,
+        repo,
+        branch,
+        path: validateRepoPath(options.path),
+        apiBaseUrl: (options.apiBaseUrl ?? DEFAULT_API_BASE_URL).replace(/\/+$/, ""),
+        apiVersion: options.apiVersion ?? DEFAULT_API_VERSION,
+    };
+}
+/**
+ * Environment variable names used by `githubOptionsFromEnv`.
+ *
+ *   COPY_GITHUB_TOKEN   fine-grained PAT, Contents read/write on one repo
+ *   COPY_GITHUB_REPO    "owner/name"
+ *   COPY_GITHUB_BRANCH  branch to commit to (default "main")
+ *   COPY_FILE_PATH      repository path of the copy file (default "content/copy.json")
+ */
+export const GITHUB_ENV = {
+    token: "COPY_GITHUB_TOKEN",
+    repo: "COPY_GITHUB_REPO",
+    branch: "COPY_GITHUB_BRANCH",
+    path: "COPY_FILE_PATH",
+};
+export function githubOptionsFromEnv(env) {
+    const token = env[GITHUB_ENV.token];
+    const repoSpec = env[GITHUB_ENV.repo];
+    if (!token) {
+        throw new ContentError("NOT_CONFIGURED", `Set ${GITHUB_ENV.token} to a fine-grained token with Contents read/write.`);
+    }
+    if (!repoSpec || !repoSpec.includes("/")) {
+        throw new ContentError("NOT_CONFIGURED", `Set ${GITHUB_ENV.repo} to "owner/name".`);
+    }
+    const [owner, repo, ...extra] = repoSpec.split("/");
+    if (!owner || !repo || extra.length > 0) {
+        throw new ContentError("NOT_CONFIGURED", `Set ${GITHUB_ENV.repo} to "owner/name".`);
+    }
+    return {
+        token,
+        owner,
+        repo,
+        branch: env[GITHUB_ENV.branch] || "main",
+        path: env[GITHUB_ENV.path] || "content/copy.json",
+    };
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@getrefino/github",
+  "version": "0.1.0-rc.1",
+  "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",
+    "github",
+    "copy",
+    "content",
+    "git"
+  ],
+  "license": "MIT",
+  "homepage": "https://refino.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forant/inline-copy.git",
+    "directory": "packages/github"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@getrefino/core": "0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.2",
+    "typescript": "6.0.3",
+    "vitest": "5.0.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  }
+}