@gitgov/core 2.1.2 → 2.2.0

package/README.md

@@ -16,6 +16,8 @@ pnpm add @gitgov/core
 
 The SDK uses dependency injection. Each adapter receives its dependencies via constructor.
 
+### Filesystem Backend (CLI, local development)
+
 ```typescript
 import { Adapters, Store, EventBus } from '@gitgov/core';
 import { FsRecordStore } from '@gitgov/core/fs';
@@ -42,6 +44,40 @@ const task = await backlog.createTask(
 );
 ```
 
+### GitHub API Backend
+
+For SaaS, Forge apps, or GitHub Actions — no filesystem needed:
+
+```typescript
+import { Octokit } from '@octokit/rest';
+import {
+  GitHubRecordStore,
+  GitHubConfigStore,
+  GitHubGitModule,
+  GitHubFileLister,
+} from '@gitgov/core/github';
+import type { TaskRecord } from '@gitgov/core';
+
+const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
+const repoOpts = { owner: 'my-org', repo: 'my-repo', basePath: '.gitgov/tasks' };
+
+const taskStore = new GitHubRecordStore<TaskRecord>(repoOpts, octokit);
+
+// Read — returns parsed JSON, caches SHA for subsequent writes
+const task = await taskStore.get('task-001');
+
+// Write — returns { commitSha } from the created commit
+const result = await taskStore.put('task-002', newTask);
+
+// Atomic batch — single commit for N records (requires GitHubGitModule)
+const gitModule = new GitHubGitModule({ owner: 'my-org', repo: 'my-repo' }, octokit);
+const batchStore = new GitHubRecordStore<TaskRecord>(repoOpts, octokit, gitModule);
+await batchStore.putMany([
+  { id: 'task-003', value: task3 },
+  { id: 'task-004', value: task4 },
+]);
+```
+
 ## Architecture
 
 ```mermaid
@@ -56,13 +92,20 @@ graph LR
         Modules --> Records
     end
 
-    subgraph "@gitgov/core/fs — I/O"
+    subgraph "@gitgov/core/fs — Local I/O"
         FsStore["FsRecordStore"]
         FsGit["LocalGitModule"]
         FsLint["FsLintModule"]
         FsOther["FsKeyProvider, FsFileLister, ..."]
     end
 
+    subgraph "@gitgov/core/github — GitHub API"
+        GhStore["GitHubRecordStore"]
+        GhGit["GitHubGitModule"]
+        GhConfig["GitHubConfigStore"]
+        GhFiles["GitHubFileLister"]
+    end
+
     subgraph "@gitgov/core/memory — Testing"
         MemStore["MemoryRecordStore"]
         MemGit["MemoryGitModule"]
@@ -70,25 +113,29 @@ graph LR
     end
 
     Adapters -.->|DI| FsStore
+    Adapters -.->|DI| GhStore
     Adapters -.->|DI| MemStore
 
     CLI["@gitgov/cli"] --> Adapters
     SaaS["@gitgov/saas-api"] --> Adapters
+    Forge["Forge Apps"] --> Adapters
 
     style Adapters fill:#e8f5e8,stroke:#4caf50,stroke-width:2px
     style FsStore fill:#e3f2fd,stroke:#1976d2
+    style GhStore fill:#f3e5f5,stroke:#7b1fa2
     style MemStore fill:#fff3e0,stroke:#f57c00
 ```
 
-### 3 Export Paths
+### 4 Export Paths
 
 | Import | Contents | I/O |
 |--------|----------|-----|
 | `@gitgov/core` | Interfaces, types, pure logic, factories, validators | No |
-| `@gitgov/core/fs` | Filesystem implementations (FsRecordStore, LocalGitModule, FsLintModule, ...) | Yes |
+| `@gitgov/core/fs` | Filesystem implementations (FsRecordStore, LocalGitModule, FsLintModule, ...) | Local |
+| `@gitgov/core/github` | GitHub API implementations (GitHubRecordStore, GitHubGitModule, GitHubConfigStore, GitHubFileLister) | Remote |
 | `@gitgov/core/memory` | In-memory implementations for testing (MemoryRecordStore, MemoryGitModule, ...) | No |
 
-The root import (`@gitgov/core`) never imports `fs`, `path`, or `child_process`.
+The root import (`@gitgov/core`) never imports `fs`, `path`, `child_process`, or `@octokit/rest`.
 
 ### Record Symmetry
 
@@ -128,8 +175,8 @@ Adapters are orchestrators that compose modules. All receive dependencies via co
 | `record_factories/` | Factories with defaults for creating records |
 | `record_validations/` | Business validators (above schema) |
 | `record_schemas/` | JSON Schemas + schema cache + errors |
