docs: add CLAUDE.md project instructions
Co-Authored-By: Virgil <virgil@lethean.io>
This commit is contained in:
Snider
parent
b263a9ea7d
commit
e5f4bbbe80
1 changed files with 54 additions and 28 deletions
82
CLAUDE.md
82
CLAUDE.md
|
|
@ -1,52 +1,78 @@
|
|||
# CLAUDE.md — go-scm Agent Instructions
|
||||
# CLAUDE.md
|
||||
|
||||
You are a dedicated domain expert for `forge.lthn.ai/core/go-scm`. Virgil orchestrates tasks via Forgejo issues. Pick up tasks in issue order, mark complete, commit and push.
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## What This Package Does
|
||||
## What This Is
|
||||
|
||||
SCM integration and data collection for the Lethean ecosystem. Three packages: `forge/` (Forgejo API client), `gitea/` (Gitea API client), `collect/` (data collection).
|
||||
SCM integration and data collection library for the Lethean ecosystem (`forge.lthn.ai/core/go-scm`). Provides Forgejo/Gitea API clients, an AgentCI pipeline for automated PR lifecycle, pluggable data collectors, and workspace management (repos registry, manifests with ed25519 signing, marketplace, plugin system).
|
||||
|
||||
**Extracted to other repos:** `agentci/` + `jobrunner/` → `core/go-agent`, `git/` → `core/go-git`.
|
||||
|
||||
**Note:** `forge/` is still used by `core/go-agent` as a dependency. `core/go-forge` is a separate, full API client with a different interface.
|
||||
Virgil orchestrates tasks via Forgejo issues. Pick up tasks in issue order, mark complete, commit and push.
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
go test ./... # Run all tests
|
||||
go test -v -run TestName ./... # Single test
|
||||
go test -race ./... # Race detector
|
||||
go vet ./... # Static analysis
|
||||
go build ./... # Compile all packages
|
||||
go test ./... # Run all tests
|
||||
go test -v -run TestName ./forge/ # Single test in a package
|
||||
go test -race ./... # Race detector (important for git/, jobrunner/, collect/)
|
||||
go vet ./... # Static analysis
|
||||
golangci-lint run ./... # Lint (govet, errcheck, staticcheck, unused, gocritic, gofmt)
|
||||
```
|
||||
|
||||
If using the `core` CLI:
|
||||
|
||||
```bash
|
||||
core go qa # fmt + vet + lint + test
|
||||
core go qa full # + race, vuln, security
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
Five subsystems — see `docs/architecture.md` for full detail:
|
||||
|
||||
1. **Forge Clients** (`forge/`, `gitea/`) — thin wrappers over Forgejo/Gitea SDKs. Auth resolves: config file → env vars (`FORGE_URL`/`FORGE_TOKEN`) → flags → default localhost. All list methods handle pagination; `*Iter` variants yield lazily via `iter.Seq2`. SDK limitation: Forgejo SDK v2 does not accept `context.Context`.
|
||||
2. **AgentCI Pipeline** (`agentci/`, `jobrunner/`, `jobrunner/forgejo/`, `jobrunner/handlers/`) — poll-dispatch-journal loop. `ForgejoSource` finds epic issues with checklists, emits `PipelineSignal` per unchecked child, handlers match and execute in registration order (first match wins). Includes Clotho Protocol dual-run verification.
|
||||
3. **Data Collection** (`collect/`) — `Collector` interface with built-in scrapers (GitHub via `gh` CLI, BitcoinTalk, CoinGecko, IACR/arXiv). `Excavator` orchestrates sequential runs with rate limiting and incremental state.
|
||||
4. **Workspace Management** (`repos/`, `manifest/`, `marketplace/`, `plugin/`) — `repos.yaml` multi-repo registry with topological sorting, `.core/manifest.yaml` with ed25519 signing, module marketplace with install/update/remove, CLI plugin system.
|
||||
5. **Git Operations** (`git/`) — parallel multi-repo status, push/pull. DI-integrated `Service` with query/task handlers.
|
||||
|
||||
CLI commands live in `cmd/forge/`, `cmd/gitea/`, `cmd/collect/`.
|
||||
|
||||
**Note:** `agentci/` + `jobrunner/` are being extracted to `core/go-agent`, `git/` to `core/go-git`. `forge/` is still used by `core/go-agent` as a dependency.
|
||||
|
||||
## Local Dependencies
|
||||
|
||||
Resolved via `replace` in go.mod or preferably via `go.work`:
|
||||
|
||||
| Module | Local Path |
|
||||
|--------|-----------|
|
||||
| `forge.lthn.ai/core/go` | `../go` |
|
||||
|
||||
## Key Types
|
||||
Use a Go workspace file (preferred over `replace` directives):
|
||||
|
||||
```go
|
||||
// forge/client.go
|
||||
type Client struct { api *forgejo.Client; url, token string }
|
||||
// ~/Code/go.work — includes all forge.lthn.ai/core/* modules
|
||||
```
|
||||
|
||||
Key dependencies: `core/go` (DI framework), `core/go-io` (filesystem abstraction), `core/go-log`, `core/go-config`, `core/go-i18n`, `core/go-crypt`.
|
||||
|
||||
## Test Patterns
|
||||
|
||||
Each subsystem has different test infrastructure — see `docs/development.md` for examples:
|
||||
|
||||
- **forge/, gitea/**: `httptest` mock server required (SDK does GET `/api/v1/version` on client construction). Always isolate config: `t.Setenv("HOME", t.TempDir())`.
|
||||
- **manifest/, marketplace/, plugin/, repos/**: Use `io.NewMockMedium()` to avoid filesystem interaction.
|
||||
- **git/**: Real temporary git repos via `t.TempDir()` + `exec.Command("git", ...)`.
|
||||
- **agentci/**: Pure unit tests, no mocks needed.
|
||||
- **jobrunner/**: Table-driven tests against `JobHandler` interface.
|
||||
- **collect/**: Mixed — pure functions test directly, HTTP-dependent use mock servers. `SetHTTPClient` for injection.
|
||||
|
||||
## Coding Standards
|
||||
|
||||
- **UK English**: colour, organisation, centre
|
||||
- **Tests**: testify assert/require, table-driven preferred, `_Good`/`_Bad`/`_Ugly` naming
|
||||
- **Conventional commits**: `feat(forge):`, `fix(gitea):`, `test(collect):`
|
||||
- **Co-Author**: `Co-Authored-By: Virgil <virgil@lethean.io>`
|
||||
- **UK English**: colour, organisation, centre, licence (noun), authorise, behaviour
|
||||
- **Tests**: testify assert/require, table-driven preferred, `_Good`/`_Bad`/`_Ugly` suffix naming
|
||||
- **Imports**: stdlib → `forge.lthn.ai/...` → third-party, each group separated by blank line
|
||||
- **Errors**: `"package.Func: context: %w"` or `log.E("package.Func", "context", err)` — no bare `fmt.Errorf`
|
||||
- **Conventional commits**: `feat(forge):`, `fix(gitea):`, `test(collect):`, `docs(agentci):`, `refactor(collect):`, `chore:`
|
||||
- **Co-Author trailer**: `Co-Authored-By: Virgil <virgil@lethean.io>`
|
||||
- **Licence**: EUPL-1.2
|
||||
- **Imports**: stdlib → forge.lthn.ai → third-party, each group separated by blank line
|
||||
- **Error pattern**: `"package.Func: context: %w"` — no bare `fmt.Errorf`
|
||||
|
||||
See `docs/development.md` for full standards and test patterns.
|
||||
|
||||
## Forge
|
||||
|
||||
- **Repo**: `forge.lthn.ai/core/go-scm`
|
||||
- **Push via SSH**: `git push origin main` (remote: `ssh://git@forge.lthn.ai:2223/core/go-scm.git`)
|
||||
- **CI**: Forgejo Actions — runs tests with race detector and coverage on push to main/dev and PRs to main
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue