@gitgov/core 2.1.2 → 2.3.0

package/dist/src/github.js

@@ -0,0 +1,1281 @@
+import picomatch from 'picomatch';
+
+// src/file_lister/github/github_file_lister.ts
+
+// src/file_lister/file_lister.errors.ts
+var FileListerError = class extends Error {
+  constructor(message, code, filePath) {
+    super(message);
+    this.code = code;
+    this.filePath = filePath;
+    this.name = "FileListerError";
+  }
+};
+
+// src/file_lister/github/github_file_lister.ts
+var GitHubFileLister = class {
+  owner;
+  repo;
+  ref;
+  basePath;
+  octokit;
+  /** Cached tree entries from the Trees API */
+  treeCache = null;
+  constructor(options, octokit) {
+    this.owner = options.owner;
+    this.repo = options.repo;
+    this.ref = options.ref ?? "gitgov-state";
+    this.basePath = options.basePath ?? "";
+    this.octokit = octokit;
+  }
+  // ═══════════════════════════════════════════════════════════════════════
+  // FileLister Interface
+  // ═══════════════════════════════════════════════════════════════════════
+  /**
+   * [EARS-A1] Lists files matching glob patterns.
+   * [EARS-B1] Uses Trees API with recursive=1 and picomatch filter.
+   * [EARS-B3] Applies basePath prefix for tree entries, strips from results.
+   * [EARS-B6] Caches tree between list() calls.
+   */
+  async list(patterns, options) {
+    const entries = await this.fetchTree();
+    const blobs = entries.filter((entry) => entry.type === "blob");
+    const prefix = this.basePath ? `${this.basePath}/` : "";
+    const relativePaths = [];
+    for (const blob of blobs) {
+      if (!blob.path) continue;
+      if (prefix && !blob.path.startsWith(prefix)) {
+        continue;
+      }
+      const relativePath = prefix ? blob.path.slice(prefix.length) : blob.path;
+      relativePaths.push(relativePath);
+    }
+    const isMatch = picomatch(patterns, {
+      ignore: options?.ignore
+    });
+    return relativePaths.filter((p) => isMatch(p)).sort();
+  }
+  /**
+   * [EARS-A2] Checks if a file exists via Contents API.
+   * [EARS-B4] Returns false for 404 responses.
+   */
+  async exists(filePath) {
+    const fullPath = this.buildFullPath(filePath);
+    try {
+      const { data } = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path: fullPath,
+        ref: this.ref
+      });
+      if (Array.isArray(data) || data.type !== "file") {
+        return false;
+      }
+      return true;
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 404) return false;
+        if (error.status === 401 || error.status === 403) {
+          throw new FileListerError(
+            `Permission denied: ${filePath}`,
+            "PERMISSION_DENIED",
+            filePath
+          );
+        }
+        if (error.status >= 500) {
+          throw new FileListerError(
+            `GitHub API server error (${error.status}): ${filePath}`,
+            "READ_ERROR",
+            filePath
+          );
+        }
+        throw new FileListerError(
+          `Unexpected GitHub API response (${error.status}): ${filePath}`,
+          "READ_ERROR",
+          filePath
+        );
+      }
+      throw new FileListerError(
+        `Network error checking file: ${filePath}`,
+        "NETWORK_ERROR",
+        filePath
+      );
+    }
+  }
+  /**
+   * [EARS-A3] Reads file content as string.
+   * [EARS-B2] Decodes base64 content from Contents API.
+   * [EARS-B7] Falls back to Blobs API for files >1MB (null content).
+   */
+  async read(filePath) {
+    const fullPath = this.buildFullPath(filePath);
+    try {
+      const { data } = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path: fullPath,
+        ref: this.ref
+      });
+      if (Array.isArray(data) || data.type !== "file") {
+        throw new FileListerError(
+          `Not a file: ${filePath}`,
+          "READ_ERROR",
+          filePath
+        );
+      }
+      if (data.content !== null && data.content !== void 0) {
+        return Buffer.from(data.content, "base64").toString("utf-8");
+      }
+      return this.readViaBlobs(data.sha, filePath);
+    } catch (error) {
+      if (error instanceof FileListerError) throw error;
+      if (isOctokitRequestError(error)) {
+        if (error.status === 404) {
+          throw new FileListerError(
+            `File not found: ${filePath}`,
+            "FILE_NOT_FOUND",
+            filePath
+          );
+        }
+        if (error.status === 401 || error.status === 403) {
+          throw new FileListerError(
+            `Permission denied: ${filePath}`,
+            "PERMISSION_DENIED",
+            filePath
+          );
+        }
+        if (error.status >= 500) {
+          throw new FileListerError(
+            `GitHub API server error (${error.status}): ${filePath}`,
+            "READ_ERROR",
+            filePath
+          );
+        }
+        throw new FileListerError(
+          `Unexpected GitHub API response (${error.status}): ${filePath}`,
+          "READ_ERROR",
+          filePath
+        );
+      }
+      throw new FileListerError(
+        `Network error reading file: ${filePath}`,
+        "NETWORK_ERROR",
+        filePath
+      );
+    }
+  }
+  /**
+   * [EARS-A4] Gets file statistics via Contents API.
+   * Returns size from API, mtime as 0 (not available via Contents API), isFile as true.
+   */
+  async stat(filePath) {
+    const fullPath = this.buildFullPath(filePath);
+    try {
+      const { data } = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path: fullPath,
+        ref: this.ref
+      });
+      if (Array.isArray(data) || data.type !== "file") {
+        throw new FileListerError(
+          `Not a file: ${filePath}`,
+          "READ_ERROR",
+          filePath
+        );
+      }
+      return {
+        size: data.size,
+        mtime: 0,
+        isFile: true
+      };
+    } catch (error) {
+      if (error instanceof FileListerError) throw error;
+      if (isOctokitRequestError(error)) {
+        if (error.status === 404) {
+          throw new FileListerError(
+            `File not found: ${filePath}`,
+            "FILE_NOT_FOUND",
+            filePath
+          );
+        }
+        if (error.status === 401 || error.status === 403) {
+          throw new FileListerError(
+            `Permission denied: ${filePath}`,
+            "PERMISSION_DENIED",
+            filePath
+          );
+        }
+        if (error.status >= 500) {
+          throw new FileListerError(
+            `GitHub API server error (${error.status}): ${filePath}`,
+            "READ_ERROR",
+            filePath
+          );
+        }
+        throw new FileListerError(
+          `Unexpected GitHub API response (${error.status}): ${filePath}`,
+          "READ_ERROR",
+          filePath
+        );
+      }
+      throw new FileListerError(
+        `Network error getting file stats: ${filePath}`,
+        "NETWORK_ERROR",
+        filePath
+      );
+    }
+  }
+  // ═══════════════════════════════════════════════════════════════════════
+  // Private Helpers
+  // ═══════════════════════════════════════════════════════════════════════
+  /**
+   * Builds the full file path including basePath prefix.
+   */
+  buildFullPath(filePath) {
+    if (this.basePath) {
+      return `${this.basePath}/${filePath}`;
+    }
+    return filePath;
+  }
+  /**
+   * [EARS-B6] Fetches and caches the full repository tree.
+   * [EARS-C3] Throws READ_ERROR if the tree response is truncated.
+   */
+  async fetchTree() {
+    if (this.treeCache !== null) {
+      return this.treeCache;
+    }
+    try {
+      const { data } = await this.octokit.rest.git.getTree({
+        owner: this.owner,
+        repo: this.repo,
+        tree_sha: this.ref,
+        recursive: "1"
+      });
+      if (data.truncated) {
+        throw new FileListerError(
+          "Repository tree is truncated; too many files to list via Trees API",
+          "READ_ERROR"
+        );
+      }
+      this.treeCache = data.tree;
+      return this.treeCache;
+    } catch (error) {
+      if (error instanceof FileListerError) throw error;
+      if (isOctokitRequestError(error)) {
+        if (error.status === 404) {
+          throw new FileListerError(
+            "Repository or ref not found",
+            "FILE_NOT_FOUND"
+          );
+        }
+        if (error.status === 401 || error.status === 403) {
+          throw new FileListerError(
+            "Permission denied accessing repository tree",
+            "PERMISSION_DENIED"
+          );
+        }
+        if (error.status >= 500) {
+          throw new FileListerError(
+            `GitHub API server error (${error.status}) fetching tree`,
+            "READ_ERROR"
+          );
+        }
+        throw new FileListerError(
+          `Unexpected GitHub API response (${error.status}) fetching tree`,
+          "READ_ERROR"
+        );
+      }
+      throw new FileListerError(
+        "Network error fetching repository tree",
+        "NETWORK_ERROR"
+      );
+    }
+  }
+  /**
+   * [EARS-B7] Reads file content via the Blobs API (fallback for >1MB files).
+   */
+  async readViaBlobs(sha, filePath) {
+    try {
+      const { data } = await this.octokit.rest.git.getBlob({
+        owner: this.owner,
+        repo: this.repo,
+        file_sha: sha
+      });
+      return Buffer.from(data.content, "base64").toString("utf-8");
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 404) {
+          throw new FileListerError(
+            `File not found: ${filePath}`,
+            "FILE_NOT_FOUND",
+            filePath
+          );
+        }
+        if (error.status === 401 || error.status === 403) {
+          throw new FileListerError(
+            `Permission denied: ${filePath}`,
+            "PERMISSION_DENIED",
+            filePath
+          );
+        }
+        throw new FileListerError(
+          `GitHub API error (${error.status}): ${filePath}`,
+          "READ_ERROR",
+          filePath
+        );
+      }
+      throw new FileListerError(
+        `Network error reading blob for file: ${filePath}`,
+        "NETWORK_ERROR",
+        filePath
+      );
+    }
+  }
+};
+
+// src/record_store/github/github_record_store.ts
+var GitHubRecordStore = class {
+  owner;
+  repo;
+  ref;
+  basePath;
+  extension;
+  idEncoder;
+  octokit;
+  /** SHA cache keyed by full file path (basePath/encoded + extension) */
+  shaCache = /* @__PURE__ */ new Map();
+  /** IGitModule dependency for putMany() atomic commits. Optional — only needed for putMany(). */
+  gitModule;
+  constructor(options, octokit, gitModule) {
+    this.owner = options.owner;
+    this.repo = options.repo;
+    this.ref = options.ref ?? "gitgov-state";
+    this.basePath = options.basePath;
+    this.extension = options.extension ?? ".json";
+    this.idEncoder = options.idEncoder;
+    this.octokit = octokit;
+    this.gitModule = gitModule;
+  }
+  async get(id) {
+    this.validateId(id);
+    const filePath = this.buildFilePath(id);
+    try {
+      const { data } = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path: filePath,
+        ref: this.ref
+      });
+      if (Array.isArray(data) || data.type !== "file") {
+        throw new GitHubApiError(`Not a file: ${filePath}`, "INVALID_RESPONSE");
+      }
+      if (data.content === null || data.content === void 0) {
+        throw new GitHubApiError(
+          `File content is null (file may exceed 1MB): ${filePath}`,
+          "INVALID_RESPONSE"
+        );
+      }
+      this.shaCache.set(filePath, data.sha);
+      const decoded = Buffer.from(data.content, "base64").toString("utf-8");
+      return JSON.parse(decoded);
+    } catch (error) {
+      if (error instanceof GitHubApiError) throw error;
+      if (isOctokitRequestError(error) && error.status === 404) return null;
+      throw mapOctokitError(error, `GET ${filePath}`);
+    }
+  }
+  async put(id, value, opts) {
+    this.validateId(id);
+    const filePath = this.buildFilePath(id);
+    const content = Buffer.from(JSON.stringify(value, null, 2)).toString("base64");
+    const cachedSha = this.shaCache.get(filePath);
+    try {
+      const { data } = await this.octokit.rest.repos.createOrUpdateFileContents({
+        owner: this.owner,
+        repo: this.repo,
+        path: filePath,
+        message: opts?.commitMessage ?? `put ${id}`,
+        content,
+        branch: this.ref,
+        ...cachedSha ? { sha: cachedSha } : {}
+      });
+      if (data.content?.sha) {
+        this.shaCache.set(filePath, data.content.sha);
+      }
+      return { commitSha: data.commit.sha };
+    } catch (error) {
+      throw mapOctokitError(error, `PUT ${filePath}`);
+    }
+  }
+  /**
+   * [EARS-A11, EARS-A12, EARS-B8] Persists multiple records in a single atomic commit.
+   * Uses GitHubGitModule staging buffer: add() with contentMap, then commit().
+   * Empty entries array returns { commitSha: undefined } without API calls.
+   * Requires gitModule dependency — throws if not injected.
+   */
+  async putMany(entries, opts) {
+    if (entries.length === 0) {
+      return {};
+    }
+    if (!this.gitModule) {
+      throw new Error("putMany requires IGitModule dependency for atomic commits");
+    }
+    for (const { id } of entries) {
+      this.validateId(id);
+    }
+    const contentMap = {};
+    const filePaths = [];
+    for (const { id, value } of entries) {
+      const filePath = this.buildFilePath(id);
+      contentMap[filePath] = JSON.stringify(value, null, 2);
+      filePaths.push(filePath);
+    }
+    await this.gitModule.add(filePaths, { contentMap });
+    const message = opts?.commitMessage ?? `putMany ${entries.length} records`;
+    const commitSha = await this.gitModule.commit(message);
+    return { commitSha };
+  }
+  async delete(id, opts) {
+    this.validateId(id);
+    const filePath = this.buildFilePath(id);
+    let sha = this.shaCache.get(filePath);
+    if (sha === void 0) {
+      try {
+        const { data } = await this.octokit.rest.repos.getContent({
+          owner: this.owner,
+          repo: this.repo,
+          path: filePath,
+          ref: this.ref
+        });
+        if (Array.isArray(data) || data.type !== "file") {
+          return {};
+        }
+        sha = data.sha;
+      } catch (error) {
+        if (isOctokitRequestError(error) && error.status === 404) {
+          return {};
+        }
+        throw mapOctokitError(error, `GET ${filePath} (for delete)`);
+      }
+    }
+    try {
+      const { data } = await this.octokit.rest.repos.deleteFile({
+        owner: this.owner,
+        repo: this.repo,
+        path: filePath,
+        message: opts?.commitMessage ?? `delete ${id}`,
+        sha,
+        branch: this.ref
+      });
+      this.shaCache.delete(filePath);
+      return { commitSha: data.commit.sha };
+    } catch (error) {
+      if (isOctokitRequestError(error) && error.status === 404) {
+        this.shaCache.delete(filePath);
+        return {};
+      }
+      throw mapOctokitError(error, `DELETE ${filePath}`);
+    }
+  }
+  async list() {
+    try {
+      const { data } = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path: this.basePath,
+        ref: this.ref
+      });
+      if (!Array.isArray(data)) {
+        return [];
+      }
+      const ids = data.filter((entry) => entry.name.endsWith(this.extension)).map((entry) => entry.name.slice(0, -this.extension.length));
+      return this.idEncoder ? ids.map((encoded) => this.idEncoder.decode(encoded)) : ids;
+    } catch (error) {
+      if (isOctokitRequestError(error) && error.status === 404) {
+        return [];
+      }
+      throw mapOctokitError(error, `GET ${this.basePath} (list)`);
+    }
+  }
+  async exists(id) {
+    this.validateId(id);
+    const filePath = this.buildFilePath(id);
+    try {
+      await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path: filePath,
+        ref: this.ref
+      });
+      return true;
+    } catch (error) {
+      if (isOctokitRequestError(error) && error.status === 404) {
+        return false;
+      }
+      throw mapOctokitError(error, `GET ${filePath} (exists)`);
+    }
+  }
+  // ─────────────────────────────────────────────────────────
+  // Private helpers
+  // ─────────────────────────────────────────────────────────
+  validateId(id) {
+    if (!id || typeof id !== "string") {
+      throw new GitHubApiError("ID must be a non-empty string", "INVALID_ID");
+    }
+    if (id.includes("..") || /[\/\\]/.test(id)) {
+      throw new GitHubApiError(
+        `Invalid ID: "${id}". IDs cannot contain /, \\, or ..`,
+        "INVALID_ID"
+      );
+    }
+  }
+  buildFilePath(id) {
+    const encoded = this.idEncoder ? this.idEncoder.encode(id) : id;
+    return `${this.basePath}/${encoded}${this.extension}`;
+  }
+};
+
+// src/git/errors.ts
+var GitError = class _GitError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GitError";
+    Object.setPrototypeOf(this, _GitError.prototype);
+  }
+};
+var BranchNotFoundError = class _BranchNotFoundError extends GitError {
+  branchName;
+  constructor(branchName) {
+    super(`Branch not found: ${branchName}`);
+    this.name = "BranchNotFoundError";
+    this.branchName = branchName;
+    Object.setPrototypeOf(this, _BranchNotFoundError.prototype);
+  }
+};
+var FileNotFoundError = class _FileNotFoundError extends GitError {
+  filePath;
+  commitHash;
+  constructor(filePath, commitHash) {
+    super(`File not found: ${filePath} in commit ${commitHash}`);
+    this.name = "FileNotFoundError";
+    this.filePath = filePath;
+    this.commitHash = commitHash;
+    Object.setPrototypeOf(this, _FileNotFoundError.prototype);
+  }
+};
+var BranchAlreadyExistsError = class _BranchAlreadyExistsError extends GitError {
+  branchName;
+  constructor(branchName) {
+    super(`Branch already exists: ${branchName}`);
+    this.name = "BranchAlreadyExistsError";
+    this.branchName = branchName;
+    Object.setPrototypeOf(this, _BranchAlreadyExistsError.prototype);
+  }
+};
+
+// src/git/github/github_git_module.ts
+var GitHubGitModule = class {
+  owner;
+  repo;
+  defaultBranch;
+  octokit;
+  /** Staging buffer: path → content (null = delete) */
+  stagingBuffer = /* @__PURE__ */ new Map();
+  /** Active ref for operations (can be changed via checkoutBranch) */
+  activeRef;
+  constructor(options, octokit) {
+    this.owner = options.owner;
+    this.repo = options.repo;
+    this.defaultBranch = options.defaultBranch ?? "gitgov-state";
+    this.octokit = octokit;
+    this.activeRef = this.defaultBranch;
+  }
+  // ═══════════════════════════════════════════════════════════════
+  // PRIVATE HELPERS
+  // ═══════════════════════════════════════════════════════════════
+  /** Category C: Not supported via GitHub API */
+  notSupported(method) {
+    throw new GitError(
+      `${method} is not supported via GitHub API`
+    );
+  }
+  // ═══════════════════════════════════════════════════════════════
+  // CATEGORY A: READ OPERATIONS (EARS-A1 to A6)
+  // ═══════════════════════════════════════════════════════════════
+  /**
+   * [EARS-A1] Read file content via Contents API + base64 decode
+   * [EARS-A2] Fallback to Blobs API for files >1MB
+   */
+  async getFileContent(commitHash, filePath) {
+    try {
+      const { data } = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path: filePath,
+        ref: commitHash
+      });
+      if (Array.isArray(data) || data.type !== "file") {
+        throw new GitError(`Not a file: ${filePath}`);
+      }
+      if (data.content !== null && data.content !== void 0) {
+        return Buffer.from(data.content, "base64").toString("utf-8");
+      }
+      const { data: blobData } = await this.octokit.rest.git.getBlob({
+        owner: this.owner,
+        repo: this.repo,
+        file_sha: data.sha
+      });
+      return Buffer.from(blobData.content, "base64").toString("utf-8");
+    } catch (error) {
+      if (error instanceof GitError) throw error;
+      if (isOctokitRequestError(error)) {
+        if (error.status === 404) {
+          throw new FileNotFoundError(filePath, commitHash);
+        }
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): getFileContent ${filePath}`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): getFileContent ${filePath}`);
+        }
+        throw new GitError(`GitHub API error (${error.status}): getFileContent ${filePath}`);
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  /**
+   * [EARS-A3] Get commit SHA from branch via Refs API
+   * [EARS-B4] Return SHA directly if already a 40-char hex
+   */
+  async getCommitHash(ref = this.activeRef) {
+    if (/^[0-9a-f]{40}$/i.test(ref)) {
+      return ref;
+    }
+    try {
+      const { data } = await this.octokit.rest.git.getRef({
+        owner: this.owner,
+        repo: this.repo,
+        ref: `heads/${ref}`
+      });
+      return data.object.sha;
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 404) {
+          throw new BranchNotFoundError(ref);
+        }
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): getCommitHash ${ref}`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): getCommitHash ${ref}`);
+        }
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  /**
+   * [EARS-A4] List changed files via Compare API
+   */
+  async getChangedFiles(fromCommit, toCommit, pathFilter) {
+    try {
+      const { data } = await this.octokit.rest.repos.compareCommits({
+        owner: this.owner,
+        repo: this.repo,
+        base: fromCommit,
+        head: toCommit
+      });
+      const statusMap = {
+        added: "A",
+        modified: "M",
+        removed: "D",
+        renamed: "M"
+      };
+      const files = (data.files ?? []).map((f) => ({
+        status: statusMap[f.status] ?? "M",
+        file: f.filename
+      })).filter((f) => !pathFilter || f.file.startsWith(pathFilter));
+      return files;
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): getChangedFiles ${fromCommit}...${toCommit}`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): getChangedFiles`);
+        }
+        throw new GitError(`Failed to compare ${fromCommit}...${toCommit}: HTTP ${error.status}`);
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  /**
+   * [EARS-A5] Get commit history via Commits API
+   */
+  async getCommitHistory(branch, options) {
+    try {
+      const { data } = await this.octokit.rest.repos.listCommits({
+        owner: this.owner,
+        repo: this.repo,
+        sha: branch,
+        ...options?.maxCount !== void 0 && { per_page: options.maxCount },
+        ...options?.pathFilter !== void 0 && { path: options.pathFilter }
+      });
+      return data.map((c) => ({
+        hash: c.sha,
+        message: c.commit.message,
+        author: `${c.commit.author?.name ?? "unknown"} <${c.commit.author?.email ?? "unknown"}>`,
+        date: c.commit.author?.date ?? ""
+      }));
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): getCommitHistory ${branch}`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): getCommitHistory`);
+        }
+        throw new GitError(`Failed to get commit history: HTTP ${error.status}`);
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  /**
+   * [EARS-B3] Get commit history between two commits via Compare API
+   */
+  async getCommitHistoryRange(fromHash, toHash, options) {
+    try {
+      const { data } = await this.octokit.rest.repos.compareCommits({
+        owner: this.owner,
+        repo: this.repo,
+        base: fromHash,
+        head: toHash
+      });
+      let commits = data.commits.map((c) => ({
+        hash: c.sha,
+        message: c.commit.message,
+        author: `${c.commit.author?.name ?? "unknown"} <${c.commit.author?.email ?? "unknown"}>`,
+        date: c.commit.author?.date ?? ""
+      }));
+      if (options?.pathFilter) {
+        const changedPaths = new Set((data.files ?? []).map((f) => f.filename));
+        commits = commits.filter(
+          () => Array.from(changedPaths).some((f) => f.startsWith(options.pathFilter))
+        );
+      }
+      if (options?.maxCount) {
+        commits = commits.slice(0, options.maxCount);
+      }
+      return commits;
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): getCommitHistoryRange ${fromHash}...${toHash}`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): getCommitHistoryRange`);
+        }
+        throw new GitError(`Failed to get commit range: HTTP ${error.status}`);
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  /**
+   * [EARS-A6] Get commit message via Commits API
+   */
+  async getCommitMessage(commitHash) {
+    try {
+      const { data } = await this.octokit.rest.repos.getCommit({
+        owner: this.owner,
+        repo: this.repo,
+        ref: commitHash
+      });
+      return data.commit.message;
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 404) {
+          throw new GitError(`Commit not found: ${commitHash}`);
+        }
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): getCommitMessage ${commitHash}`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): getCommitMessage`);
+        }
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  // ═══════════════════════════════════════════════════════════════
+  // CATEGORY A: BRANCH OPERATIONS (EARS-B1 to B2)
+  // ═══════════════════════════════════════════════════════════════
+  /**
+   * [EARS-B1] Check if branch exists via Branches API
+   */
+  async branchExists(branchName) {
+    try {
+      await this.octokit.rest.repos.getBranch({
+        owner: this.owner,
+        repo: this.repo,
+        branch: branchName
+      });
+      return true;
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 404) return false;
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): branchExists ${branchName}`);
+        }
+        throw new GitError(`Failed to check branch: HTTP ${error.status}`);
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  /**
+   * [EARS-B2] List remote branches via Branches API
+   * remoteName is ignored — repo itself is the implicit remote
+   */
+  async listRemoteBranches(_remoteName) {
+    try {
+      const { data } = await this.octokit.rest.repos.listBranches({
+        owner: this.owner,
+        repo: this.repo
+      });
+      return data.map((b) => b.name);
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): listRemoteBranches`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): listRemoteBranches`);
+        }
+        throw new GitError(`Failed to list branches: HTTP ${error.status}`);
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  // ═══════════════════════════════════════════════════════════════
+  // CATEGORY A: WRITE OPERATIONS (EARS-C1 to C7)
+  // ═══════════════════════════════════════════════════════════════
+  /** [EARS-C1] Read file content and store in staging buffer */
+  async add(filePaths, options) {
+    for (const filePath of filePaths) {
+      const content = options?.contentMap?.[filePath] ?? await this.getFileContent(this.activeRef, filePath);
+      this.stagingBuffer.set(filePath, content);
+    }
+  }
+  /** [EARS-C2] Mark files as deleted in staging buffer */
+  async rm(filePaths) {
+    for (const filePath of filePaths) {
+      this.stagingBuffer.set(filePath, null);
+    }
+  }
+  /** [EARS-C7] Return staged file paths from buffer */
+  async getStagedFiles() {
+    return Array.from(this.stagingBuffer.keys());
+  }
+  /**
+   * [EARS-C6] Create branch via Refs API POST
+   */
+  async createBranch(branchName, startPoint) {
+    const sha = startPoint ? await this.getCommitHash(startPoint) : await this.getCommitHash(this.activeRef);
+    try {
+      await this.octokit.rest.git.createRef({
+        owner: this.owner,
+        repo: this.repo,
+        ref: `refs/heads/${branchName}`,
+        sha
+      });
+    } catch (error) {
+      if (isOctokitRequestError(error)) {
+        if (error.status === 422) {
+          throw new BranchAlreadyExistsError(branchName);
+        }
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): createBranch ${branchName}`);
+        }
+        throw new GitError(`Failed to create branch ${branchName}: HTTP ${error.status}`);
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  /**
+   * Internal commit implementation shared by commit() and commitAllowEmpty().
+   *
+   * [EARS-C3] 6-step atomic transaction
+   * [EARS-C4] Clears staging buffer after successful commit
+   * [EARS-C5] Throws if staging buffer is empty (unless allowEmpty)
+   */
+  async commitInternal(message, author, allowEmpty = false) {
+    if (!allowEmpty && this.stagingBuffer.size === 0) {
+      throw new GitError("Nothing to commit: staging buffer is empty");
+    }
+    try {
+      const { data: refData } = await this.octokit.rest.git.getRef({
+        owner: this.owner,
+        repo: this.repo,
+        ref: `heads/${this.activeRef}`
+      });
+      const currentSha = refData.object.sha;
+      const { data: commitData } = await this.octokit.rest.git.getCommit({
+        owner: this.owner,
+        repo: this.repo,
+        commit_sha: currentSha
+      });
+      const treeSha = commitData.tree.sha;
+      const treeEntries = [];
+      for (const [path, content] of this.stagingBuffer) {
+        if (content === null) {
+          treeEntries.push({
+            path,
+            mode: "100644",
+            type: "blob",
+            sha: null
+          });
+        } else {
+          const { data: blobData } = await this.octokit.rest.git.createBlob({
+            owner: this.owner,
+            repo: this.repo,
+            content: Buffer.from(content).toString("base64"),
+            encoding: "base64"
+          });
+          treeEntries.push({
+            path,
+            mode: "100644",
+            type: "blob",
+            sha: blobData.sha
+          });
+        }
+      }
+      const { data: treeData } = await this.octokit.rest.git.createTree({
+        owner: this.owner,
+        repo: this.repo,
+        base_tree: treeSha,
+        tree: treeEntries
+      });
+      const newTreeSha = treeData.sha;
+      const commitParams = {
+        owner: this.owner,
+        repo: this.repo,
+        message,
+        tree: newTreeSha,
+        parents: [currentSha]
+      };
+      if (author) {
+        commitParams.author = {
+          name: author.name,
+          email: author.email,
+          date: (/* @__PURE__ */ new Date()).toISOString()
+        };
+      }
+      const { data: newCommitData } = await this.octokit.rest.git.createCommit(commitParams);
+      const newCommitSha = newCommitData.sha;
+      try {
+        await this.octokit.rest.git.updateRef({
+          owner: this.owner,
+          repo: this.repo,
+          ref: `heads/${this.activeRef}`,
+          sha: newCommitSha
+        });
+      } catch (error) {
+        if (isOctokitRequestError(error) && error.status === 422) {
+          throw new GitError("non-fast-forward update rejected");
+        }
+        throw error;
+      }
+      this.stagingBuffer.clear();
+      return newCommitSha;
+    } catch (error) {
+      if (error instanceof GitError) throw error;
+      if (isOctokitRequestError(error)) {
+        if (error.status === 401 || error.status === 403) {
+          throw new GitError(`authentication/permission error (${error.status}): commit`);
+        }
+        if (error.status >= 500) {
+          throw new GitError(`GitHub server error (${error.status}): commit`);
+        }
+        throw new GitError(`GitHub API error (${error.status}): commit`);
+      }
+      const msg = error instanceof Error ? error.message : String(error);
+      throw new GitError(`network error: ${msg}`);
+    }
+  }
+  /**
+   * [EARS-C3] Commit staged changes via 6-step atomic transaction
+   * [EARS-C5] Throws if staging buffer is empty
+   */
+  async commit(message, author) {
+    return this.commitInternal(message, author, false);
+  }
+  // ═══════════════════════════════════════════════════════════════
+  // CATEGORY B: NO-OPS (sensible defaults)
+  // ═══════════════════════════════════════════════════════════════
+  /** [EARS-D5] exec not supported in API mode */
+  async exec(_command, _args, _options) {
+    return { exitCode: 1, stdout: "", stderr: "exec() not supported in GitHub API mode" };
+  }
+  /** No-op: repos are created via GitHub API, not initialized locally */
+  async init() {
+  }
+  /** [EARS-D1] Return virtual path representing the repo */
+  async getRepoRoot() {
+    return `github://${this.owner}/${this.repo}`;
+  }
+  /** [EARS-D1] Return active ref (starts as defaultBranch) */
+  async getCurrentBranch() {
+    return this.activeRef;
+  }
+  /** No-op: git config doesn't apply to GitHub API */
+  async setConfig(_key, _value, _scope) {
+  }
+  /** [EARS-D1] Return true if staging buffer has entries */
+  async hasUncommittedChanges(_pathFilter) {
+    return this.stagingBuffer.size > 0;
+  }
+  /** No-op: GitHub API doesn't have rebase-in-progress concept */
+  async isRebaseInProgress() {
+    return false;
+  }
+  /** [EARS-D1] GitHub repos always have 'origin' conceptually */
+  async isRemoteConfigured(_remoteName) {
+    return true;
+  }
+  /** No-op: always 'origin' */
+  async getBranchRemote(_branchName) {
+    return "origin";
+  }
+  /** No-op: GitHub API handles merges atomically */
+  async getConflictedFiles() {
+    return [];
+  }
+  /** [EARS-D2] Update activeRef for subsequent operations */
+  async checkoutBranch(branchName) {
+    this.activeRef = branchName;
+  }
+  /** No-op: GitHub API doesn't have stash concept */
+  async stash(_message) {
+    return null;
+  }
+  /** No-op */
+  async stashPop() {
+    return false;
+  }
+  /** No-op */
+  async stashDrop(_stashHash) {
+  }
+  /** No-op: API always fresh */
+  async fetch(_remote) {
+  }
+  /** No-op: API mode */
+  async pull(_remote, _branchName) {
+  }
+  /** No-op: API mode */
+  async pullRebase(_remote, _branchName) {
+  }
+  /** [EARS-D4] No-op: commits via API are already remote */
+  async push(_remote, _branchName) {
+  }
+  /** [EARS-D4] No-op: commits via API are already remote */
+  async pushWithUpstream(_remote, _branchName) {
+  }
+  /** No-op: API mode */
+  async setUpstream(_branchName, _remote, _remoteBranch) {
+  }
+  /** No-op */
+  async rebaseAbort() {
+  }
+  /** [EARS-D1] Delegates to commitInternal, allowing empty staging buffer */
+  async commitAllowEmpty(message, author) {
+    return this.commitInternal(message, author, true);
+  }
+  // ═══════════════════════════════════════════════════════════════
+  // CATEGORY C: NOT SUPPORTED (throw GitError)
+  // ═══════════════════════════════════════════════════════════════
+  /** [EARS-D3] Not supported via GitHub API */
+  async rebase(_targetBranch) {
+    this.notSupported("rebase");
+  }
+  /** [EARS-D3] Not supported via GitHub API */
+  async rebaseContinue() {
+    this.notSupported("rebaseContinue");
+  }
+  /** [EARS-D3] Not supported via GitHub API */
+  async resetHard(_target) {
+    this.notSupported("resetHard");
+  }
+  /** [EARS-D3] Not supported via GitHub API */
+  async checkoutOrphanBranch(_branchName) {
+    this.notSupported("checkoutOrphanBranch");
+  }
+  /** [EARS-D3] Not supported via GitHub API */
+  async checkoutFilesFromBranch(_sourceBranch, _filePaths) {
+    this.notSupported("checkoutFilesFromBranch");
+  }
+  /** [EARS-D3] Not supported via GitHub API */
+  async getMergeBase(_branchA, _branchB) {
+    this.notSupported("getMergeBase");
+  }
+};
+
+// src/config_store/github/github_config_store.ts
+var GitHubConfigStore = class {
+  owner;
+  repo;
+  ref;
+  basePath;
+  octokit;
+  /** Cached blob SHA from the last loadConfig call, used for PUT updates */
+  cachedSha = null;
+  constructor(options, octokit) {
+    this.owner = options.owner;
+    this.repo = options.repo;
+    this.ref = options.ref ?? "gitgov-state";
+    this.basePath = options.basePath ?? ".gitgov";
+    this.octokit = octokit;
+  }
+  /**
+   * Load project configuration from GitHub Contents API.
+   *
+   * [EARS-A1] Returns GitGovConfig when valid JSON is found.
+   * [EARS-A2] Returns null on 404 (fail-safe).
+   * [EARS-A3] Returns null on invalid JSON (fail-safe).
+   * [EARS-B1] Fetches via Contents API with base64 decode.
+   * [EARS-B2] Caches SHA from response for subsequent saveConfig.
+   */
+  async loadConfig() {
+    const path = `${this.basePath}/config.json`;
+    try {
+      const { data } = await this.octokit.rest.repos.getContent({
+        owner: this.owner,
+        repo: this.repo,
+        path,
+        ref: this.ref
+      });
+      if (Array.isArray(data) || data.type !== "file") {
+        return null;
+      }
+      if (!data.content) {
+        return null;
+      }
+      this.cachedSha = data.sha;
+      try {
+        const decoded = Buffer.from(data.content, "base64").toString("utf-8");
+        return JSON.parse(decoded);
+      } catch {
+        return null;
+      }
+    } catch (error) {
+      if (isOctokitRequestError(error) && error.status === 404) {
+        return null;
+      }
+      throw mapOctokitError(error, `loadConfig ${this.owner}/${this.repo}/${path}`);
+    }
+  }
+  /**
+   * Save project configuration to GitHub via Contents API PUT.
+   *
+   * [EARS-A4] Writes config via PUT to Contents API.
+   * [EARS-B3] Includes cached SHA for updates (optimistic concurrency).
+   * [EARS-B4] Omits SHA for initial creation.
+   * [EARS-C1] Throws PERMISSION_DENIED on 401/403.
+   * [EARS-C2] Throws CONFLICT on 409.
+   * [EARS-C3] Throws SERVER_ERROR on 5xx.
+   */
+  async saveConfig(config) {
+    const path = `${this.basePath}/config.json`;
+    const content = Buffer.from(JSON.stringify(config, null, 2)).toString("base64");
+    try {
+      const { data } = await this.octokit.rest.repos.createOrUpdateFileContents({
+        owner: this.owner,
+        repo: this.repo,
+        path,
+        message: "chore(config): update gitgov config.json",
+        content,
+        branch: this.ref,
+        ...this.cachedSha ? { sha: this.cachedSha } : {}
+      });
+      if (data.content?.sha) {
+        this.cachedSha = data.content.sha;
+      }
+      return { commitSha: data.commit.sha };
+    } catch (error) {
+      throw mapOctokitError(error, `saveConfig ${this.owner}/${this.repo}/${path}`);
+    }
+  }
+};
+
+// src/github.ts
+var GitHubApiError = class _GitHubApiError extends Error {
+  constructor(message, code, statusCode) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.name = "GitHubApiError";
+    Object.setPrototypeOf(this, _GitHubApiError.prototype);
+  }
+};
+function isOctokitRequestError(error) {
+  return error instanceof Error && typeof error["status"] === "number";
+}
+function mapOctokitError(error, context) {
+  if (isOctokitRequestError(error)) {
+    const status = error.status;
+    if (status === 401 || status === 403) {
+      return new GitHubApiError(
+        `Permission denied: ${context}`,
+        "PERMISSION_DENIED",
+        status
+      );
+    }
+    if (status === 404) {
+      return new GitHubApiError(
+        `Not found: ${context}`,
+        "NOT_FOUND",
+        status
+      );
+    }
+    if (status === 409) {
+      return new GitHubApiError(
+        `Conflict: ${context}`,
+        "CONFLICT",
+        status
+      );
+    }
+    if (status === 422) {
+      return new GitHubApiError(
+        `Validation failed: ${context}`,
+        "CONFLICT",
+        status
+      );
+    }
+    if (status >= 500) {
+      return new GitHubApiError(
+        `Server error (${status}): ${context}`,
+        "SERVER_ERROR",
+        status
+      );
+    }
+    return new GitHubApiError(
+      `GitHub API error (${status}): ${context}`,
+      "SERVER_ERROR",
+      status
+    );
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return new GitHubApiError(`Network error: ${message}`, "NETWORK_ERROR");
+}
+
+export { GitHubApiError, GitHubConfigStore, GitHubFileLister, GitHubGitModule, GitHubRecordStore, isOctokitRequestError, mapOctokitError };
+//# sourceMappingURL=github.js.map
+//# sourceMappingURL=github.js.map