-| `record_store/` | `RecordStore<T>` interface (impl in fs/memory) |
-| `config_store/` | Storage for project config.json |
+| `record_store/` | `RecordStore<V, R, O>` interface (impl in fs/memory/github) |
+| `config_store/` | Storage for project config.json (impl in fs/github) |
 | `config_manager/` | Typed access to config.json (versioned in git) |
 | `session_store/` | Storage for .session.json |
 | `session_manager/` | Typed access to .session.json (ephemeral, not versioned) |

package/dist/src/{agent_runner-ByOUWOt6.d.ts → agent_runner-Cs5HXt4h.d.ts}

@@ -1,4 +1,5 @@
-import { m as IConfigManager, C as ConfigStore, G as GitGovConfig, n as SyncConfig, o as SyncDefaults, k as AuditState, l as AuditStateUpdate, h as ISessionManager, S as SessionStore, a as GitGovSession, A as ActorState, i as SyncPreferencesUpdate, K as KeyProvider, s as FileLister, F as FsFileListerOptions, r as FileListOptions, t as FileStats, R as RecordStore, I as IGitModule } from './index--ahcnsG3.js';
+import { I as ISessionManager, S as SessionStore, G as GitGovSession, A as ActorState, a as SyncPreferencesUpdate, K as KeyProvider } from './key_provider-CRpHFGjN.js';
+import { l as IConfigManager, C as ConfigStore, G as GitGovConfig, S as SyncConfig, m as SyncDefaults, A as AuditState, k as AuditStateUpdate, h as FileLister, F as FsFileListerOptions, i as FileListOptions, j as FileStats, R as RecordStore, a as IGitModule } from './index-D1RVufxB.js';
 
 /**
  * ConfigManager - Project Configuration Manager

package/dist/src/fs.d.ts

@@ -1,7 +1,8 @@
-import { R as RecordStore, C as ConfigStore, G as GitGovConfig, S as SessionStore, a as GitGovSession, I as IGitModule, b as GitModuleDependencies, E as ExecOptions, c as ExecResult, d as ChangedFile, e as GetCommitHistoryOptions, f as CommitInfo, g as CommitAuthor } from './index--ahcnsG3.js';
-export { F as FsFileListerOptions } from './index--ahcnsG3.js';
-import { C as ConfigManager, S as SessionManager, I as ILintModule, L as LintOptions, a as LintReport, F as FixRecordOptions, b as FixReport, R as RecordStores, c as IIndexerAdapter, G as GitGovRecord, d as LintRecordContext, e as LintResult, f as IProjectInitializer, E as EnvironmentValidation, g as ISyncStateModule, h as SyncStateModuleDependencies, i as StateDeltaFile, j as ConflictDiff, k as IntegrityViolation, A as AuditStateOptions, l as AuditStateReport, m as SyncStatePushOptions, n as SyncStatePushResult, o as SyncStatePullOptions, p as SyncStatePullResult, q as SyncStateResolveOptions, r as SyncStateResolveResult, s as IEventStream, t as IAgentRunner, P as ProtocolHandlerRegistry, u as AgentRunnerDependencies, v as RunOptions, w as AgentResponse } from './agent_runner-ByOUWOt6.js';
-export { z as FsFileLister, x as FsKeyProvider, y as FsKeyProviderOptions } from './agent_runner-ByOUWOt6.js';
+import { R as RecordStore, I as IdEncoder, C as ConfigStore, G as GitGovConfig, a as IGitModule, b as GitModuleDependencies, E as ExecOptions, c as ExecResult, d as ChangedFile, e as GetCommitHistoryOptions, f as CommitInfo, g as CommitAuthor } from './index-D1RVufxB.js';
+export { D as DEFAULT_ID_ENCODER, F as FsFileListerOptions } from './index-D1RVufxB.js';
+import { C as ConfigManager, S as SessionManager, I as ILintModule, L as LintOptions, a as LintReport, F as FixRecordOptions, b as FixReport, R as RecordStores, c as IIndexerAdapter, G as GitGovRecord, d as LintRecordContext, e as LintResult, f as IProjectInitializer, E as EnvironmentValidation, g as ISyncStateModule, h as SyncStateModuleDependencies, i as StateDeltaFile, j as ConflictDiff, k as IntegrityViolation, A as AuditStateOptions, l as AuditStateReport, m as SyncStatePushOptions, n as SyncStatePushResult, o as SyncStatePullOptions, p as SyncStatePullResult, q as SyncStateResolveOptions, r as SyncStateResolveResult, s as IEventStream, t as IAgentRunner, P as ProtocolHandlerRegistry, u as AgentRunnerDependencies, v as RunOptions, w as AgentResponse } from './agent_runner-Cs5HXt4h.js';
+export { z as FsFileLister, x as FsKeyProvider, y as FsKeyProviderOptions } from './agent_runner-Cs5HXt4h.js';
+import { S as SessionStore, G as GitGovSession } from './key_provider-CRpHFGjN.js';
 
 /**
  * Serializer for FsRecordStore - allows custom serialization
@@ -10,21 +11,6 @@ interface Serializer {
     stringify: (value: unknown) => string;
     parse: <T>(text: string) => T;
 }
-/**
- * IdEncoder for transforming IDs to filesystem-safe filenames
- * Useful for characters not allowed in filesystem (e.g., `:` on Windows)
- */
-interface IdEncoder {
-    /** Transform ID to filename-safe string */
-    encode: (id: string) => string;
-    /** Recover original ID from filename */
-    decode: (encoded: string) => string;
-}
-/**
- * Default encoder: `:` → `_` (for IDs like "human:camilo")
- * Reversible because IDs cannot contain `_` (see id_generator.ts)
- */
-declare const DEFAULT_ID_ENCODER: IdEncoder;
 /**
  * Options for FsRecordStore
  */
