@setzkasten-cms/github-adapter 0.4.2

package/LICENSE

@@ -0,0 +1,37 @@
+Setzkasten Community License
+
+Copyright (c) 2026 Lilapixel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, merge, publish, and distribute the Software, subject to the
+following conditions:
+
+1. The above copyright notice and this permission notice shall be included in
+   all copies or substantial portions of the Software.
+
+2. The Software may not be used for commercial purposes without a separate
+   commercial license from the copyright holder. "Commercial purposes" means
+   any use of the Software that is primarily intended for or directed toward
+   commercial advantage or monetary compensation. This includes, but is not
+   limited to:
+   - Using the Software to manage content for a commercial website or product
+   - Offering the Software as part of a paid service
+   - Using the Software within a for-profit organization
+
+3. Non-commercial use is permitted without restriction. This includes:
+   - Personal projects
+   - Open source projects
+   - Educational and academic use
+   - Non-profit organizations
+
+4. A commercial license ("Enterprise License") may be obtained by contacting
+   Lilapixel at hello@lilapixel.de.
+
+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/dist/index.d.ts

@@ -0,0 +1,103 @@
+import { Result, ContentRepository, EntryListItem, EntryData, Asset, CommitResult, TreeNode } from '@setzkasten-cms/core';
+
+interface GitHubClientConfig {
+    token: string;
+    owner: string;
+    repo: string;
+    branch: string;
+}
+/**
+ * Low-level GitHub API client wrapping Octokit.
+ * All methods return Result types – never throws.
+ */
+declare class GitHubClient {
+    private octokit;
+    private owner;
+    private repo;
+    private branch;
+    private etagCache;
+    constructor(config: GitHubClientConfig);
+    getFileContent(path: string): Promise<Result<{
+        content: string;
+        sha: string;
+    }>>;
+    listDirectory(path: string): Promise<Result<Array<{
+        name: string;
+        type: string;
+        sha: string;
+    }>>>;
+    /**
+     * Get the current HEAD SHA for the configured branch.
+     */
+    getHeadSha(): Promise<Result<string>>;
+    /**
+     * Get the tree SHA for a given commit.
+     */
+    getCommitTree(commitSha: string): Promise<Result<string>>;
+    /**
+     * Create a new tree from a list of file changes.
+     */
+    createTree(baseTreeSha: string, files: Array<{
+        path: string;
+        content: string;
+        mode?: '100644';
+    }>): Promise<Result<string>>;
+    /**
+     * Create a commit.
+     */
+    createCommit(treeSha: string, parentSha: string, message: string): Promise<Result<string>>;
+    /**
+     * Update the branch ref to point to a new commit.
+     */
+    updateRef(commitSha: string): Promise<Result<void>>;
+    /**
+     * Upload a binary file (image) via the Contents API.
+     */
+    uploadFile(path: string, content: Uint8Array, message: string, existingSha?: string): Promise<Result<{
+        sha: string;
+    }>>;
+    private handleError;
+}
+
+/**
+ * ContentRepository implementation using GitHub API.
+ * Uses Git Trees API for atomic batch commits.
+ */
+declare class GitHubContentRepository implements ContentRepository {
+    private client;
+    private treeBuilder;
+    constructor(config: GitHubClientConfig);
+    listEntries(collection: string): Promise<Result<EntryListItem[]>>;
+    getEntry(collection: string, slug: string): Promise<Result<EntryData>>;
+    saveEntry(collection: string, slug: string, data: EntryData, assets?: Asset[]): Promise<Result<CommitResult>>;
+    deleteEntry(collection: string, slug: string): Promise<Result<CommitResult>>;
+    getTree(ref?: string): Promise<Result<TreeNode[]>>;
+}
+
+interface FileChange {
+    path: string;
+    content: string;
+}
+/**
+ * Batch commit builder using the Git Trees API.
+ *
+ * Instead of creating individual commits per file (Keystatic's approach),
+ * this creates a single atomic commit with all changes.
+ *
+ * Flow:
+ * 1. GET current HEAD SHA
+ * 2. GET tree SHA of HEAD commit
+ * 3. POST new tree with all file changes
+ * 4. POST new commit pointing to the new tree
+ * 5. PATCH ref to point to the new commit
+ */
+declare class TreeBuilder {
+    private client;
+    constructor(client: GitHubClient);
+    commit(files: FileChange[], message: string): Promise<Result<{
+        sha: string;
+        url?: string;
+    }>>;
+}
+
+export { type FileChange, GitHubClient, type GitHubClientConfig, GitHubContentRepository, TreeBuilder };

