diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..2e2b24a --- /dev/null +++ b/Home.md @@ -0,0 +1,112 @@ +# go-scm + +**Module:** `forge.lthn.ai/core/go-scm` +**Go:** 1.25.5 +**Licence:** EUPL-1.2 + +Multi-platform source control abstraction for the Core ecosystem. Provides unified Forgejo and Gitea clients, AgentCI orchestration via the Clotho Protocol, parallel git operations, a poll-dispatch job runner, and a data collection subsystem. + +## Package Structure + +| Package | Import Path | Purpose | +|---------|-------------|---------| +| `forge/` | `forge.lthn.ai/core/go-scm/forge` | Forgejo SDK wrapper -- repos, issues, PRs, labels, webhooks, organisations | +| `gitea/` | `forge.lthn.ai/core/go-scm/gitea` | Gitea SDK wrapper -- repos, issues, PRs, mirrors | +| `agentci/` | `forge.lthn.ai/core/go-scm/agentci` | Clotho Protocol orchestration, agent config, security utilities | +| `git/` | `forge.lthn.ai/core/go-scm/git` | Multi-repo parallel status, push, pull operations | +| `jobrunner/` | `forge.lthn.ai/core/go-scm/jobrunner` | Signal polling, handler dispatch, JSONL audit journal | +| `jobrunner/forgejo/` | `forge.lthn.ai/core/go-scm/jobrunner/forgejo` | Forgejo-specific job source (epic polling) | +| `jobrunner/handlers/` | `forge.lthn.ai/core/go-scm/jobrunner/handlers` | Built-in handlers: dispatch, completion, merge, draft publish, fix commands, tick parent | +| `collect/` | `forge.lthn.ai/core/go-scm/collect` | Data collection: GitHub issues, BitcoinTalk scraping, CoinGecko market data, IACR/arXiv papers | + +## Quick Start + +### Forgejo Client + +```go +import "forge.lthn.ai/core/go-scm/forge" + +// Create from explicit credentials +client, err := forge.New("https://forge.lthn.ai", "your-token") + +// Or resolve from config file / env vars / flags +client, err := forge.NewFromConfig("", "") + +// Use the client +user, err := client.GetCurrentUser() +issues, err := client.ListIssues("core", "go-scm", forge.ListIssuesOpts{State: "open"}) +``` + +### Gitea Client + +```go +import "forge.lthn.ai/core/go-scm/gitea" + +client, err := gitea.New("https://git.lthn.ai", "your-token") +repos, err := client.ListOrgRepos("Agentic") +``` + +### Multi-Repo Git Status + +```go +import "forge.lthn.ai/core/go-scm/git" + +statuses := git.Status(ctx, git.StatusOptions{ + Paths: []string{"/path/to/repo-a", "/path/to/repo-b"}, + Names: map[string]string{"/path/to/repo-a": "repo-a"}, +}) + +for _, s := range statuses { + if s.IsDirty() { + fmt.Printf("%s has %d modified, %d untracked files\n", s.Name, s.Modified, s.Untracked) + } +} +``` + +### Job Runner + +```go +import ( + "forge.lthn.ai/core/go-scm/jobrunner" + forgejoSource "forge.lthn.ai/core/go-scm/jobrunner/forgejo" + "forge.lthn.ai/core/go-scm/jobrunner/handlers" +) + +poller := jobrunner.NewPoller(jobrunner.PollerConfig{ + Sources: []jobrunner.JobSource{forgejoSource.New(cfg, forgeClient)}, + Handlers: []jobrunner.JobHandler{handlers.NewEnableAutoMergeHandler(forgeClient)}, + Journal: journal, + PollInterval: 60 * time.Second, +}) + +poller.Run(ctx) // Blocking poll-dispatch loop +``` + +## Dependencies + +| Dependency | Version | Purpose | +|-----------|---------|---------| +| `codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v2` | v2.2.0 | Forgejo API SDK | +| `code.gitea.io/sdk/gitea` | v0.23.2 | Gitea API SDK | +| `forge.lthn.ai/core/go` | workspace | Core framework (config, logging, services) | +| `golang.org/x/net` | v0.50.0 | HTML parsing for collect package | + +## Key Features + +- **Dual SCM support** -- identical patterns for Forgejo and Gitea with shared auth resolution +- **Clotho Protocol** -- dual-run verification for critical repositories, configurable per-agent +- **Epic-driven pipeline** -- polls epic issues, discovers child tasks, dispatches to agents via SSH +- **Built-in handlers** -- auto-merge, draft publishing, review dismissal, fix commands, parent checkbox ticking +- **Data collection** -- GitHub, BitcoinTalk, CoinGecko, IACR, arXiv with rate limiting and resume support +- **Parallel git ops** -- concurrent status checks across dozens of repositories +- **JSONL audit journal** -- date-partitioned, path-traversal-safe logging of all pipeline actions +- **Security hardened** -- path sanitisation, shell argument escaping, strict SSH, token masking + +## Wiki Pages + +- [[Forge-Client]] -- Forgejo API wrapper and configuration +- [[Gitea-Client]] -- Gitea API wrapper and configuration +- [[AgentCI-and-Clotho]] -- Agent orchestration and the Clotho Protocol +- [[Git-Operations]] -- Multi-repo git utilities and Core service integration +- [[Job-Runner]] -- Signal polling, handler dispatch, and built-in handlers +- [[Data-Collection]] -- GitHub, BitcoinTalk, market data, and paper collection