@@ -63,6 +49,10 @@ declare class FsRecordStore<T> implements RecordStore<T> {
     private getFilePath;
     get(id: string): Promise<T | null>;
     put(id: string, value: T): Promise<void>;
+    putMany(entries: Array<{
+        id: string;
+        value: T;
+    }>): Promise<void>;
     delete(id: string): Promise<void>;
     list(): Promise<string[]>;
     exists(id: string): Promise<boolean>;
@@ -920,6 +910,7 @@ declare class LocalGitModule implements IGitModule {
      */
     add(filePaths: string[], options?: {
         force?: boolean;
+        contentMap?: Record<string, string>;
     }): Promise<void>;
     /**
      * Removes files from both working directory and staging area
@@ -1366,4 +1357,4 @@ declare class FsAgentRunner implements IAgentRunner {
  */
 declare function createAgentRunner(deps: AgentRunnerDependencies): IAgentRunner;
 
-export { DEFAULT_ID_ENCODER, type FileSystem, FsAgentRunner, AgentRunnerDependencies as FsAgentRunnerDependencies, FsConfigStore, type FsFixOptions, FsLintModule, type FsLintModuleDependencies, type FsLintOptions, FsProjectInitializer, FsRecordStore, FsSessionStore, FsSyncStateModule, FsWatcherStateModule, LocalGitModule as GitModule, GitModuleDependencies, type IFsLintModule, IGitModule, LocalGitModule, createAgentRunner, createConfigManager, createSessionManager, findGitgovRoot, findProjectRoot, getGitgovPath, isGitgovProject, resetDiscoveryCache };
+export { type FileSystem, FsAgentRunner, AgentRunnerDependencies as FsAgentRunnerDependencies, FsConfigStore, type FsFixOptions, FsLintModule, type FsLintModuleDependencies, type FsLintOptions, FsProjectInitializer, FsRecordStore, FsSessionStore, FsSyncStateModule, FsWatcherStateModule, LocalGitModule as GitModule, GitModuleDependencies, type IFsLintModule, IGitModule, LocalGitModule, createAgentRunner, createConfigManager, createSessionManager, findGitgovRoot, findProjectRoot, getGitgovPath, isGitgovProject, resetDiscoveryCache };

package/dist/src/fs.js

@@ -16,10 +16,14 @@ import os from 'os';
 import chokidar from 'chokidar';
 
 // src/record_store/fs/fs_record_store.ts
+
+// src/record_store/record_store.ts
 var DEFAULT_ID_ENCODER = {
   encode: (id) => id.replace(/:/g, "_"),
   decode: (encoded) => encoded.replace(/_/g, ":")
 };
+
+// src/record_store/fs/fs_record_store.ts
 var DEFAULT_SERIALIZER = {
   stringify: (value) => JSON.stringify(value, null, 2),
   parse: (text) => JSON.parse(text)
@@ -70,6 +74,11 @@ var FsRecordStore = class {
     const content = this.serializer.stringify(value);
     await fs.writeFile(filePath, content, "utf-8");
   }
+  async putMany(entries) {
+    for (const { id, value } of entries) {
+      await this.put(id, value);
+    }
+  }
   async delete(id) {
     const filePath = this.getFilePath(id);
     try {