package/dist/index.js

@@ -0,0 +1,296 @@
+// src/github-client.ts
+import { Octokit } from "octokit";
+import {
+  err,
+  ok,
+  rateLimitError,
+  networkError,
+  notFoundError,
+  conflictError
+} from "@setzkasten-cms/core";
+var GitHubClient = class {
+  octokit;
+  owner;
+  repo;
+  branch;
+  etagCache = /* @__PURE__ */ new Map();
+  constructor(config) {
+    this.octokit = new Octokit({ auth: config.token });
+    this.owner = config.owner;
+    this.repo = config.repo;
+    this.branch = config.branch;
+  }
+  async getFileContent(path) {
+    try {
+      const response = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path,
+        ref: this.branch
+      });
+      const data = response.data;
+      if (Array.isArray(data) || data.type !== "file") {
+        return err(notFoundError(path));
+      }
+      const content = Buffer.from(data.content, "base64").toString("utf-8");
+      return ok({ content, sha: data.sha });
+    } catch (error) {
+      return this.handleError(error, path);
+    }
+  }
+  async listDirectory(path) {
+    try {
+      const response = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path,
+        ref: this.branch
+      });
+      if (!Array.isArray(response.data)) {
+        return err(notFoundError(path));
+      }
+      return ok(
+        response.data.map((item) => ({
+          name: item.name,
+          type: item.type,
+          sha: item.sha
+        }))
+      );
+    } catch (error) {
+      return this.handleError(error, path);
+    }
+  }
+  /**
+   * Get the current HEAD SHA for the configured branch.
+   */
+  async getHeadSha() {
+    try {
+      const response = await this.octokit.rest.git.getRef({
+        owner: this.owner,
+        repo: this.repo,
+        ref: `heads/${this.branch}`
+      });
+      return ok(response.data.object.sha);
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+  /**
+   * Get the tree SHA for a given commit.
+   */
+  async getCommitTree(commitSha) {
+    try {
+      const response = await this.octokit.rest.git.getCommit({
+        owner: this.owner,
+        repo: this.repo,
+        commit_sha: commitSha
+      });
+      return ok(response.data.tree.sha);
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+  /**
+   * Create a new tree from a list of file changes.
+   */
+  async createTree(baseTreeSha, files) {
+    try {
+      const response = await this.octokit.rest.git.createTree({
+        owner: this.owner,
+        repo: this.repo,
+        base_tree: baseTreeSha,
+        tree: files.map((f) => ({
+          path: f.path,
+          mode: f.mode ?? "100644",
+          type: "blob",
+          content: f.content
+        }))
+      });
+      return ok(response.data.sha);
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+  /**
+   * Create a commit.
+   */
+  async createCommit(treeSha, parentSha, message) {
+    try {
+      const response = await this.octokit.rest.git.createCommit({
+        owner: this.owner,
+        repo: this.repo,
+        tree: treeSha,
+        parents: [parentSha],
+        message
+      });
+      return ok(response.data.sha);
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+  /**
+   * Update the branch ref to point to a new commit.
+   */
+  async updateRef(commitSha) {
+    try {
+      await this.octokit.rest.git.updateRef({
+        owner: this.owner,
+        repo: this.repo,
+        ref: `heads/${this.branch}`,
+        sha: commitSha
+      });
+      return ok(void 0);
+    } catch (error) {
+      return this.handleError(error);
+    }
+  }
+  /**
+   * Upload a binary file (image) via the Contents API.
+   */
+  async uploadFile(path, content, message, existingSha) {
+    try {
+      const base64Content = Buffer.from(content).toString("base64");
+      const response = await this.octokit.rest.repos.createOrUpdateFileContents({
+        owner: this.owner,
+        repo: this.repo,
+        path,
+        message,
+        content: base64Content,
+        branch: this.branch,
+        ...existingSha ? { sha: existingSha } : {}
+      });
+      return ok({ sha: response.data.content?.sha ?? "" });
+    } catch (error) {
+      return this.handleError(error, path);
+    }
+  }
+  handleError(error, path) {
+    if (error && typeof error === "object" && "status" in error) {
+      const status = error.status;
+      if (status === 404) {
+        return err(notFoundError(path ?? "unknown"));
+      }
+      if (status === 409) {
+        return err(conflictError("Concurrent edit detected. Please refresh and try again."));
+      }
+      if (status === 403 || status === 429) {
+        const retryAfter = 60;
+        return err(rateLimitError(retryAfter, 0));
+      }
+    }
+    const message = error instanceof Error ? error.message : "Unknown network error";
+    return err(networkError(message, error));
+  }
+};
+
+// src/github-content-repository.ts
+import {
+  ok as ok3,
+  err as err3,
+  serializationError
+} from "@setzkasten-cms/core";
+
+// src/tree-builder.ts
+import { ok as ok2 } from "@setzkasten-cms/core";
+var TreeBuilder = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async commit(files, message) {
+    const headResult = await this.client.getHeadSha();
+    if (!headResult.ok) return headResult;
+    const treeResult = await this.client.getCommitTree(headResult.value);
+    if (!treeResult.ok) return treeResult;
+    const newTreeResult = await this.client.createTree(treeResult.value, files);
+    if (!newTreeResult.ok) return newTreeResult;
+    const commitResult = await this.client.createCommit(
+      newTreeResult.value,
+      headResult.value,
+      message
+    );
+    if (!commitResult.ok) return commitResult;
+    const updateResult = await this.client.updateRef(commitResult.value);
+    if (!updateResult.ok) return updateResult;
+    return ok2({ sha: commitResult.value });
+  }
+};
+
+// src/github-content-repository.ts
+var GitHubContentRepository = class {
+  client;
+  treeBuilder;
+  constructor(config) {
+    this.client = new GitHubClient(config);
+    this.treeBuilder = new TreeBuilder(this.client);
+  }
+  async listEntries(collection) {
+    const result = await this.client.listDirectory(collection);
+    if (!result.ok) return result;
+    return ok3(
+      result.value.filter((item) => item.name.endsWith(".json")).map((item) => ({
+        slug: item.name.replace(/\.json$/, ""),
+        name: item.name.replace(/\.json$/, "")
+      }))
+    );
+  }
+  async getEntry(collection, slug) {
+    const path = `${collection}/${slug}.json`;
+    const result = await this.client.getFileContent(path);
+    if (!result.ok) return result;
+    try {
+      const content = JSON.parse(result.value.content);
+      return ok3({ content, sha: result.value.sha });
+    } catch {
+      return err3(serializationError(`Failed to parse JSON at ${path}`, path));
+    }
+  }
+  async saveEntry(collection, slug, data, assets) {
+    const files = [];
+    const jsonPath = `${collection}/${slug}.json`;
+    const jsonContent = JSON.stringify(data.content, null, 2);
+    files.push({ path: jsonPath, content: jsonContent });
+    if (assets && assets.length > 0) {
+      for (const asset of assets) {
+        const uploadResult = await this.client.uploadFile(
+          asset.path,
+          asset.content,
+          `Upload ${asset.path}`
+        );
+        if (!uploadResult.ok) return uploadResult;
+      }
+    }
+    const commitMessage = `Update ${collection}/${slug}`;
+    const result = await this.treeBuilder.commit(files, commitMessage);
+    if (!result.ok) return result;
+    return ok3({
+      sha: result.value.sha,
+      message: commitMessage,
+      url: result.value.url
+    });
+  }
+  async deleteEntry(collection, slug) {
+    const path = `${collection}/${slug}.json`;
+    const fileResult = await this.client.getFileContent(path);
+    if (!fileResult.ok) return fileResult;
+    return ok3({
+      sha: "",
+      message: `Delete ${collection}/${slug}`
+    });
+  }
+  async getTree(ref) {
+    const result = await this.client.listDirectory("");
+    if (!result.ok) return result;
+    return ok3(
+      result.value.map((item) => ({
+        path: item.name,
+        type: item.type === "dir" ? "dir" : "file",
+        sha: item.sha
+      }))
+    );
+  }
+};
+export {
+  GitHubClient,
+  GitHubContentRepository,
+  TreeBuilder
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@setzkasten-cms/github-adapter",
+  "version": "0.4.2",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "octokit": "^4.1.0",
+    "@setzkasten-cms/core": "0.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/github-client.ts

@@ -0,0 +1,226 @@
+import { Octokit } from 'octokit'
+import {
+  err,
+  ok,
+  rateLimitError,
+  networkError,
+  notFoundError,
+  conflictError,
+  type Result,
+} from '@setzkasten-cms/core'
+
+export interface GitHubClientConfig {
+  token: string
+  owner: string
+  repo: string
+  branch: string
+}
+
+/**
+ * Low-level GitHub API client wrapping Octokit.
+ * All methods return Result types – never throws.
+ */
+export class GitHubClient {
+  private octokit: Octokit
+  private owner: string
+  private repo: string
+  private branch: string
+  private etagCache = new Map<string, { etag: string; data: unknown }>()
+
+  constructor(config: GitHubClientConfig) {
+    this.octokit = new Octokit({ auth: config.token })
+    this.owner = config.owner
+    this.repo = config.repo
+    this.branch = config.branch
+  }
+
+  async getFileContent(path: string): Promise<Result<{ content: string; sha: string }>> {
+    try {
+      const response = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path,
+        ref: this.branch,
+      })
+
+      const data = response.data
+      if (Array.isArray(data) || data.type !== 'file') {
+        return err(notFoundError(path))
+      }
+
+      const content = Buffer.from(data.content, 'base64').toString('utf-8')
+      return ok({ content, sha: data.sha })
+    } catch (error) {
+      return this.handleError(error, path)
+    }
+  }
+
+  async listDirectory(path: string): Promise<Result<Array<{ name: string; type: string; sha: string }>>> {
+    try {
+      const response = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path,
+        ref: this.branch,
+      })
+
+      if (!Array.isArray(response.data)) {
+        return err(notFoundError(path))
+      }
+
+      return ok(
+        response.data.map((item) => ({
+          name: item.name,
+          type: item.type,
+          sha: item.sha,
+        })),
+      )
+    } catch (error) {
+      return this.handleError(error, path)
+    }
+  }
+
+  /**
+   * Get the current HEAD SHA for the configured branch.
+   */
+  async getHeadSha(): Promise<Result<string>> {
+    try {
+      const response = await this.octokit.rest.git.getRef({
+        owner: this.owner,
+        repo: this.repo,
+        ref: `heads/${this.branch}`,
+      })
+      return ok(response.data.object.sha)
+    } catch (error) {
+      return this.handleError(error)
+    }
+  }
+
+  /**
+   * Get the tree SHA for a given commit.
+   */
+  async getCommitTree(commitSha: string): Promise<Result<string>> {
+    try {
+      const response = await this.octokit.rest.git.getCommit({
+        owner: this.owner,
+        repo: this.repo,
+        commit_sha: commitSha,
+      })
+      return ok(response.data.tree.sha)
+    } catch (error) {
+      return this.handleError(error)
+    }
+  }
+
+  /**
+   * Create a new tree from a list of file changes.
+   */
+  async createTree(
+    baseTreeSha: string,
+    files: Array<{ path: string; content: string; mode?: '100644' }>,
+  ): Promise<Result<string>> {
+    try {
+      const response = await this.octokit.rest.git.createTree({
+        owner: this.owner,
+        repo: this.repo,
+        base_tree: baseTreeSha,
+        tree: files.map((f) => ({
+          path: f.path,
+          mode: f.mode ?? '100644',
+          type: 'blob',
+          content: f.content,
+        })),
+      })
+      return ok(response.data.sha)
+    } catch (error) {
+      return this.handleError(error)
+    }
+  }
+
+  /**
+   * Create a commit.
+   */
+  async createCommit(
+    treeSha: string,
+    parentSha: string,
+    message: string,
+  ): Promise<Result<string>> {
+    try {
+      const response = await this.octokit.rest.git.createCommit({
+        owner: this.owner,
+        repo: this.repo,
+        tree: treeSha,
+        parents: [parentSha],
+        message,
+      })
+      return ok(response.data.sha)
+    } catch (error) {
+      return this.handleError(error)
+    }
+  }
+
+  /**
+   * Update the branch ref to point to a new commit.
+   */
+  async updateRef(commitSha: string): Promise<Result<void>> {
+    try {
+      await this.octokit.rest.git.updateRef({
+        owner: this.owner,
+        repo: this.repo,
+        ref: `heads/${this.branch}`,
+        sha: commitSha,
+      })
+      return ok(undefined)
+    } catch (error) {
+      return this.handleError(error)
+    }
+  }
+
+  /**
+   * Upload a binary file (image) via the Contents API.
+   */
+  async uploadFile(
+    path: string,
+    content: Uint8Array,
+    message: string,
+    existingSha?: string,
+  ): Promise<Result<{ sha: string }>> {
+    try {
+      const base64Content = Buffer.from(content).toString('base64')
+
+      const response = await this.octokit.rest.repos.createOrUpdateFileContents({
+        owner: this.owner,
+        repo: this.repo,
+        path,
+        message,
+        content: base64Content,
+        branch: this.branch,
+        ...(existingSha ? { sha: existingSha } : {}),
+      })
+
+      return ok({ sha: response.data.content?.sha ?? '' })
+    } catch (error) {
+      return this.handleError(error, path)
+    }
+  }
+
+  private handleError(error: unknown, path?: string): Result<never> {
+    if (error && typeof error === 'object' && 'status' in error) {
+      const status = (error as { status: number }).status
+
+      if (status === 404) {
+        return err(notFoundError(path ?? 'unknown'))
+      }
+      if (status === 409) {
+        return err(conflictError('Concurrent edit detected. Please refresh and try again.'))
+      }
+      if (status === 403 || status === 429) {
+        const retryAfter = 60 // default
+        return err(rateLimitError(retryAfter, 0))
+      }
+    }
+
+    const message = error instanceof Error ? error.message : 'Unknown network error'
+    return err(networkError(message, error))
+  }
+}

package/src/github-content-repository.ts

@@ -0,0 +1,121 @@
+import {
+  ok,
+  err,
+  serializationError,
+  type ContentRepository,
+  type EntryData,
+  type EntryListItem,
+  type Asset,
+  type CommitResult,
+  type TreeNode,
+  type Result,
+} from '@setzkasten-cms/core'
+import { GitHubClient, type GitHubClientConfig } from './github-client'
+import { TreeBuilder, type FileChange } from './tree-builder'
+
+/**
+ * ContentRepository implementation using GitHub API.
+ * Uses Git Trees API for atomic batch commits.
+ */
+export class GitHubContentRepository implements ContentRepository {
+  private client: GitHubClient
+  private treeBuilder: TreeBuilder
+
+  constructor(config: GitHubClientConfig) {
+    this.client = new GitHubClient(config)
+    this.treeBuilder = new TreeBuilder(this.client)
+  }
+
+  async listEntries(collection: string): Promise<Result<EntryListItem[]>> {
+    const result = await this.client.listDirectory(collection)
+    if (!result.ok) return result
+
+    return ok(
+      result.value
+        .filter((item) => item.name.endsWith('.json'))
+        .map((item) => ({
+          slug: item.name.replace(/\.json$/, ''),
+          name: item.name.replace(/\.json$/, ''),
+        })),
+    )
+  }
+
+  async getEntry(collection: string, slug: string): Promise<Result<EntryData>> {
+    const path = `${collection}/${slug}.json`
+    const result = await this.client.getFileContent(path)
+    if (!result.ok) return result
+
+    try {
+      const content = JSON.parse(result.value.content) as Record<string, unknown>
+      return ok({ content, sha: result.value.sha })
+    } catch {
+      return err(serializationError(`Failed to parse JSON at ${path}`, path))
+    }
+  }
+
+  async saveEntry(
+    collection: string,
+    slug: string,
+    data: EntryData,
+    assets?: Asset[],
+  ): Promise<Result<CommitResult>> {
+    const files: FileChange[] = []
+
+    // Add the JSON content file
+    const jsonPath = `${collection}/${slug}.json`
+    const jsonContent = JSON.stringify(data.content, null, 2)
+    files.push({ path: jsonPath, content: jsonContent })
+
+    // Upload assets first (via Contents API for binary files)
+    if (assets && assets.length > 0) {
+      for (const asset of assets) {
+        const uploadResult = await this.client.uploadFile(
+          asset.path,
+          asset.content,
+          `Upload ${asset.path}`,
+        )
+        if (!uploadResult.ok) return uploadResult as Result<never>
+      }
+    }
+
+    // Batch commit all JSON changes
+    const commitMessage = `Update ${collection}/${slug}`
+    const result = await this.treeBuilder.commit(files, commitMessage)
+
+    if (!result.ok) return result as Result<never>
+
+    return ok({
+      sha: result.value.sha,
+      message: commitMessage,
+      url: result.value.url,
+    })
+  }
+
+  async deleteEntry(collection: string, slug: string): Promise<Result<CommitResult>> {
+    // For delete, we'd need to use the Contents API with the file SHA
+    // This is a simplified version – full implementation would use tree builder
+    const path = `${collection}/${slug}.json`
+    const fileResult = await this.client.getFileContent(path)
+    if (!fileResult.ok) return fileResult as Result<never>
+
+    // TODO: Implement deletion via tree builder (remove file from tree)
+    return ok({
+      sha: '',
+      message: `Delete ${collection}/${slug}`,
+    })
+  }
+
+  async getTree(ref?: string): Promise<Result<TreeNode[]>> {
+    // Simplified – returns top-level directory listing
+    const result = await this.client.listDirectory('')
+    if (!result.ok) return result as Result<never>
+
+    return ok(
+      result.value.map((item) => ({
+        path: item.name,
+        type: item.type === 'dir' ? 'dir' as const : 'file' as const,
+        sha: item.sha,
+      })),
+    )
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { GitHubClient, type GitHubClientConfig } from './github-client'
+export { GitHubContentRepository } from './github-content-repository'
+export { TreeBuilder, type FileChange } from './tree-builder'

package/src/tree-builder.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, vi } from 'vitest'
+import { ok, err, networkError } from '@setzkasten-cms/core'
+import { TreeBuilder, type FileChange } from './tree-builder'
+import type { GitHubClient } from './github-client'
+
+function createMockClient(overrides: Partial<GitHubClient> = {}): GitHubClient {
+  return {
+    getHeadSha: vi.fn().mockResolvedValue(ok('head-sha-123')),
+    getCommitTree: vi.fn().mockResolvedValue(ok('tree-sha-456')),
+    createTree: vi.fn().mockResolvedValue(ok('new-tree-sha-789')),
+    createCommit: vi.fn().mockResolvedValue(ok('commit-sha-abc')),
+    updateRef: vi.fn().mockResolvedValue(ok(undefined)),
+    ...overrides,
+  } as unknown as GitHubClient
+}
+
+describe('TreeBuilder', () => {
+  const files: FileChange[] = [
+    { path: 'content/posts/hello.json', content: '{"title":"Hello"}' },
+    { path: 'content/posts/world.json', content: '{"title":"World"}' },
+  ]
+
+  it('commits files through the full Git tree flow', async () => {
+    const client = createMockClient()
+    const builder = new TreeBuilder(client)
+
+    const result = await builder.commit(files, 'Update posts')
+
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.value.sha).toBe('commit-sha-abc')
+    }
+
+    expect(client.getHeadSha).toHaveBeenCalledOnce()
+    expect(client.getCommitTree).toHaveBeenCalledWith('head-sha-123')
+    expect(client.createTree).toHaveBeenCalledWith('tree-sha-456', files)
+    expect(client.createCommit).toHaveBeenCalledWith('new-tree-sha-789', 'head-sha-123', 'Update posts')
+    expect(client.updateRef).toHaveBeenCalledWith('commit-sha-abc')
+  })
+
+  it('returns error if getHeadSha fails', async () => {
+    const client = createMockClient({
+      getHeadSha: vi.fn().mockResolvedValue(err(networkError('Network down'))),
+    })
+    const builder = new TreeBuilder(client)
+
+    const result = await builder.commit(files, 'msg')
+    expect(result.ok).toBe(false)
+    expect(client.getCommitTree).not.toHaveBeenCalled()
+  })
+
+  it('returns error if getCommitTree fails', async () => {
+    const client = createMockClient({
+      getCommitTree: vi.fn().mockResolvedValue(err(networkError('Commit not found'))),
+    })
+    const builder = new TreeBuilder(client)
+
+    const result = await builder.commit(files, 'msg')
+    expect(result.ok).toBe(false)
+    expect(client.createTree).not.toHaveBeenCalled()
+  })
+
+  it('returns error if createTree fails', async () => {
+    const client = createMockClient({
+      createTree: vi.fn().mockResolvedValue(err(networkError('Tree creation failed'))),
+    })
+    const builder = new TreeBuilder(client)
+
+    const result = await builder.commit(files, 'msg')
+    expect(result.ok).toBe(false)
+    expect(client.createCommit).not.toHaveBeenCalled()
+  })
+
+  it('returns error if createCommit fails', async () => {
+    const client = createMockClient({
+      createCommit: vi.fn().mockResolvedValue(err(networkError('Commit failed'))),
+    })
+    const builder = new TreeBuilder(client)
+
+    const result = await builder.commit(files, 'msg')
+    expect(result.ok).toBe(false)
+    expect(client.updateRef).not.toHaveBeenCalled()
+  })
+
+  it('returns error if updateRef fails', async () => {
+    const client = createMockClient({
+      updateRef: vi.fn().mockResolvedValue(err(networkError('Ref update failed'))),
+    })
+    const builder = new TreeBuilder(client)
+
+    const result = await builder.commit(files, 'msg')
+    expect(result.ok).toBe(false)
+  })
+})

package/src/tree-builder.ts

@@ -0,0 +1,53 @@
+import type { Result } from '@setzkasten-cms/core'
+import { ok, err, networkError } from '@setzkasten-cms/core'
+import type { GitHubClient } from './github-client'
+
+export interface FileChange {
+  path: string
+  content: string
+}
+
+/**
+ * Batch commit builder using the Git Trees API.
+ *
+ * Instead of creating individual commits per file (Keystatic's approach),
+ * this creates a single atomic commit with all changes.
+ *
+ * Flow:
+ * 1. GET current HEAD SHA
+ * 2. GET tree SHA of HEAD commit
+ * 3. POST new tree with all file changes
+ * 4. POST new commit pointing to the new tree
+ * 5. PATCH ref to point to the new commit
+ */
+export class TreeBuilder {
+  constructor(private client: GitHubClient) {}
+
+  async commit(files: FileChange[], message: string): Promise<Result<{ sha: string; url?: string }>> {
+    // 1. Get current HEAD
+    const headResult = await this.client.getHeadSha()
+    if (!headResult.ok) return headResult
+
+    // 2. Get base tree
+    const treeResult = await this.client.getCommitTree(headResult.value)
+    if (!treeResult.ok) return treeResult
+
+    // 3. Create new tree with all changes
+    const newTreeResult = await this.client.createTree(treeResult.value, files)
+    if (!newTreeResult.ok) return newTreeResult
+
+    // 4. Create commit
+    const commitResult = await this.client.createCommit(
+      newTreeResult.value,
+      headResult.value,
+      message,
+    )
+    if (!commitResult.ok) return commitResult
+
+    // 5. Update branch ref
+    const updateResult = await this.client.updateRef(commitResult.value)
+    if (!updateResult.ok) return updateResult
+
+    return ok({ sha: commitResult.value })
+  }
+}