@gitgov/core 2.1.2 → 2.2.0

package/dist/src/github.d.ts

@@ -0,0 +1,472 @@
+import { Octokit } from '@octokit/rest';
+export { Octokit, RestEndpointMethodTypes } from '@octokit/rest';
+import { h as FileLister, i as FileListOptions, j as FileStats, I as IdEncoder, R as RecordStore, a as IGitModule, d as ChangedFile, e as GetCommitHistoryOptions, f as CommitInfo, g as CommitAuthor, E as ExecOptions, c as ExecResult, C as ConfigStore, G as GitGovConfig } from './index-D1RVufxB.js';
+
+/**
+ * Types for GitHubFileLister module.
+ *
+ * @module file_lister/github/github_file_lister.types
+ */
+/**
+ * Configuration options for GitHubFileLister.
+ * Auth and API base URL are configured on the Octokit instance, not here.
+ */
+type GitHubFileListerOptions = {
+    /** GitHub repository owner (user or org) */
+    owner: string;
+    /** GitHub repository name */
+    repo: string;
+    /** Git ref to use (branch, tag, or SHA). Default: 'gitgov-state' */
+    ref?: string;
+    /** Base path within the repo to scope operations. Default: '' (repo root) */
+    basePath?: string;
+};
+
+/**
+ * GitHubFileLister - GitHub REST API implementation of FileLister
+ *
+ * Provides file listing and reading operations via GitHub's REST API
+ * for SaaS environments where direct filesystem access is not available.
+ *
+ * Uses the Git Trees API for listing (with caching) and the Contents API
+ * for reading individual files. Falls back to the Blobs API for files
+ * larger than 1MB where the Contents API returns null content.
+ *
+ * @module file_lister/github/github_file_lister
+ */
+
+/**
+ * GitHubFileLister - GitHub REST API FileLister implementation.
+ *
+ * Implements the FileLister interface using GitHub's REST API endpoints:
+ * - Trees API for listing files (cached)
+ * - Contents API for reading, stat, and exists
+ * - Blobs API as fallback for large files (>1MB)
+ *
+ * @example
+ * ```typescript
+ * import { Octokit } from '@octokit/rest';
+ * const octokit = new Octokit({ auth: 'ghp_xxx' });
+ * const lister = new GitHubFileLister({
+ *   owner: 'myorg',
+ *   repo: 'myrepo',
+ *   ref: 'gitgov-state',
+ *   basePath: '.gitgov',
+ * }, octokit);
+ *
+ * const files = await lister.list(['**\/*.ts']);
+ * const content = await lister.read('config.json');
+ * ```
+ */
+declare class GitHubFileLister implements FileLister {
+    private readonly owner;
+    private readonly repo;
+    private readonly ref;
+    private readonly basePath;
+    private readonly octokit;
+    /** Cached tree entries from the Trees API */
+    private treeCache;
+    constructor(options: GitHubFileListerOptions, octokit: Octokit);
+    /**
+     * [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.
+     */
+    list(patterns: string[], options?: FileListOptions): Promise<string[]>;
+    /**
+     * [EARS-A2] Checks if a file exists via Contents API.
+     * [EARS-B4] Returns false for 404 responses.
+     */
+    exists(filePath: string): Promise<boolean>;
+    /**
+     * [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).
+     */
+    read(filePath: string): Promise<string>;
+    /**
+     * [EARS-A4] Gets file statistics via Contents API.
+     * Returns size from API, mtime as 0 (not available via Contents API), isFile as true.
+     */
+    stat(filePath: string): Promise<FileStats>;
+    /**
+     * Builds the full file path including basePath prefix.
+     */
+    private buildFullPath;
+    /**
+     * [EARS-B6] Fetches and caches the full repository tree.
+     * [EARS-C3] Throws READ_ERROR if the tree response is truncated.
+     */
+    private fetchTree;
+    /**
+     * [EARS-B7] Reads file content via the Blobs API (fallback for >1MB files).
+     */
+    private readViaBlobs;
+}
+
+/**
+ * Options for GitHubRecordStore.
+ * Auth and API base URL are configured on the Octokit instance, not here.
+ */
+type GitHubRecordStoreOptions = {
+    /** GitHub repository owner (user or org) */
+    owner: string;
+    /** GitHub repository name */
+    repo: string;
+    /** Branch ref (default: 'gitgov-state') */
+    ref?: string;
+    /** Base directory path in the repo (e.g., '.gitgov/actors') */
+    basePath: string;
+    /** File extension for records (default: '.json') */
+    extension?: string;
+    /** ID encoder for filename-safe IDs (default: undefined = no encoding) */
+    idEncoder?: IdEncoder;
+};
+/**
+ * Result returned by write operations (put, putMany, delete) on GitHubRecordStore.
+ * Contains the commit SHA from the GitHub API response.
+ */
+type GitHubWriteResult = {
+    /** SHA of the commit created by the write operation */
+    commitSha?: string;
+};
+/**
+ * Options for write operations on GitHubRecordStore.
+ */
+type GitHubWriteOpts = {
+    /** Custom commit message (default: auto-generated) */
+    commitMessage?: string;
+};
+
+/**
+ * GitHubRecordStore<V> - GitHub Contents API implementation of RecordStore<V, GitHubWriteResult, GitHubWriteOpts>
+ *
+ * Persists records as JSON files in a GitHub repository via Octokit.
+ * Supports SHA caching to avoid redundant GET calls before PUT/DELETE.
+ */
+declare class GitHubRecordStore<V> implements RecordStore<V, GitHubWriteResult, GitHubWriteOpts> {
+    private readonly owner;
+    private readonly repo;
+    private readonly ref;
+    private readonly basePath;
+    private readonly extension;
+    private readonly idEncoder;
+    private readonly octokit;
+    /** SHA cache keyed by full file path (basePath/encoded + extension) */
+    private readonly shaCache;
+    /** IGitModule dependency for putMany() atomic commits. Optional — only needed for putMany(). */
+    private readonly gitModule;
+    constructor(options: GitHubRecordStoreOptions, octokit: Octokit, gitModule?: IGitModule);
+    get(id: string): Promise<V | null>;
+    put(id: string, value: V, opts?: GitHubWriteOpts): Promise<GitHubWriteResult>;
+    /**
+     * [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.
+     */
+    putMany(entries: Array<{
+        id: string;
+        value: V;
+    }>, opts?: GitHubWriteOpts): Promise<GitHubWriteResult>;
+    delete(id: string, opts?: GitHubWriteOpts): Promise<GitHubWriteResult>;
+    list(): Promise<string[]>;
+    exists(id: string): Promise<boolean>;
+    private validateId;
+    private buildFilePath;
+}
+
+/**
+ * Types for GitHubGitModule.
+ * All EARS prefixes map to github_git_module.md
+ */
+/**
+ * Configuration for GitHubGitModule.
+ * All operations target the specified owner/repo via GitHub REST API.
+ * Note: defaultBranch (not ref) because GitModule tracks which branch
+ * operations target, switchable via checkoutBranch().
+ */
+type GitHubGitModuleOptions = {
+    /** GitHub repository owner (user or organization) */
+    owner: string;
+    /** GitHub repository name */
+    repo: string;
+    /** Default branch name (default: 'gitgov-state') */
+    defaultBranch?: string;
+};
+
+/**
+ * GitHubGitModule - GitHub REST API implementation of IGitModule
+ *
+ * Implements IGitModule for SaaS environments where direct filesystem
+ * and git CLI are not available. Uses GitHub REST API via Octokit for all operations.
+ *
+ * Method categories:
+ * - Category A (Implement): Real API calls — getFileContent, getCommitHash, etc.
+ * - Category B (No-op): Return sensible defaults — push, fetch, stash, etc.
+ * - Category C (Not Supported): Throw GitError — rebase, resetHard, etc.
+ *
+ * All EARS prefixes map to github_git_module.md
+ *
+ * @module git/github
+ */
+
+declare class GitHubGitModule implements IGitModule {
+    private readonly owner;
+    private readonly repo;
+    private readonly defaultBranch;
+    private readonly octokit;
+    /** Staging buffer: path → content (null = delete) */
+    private stagingBuffer;
+    /** Active ref for operations (can be changed via checkoutBranch) */
+    private activeRef;
+    constructor(options: GitHubGitModuleOptions, octokit: Octokit);
+    /** Category C: Not supported via GitHub API */
+    private notSupported;
+    /**
+     * [EARS-A1] Read file content via Contents API + base64 decode
+     * [EARS-A2] Fallback to Blobs API for files >1MB
+     */
+    getFileContent(commitHash: string, filePath: string): Promise<string>;
+    /**
+     * [EARS-A3] Get commit SHA from branch via Refs API
+     * [EARS-B4] Return SHA directly if already a 40-char hex
+     */
+    getCommitHash(ref?: string): Promise<string>;
+    /**
+     * [EARS-A4] List changed files via Compare API
+     */
+    getChangedFiles(fromCommit: string, toCommit: string, pathFilter: string): Promise<ChangedFile[]>;
+    /**
+     * [EARS-A5] Get commit history via Commits API
+     */
+    getCommitHistory(branch: string, options?: GetCommitHistoryOptions): Promise<CommitInfo[]>;
+    /**
+     * [EARS-B3] Get commit history between two commits via Compare API
+     */
+    getCommitHistoryRange(fromHash: string, toHash: string, options?: GetCommitHistoryOptions): Promise<CommitInfo[]>;
+    /**
+     * [EARS-A6] Get commit message via Commits API
+     */
+    getCommitMessage(commitHash: string): Promise<string>;
+    /**
+     * [EARS-B1] Check if branch exists via Branches API
+     */
+    branchExists(branchName: string): Promise<boolean>;
+    /**
+     * [EARS-B2] List remote branches via Branches API
+     * remoteName is ignored — repo itself is the implicit remote
+     */
+    listRemoteBranches(_remoteName: string): Promise<string[]>;
+    /** [EARS-C1] Read file content and store in staging buffer */
+    add(filePaths: string[], options?: {
+        force?: boolean;
+        contentMap?: Record<string, string>;
+    }): Promise<void>;
+    /** [EARS-C2] Mark files as deleted in staging buffer */
+    rm(filePaths: string[]): Promise<void>;
+    /** [EARS-C7] Return staged file paths from buffer */
+    getStagedFiles(): Promise<string[]>;
+    /**
+     * [EARS-C6] Create branch via Refs API POST
+     */
+    createBranch(branchName: string, startPoint?: string): Promise<void>;
+    /**
+     * 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)
+     */
+    private commitInternal;
+    /**
+     * [EARS-C3] Commit staged changes via 6-step atomic transaction
+     * [EARS-C5] Throws if staging buffer is empty
+     */
+    commit(message: string, author?: CommitAuthor): Promise<string>;
+    /** [EARS-D5] exec not supported in API mode */
+    exec(_command: string, _args: string[], _options?: ExecOptions): Promise<ExecResult>;
+    /** No-op: repos are created via GitHub API, not initialized locally */
+    init(): Promise<void>;
+    /** [EARS-D1] Return virtual path representing the repo */
+    getRepoRoot(): Promise<string>;
+    /** [EARS-D1] Return active ref (starts as defaultBranch) */
+    getCurrentBranch(): Promise<string>;
+    /** No-op: git config doesn't apply to GitHub API */
+    setConfig(_key: string, _value: string, _scope?: 'local' | 'global' | 'system'): Promise<void>;
+    /** [EARS-D1] Return true if staging buffer has entries */
+    hasUncommittedChanges(_pathFilter?: string): Promise<boolean>;
+    /** No-op: GitHub API doesn't have rebase-in-progress concept */
+    isRebaseInProgress(): Promise<boolean>;
+    /** [EARS-D1] GitHub repos always have 'origin' conceptually */
+    isRemoteConfigured(_remoteName: string): Promise<boolean>;
+    /** No-op: always 'origin' */
+    getBranchRemote(_branchName: string): Promise<string | null>;
+    /** No-op: GitHub API handles merges atomically */
+    getConflictedFiles(): Promise<string[]>;
+    /** [EARS-D2] Update activeRef for subsequent operations */
+    checkoutBranch(branchName: string): Promise<void>;
+    /** No-op: GitHub API doesn't have stash concept */
+    stash(_message?: string): Promise<string | null>;
+    /** No-op */
+    stashPop(): Promise<boolean>;
+    /** No-op */
+    stashDrop(_stashHash?: string): Promise<void>;
+    /** No-op: API always fresh */
+    fetch(_remote: string): Promise<void>;
+    /** No-op: API mode */
+    pull(_remote: string, _branchName: string): Promise<void>;
+    /** No-op: API mode */
+    pullRebase(_remote: string, _branchName: string): Promise<void>;
+    /** [EARS-D4] No-op: commits via API are already remote */
+    push(_remote: string, _branchName: string): Promise<void>;
+    /** [EARS-D4] No-op: commits via API are already remote */
+    pushWithUpstream(_remote: string, _branchName: string): Promise<void>;
+    /** No-op: API mode */
+    setUpstream(_branchName: string, _remote: string, _remoteBranch: string): Promise<void>;
+    /** No-op */
+    rebaseAbort(): Promise<void>;
+    /** [EARS-D1] Delegates to commitInternal, allowing empty staging buffer */
+    commitAllowEmpty(message: string, author?: CommitAuthor): Promise<string>;
+    /** [EARS-D3] Not supported via GitHub API */
+    rebase(_targetBranch: string): Promise<void>;
+    /** [EARS-D3] Not supported via GitHub API */
+    rebaseContinue(): Promise<string>;
+    /** [EARS-D3] Not supported via GitHub API */
+    resetHard(_target: string): Promise<void>;
+    /** [EARS-D3] Not supported via GitHub API */
+    checkoutOrphanBranch(_branchName: string): Promise<void>;
+    /** [EARS-D3] Not supported via GitHub API */
+    checkoutFilesFromBranch(_sourceBranch: string, _filePaths: string[]): Promise<void>;
+    /** [EARS-D3] Not supported via GitHub API */
+    getMergeBase(_branchA: string, _branchB: string): Promise<string>;
+}
+
+/**
+ * GitHubConfigStore Types
+ *
+ * Configuration types for the GitHub-backed ConfigStore implementation.
+ * Auth (token) and base URL are configured via the Octokit instance.
+ */
+/**
+ * Options for constructing a GitHubConfigStore instance.
+ * Auth and API base URL are configured on the Octokit instance, not here.
+ */
+type GitHubConfigStoreOptions = {
+    /** GitHub repository owner (user or organization) */
+    owner: string;
+    /** GitHub repository name */
+    repo: string;
+    /** Branch to read from / write to (default: 'gitgov-state'). Must be a branch name for saves. */
+    ref?: string;
+    /** Base path within the repo (default: '.gitgov') */
+    basePath?: string;
+};
+/**
+ * Result returned by saveConfig on GitHubConfigStore.
+ * Contains the commit SHA from the GitHub API response.
+ */
+type GitHubSaveResult = {
+    /**
+     * SHA of the commit created by the save operation.
+     * Always present — saveConfig either creates a commit (success) or throws (failure).
+     * Contrast with GitHubWriteResult.commitSha which is optional (idempotent delete).
+     */
+    commitSha: string;
+};
+
+/**
+ * GitHubConfigStore - GitHub Contents API implementation of ConfigStore
+ *
+ * Persists config.json to a GitHub repository via Octokit.
+ * Used by SaaS/server-side environments where the project lives on GitHub
+ * and direct filesystem access is not available.
+ *
+ * Key behaviors:
+ * - loadConfig: GET contents, base64 decode, JSON parse. Fail-safe on 404/invalid JSON.
+ * - saveConfig: JSON serialize + base64 encode, PUT contents with optional SHA for updates.
+ * - Caches blob SHA from loadConfig for subsequent saveConfig (optimistic concurrency).
+ */
+
+declare class GitHubConfigStore implements ConfigStore<GitHubSaveResult> {
+    private readonly owner;
+    private readonly repo;
+    private readonly ref;
+    private readonly basePath;
+    private readonly octokit;
+    /** Cached blob SHA from the last loadConfig call, used for PUT updates */
+    private cachedSha;
+    constructor(options: GitHubConfigStoreOptions, 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.
+     */
+    loadConfig(): Promise<GitGovConfig | null>;
+    /**
+     * 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.
+     */
+    saveConfig(config: GitGovConfig): Promise<GitHubSaveResult>;
+}
+
+/**
+ * GitHub API implementations for @gitgov/core/github
+ *
+ * This module exports all implementations that use GitHub REST API.
+ * Suitable for SaaS environments, Forge apps, GitHub Actions,
+ * and any context without local filesystem access.
+ *
+ * Usage:
+ *   import { GitHubFileLister, GitHubRecordStore, GitHubGitModule, GitHubConfigStore } from '@gitgov/core/github';
+ *
+ * Each implementation receives an `Octokit` instance for testability and shared auth/base-URL config.
+ */
+
+/**
+ * Error codes for GitHub API errors.
+ * Semantic codes that abstract HTTP status codes.
+ */
+type GitHubApiErrorCode = 'PERMISSION_DENIED' | 'NOT_FOUND' | 'CONFLICT' | 'SERVER_ERROR' | 'NETWORK_ERROR' | 'INVALID_ID' | 'INVALID_RESPONSE';
+/**
+ * Typed error for GitHub API operations.
+ * Used by RecordStore, ConfigStore, and other modules that
+ * interact with GitHub Contents API directly.
+ */
+declare class GitHubApiError extends Error {
+    /** Semantic error code */
+    readonly code: GitHubApiErrorCode;
+    /** HTTP status code (if applicable) */
+    readonly statusCode?: number | undefined;
+    constructor(message: string, 
+    /** Semantic error code */
+    code: GitHubApiErrorCode, 
+    /** HTTP status code (if applicable) */
+    statusCode?: number | undefined);
+}
+/**
+ * Type guard: checks if an error is an Octokit RequestError (duck-typing).
+ * Avoids runtime import of ESM-only @octokit/request-error.
+ */
+declare function isOctokitRequestError(error: unknown): error is {
+    status: number;
+    message: string;
+};
+/**
+ * Maps Octokit RequestError (and unknown errors) to GitHubApiError.
+ * Shared utility used by all GitHub backend modules.
+ */
+declare function mapOctokitError(error: unknown, context: string): GitHubApiError;
+
+export { GitHubApiError, type GitHubApiErrorCode, GitHubConfigStore, type GitHubConfigStoreOptions, GitHubFileLister, type GitHubFileListerOptions, GitHubGitModule, type GitHubGitModuleOptions, GitHubRecordStore, type GitHubRecordStoreOptions, type GitHubSaveResult, type GitHubWriteOpts, type GitHubWriteResult, isOctokitRequestError, mapOctokitError };