@gitgov/core 2.5.0 → 2.7.0

package/dist/src/github.d.ts

@@ -1,7 +1,8 @@
 import { Octokit } from '@octokit/rest';
 export { Octokit, RestEndpointMethodTypes } from '@octokit/rest';
-import { g as FileLister, h as FileListOptions, i as FileStats, I as IGitModule, c as ChangedFile, d as GetCommitHistoryOptions, e as CommitInfo, f as CommitAuthor, E as ExecOptions, b as ExecResult, C as ConfigStore, G as GitGovConfig } from './index-Bhc341pf.js';
-import { I as IdEncoder, R as RecordStore } from './record_store-BXKWqon5.js';
+import { h as FileLister, i as FileListOptions, j as FileStats, I 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-LULVRsCZ.js';
+import { I as IdEncoder, R as RecordStore, a as IRecordProjector } from './record_projection.types-Dz9YU3r9.js';
+import { C as ConfigManager, q as IIdentityAdapter, I as ILintModule, e as ISyncStateModule, j as SyncStatePushOptions, k as SyncStatePushResult, l as SyncStatePullOptions, m as SyncStatePullResult, f as StateDeltaFile, g as ConflictDiff, n as SyncStateResolveOptions, o as SyncStateResolveResult, h as IntegrityViolation, A as AuditStateOptions, i as AuditStateReport } from './sync_state-Bn_LogJ2.js';
 
 /**
  * Types for GitHubFileLister module.
@@ -422,6 +423,119 @@ declare class GitHubConfigStore implements ConfigStore<GitHubSaveResult> {
     saveConfig(config: GitGovConfig): Promise<GitHubSaveResult>;
 }
 
+/**
+ * Types for GithubSyncStateModule.
+ *
+ * Blueprint: github_sync_state_module.md §3.1
+ * @module sync_state/github_sync_state
+ */
+
+/**
+ * Dependencies for GithubSyncStateModule.
+ *
+ * Uses Octokit directly (not IGitModule) because:
+ * - GitHubGitModule has a stateful staging buffer that complicates the flow
+ * - Tree API recursive operations (getTree, compare) are not exposed in IGitModule
+ * - Direct Octokit control is simpler for atomic tree+commit+ref operations
+ */
+type GithubSyncStateDependencies = {
+    /** Octokit instance (authenticated) */
+    octokit: Octokit;
+    /** GitHub repo owner */
+    owner: string;
+    /** GitHub repo name */
+    repo: string;
+    /** Configuration manager (DI consistency — not actively used in initial implementation) */
+    config: ConfigManager;
+    /** Identity adapter (DI consistency — not actively used; lint handles validation internally) */
+    identity: IIdentityAdapter;
+    /** Lint module for record validation */
+    lint: ILintModule;
+    /** Record projector for re-indexing after pull */
+    indexer: IRecordProjector;
+};
+
+/**
+ * GithubSyncStateModule — ISyncStateModule via GitHub API (Octokit)
+ *
+ * Implements state synchronization between .gitgov/ records and a shared
+ * gitgov-state branch using the GitHub Trees/Commits/Refs API.
+ * No local filesystem or git CLI required.
+ *
+ * Blueprint: github_sync_state_module.md
+ * @module sync_state/github_sync_state
+ */
+
+/**
+ * [EARS-GS-A1..F2] GithubSyncStateModule
+ *
+ * Synchronizes .gitgov/ state with a GitHub remote via API.
+ * Uses optimistic concurrency (SHA-based) instead of rebase.
+ */
+declare class GithubSyncStateModule implements ISyncStateModule {
+    private readonly deps;
+    private lastKnownSha;
+    constructor(deps: GithubSyncStateDependencies);
+    /**
+     * [EARS-GS-A3] Returns the configured state branch name.
+     */
+    getStateBranchName(): Promise<string>;
+    /**
+     * [EARS-GS-A1] Creates gitgov-state branch if it does not exist.
+     * [EARS-GS-A2] Idempotent — no-op if branch already exists.
+     */
+    ensureStateBranch(): Promise<void>;
+    /**
+     * [EARS-GS-B1..B5] Push local .gitgov/ state to gitgov-state branch via API.
+     *
+     * Uses the 6-step atomic commit pattern:
+     * getRef → getCommit → createBlob → createTree → createCommit → updateRef
+     *
+     * Optimistic concurrency: if remote ref advanced since our read, updateRef
+     * fails with 422 → return conflictDetected: true.
+     */
+    pushState(options: SyncStatePushOptions): Promise<SyncStatePushResult>;
+    /**
+     * [EARS-GS-C1..C4] Pull remote state from gitgov-state branch.
+     *
+     * Fetches tree + blobs, updates lastKnownSha, triggers re-indexing.
+     */
+    pullState(options?: SyncStatePullOptions): Promise<SyncStatePullResult>;
+    /**
+     * [EARS-GS-D1..D3] Calculate file delta between known state and current remote.
+     */
+    calculateStateDelta(_sourceBranch: string): Promise<StateDeltaFile[]>;
+    /**
+     * Always empty — no local pending changes in API mode.
+     * In API mode there is no local filesystem; all state is remote.
+     */
+    getPendingChanges(): Promise<StateDeltaFile[]>;
+    /**
+     * Always false — no rebase in API mode.
+     */
+    isRebaseInProgress(): Promise<boolean>;
+    /**
+     * Always empty — no conflict markers in API mode.
+     */
+    checkConflictMarkers(_filePaths: string[]): Promise<string[]>;
+    /**
+     * Empty diff — no git-level conflict markers in API mode.
+     */
+    getConflictDiff(_filePaths?: string[]): Promise<ConflictDiff>;
+    /**
+     * [EARS-GS-E1..E2] Resolve conflict by pulling latest and retrying push.
+     */
+    resolveConflict(options: SyncStateResolveOptions): Promise<SyncStateResolveResult>;
+    /**
+     * No integrity violations in API mode (no rebase commits).
+     */
+    verifyResolutionIntegrity(): Promise<IntegrityViolation[]>;
+    /**
+     * [EARS-GS-F1..F2] Audit the remote gitgov-state branch.
+     */
+    auditState(options?: AuditStateOptions): Promise<AuditStateReport>;
+}
+
 /**
  * GitHub API implementations for @gitgov/core/github
  *
@@ -470,4 +584,4 @@ declare function isOctokitRequestError(error: unknown): error is {
  */
 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 };
+export { GitHubApiError, type GitHubApiErrorCode, GitHubConfigStore, type GitHubConfigStoreOptions, GitHubFileLister, type GitHubFileListerOptions, GitHubGitModule, type GitHubGitModuleOptions, GitHubRecordStore, type GitHubRecordStoreOptions, type GitHubSaveResult, type GitHubWriteOpts, type GitHubWriteResult, type GithubSyncStateDependencies, GithubSyncStateModule, isOctokitRequestError, mapOctokitError };