Compare commits
13 Commits
3b490271ef
...
v0.2.7
| Author | SHA1 | Date | |
|---|---|---|---|
|
60212fc5d2 | ||
|
|
dc907fb7e0 | ||
|
|
c4bd3396c4 | ||
|
|
11f86f5d99 | ||
|
|
f7076c9ac8 | ||
| e31fd3f023 | |||
|
|
3cccbfb8cb | ||
| 3648373333 | |||
|
|
eeefc626ed | ||
|
|
5545d6ab4b | ||
|
|
9013c8ff9c | ||
|
|
f26f922c96 | ||
| a414222610 |
@@ -36,9 +36,18 @@ These rules apply to every task across every project, regardless of harness.
|
||||
4. **Goal-driven execution.** Define clear success criteria up front for every task.
|
||||
Loop — implement, verify, refine — until those criteria are met. Don't claim
|
||||
completion without evidence (tests pass, command output, observed behavior).
|
||||
5. **Branch-per-task for multi-agent repos.** When another agent may be active on
|
||||
the same repo, create a branch (`agent/<description>`), commit there, and open a
|
||||
PR. Do not merge without explicit instruction from Mathias.
|
||||
5. **Trunk-Based Development — commit directly to main.** Every commit is one
|
||||
logical change (one tool, one fix, one test) with passing tests. Main is always
|
||||
deployable. Never create long-lived feature branches.
|
||||
|
||||
**Exception — parallel agents on same repo:** If another agent is known to be
|
||||
actively working on the same repo simultaneously, create a short-lived branch
|
||||
(`agent/<description>`), finish the task, and merge to main within the same
|
||||
session. Do not leave agent branches open between sessions.
|
||||
|
||||
**Exception — external contributor or client four-eyes requirement:** Use
|
||||
PR flow only when a human reviewer outside the project is required. Document
|
||||
the reason in PROJECT.md.
|
||||
|
||||
## Default stack
|
||||
|
||||
@@ -62,7 +71,10 @@ Exploratory: Rust, Zig — I'll tell you when I want these.
|
||||
- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return
|
||||
- **Naming**: stdlib conventions, no stuttering
|
||||
- **Architecture**: prefer stdlib over frameworks, constructor injection, env-var config parsed into typed structs
|
||||
- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), one concern per PR, PR describes *why* not *what*
|
||||
- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), commit directly to main,
|
||||
one logical change per commit, CI is the quality gate
|
||||
- **Never**: long-lived feature branches, PRs for solo work, direct push without
|
||||
passing `task check` locally first
|
||||
- **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config
|
||||
- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message
|
||||
|
||||
@@ -104,18 +116,64 @@ See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
|
||||
- **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
|
||||
- **klimatkollen** (`XT/`) — Swedish municipal climate data platform
|
||||
|
||||
## Knowledge base
|
||||
## Knowledge base — actively use it
|
||||
|
||||
When available, agents can query the shared knowledge base:
|
||||
A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions,
|
||||
hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems,
|
||||
Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional
|
||||
reference material — query it actively, not just when explicitly told.**
|
||||
|
||||
- **MCP**: `mcp://hyperguild.<TAILNET>.ts.net:3100/knowledge`
|
||||
- **HTTP**: `http://hyperguild.<TAILNET>.ts.net:3100/api/v1/search`
|
||||
### When to query (treat as a reflex)
|
||||
|
||||
<!-- TODO: replace <TAILNET> placeholder with the real Tailscale tailnet
|
||||
name once hyperguild is deployed. Until then, agents that try to
|
||||
reach the knowledge service on a host where it isn't running will
|
||||
get DNS NXDOMAIN, which is the desired fail-loudly behavior. -->
|
||||
- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`
|
||||
- **Before** starting a non-trivial task — search for prior art with the symptom
|
||||
AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours.
|
||||
- **When debugging** — search for the error string, the stack frame, the affected
|
||||
service. Past you may have already paid this tax.
|
||||
- **Before adopting** a pattern, library, framework, or model name — check if it
|
||||
was tried and rejected, or what the integration footguns are.
|
||||
- **When making architectural decisions** — search for the domain + "ADR" or
|
||||
"decision" to find prior reasoning before re-deriving it.
|
||||
- **When a recommendation feels novel** — challenge yourself: "has this been
|
||||
documented?" The brain often has it.
|
||||
|
||||
### When to write
|
||||
|
||||
After you discover something that **future-you would forget** and that **isn't
|
||||
recoverable from the code, git log, or PR description alone**:
|
||||
|
||||
- Bugs whose root cause is non-obvious and generalisable beyond this project.
|
||||
- Framework / library / model-name quirks that bit you and would bite anyone.
|
||||
- Design principles validated under fire (e.g. "every `_get` needs a `_list`").
|
||||
- Postmortems for incidents: what broke, why, how diagnosed, what to do next time.
|
||||
|
||||
DON'T write project status, sprint progress, PR summaries, or "what I did this
|
||||
session" — those rot fast and the originals are in git/gitea anyway. Brain
|
||||
entries that age well are about *why*, *how to avoid*, and *what to do when*.
|
||||
|
||||
### How to access (per harness)
|
||||
|
||||
| Harness | Query | Write |
|
||||
|---------|-------|-------|
|
||||
| **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool |
|
||||
| **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same |
|
||||
| **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` |
|
||||
| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
|
||||
|
||||
- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`.
|
||||
- **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as
|
||||
fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml`
|
||||
on the koala k3s cluster; don't hardcode local-only model names into the
|
||||
berget URL (see knowledge entry on namespace mismatches).
|
||||
|
||||
### Quick reflex checks
|
||||
|
||||
If you find yourself about to say any of these out loud, you owe yourself a brain query first:
|
||||
|
||||
- "I think the issue might be..."
|
||||
- "Let me try X and see..."
|
||||
- "I'll just write a script to..."
|
||||
- "This is probably a new bug..."
|
||||
- "Has anyone done this before?" — *yes, probably, go check.*
|
||||
|
||||
## Client work rules
|
||||
|
||||
@@ -212,8 +270,11 @@ Key skills:
|
||||
|
||||
### Git
|
||||
- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
|
||||
- Branch naming: `feat/short-description`, `fix/short-description`
|
||||
- PRs: one concern per PR, description explains *why* not *what*
|
||||
- **Trunk-Based Development:** commit directly to main. One logical change per commit.
|
||||
- Run `task check` locally before every push. CI is the quality gate, not branch protection.
|
||||
- No feature branches, no PRs for solo/agent work.
|
||||
- Exception: if a parallel agent session is active on this repo, use a short-lived
|
||||
`agent/<description>` branch and merge within the same session.
|
||||
|
||||
### Security
|
||||
- No secrets in code, ever — use env vars or SOPS-encrypted files
|
||||
@@ -251,68 +312,29 @@ When acting as a coding agent on this project:
|
||||
3. If unsure about a convention, check `DECISIONS.md` or ask
|
||||
4. Never modify files outside the project root without explicit permission
|
||||
5. When adding a dependency, explain why in the commit message
|
||||
6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|
||||
6. Commit directly to main. Run `task check` before every push. Never create
|
||||
feature branches unless a parallel agent is simultaneously active on this repo.
|
||||
7. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|
||||
|
||||
## Current sprint — gitea-mcp v0.2 (2026-05-14)
|
||||
## Current state — v0.2.5 (2026-05-17)
|
||||
|
||||
### Context
|
||||
This sprint implements new MCP tools needed for `hyperguild new-project` —
|
||||
the automated project creation flow triggered from claude.ai. See brain knowledge
|
||||
nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline`
|
||||
for full background.
|
||||
All v0.2 work is complete and deployed. No active sprint.
|
||||
|
||||
### Issues to implement (priority order)
|
||||
### What shipped
|
||||
|
||||
**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
|
||||
| Tag | PR | Tools / fixes |
|
||||
|-----|----|---------------|
|
||||
| v0.2.2 | #21 | repo_create, repo_update, repo_mirror_push |
|
||||
| v0.2.3 | #22 | repo_tree, repo_topics_update, file_read dir fix |
|
||||
| v0.2.4 | #23 | issue_get, release_create, repo_delete |
|
||||
| v0.2.5 | #26 | repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix |
|
||||
|
||||
| Issue | Tool | Gitea API |
|
||||
|-------|------|-----------|
|
||||
| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos |
|
||||
| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors |
|
||||
| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} |
|
||||
Current main: `e31fd3f`. CI green. Deployed via Flux.
|
||||
|
||||
**Batch 2 — quality of life (second PR: `feat/repo-ux`)**
|
||||
### Next up
|
||||
|
||||
| Issue | Tool | Gitea API |
|
||||
|-------|------|-----------|
|
||||
| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response |
|
||||
| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true |
|
||||
| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics |
|
||||
1. **`hyperguild new-project` v1** — primary next target.
|
||||
See brain node `adr-new-project-gitea-first-github-mirror` for full flow spec.
|
||||
|
||||
**Batch 3 — can wait**
|
||||
|
||||
| Issue | Tool | Note |
|
||||
|-------|------|------|
|
||||
| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name |
|
||||
| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases |
|
||||
|
||||
### How to add a tool (pattern)
|
||||
|
||||
Every tool = 4 files following `internal/tools/repo_get.go` exactly:
|
||||
|
||||
1. `internal/gitea/<domain>.go` — API client method (use PostJSON/PatchJSON/DeleteJSON)
|
||||
2. `internal/tools/repo_<name>.go` — tool handler with Descriptor() + Call()
|
||||
3. `internal/tools/repo_<name>_test.go` — table-driven tests with httptest.NewServer
|
||||
4. Registration in main — find where `NewRepoGet` is registered, add new tool same place
|
||||
|
||||
Key rules:
|
||||
- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard)
|
||||
- Use `textOK(result)` for success output
|
||||
- For `repo_mirror_push`: NEVER log or return `remote_password` in any output
|
||||
- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name
|
||||
|
||||
### Token permissions needed
|
||||
|
||||
New tools require these additional Gitea token scopes:
|
||||
- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create
|
||||
- `delete_repo` — repo_delete
|
||||
|
||||
Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user`
|
||||
If scopes are missing, update token in Gitea settings before running tests.
|
||||
|
||||
### Definition of done
|
||||
|
||||
- `task check` passes (all tools, all batches)
|
||||
- Each new tool manually callable via `claude mcp call`
|
||||
- PR #1 (batch 1) merged before starting batch 2
|
||||
- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed
|
||||
2. **Issue #19** — end-to-end mirror flow verification.
|
||||
`repo_mirror_push` is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.
|
||||
|
||||
@@ -37,8 +37,11 @@
|
||||
|
||||
### Git
|
||||
- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
|
||||
- Branch naming: `feat/short-description`, `fix/short-description`
|
||||
- PRs: one concern per PR, description explains *why* not *what*
|
||||
- **Trunk-Based Development:** commit directly to main. One logical change per commit.
|
||||
- Run `task check` locally before every push. CI is the quality gate, not branch protection.
|
||||
- No feature branches, no PRs for solo/agent work.
|
||||
- Exception: if a parallel agent session is active on this repo, use a short-lived
|
||||
`agent/<description>` branch and merge within the same session.
|
||||
|
||||
### Security
|
||||
- No secrets in code, ever — use env vars or SOPS-encrypted files
|
||||
@@ -76,68 +79,29 @@ When acting as a coding agent on this project:
|
||||
3. If unsure about a convention, check `DECISIONS.md` or ask
|
||||
4. Never modify files outside the project root without explicit permission
|
||||
5. When adding a dependency, explain why in the commit message
|
||||
6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|
||||
6. Commit directly to main. Run `task check` before every push. Never create
|
||||
feature branches unless a parallel agent is simultaneously active on this repo.
|
||||
7. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|
||||
|
||||
## Current sprint — gitea-mcp v0.2 (2026-05-14)
|
||||
## Current state — v0.2.5 (2026-05-17)
|
||||
|
||||
### Context
|
||||
This sprint implements new MCP tools needed for `hyperguild new-project` —
|
||||
the automated project creation flow triggered from claude.ai. See brain knowledge
|
||||
nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline`
|
||||
for full background.
|
||||
All v0.2 work is complete and deployed. No active sprint.
|
||||
|
||||
### Issues to implement (priority order)
|
||||
### What shipped
|
||||
|
||||
**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
|
||||
| Tag | PR | Tools / fixes |
|
||||
|-----|----|---------------|
|
||||
| v0.2.2 | #21 | repo_create, repo_update, repo_mirror_push |
|
||||
| v0.2.3 | #22 | repo_tree, repo_topics_update, file_read dir fix |
|
||||
| v0.2.4 | #23 | issue_get, release_create, repo_delete |
|
||||
| v0.2.5 | #26 | repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix |
|
||||
|
||||
| Issue | Tool | Gitea API |
|
||||
|-------|------|-----------|
|
||||
| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos |
|
||||
| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors |
|
||||
| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} |
|
||||
Current main: `e31fd3f`. CI green. Deployed via Flux.
|
||||
|
||||
**Batch 2 — quality of life (second PR: `feat/repo-ux`)**
|
||||
### Next up
|
||||
|
||||
| Issue | Tool | Gitea API |
|
||||
|-------|------|-----------|
|
||||
| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response |
|
||||
| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true |
|
||||
| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics |
|
||||
1. **`hyperguild new-project` v1** — primary next target.
|
||||
See brain node `adr-new-project-gitea-first-github-mirror` for full flow spec.
|
||||
|
||||
**Batch 3 — can wait**
|
||||
|
||||
| Issue | Tool | Note |
|
||||
|-------|------|------|
|
||||
| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name |
|
||||
| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases |
|
||||
|
||||
### How to add a tool (pattern)
|
||||
|
||||
Every tool = 4 files following `internal/tools/repo_get.go` exactly:
|
||||
|
||||
1. `internal/gitea/<domain>.go` — API client method (use PostJSON/PatchJSON/DeleteJSON)
|
||||
2. `internal/tools/repo_<name>.go` — tool handler with Descriptor() + Call()
|
||||
3. `internal/tools/repo_<name>_test.go` — table-driven tests with httptest.NewServer
|
||||
4. Registration in main — find where `NewRepoGet` is registered, add new tool same place
|
||||
|
||||
Key rules:
|
||||
- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard)
|
||||
- Use `textOK(result)` for success output
|
||||
- For `repo_mirror_push`: NEVER log or return `remote_password` in any output
|
||||
- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name
|
||||
|
||||
### Token permissions needed
|
||||
|
||||
New tools require these additional Gitea token scopes:
|
||||
- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create
|
||||
- `delete_repo` — repo_delete
|
||||
|
||||
Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user`
|
||||
If scopes are missing, update token in Gitea settings before running tests.
|
||||
|
||||
### Definition of done
|
||||
|
||||
- `task check` passes (all tools, all batches)
|
||||
- Each new tool manually callable via `claude mcp call`
|
||||
- PR #1 (batch 1) merged before starting batch 2
|
||||
- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed
|
||||
2. **Issue #19** — end-to-end mirror flow verification.
|
||||
`repo_mirror_push` is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.
|
||||
|
||||
@@ -41,9 +41,18 @@ These rules apply to every task across every project, regardless of harness.
|
||||
4. **Goal-driven execution.** Define clear success criteria up front for every task.
|
||||
Loop — implement, verify, refine — until those criteria are met. Don't claim
|
||||
completion without evidence (tests pass, command output, observed behavior).
|
||||
5. **Branch-per-task for multi-agent repos.** When another agent may be active on
|
||||
the same repo, create a branch (`agent/<description>`), commit there, and open a
|
||||
PR. Do not merge without explicit instruction from Mathias.
|
||||
5. **Trunk-Based Development — commit directly to main.** Every commit is one
|
||||
logical change (one tool, one fix, one test) with passing tests. Main is always
|
||||
deployable. Never create long-lived feature branches.
|
||||
|
||||
**Exception — parallel agents on same repo:** If another agent is known to be
|
||||
actively working on the same repo simultaneously, create a short-lived branch
|
||||
(`agent/<description>`), finish the task, and merge to main within the same
|
||||
session. Do not leave agent branches open between sessions.
|
||||
|
||||
**Exception — external contributor or client four-eyes requirement:** Use
|
||||
PR flow only when a human reviewer outside the project is required. Document
|
||||
the reason in PROJECT.md.
|
||||
|
||||
## Default stack
|
||||
|
||||
@@ -67,7 +76,10 @@ Exploratory: Rust, Zig — I'll tell you when I want these.
|
||||
- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return
|
||||
- **Naming**: stdlib conventions, no stuttering
|
||||
- **Architecture**: prefer stdlib over frameworks, constructor injection, env-var config parsed into typed structs
|
||||
- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), one concern per PR, PR describes *why* not *what*
|
||||
- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), commit directly to main,
|
||||
one logical change per commit, CI is the quality gate
|
||||
- **Never**: long-lived feature branches, PRs for solo work, direct push without
|
||||
passing `task check` locally first
|
||||
- **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config
|
||||
- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message
|
||||
|
||||
@@ -109,18 +121,64 @@ See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
|
||||
- **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
|
||||
- **klimatkollen** (`XT/`) — Swedish municipal climate data platform
|
||||
|
||||
## Knowledge base
|
||||
## Knowledge base — actively use it
|
||||
|
||||
When available, agents can query the shared knowledge base:
|
||||
A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions,
|
||||
hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems,
|
||||
Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional
|
||||
reference material — query it actively, not just when explicitly told.**
|
||||
|
||||
- **MCP**: `mcp://hyperguild.<TAILNET>.ts.net:3100/knowledge`
|
||||
- **HTTP**: `http://hyperguild.<TAILNET>.ts.net:3100/api/v1/search`
|
||||
### When to query (treat as a reflex)
|
||||
|
||||
<!-- TODO: replace <TAILNET> placeholder with the real Tailscale tailnet
|
||||
name once hyperguild is deployed. Until then, agents that try to
|
||||
reach the knowledge service on a host where it isn't running will
|
||||
get DNS NXDOMAIN, which is the desired fail-loudly behavior. -->
|
||||
- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`
|
||||
- **Before** starting a non-trivial task — search for prior art with the symptom
|
||||
AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours.
|
||||
- **When debugging** — search for the error string, the stack frame, the affected
|
||||
service. Past you may have already paid this tax.
|
||||
- **Before adopting** a pattern, library, framework, or model name — check if it
|
||||
was tried and rejected, or what the integration footguns are.
|
||||
- **When making architectural decisions** — search for the domain + "ADR" or
|
||||
"decision" to find prior reasoning before re-deriving it.
|
||||
- **When a recommendation feels novel** — challenge yourself: "has this been
|
||||
documented?" The brain often has it.
|
||||
|
||||
### When to write
|
||||
|
||||
After you discover something that **future-you would forget** and that **isn't
|
||||
recoverable from the code, git log, or PR description alone**:
|
||||
|
||||
- Bugs whose root cause is non-obvious and generalisable beyond this project.
|
||||
- Framework / library / model-name quirks that bit you and would bite anyone.
|
||||
- Design principles validated under fire (e.g. "every `_get` needs a `_list`").
|
||||
- Postmortems for incidents: what broke, why, how diagnosed, what to do next time.
|
||||
|
||||
DON'T write project status, sprint progress, PR summaries, or "what I did this
|
||||
session" — those rot fast and the originals are in git/gitea anyway. Brain
|
||||
entries that age well are about *why*, *how to avoid*, and *what to do when*.
|
||||
|
||||
### How to access (per harness)
|
||||
|
||||
| Harness | Query | Write |
|
||||
|---------|-------|-------|
|
||||
| **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool |
|
||||
| **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same |
|
||||
| **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` |
|
||||
| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
|
||||
|
||||
- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`.
|
||||
- **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as
|
||||
fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml`
|
||||
on the koala k3s cluster; don't hardcode local-only model names into the
|
||||
berget URL (see knowledge entry on namespace mismatches).
|
||||
|
||||
### Quick reflex checks
|
||||
|
||||
If you find yourself about to say any of these out loud, you owe yourself a brain query first:
|
||||
|
||||
- "I think the issue might be..."
|
||||
- "Let me try X and see..."
|
||||
- "I'll just write a script to..."
|
||||
- "This is probably a new bug..."
|
||||
- "Has anyone done this before?" — *yes, probably, go check.*
|
||||
|
||||
## Client work rules
|
||||
|
||||
@@ -217,8 +275,11 @@ Key skills:
|
||||
|
||||
### Git
|
||||
- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
|
||||
- Branch naming: `feat/short-description`, `fix/short-description`
|
||||
- PRs: one concern per PR, description explains *why* not *what*
|
||||
- **Trunk-Based Development:** commit directly to main. One logical change per commit.
|
||||
- Run `task check` locally before every push. CI is the quality gate, not branch protection.
|
||||
- No feature branches, no PRs for solo/agent work.
|
||||
- Exception: if a parallel agent session is active on this repo, use a short-lived
|
||||
`agent/<description>` branch and merge within the same session.
|
||||
|
||||
### Security
|
||||
- No secrets in code, ever — use env vars or SOPS-encrypted files
|
||||
@@ -256,70 +317,31 @@ When acting as a coding agent on this project:
|
||||
3. If unsure about a convention, check `DECISIONS.md` or ask
|
||||
4. Never modify files outside the project root without explicit permission
|
||||
5. When adding a dependency, explain why in the commit message
|
||||
6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|
||||
6. Commit directly to main. Run `task check` before every push. Never create
|
||||
feature branches unless a parallel agent is simultaneously active on this repo.
|
||||
7. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|
||||
|
||||
## Current sprint — gitea-mcp v0.2 (2026-05-14)
|
||||
## Current state — v0.2.5 (2026-05-17)
|
||||
|
||||
### Context
|
||||
This sprint implements new MCP tools needed for `hyperguild new-project` —
|
||||
the automated project creation flow triggered from claude.ai. See brain knowledge
|
||||
nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline`
|
||||
for full background.
|
||||
All v0.2 work is complete and deployed. No active sprint.
|
||||
|
||||
### Issues to implement (priority order)
|
||||
### What shipped
|
||||
|
||||
**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
|
||||
| Tag | PR | Tools / fixes |
|
||||
|-----|----|---------------|
|
||||
| v0.2.2 | #21 | repo_create, repo_update, repo_mirror_push |
|
||||
| v0.2.3 | #22 | repo_tree, repo_topics_update, file_read dir fix |
|
||||
| v0.2.4 | #23 | issue_get, release_create, repo_delete |
|
||||
| v0.2.5 | #26 | repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix |
|
||||
|
||||
| Issue | Tool | Gitea API |
|
||||
|-------|------|-----------|
|
||||
| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos |
|
||||
| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors |
|
||||
| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} |
|
||||
Current main: `e31fd3f`. CI green. Deployed via Flux.
|
||||
|
||||
**Batch 2 — quality of life (second PR: `feat/repo-ux`)**
|
||||
### Next up
|
||||
|
||||
| Issue | Tool | Gitea API |
|
||||
|-------|------|-----------|
|
||||
| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response |
|
||||
| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true |
|
||||
| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics |
|
||||
1. **`hyperguild new-project` v1** — primary next target.
|
||||
See brain node `adr-new-project-gitea-first-github-mirror` for full flow spec.
|
||||
|
||||
**Batch 3 — can wait**
|
||||
|
||||
| Issue | Tool | Note |
|
||||
|-------|------|------|
|
||||
| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name |
|
||||
| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases |
|
||||
|
||||
### How to add a tool (pattern)
|
||||
|
||||
Every tool = 4 files following `internal/tools/repo_get.go` exactly:
|
||||
|
||||
1. `internal/gitea/<domain>.go` — API client method (use PostJSON/PatchJSON/DeleteJSON)
|
||||
2. `internal/tools/repo_<name>.go` — tool handler with Descriptor() + Call()
|
||||
3. `internal/tools/repo_<name>_test.go` — table-driven tests with httptest.NewServer
|
||||
4. Registration in main — find where `NewRepoGet` is registered, add new tool same place
|
||||
|
||||
Key rules:
|
||||
- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard)
|
||||
- Use `textOK(result)` for success output
|
||||
- For `repo_mirror_push`: NEVER log or return `remote_password` in any output
|
||||
- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name
|
||||
|
||||
### Token permissions needed
|
||||
|
||||
New tools require these additional Gitea token scopes:
|
||||
- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create
|
||||
- `delete_repo` — repo_delete
|
||||
|
||||
Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user`
|
||||
If scopes are missing, update token in Gitea settings before running tests.
|
||||
|
||||
### Definition of done
|
||||
|
||||
- `task check` passes (all tools, all batches)
|
||||
- Each new tool manually callable via `claude mcp call`
|
||||
- PR #1 (batch 1) merged before starting batch 2
|
||||
- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed
|
||||
2. **Issue #19** — end-to-end mirror flow verification.
|
||||
`repo_mirror_push` is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.
|
||||
|
||||
---
|
||||
|
||||
166
.cursorrules
166
.cursorrules
@@ -39,9 +39,18 @@ These rules apply to every task across every project, regardless of harness.
|
||||
4. **Goal-driven execution.** Define clear success criteria up front for every task.
|
||||
Loop — implement, verify, refine — until those criteria are met. Don't claim
|
||||
completion without evidence (tests pass, command output, observed behavior).
|
||||
5. **Branch-per-task for multi-agent repos.** When another agent may be active on
|
||||
the same repo, create a branch (`agent/<description>`), commit there, and open a
|
||||
PR. Do not merge without explicit instruction from Mathias.
|
||||
5. **Trunk-Based Development — commit directly to main.** Every commit is one
|
||||
logical change (one tool, one fix, one test) with passing tests. Main is always
|
||||
deployable. Never create long-lived feature branches.
|
||||
|
||||
**Exception — parallel agents on same repo:** If another agent is known to be
|
||||
actively working on the same repo simultaneously, create a short-lived branch
|
||||
(`agent/<description>`), finish the task, and merge to main within the same
|
||||
session. Do not leave agent branches open between sessions.
|
||||
|
||||
**Exception — external contributor or client four-eyes requirement:** Use
|
||||
PR flow only when a human reviewer outside the project is required. Document
|
||||
the reason in PROJECT.md.
|
||||
|
||||
## Default stack
|
||||
|
||||
@@ -65,7 +74,10 @@ Exploratory: Rust, Zig — I'll tell you when I want these.
|
||||
- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return
|
||||
- **Naming**: stdlib conventions, no stuttering
|
||||
- **Architecture**: prefer stdlib over frameworks, constructor injection, env-var config parsed into typed structs
|
||||
- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), one concern per PR, PR describes *why* not *what*
|
||||
- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), commit directly to main,
|
||||
one logical change per commit, CI is the quality gate
|
||||
- **Never**: long-lived feature branches, PRs for solo work, direct push without
|
||||
passing `task check` locally first
|
||||
- **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config
|
||||
- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message
|
||||
|
||||
@@ -107,18 +119,64 @@ See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
|
||||
- **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
|
||||
- **klimatkollen** (`XT/`) — Swedish municipal climate data platform
|
||||
|
||||
## Knowledge base
|
||||
## Knowledge base — actively use it
|
||||
|
||||
When available, agents can query the shared knowledge base:
|
||||
A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions,
|
||||
hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems,
|
||||
Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional
|
||||
reference material — query it actively, not just when explicitly told.**
|
||||
|
||||
- **MCP**: `mcp://hyperguild.<TAILNET>.ts.net:3100/knowledge`
|
||||
- **HTTP**: `http://hyperguild.<TAILNET>.ts.net:3100/api/v1/search`
|
||||
### When to query (treat as a reflex)
|
||||
|
||||
<!-- TODO: replace <TAILNET> placeholder with the real Tailscale tailnet
|
||||
name once hyperguild is deployed. Until then, agents that try to
|
||||
reach the knowledge service on a host where it isn't running will
|
||||
get DNS NXDOMAIN, which is the desired fail-loudly behavior. -->
|
||||
- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`
|
||||
- **Before** starting a non-trivial task — search for prior art with the symptom
|
||||
AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours.
|
||||
- **When debugging** — search for the error string, the stack frame, the affected
|
||||
service. Past you may have already paid this tax.
|
||||
- **Before adopting** a pattern, library, framework, or model name — check if it
|
||||
was tried and rejected, or what the integration footguns are.
|
||||
- **When making architectural decisions** — search for the domain + "ADR" or
|
||||
"decision" to find prior reasoning before re-deriving it.
|
||||
- **When a recommendation feels novel** — challenge yourself: "has this been
|
||||
documented?" The brain often has it.
|
||||
|
||||
### When to write
|
||||
|
||||
After you discover something that **future-you would forget** and that **isn't
|
||||
recoverable from the code, git log, or PR description alone**:
|
||||
|
||||
- Bugs whose root cause is non-obvious and generalisable beyond this project.
|
||||
- Framework / library / model-name quirks that bit you and would bite anyone.
|
||||
- Design principles validated under fire (e.g. "every `_get` needs a `_list`").
|
||||
- Postmortems for incidents: what broke, why, how diagnosed, what to do next time.
|
||||
|
||||
DON'T write project status, sprint progress, PR summaries, or "what I did this
|
||||
session" — those rot fast and the originals are in git/gitea anyway. Brain
|
||||
entries that age well are about *why*, *how to avoid*, and *what to do when*.
|
||||
|
||||
### How to access (per harness)
|
||||
|
||||
| Harness | Query | Write |
|
||||
|---------|-------|-------|
|
||||
| **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool |
|
||||
| **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same |
|
||||
| **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` |
|
||||
| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
|
||||
|
||||
- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`.
|
||||
- **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as
|
||||
fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml`
|
||||
on the koala k3s cluster; don't hardcode local-only model names into the
|
||||
berget URL (see knowledge entry on namespace mismatches).
|
||||
|
||||
### Quick reflex checks
|
||||
|
||||
If you find yourself about to say any of these out loud, you owe yourself a brain query first:
|
||||
|
||||
- "I think the issue might be..."
|
||||
- "Let me try X and see..."
|
||||
- "I'll just write a script to..."
|
||||
- "This is probably a new bug..."
|
||||
- "Has anyone done this before?" — *yes, probably, go check.*
|
||||
|
||||
## Client work rules
|
||||
|
||||
@@ -215,8 +273,11 @@ Key skills:
|
||||
|
||||
### Git
|
||||
- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
|
||||
- Branch naming: `feat/short-description`, `fix/short-description`
|
||||
- PRs: one concern per PR, description explains *why* not *what*
|
||||
- **Trunk-Based Development:** commit directly to main. One logical change per commit.
|
||||
- Run `task check` locally before every push. CI is the quality gate, not branch protection.
|
||||
- No feature branches, no PRs for solo/agent work.
|
||||
- Exception: if a parallel agent session is active on this repo, use a short-lived
|
||||
`agent/<description>` branch and merge within the same session.
|
||||
|
||||
### Security
|
||||
- No secrets in code, ever — use env vars or SOPS-encrypted files
|
||||
@@ -254,68 +315,29 @@ When acting as a coding agent on this project:
|
||||
3. If unsure about a convention, check `DECISIONS.md` or ask
|
||||
4. Never modify files outside the project root without explicit permission
|
||||
5. When adding a dependency, explain why in the commit message
|
||||
6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|
||||
6. Commit directly to main. Run `task check` before every push. Never create
|
||||
feature branches unless a parallel agent is simultaneously active on this repo.
|
||||
7. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|
||||
|
||||
## Current sprint — gitea-mcp v0.2 (2026-05-14)
|
||||
## Current state — v0.2.5 (2026-05-17)
|
||||
|
||||
### Context
|
||||
This sprint implements new MCP tools needed for `hyperguild new-project` —
|
||||
the automated project creation flow triggered from claude.ai. See brain knowledge
|
||||
nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline`
|
||||
for full background.
|
||||
All v0.2 work is complete and deployed. No active sprint.
|
||||
|
||||
### Issues to implement (priority order)
|
||||
### What shipped
|
||||
|
||||
**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
|
||||
| Tag | PR | Tools / fixes |
|
||||
|-----|----|---------------|
|
||||
| v0.2.2 | #21 | repo_create, repo_update, repo_mirror_push |
|
||||
| v0.2.3 | #22 | repo_tree, repo_topics_update, file_read dir fix |
|
||||
| v0.2.4 | #23 | issue_get, release_create, repo_delete |
|
||||
| v0.2.5 | #26 | repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix |
|
||||
|
||||
| Issue | Tool | Gitea API |
|
||||
|-------|------|-----------|
|
||||
| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos |
|
||||
| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors |
|
||||
| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} |
|
||||
Current main: `e31fd3f`. CI green. Deployed via Flux.
|
||||
|
||||
**Batch 2 — quality of life (second PR: `feat/repo-ux`)**
|
||||
### Next up
|
||||
|
||||
| Issue | Tool | Gitea API |
|
||||
|-------|------|-----------|
|
||||
| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response |
|
||||
| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true |
|
||||
| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics |
|
||||
1. **`hyperguild new-project` v1** — primary next target.
|
||||
See brain node `adr-new-project-gitea-first-github-mirror` for full flow spec.
|
||||
|
||||
**Batch 3 — can wait**
|
||||
|
||||
| Issue | Tool | Note |
|
||||
|-------|------|------|
|
||||
| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name |
|
||||
| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases |
|
||||
|
||||
### How to add a tool (pattern)
|
||||
|
||||
Every tool = 4 files following `internal/tools/repo_get.go` exactly:
|
||||
|
||||
1. `internal/gitea/<domain>.go` — API client method (use PostJSON/PatchJSON/DeleteJSON)
|
||||
2. `internal/tools/repo_<name>.go` — tool handler with Descriptor() + Call()
|
||||
3. `internal/tools/repo_<name>_test.go` — table-driven tests with httptest.NewServer
|
||||
4. Registration in main — find where `NewRepoGet` is registered, add new tool same place
|
||||
|
||||
Key rules:
|
||||
- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard)
|
||||
- Use `textOK(result)` for success output
|
||||
- For `repo_mirror_push`: NEVER log or return `remote_password` in any output
|
||||
- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name
|
||||
|
||||
### Token permissions needed
|
||||
|
||||
New tools require these additional Gitea token scopes:
|
||||
- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create
|
||||
- `delete_repo` — repo_delete
|
||||
|
||||
Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user`
|
||||
If scopes are missing, update token in Gitea settings before running tests.
|
||||
|
||||
### Definition of done
|
||||
|
||||
- `task check` passes (all tools, all batches)
|
||||
- Each new tool manually callable via `claude mcp call`
|
||||
- PR #1 (batch 1) merged before starting batch 2
|
||||
- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed
|
||||
2. **Issue #19** — end-to-end mirror flow verification.
|
||||
`repo_mirror_push` is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.
|
||||
|
||||
@@ -4,8 +4,6 @@ on:
|
||||
push:
|
||||
branches: [main]
|
||||
tags: ["v*"]
|
||||
pull_request:
|
||||
branches: [main]
|
||||
|
||||
env:
|
||||
IMAGE: gitea-mcp
|
||||
@@ -43,7 +41,6 @@ jobs:
|
||||
name: Build & Import
|
||||
needs: check
|
||||
runs-on: self-hosted
|
||||
if: github.event_name != 'pull_request'
|
||||
outputs:
|
||||
image-tag: ${{ steps.meta.outputs.sha-tag }}
|
||||
steps:
|
||||
|
||||
5
.githooks/pre-push
Normal file
5
.githooks/pre-push
Normal file
@@ -0,0 +1,5 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
echo "→ Running task check before push..."
|
||||
task check
|
||||
echo "✓ pre-push check passed"
|
||||
166
AGENTS.md
166
AGENTS.md
@@ -36,9 +36,18 @@ These rules apply to every task across every project, regardless of harness.
|
||||
4. **Goal-driven execution.** Define clear success criteria up front for every task.
|
||||
Loop — implement, verify, refine — until those criteria are met. Don't claim
|
||||
completion without evidence (tests pass, command output, observed behavior).
|
||||
5. **Branch-per-task for multi-agent repos.** When another agent may be active on
|
||||
the same repo, create a branch (`agent/<description>`), commit there, and open a
|
||||
PR. Do not merge without explicit instruction from Mathias.
|
||||
5. **Trunk-Based Development — commit directly to main.** Every commit is one
|
||||
logical change (one tool, one fix, one test) with passing tests. Main is always
|
||||
deployable. Never create long-lived feature branches.
|
||||
|
||||
**Exception — parallel agents on same repo:** If another agent is known to be
|
||||
actively working on the same repo simultaneously, create a short-lived branch
|
||||
(`agent/<description>`), finish the task, and merge to main within the same
|
||||
session. Do not leave agent branches open between sessions.
|
||||
|
||||
**Exception — external contributor or client four-eyes requirement:** Use
|
||||
PR flow only when a human reviewer outside the project is required. Document
|
||||
the reason in PROJECT.md.
|
||||
|
||||
## Default stack
|
||||
|
||||
@@ -62,7 +71,10 @@ Exploratory: Rust, Zig — I'll tell you when I want these.
|
||||
- **Errors**: `fmt.Errorf("operation: %w", err)` — never naked, never log-and-return
|
||||
- **Naming**: stdlib conventions, no stuttering
|
||||
- **Architecture**: prefer stdlib over frameworks, constructor injection, env-var config parsed into typed structs
|
||||
- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), one concern per PR, PR describes *why* not *what*
|
||||
- **Git**: conventional commits (`feat:`, `fix:`, `chore:`), commit directly to main,
|
||||
one logical change per commit, CI is the quality gate
|
||||
- **Never**: long-lived feature branches, PRs for solo work, direct push without
|
||||
passing `task check` locally first
|
||||
- **Security**: no secrets in code, govulncheck before adding deps, SOPS for encrypted config
|
||||
- **Dependencies**: prefer stdlib. testify, slog, templ, sqlc, google.golang.org/adk (agent projects only) are pre-approved; anything else needs justification in the commit message
|
||||
|
||||
@@ -104,18 +116,64 @@ See `~/dev/PROJECT_SUMMARY.md` for detailed descriptions of each project.
|
||||
- **koala-ai-stack** (`AGENTS/`) — local AI server infrastructure management
|
||||
- **klimatkollen** (`XT/`) — Swedish municipal climate data platform
|
||||
|
||||
## Knowledge base
|
||||
## Knowledge base — actively use it
|
||||
|
||||
When available, agents can query the shared knowledge base:
|
||||
A persistent brain (BM25 search + LLM-synthesised Q&A) survives across sessions,
|
||||
hosts, and harnesses. It holds 100+ hard-won entries: infra incident postmortems,
|
||||
Go pitfalls, framework gotchas, design principles, ADRs. **It is not optional
|
||||
reference material — query it actively, not just when explicitly told.**
|
||||
|
||||
- **MCP**: `mcp://hyperguild.<TAILNET>.ts.net:3100/knowledge`
|
||||
- **HTTP**: `http://hyperguild.<TAILNET>.ts.net:3100/api/v1/search`
|
||||
### When to query (treat as a reflex)
|
||||
|
||||
<!-- TODO: replace <TAILNET> placeholder with the real Tailscale tailnet
|
||||
name once hyperguild is deployed. Until then, agents that try to
|
||||
reach the knowledge service on a host where it isn't running will
|
||||
get DNS NXDOMAIN, which is the desired fail-loudly behavior. -->
|
||||
- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`
|
||||
- **Before** starting a non-trivial task — search for prior art with the symptom
|
||||
AND the system component ("how did we solve X in Y?"). 5 seconds beats 5 hours.
|
||||
- **When debugging** — search for the error string, the stack frame, the affected
|
||||
service. Past you may have already paid this tax.
|
||||
- **Before adopting** a pattern, library, framework, or model name — check if it
|
||||
was tried and rejected, or what the integration footguns are.
|
||||
- **When making architectural decisions** — search for the domain + "ADR" or
|
||||
"decision" to find prior reasoning before re-deriving it.
|
||||
- **When a recommendation feels novel** — challenge yourself: "has this been
|
||||
documented?" The brain often has it.
|
||||
|
||||
### When to write
|
||||
|
||||
After you discover something that **future-you would forget** and that **isn't
|
||||
recoverable from the code, git log, or PR description alone**:
|
||||
|
||||
- Bugs whose root cause is non-obvious and generalisable beyond this project.
|
||||
- Framework / library / model-name quirks that bit you and would bite anyone.
|
||||
- Design principles validated under fire (e.g. "every `_get` needs a `_list`").
|
||||
- Postmortems for incidents: what broke, why, how diagnosed, what to do next time.
|
||||
|
||||
DON'T write project status, sprint progress, PR summaries, or "what I did this
|
||||
session" — those rot fast and the originals are in git/gitea anyway. Brain
|
||||
entries that age well are about *why*, *how to avoid*, and *what to do when*.
|
||||
|
||||
### How to access (per harness)
|
||||
|
||||
| Harness | Query | Write |
|
||||
|---------|-------|-------|
|
||||
| **Claude Code, Claude Desktop** | `brain_query` (BM25), `brain_answer` (LLM-synth + sources) MCP tools | `brain_write` MCP tool |
|
||||
| **Crush, Pi, Antigravity, other MCP-capable** | same MCP server: `ingestion-brain` (via the `mcp__*_brain__*` namespace once authenticated) | same |
|
||||
| **Anything HTTP-only (curl, scripts)** | `POST https://brain-mcp.d-ma.be/query` with `{"query":"..."}` (auth via `BRAIN_MCP_TOKEN`) | `POST .../write` with `{"content":"...","filename":"..."}` |
|
||||
| **Browser / human inspection** | `https://gitea.d-ma.be/mathias/hyperguild` → `knowledge/` and `wiki/` markdown files |
|
||||
|
||||
- **Scoping**: defaults to `public` collection; client projects filter to `{client}` + `public`.
|
||||
- **Routing**: brain_answer's LLM uses berget.ai as primary, iguana ollama as
|
||||
fallback. Both are configurable in the `supervisor/ingestion-deployment.yaml`
|
||||
on the koala k3s cluster; don't hardcode local-only model names into the
|
||||
berget URL (see knowledge entry on namespace mismatches).
|
||||
|
||||
### Quick reflex checks
|
||||
|
||||
If you find yourself about to say any of these out loud, you owe yourself a brain query first:
|
||||
|
||||
- "I think the issue might be..."
|
||||
- "Let me try X and see..."
|
||||
- "I'll just write a script to..."
|
||||
- "This is probably a new bug..."
|
||||
- "Has anyone done this before?" — *yes, probably, go check.*
|
||||
|
||||
## Client work rules
|
||||
|
||||
@@ -212,8 +270,11 @@ Key skills:
|
||||
|
||||
### Git
|
||||
- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
|
||||
- Branch naming: `feat/short-description`, `fix/short-description`
|
||||
- PRs: one concern per PR, description explains *why* not *what*
|
||||
- **Trunk-Based Development:** commit directly to main. One logical change per commit.
|
||||
- Run `task check` locally before every push. CI is the quality gate, not branch protection.
|
||||
- No feature branches, no PRs for solo/agent work.
|
||||
- Exception: if a parallel agent session is active on this repo, use a short-lived
|
||||
`agent/<description>` branch and merge within the same session.
|
||||
|
||||
### Security
|
||||
- No secrets in code, ever — use env vars or SOPS-encrypted files
|
||||
@@ -251,68 +312,29 @@ When acting as a coding agent on this project:
|
||||
3. If unsure about a convention, check `DECISIONS.md` or ask
|
||||
4. Never modify files outside the project root without explicit permission
|
||||
5. When adding a dependency, explain why in the commit message
|
||||
6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|
||||
6. Commit directly to main. Run `task check` before every push. Never create
|
||||
feature branches unless a parallel agent is simultaneously active on this repo.
|
||||
7. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|
||||
|
||||
## Current sprint — gitea-mcp v0.2 (2026-05-14)
|
||||
## Current state — v0.2.5 (2026-05-17)
|
||||
|
||||
### Context
|
||||
This sprint implements new MCP tools needed for `hyperguild new-project` —
|
||||
the automated project creation flow triggered from claude.ai. See brain knowledge
|
||||
nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline`
|
||||
for full background.
|
||||
All v0.2 work is complete and deployed. No active sprint.
|
||||
|
||||
### Issues to implement (priority order)
|
||||
### What shipped
|
||||
|
||||
**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
|
||||
| Tag | PR | Tools / fixes |
|
||||
|-----|----|---------------|
|
||||
| v0.2.2 | #21 | repo_create, repo_update, repo_mirror_push |
|
||||
| v0.2.3 | #22 | repo_tree, repo_topics_update, file_read dir fix |
|
||||
| v0.2.4 | #23 | issue_get, release_create, repo_delete |
|
||||
| v0.2.5 | #26 | repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix |
|
||||
|
||||
| Issue | Tool | Gitea API |
|
||||
|-------|------|-----------|
|
||||
| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos |
|
||||
| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors |
|
||||
| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} |
|
||||
Current main: `e31fd3f`. CI green. Deployed via Flux.
|
||||
|
||||
**Batch 2 — quality of life (second PR: `feat/repo-ux`)**
|
||||
### Next up
|
||||
|
||||
| Issue | Tool | Gitea API |
|
||||
|-------|------|-----------|
|
||||
| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response |
|
||||
| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true |
|
||||
| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics |
|
||||
1. **`hyperguild new-project` v1** — primary next target.
|
||||
See brain node `adr-new-project-gitea-first-github-mirror` for full flow spec.
|
||||
|
||||
**Batch 3 — can wait**
|
||||
|
||||
| Issue | Tool | Note |
|
||||
|-------|------|------|
|
||||
| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name |
|
||||
| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases |
|
||||
|
||||
### How to add a tool (pattern)
|
||||
|
||||
Every tool = 4 files following `internal/tools/repo_get.go` exactly:
|
||||
|
||||
1. `internal/gitea/<domain>.go` — API client method (use PostJSON/PatchJSON/DeleteJSON)
|
||||
2. `internal/tools/repo_<name>.go` — tool handler with Descriptor() + Call()
|
||||
3. `internal/tools/repo_<name>_test.go` — table-driven tests with httptest.NewServer
|
||||
4. Registration in main — find where `NewRepoGet` is registered, add new tool same place
|
||||
|
||||
Key rules:
|
||||
- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard)
|
||||
- Use `textOK(result)` for success output
|
||||
- For `repo_mirror_push`: NEVER log or return `remote_password` in any output
|
||||
- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name
|
||||
|
||||
### Token permissions needed
|
||||
|
||||
New tools require these additional Gitea token scopes:
|
||||
- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create
|
||||
- `delete_repo` — repo_delete
|
||||
|
||||
Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user`
|
||||
If scopes are missing, update token in Gitea settings before running tests.
|
||||
|
||||
### Definition of done
|
||||
|
||||
- `task check` passes (all tools, all batches)
|
||||
- Each new tool manually callable via `claude mcp call`
|
||||
- PR #1 (batch 1) merged before starting batch 2
|
||||
- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed
|
||||
2. **Issue #19** — end-to-end mirror flow verification.
|
||||
`repo_mirror_push` is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.
|
||||
|
||||
82
CLAUDE.md
82
CLAUDE.md
@@ -37,8 +37,11 @@
|
||||
|
||||
### Git
|
||||
- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
|
||||
- Branch naming: `feat/short-description`, `fix/short-description`
|
||||
- PRs: one concern per PR, description explains *why* not *what*
|
||||
- **Trunk-Based Development:** commit directly to main. One logical change per commit.
|
||||
- Run `task check` locally before every push. CI is the quality gate, not branch protection.
|
||||
- No feature branches, no PRs for solo/agent work.
|
||||
- Exception: if a parallel agent session is active on this repo, use a short-lived
|
||||
`agent/<description>` branch and merge within the same session.
|
||||
|
||||
### Security
|
||||
- No secrets in code, ever — use env vars or SOPS-encrypted files
|
||||
@@ -76,68 +79,29 @@ When acting as a coding agent on this project:
|
||||
3. If unsure about a convention, check `DECISIONS.md` or ask
|
||||
4. Never modify files outside the project root without explicit permission
|
||||
5. When adding a dependency, explain why in the commit message
|
||||
6. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|
||||
6. Commit directly to main. Run `task check` before every push. Never create
|
||||
feature branches unless a parallel agent is simultaneously active on this repo.
|
||||
7. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|
||||
|
||||
## Current sprint — gitea-mcp v0.2 (2026-05-14)
|
||||
## Current state — v0.2.5 (2026-05-17)
|
||||
|
||||
### Context
|
||||
This sprint implements new MCP tools needed for `hyperguild new-project` —
|
||||
the automated project creation flow triggered from claude.ai. See brain knowledge
|
||||
nodes `adr-new-project-gitea-first-github-mirror` and `roadmap-github-ingestion-pipeline`
|
||||
for full background.
|
||||
All v0.2 work is complete and deployed. No active sprint.
|
||||
|
||||
### Issues to implement (priority order)
|
||||
### What shipped
|
||||
|
||||
**Batch 1 — blockers (do first, one PR: `feat/repo-crud`)**
|
||||
| Tag | PR | Tools / fixes |
|
||||
|-----|----|---------------|
|
||||
| v0.2.2 | #21 | repo_create, repo_update, repo_mirror_push |
|
||||
| v0.2.3 | #22 | repo_tree, repo_topics_update, file_read dir fix |
|
||||
| v0.2.4 | #23 | issue_get, release_create, repo_delete |
|
||||
| v0.2.5 | #26 | repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix |
|
||||
|
||||
| Issue | Tool | Gitea API |
|
||||
|-------|------|-----------|
|
||||
| #13 | `repo_create` | POST /api/v1/user/repos or /api/v1/orgs/{org}/repos |
|
||||
| #16 | `repo_mirror_push` (add/list/delete) | POST/GET/DELETE /api/v1/repos/{owner}/{repo}/push_mirrors |
|
||||
| #12 | `repo_update` | PATCH /api/v1/repos/{owner}/{repo} |
|
||||
Current main: `e31fd3f`. CI green. Deployed via Flux.
|
||||
|
||||
**Batch 2 — quality of life (second PR: `feat/repo-ux`)**
|
||||
### Next up
|
||||
|
||||
| Issue | Tool | Gitea API |
|
||||
|-------|------|-----------|
|
||||
| #15 | `file_read` dir-path fix | existing endpoint, detect array vs object response |
|
||||
| #14 | `repo_tree` | GET /api/v1/repos/{owner}/{repo}/git/trees/{sha}?recursive=true |
|
||||
| #18 | `repo_topics_update` | PUT /api/v1/repos/{owner}/{repo}/topics |
|
||||
1. **`hyperguild new-project` v1** — primary next target.
|
||||
See brain node `adr-new-project-gitea-first-github-mirror` for full flow spec.
|
||||
|
||||
**Batch 3 — can wait**
|
||||
|
||||
| Issue | Tool | Note |
|
||||
|-------|------|------|
|
||||
| #11 | `repo_delete` | HIGH risk — needs `confirm` param == repo name |
|
||||
| #17 | `release_create` | POST /api/v1/repos/{owner}/{repo}/releases |
|
||||
|
||||
### How to add a tool (pattern)
|
||||
|
||||
Every tool = 4 files following `internal/tools/repo_get.go` exactly:
|
||||
|
||||
1. `internal/gitea/<domain>.go` — API client method (use PostJSON/PatchJSON/DeleteJSON)
|
||||
2. `internal/tools/repo_<name>.go` — tool handler with Descriptor() + Call()
|
||||
3. `internal/tools/repo_<name>_test.go` — table-driven tests with httptest.NewServer
|
||||
4. Registration in main — find where `NewRepoGet` is registered, add new tool same place
|
||||
|
||||
Key rules:
|
||||
- Always call `t.a.Check(args.Owner)` before any API call (allowlist guard)
|
||||
- Use `textOK(result)` for success output
|
||||
- For `repo_mirror_push`: NEVER log or return `remote_password` in any output
|
||||
- For `repo_update` with `private: false` and `repo_delete`: require `confirm` param == repo name
|
||||
|
||||
### Token permissions needed
|
||||
|
||||
New tools require these additional Gitea token scopes:
|
||||
- `write:repository` — repo_create, repo_update, repo_mirror_push, repo_topics_update, release_create
|
||||
- `delete_repo` — repo_delete
|
||||
|
||||
Check current token: `curl -H "Authorization: token $GITEA_TOKEN" https://gitea.d-ma.be/api/v1/user`
|
||||
If scopes are missing, update token in Gitea settings before running tests.
|
||||
|
||||
### Definition of done
|
||||
|
||||
- `task check` passes (all tools, all batches)
|
||||
- Each new tool manually callable via `claude mcp call`
|
||||
- PR #1 (batch 1) merged before starting batch 2
|
||||
- Issue #19 (mirror flow e2e test) verified manually after batch 1 is deployed
|
||||
2. **Issue #19** — end-to-end mirror flow verification.
|
||||
`repo_mirror_push` is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.
|
||||
|
||||
11
README.md
11
README.md
@@ -2,3 +2,14 @@
|
||||
|
||||
Streamable HTTP MCP service exposing Gitea repo operations to Claude apps.
|
||||
See `~/dev/AI/infra/docs/superpowers/specs/2026-05-04-gitea-mcp-gitops-workflow-design.md`.
|
||||
|
||||
## Quickstart
|
||||
|
||||
```bash
|
||||
task setup:hooks # installs .githooks/pre-push — runs task check before every push
|
||||
task check # context sync + lint + test + vet
|
||||
task build # produces bin/gitea-mcp
|
||||
```
|
||||
|
||||
This repo uses Trunk-Based Development. Commit directly to `main`. The pre-push
|
||||
hook enforces the quality gate locally; CI re-runs `task check` on every push.
|
||||
|
||||
@@ -47,6 +47,13 @@ tasks:
|
||||
cmds:
|
||||
- bash scripts/context-sync.sh
|
||||
|
||||
setup:hooks:
|
||||
desc: Install git hooks (.githooks/pre-push)
|
||||
cmds:
|
||||
- git config core.hooksPath .githooks
|
||||
- chmod +x .githooks/pre-push
|
||||
- echo "✓ git hooks installed (pre-push runs task check)"
|
||||
|
||||
context:sync:claude:
|
||||
cmds: [bash scripts/context-sync.sh claude]
|
||||
context:sync:agents:
|
||||
|
||||
@@ -66,6 +66,10 @@ func main() {
|
||||
reg.Register(tools.NewRepoTree(giteaClient, ownerAllow))
|
||||
reg.Register(tools.NewRepoTopicsUpdate(giteaClient, ownerAllow))
|
||||
reg.Register(tools.NewIssueGet(giteaClient, ownerAllow))
|
||||
reg.Register(tools.NewIssueList(giteaClient, ownerAllow))
|
||||
reg.Register(tools.NewIssueClose(giteaClient, ownerAllow))
|
||||
reg.Register(tools.NewIssueReopen(giteaClient, ownerAllow))
|
||||
reg.Register(tools.NewWorkflowRunList(giteaClient, ownerAllow))
|
||||
reg.Register(tools.NewReleaseCreate(giteaClient, ownerAllow))
|
||||
reg.Register(tools.NewRepoDelete(giteaClient, ownerAllow))
|
||||
|
||||
|
||||
@@ -4,6 +4,8 @@ import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/url"
|
||||
"strconv"
|
||||
)
|
||||
|
||||
type Issue struct {
|
||||
@@ -72,6 +74,72 @@ func (c *Client) CreateIssue(ctx context.Context, owner, repo string, args Creat
|
||||
return &iss, nil
|
||||
}
|
||||
|
||||
// ListIssuesArgs captures the optional query params for ListIssues.
|
||||
type ListIssuesArgs struct {
|
||||
State string // "open" | "closed" | "all"
|
||||
Labels string // comma-separated label names
|
||||
Since string // ISO 8601
|
||||
Page int
|
||||
Limit int
|
||||
}
|
||||
|
||||
// ListIssues fetches issues for a repo. Pulls are excluded server-side
|
||||
// (type=issues) so they don't leak through the same endpoint.
|
||||
func (c *Client) ListIssues(ctx context.Context, owner, repo string, args ListIssuesArgs) ([]Issue, error) {
|
||||
q := url.Values{}
|
||||
q.Set("type", "issues")
|
||||
if args.State != "" {
|
||||
q.Set("state", args.State)
|
||||
}
|
||||
if args.Labels != "" {
|
||||
q.Set("labels", args.Labels)
|
||||
}
|
||||
if args.Since != "" {
|
||||
q.Set("since", args.Since)
|
||||
}
|
||||
if args.Page > 0 {
|
||||
q.Set("page", strconv.Itoa(args.Page))
|
||||
}
|
||||
if args.Limit > 0 {
|
||||
q.Set("limit", strconv.Itoa(args.Limit))
|
||||
}
|
||||
p := fmt.Sprintf("/api/v1/repos/%s/%s/issues?%s", owner, repo, q.Encode())
|
||||
body, status, err := c.GetJSON(ctx, p)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if err := MapStatus(status, body); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var issues []Issue
|
||||
if err := json.Unmarshal(body, &issues); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return issues, nil
|
||||
}
|
||||
|
||||
// SetIssueState flips an issue between "open" and "closed" via PATCH.
|
||||
// Gitea uses the same endpoint for both transitions.
|
||||
func (c *Client) SetIssueState(ctx context.Context, owner, repo string, number int, state string) (*Issue, error) {
|
||||
p := fmt.Sprintf("/api/v1/repos/%s/%s/issues/%d", owner, repo, number)
|
||||
payload, err := json.Marshal(map[string]string{"state": state})
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
body, status, err := c.PatchJSON(ctx, p, payload)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if err := MapStatus(status, body); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var iss Issue
|
||||
if err := json.Unmarshal(body, &iss); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &iss, nil
|
||||
}
|
||||
|
||||
type IssueComment struct {
|
||||
ID int64 `json:"id"`
|
||||
Body string `json:"body"`
|
||||
|
||||
@@ -216,6 +216,8 @@ type UpdateRepoArgs struct {
|
||||
Private *bool `json:"private,omitempty"`
|
||||
Website *string `json:"website,omitempty"`
|
||||
DefaultBranch *string `json:"default_branch,omitempty"`
|
||||
Archived *bool `json:"archived,omitempty"`
|
||||
Template *bool `json:"template,omitempty"`
|
||||
}
|
||||
|
||||
func (c *Client) UpdateRepo(ctx context.Context, owner, name string, args UpdateRepoArgs) (*Repo, error) {
|
||||
@@ -253,3 +255,4 @@ func (c *Client) GetRepo(ctx context.Context, owner, name string) (*Repo, error)
|
||||
}
|
||||
return &r, nil
|
||||
}
|
||||
|
||||
|
||||
@@ -4,6 +4,7 @@ import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/url"
|
||||
"strconv"
|
||||
"strings"
|
||||
)
|
||||
@@ -55,10 +56,20 @@ func (c *Client) DispatchWorkflow(ctx context.Context, owner, repo, workflow str
|
||||
// WorkflowRun represents a Gitea Actions run.
|
||||
type WorkflowRun struct {
|
||||
ID int64 `json:"id"`
|
||||
DisplayTitle string `json:"display_title,omitempty"`
|
||||
Status string `json:"status"` // queued | in_progress | completed
|
||||
Conclusion string `json:"conclusion"` // success | failure | cancelled | skipped (only when completed)
|
||||
Event string `json:"event,omitempty"`
|
||||
HeadSHA string `json:"head_sha,omitempty"`
|
||||
HeadBranch string `json:"head_branch,omitempty"`
|
||||
WorkflowID string `json:"workflow_id,omitempty"`
|
||||
RunNumber int64 `json:"run_number,omitempty"`
|
||||
StartedAt string `json:"started_at"`
|
||||
UpdatedAt string `json:"updated_at,omitempty"`
|
||||
HTMLURL string `json:"html_url"`
|
||||
Actor struct {
|
||||
Login string `json:"login"`
|
||||
} `json:"actor,omitempty"`
|
||||
}
|
||||
|
||||
// GetWorkflowRun fetches the status of a specific Actions run.
|
||||
@@ -77,3 +88,59 @@ func (c *Client) GetWorkflowRun(ctx context.Context, owner, repo string, runID i
|
||||
}
|
||||
return &run, nil
|
||||
}
|
||||
|
||||
// ListWorkflowRunsArgs captures the optional query params for ListWorkflowRuns.
|
||||
type ListWorkflowRunsArgs struct {
|
||||
Branch string
|
||||
HeadSHA string
|
||||
Status string // queued | in_progress | completed | all
|
||||
Event string // push | pull_request | schedule | workflow_dispatch | all
|
||||
Workflow string
|
||||
Page int
|
||||
Limit int
|
||||
}
|
||||
|
||||
type workflowRunsResponse struct {
|
||||
TotalCount int64 `json:"total_count"`
|
||||
WorkflowRuns []WorkflowRun `json:"workflow_runs"`
|
||||
}
|
||||
|
||||
// ListWorkflowRuns fetches recent Actions runs for a repo with optional filters.
|
||||
// Status / Event of "all" or "" are treated as no-filter.
|
||||
func (c *Client) ListWorkflowRuns(ctx context.Context, owner, repo string, args ListWorkflowRunsArgs) (*workflowRunsResponse, error) {
|
||||
q := url.Values{}
|
||||
if args.Branch != "" {
|
||||
q.Set("branch", args.Branch)
|
||||
}
|
||||
if args.HeadSHA != "" {
|
||||
q.Set("head_sha", args.HeadSHA)
|
||||
}
|
||||
if args.Status != "" && args.Status != "all" {
|
||||
q.Set("status", args.Status)
|
||||
}
|
||||
if args.Event != "" && args.Event != "all" {
|
||||
q.Set("event", args.Event)
|
||||
}
|
||||
if args.Workflow != "" {
|
||||
q.Set("workflow", args.Workflow)
|
||||
}
|
||||
if args.Page > 0 {
|
||||
q.Set("page", strconv.Itoa(args.Page))
|
||||
}
|
||||
if args.Limit > 0 {
|
||||
q.Set("limit", strconv.Itoa(args.Limit))
|
||||
}
|
||||
p := fmt.Sprintf("/api/v1/repos/%s/%s/actions/runs?%s", owner, repo, q.Encode())
|
||||
body, status, err := c.GetJSON(ctx, p)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if err := MapStatus(status, body); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var resp workflowRunsResponse
|
||||
if err := json.Unmarshal(body, &resp); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &resp, nil
|
||||
}
|
||||
|
||||
@@ -45,14 +45,15 @@ func NewCreateProjectFromTemplate(c *gitea.Client, a *allowlist.Allowlist, tmplO
|
||||
func (t *CreateProjectFromTemplate) Descriptor() registry.ToolDescriptor {
|
||||
return registry.ToolDescriptor{
|
||||
Name: "create_project_from_template",
|
||||
Description: "Create a new project repo from the template, applying placeholder substitutions to known files.",
|
||||
Description: "Create a new project repo from a template, applying placeholder substitutions to known files. Defaults to the server-configured template; pass template_name to override (e.g. template-go-agent).",
|
||||
InputSchema: json.RawMessage(`{
|
||||
"type":"object",
|
||||
"properties":{
|
||||
"owner":{"type":"string"},
|
||||
"name":{"type":"string","pattern":"^[a-z][a-z0-9-]{1,38}[a-z0-9]$"},
|
||||
"description":{"type":"string"},
|
||||
"private":{"type":"boolean"}
|
||||
"private":{"type":"boolean"},
|
||||
"template_name":{"type":"string","description":"Template repo name to generate from. Defaults to the server-configured template."}
|
||||
},
|
||||
"required":["owner","name"]
|
||||
}`),
|
||||
@@ -64,6 +65,7 @@ type createProjectArgs struct {
|
||||
Name string `json:"name"`
|
||||
Description string `json:"description"`
|
||||
Private bool `json:"private"`
|
||||
TemplateName string `json:"template_name"`
|
||||
}
|
||||
|
||||
type createProjectResult struct {
|
||||
@@ -91,13 +93,20 @@ func (t *CreateProjectFromTemplate) Call(ctx context.Context, raw json.RawMessag
|
||||
return nil, fmt.Errorf("name %q does not match pattern %s: %w", args.Name, nameRe.String(), gitea.ErrValidation)
|
||||
}
|
||||
|
||||
// Resolve template: per-call override takes precedence over the
|
||||
// server-configured default. Owner stays server-configured.
|
||||
tmplName := args.TemplateName
|
||||
if tmplName == "" {
|
||||
tmplName = t.templateName
|
||||
}
|
||||
|
||||
// Verify template exists and is marked as a template repo.
|
||||
tmpl, err := t.c.GetRepo(ctx, t.templateOwner, t.templateName)
|
||||
tmpl, err := t.c.GetRepo(ctx, t.templateOwner, tmplName)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("template lookup: %w", err)
|
||||
}
|
||||
if !tmpl.Template {
|
||||
return nil, fmt.Errorf("repo %s/%s is not marked as template: %w", t.templateOwner, t.templateName, gitea.ErrValidation)
|
||||
return nil, fmt.Errorf("repo %s/%s is not marked as template: %w", t.templateOwner, tmplName, gitea.ErrValidation)
|
||||
}
|
||||
|
||||
// Verify destination doesn't already exist.
|
||||
@@ -108,7 +117,7 @@ func (t *CreateProjectFromTemplate) Call(ctx context.Context, raw json.RawMessag
|
||||
}
|
||||
|
||||
// Generate repo from template.
|
||||
newRepo, err := t.c.GenerateFromTemplate(ctx, t.templateOwner, t.templateName, gitea.GenerateFromTemplateArgs{
|
||||
newRepo, err := t.c.GenerateFromTemplate(ctx, t.templateOwner, tmplName, gitea.GenerateFromTemplateArgs{
|
||||
Owner: args.Owner,
|
||||
Name: args.Name,
|
||||
Description: args.Description,
|
||||
|
||||
@@ -122,6 +122,62 @@ func TestCreateProjectHappyPath(t *testing.T) {
|
||||
assert.Empty(t, out.PartialFailure)
|
||||
}
|
||||
|
||||
// TestCreateProjectTemplateNameOverride (issue #24): per-call template_name overrides the
|
||||
// server-configured default, so the same binary can generate from template-go-web or
|
||||
// template-go-agent without restart.
|
||||
func TestCreateProjectTemplateNameOverride(t *testing.T) {
|
||||
var templateLookups, generateCalls []string
|
||||
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
switch {
|
||||
case r.Method == http.MethodGet && r.URL.Path == "/api/v1/repos/mathias/template-go-agent":
|
||||
templateLookups = append(templateLookups, "template-go-agent")
|
||||
_, _ = w.Write([]byte(newTemplateRepoJSON("template-go-agent", true)))
|
||||
|
||||
case r.Method == http.MethodGet && r.URL.Path == "/api/v1/repos/mathias/template-go-web":
|
||||
templateLookups = append(templateLookups, "template-go-web")
|
||||
_, _ = w.Write([]byte(newTemplateRepoJSON("template-go-web", true)))
|
||||
|
||||
case r.Method == http.MethodGet && r.URL.Path == "/api/v1/repos/mathias/new-agent":
|
||||
w.WriteHeader(http.StatusNotFound)
|
||||
_, _ = w.Write([]byte(`{"message":"not found"}`))
|
||||
|
||||
case r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/generate"):
|
||||
generateCalls = append(generateCalls, r.URL.Path)
|
||||
w.WriteHeader(http.StatusCreated)
|
||||
_, _ = w.Write([]byte(newGeneratedRepoJSON("new-agent")))
|
||||
|
||||
case r.Method == http.MethodGet && strings.HasPrefix(r.URL.Path, "/api/v1/repos/mathias/new-agent/contents/"):
|
||||
filePath := strings.TrimPrefix(r.URL.Path, "/api/v1/repos/mathias/new-agent/contents/")
|
||||
_, _ = w.Write([]byte(fileContentsJSON(filePath)))
|
||||
|
||||
case r.Method == http.MethodPut && strings.HasPrefix(r.URL.Path, "/api/v1/repos/mathias/new-agent/contents/"):
|
||||
filePath := strings.TrimPrefix(r.URL.Path, "/api/v1/repos/mathias/new-agent/contents/")
|
||||
w.WriteHeader(http.StatusOK)
|
||||
_, _ = w.Write([]byte(fileWriteResultJSON(filePath)))
|
||||
|
||||
default:
|
||||
t.Errorf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
w.WriteHeader(http.StatusNotFound)
|
||||
}
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
// Server is configured with template-go-web as the default; call overrides to template-go-agent.
|
||||
tool := newCreateProjectTool(srv.URL)
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(
|
||||
`{"owner":"mathias","name":"new-agent","template_name":"template-go-agent"}`,
|
||||
))
|
||||
require.NoError(t, err)
|
||||
|
||||
assert.Equal(t, []string{"template-go-agent"}, templateLookups,
|
||||
"override must direct the template lookup, not the server default")
|
||||
require.Len(t, generateCalls, 1)
|
||||
assert.Equal(t, "/api/v1/repos/mathias/template-go-agent/generate", generateCalls[0],
|
||||
"override must direct the /generate call too")
|
||||
}
|
||||
|
||||
// TestCreateProjectNameRegexFailure: invalid name returns ErrValidation without hitting network.
|
||||
func TestCreateProjectNameRegexFailure(t *testing.T) {
|
||||
tool := tools.NewCreateProjectFromTemplate(
|
||||
|
||||
56
internal/tools/issue_close.go
Normal file
56
internal/tools/issue_close.go
Normal file
@@ -0,0 +1,56 @@
|
||||
package tools
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
|
||||
)
|
||||
|
||||
type IssueClose struct {
|
||||
c *gitea.Client
|
||||
a *allowlist.Allowlist
|
||||
}
|
||||
|
||||
func NewIssueClose(c *gitea.Client, a *allowlist.Allowlist) *IssueClose {
|
||||
return &IssueClose{c: c, a: a}
|
||||
}
|
||||
|
||||
func (t *IssueClose) Descriptor() registry.ToolDescriptor {
|
||||
return registry.ToolDescriptor{
|
||||
Name: "issue_close",
|
||||
Description: "Close an open issue. Reversible via issue_reopen.",
|
||||
InputSchema: json.RawMessage(`{
|
||||
"type":"object",
|
||||
"properties":{
|
||||
"owner":{"type":"string"},
|
||||
"name":{"type":"string"},
|
||||
"number":{"type":"integer","minimum":1}
|
||||
},
|
||||
"required":["owner","name","number"]
|
||||
}`),
|
||||
}
|
||||
}
|
||||
|
||||
type issueCloseArgs struct {
|
||||
Owner string `json:"owner"`
|
||||
Name string `json:"name"`
|
||||
Number int `json:"number"`
|
||||
}
|
||||
|
||||
func (t *IssueClose) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
|
||||
var args issueCloseArgs
|
||||
if err := parseArgs(raw, &args); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if err := t.a.Check(args.Owner); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
iss, err := t.c.SetIssueState(ctx, args.Owner, args.Name, args.Number, "closed")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return textOK(iss)
|
||||
}
|
||||
52
internal/tools/issue_close_test.go
Normal file
52
internal/tools/issue_close_test.go
Normal file
@@ -0,0 +1,52 @@
|
||||
package tools_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"io"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
)
|
||||
|
||||
func TestIssueCloseTool(t *testing.T) {
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
assert.Equal(t, http.MethodPatch, r.Method)
|
||||
assert.Equal(t, "/api/v1/repos/mathias/infra/issues/26", r.URL.Path)
|
||||
b, _ := io.ReadAll(r.Body)
|
||||
assert.JSONEq(t, `{"state":"closed"}`, string(b))
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write([]byte(`{"number":26,"title":"feat: ntfy via NPM","state":"closed","html_url":"http://gitea.example.com/mathias/infra/issues/26"}`))
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
tool := tools.NewIssueClose(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
|
||||
out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":26}`))
|
||||
require.NoError(t, err)
|
||||
assert.Contains(t, string(out), `"number":26`)
|
||||
assert.Contains(t, string(out), `"state":"closed"`)
|
||||
}
|
||||
|
||||
func TestIssueCloseTool_NotFound(t *testing.T) {
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
w.WriteHeader(http.StatusNotFound)
|
||||
_, _ = w.Write([]byte(`{"message":"issue not found"}`))
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
tool := tools.NewIssueClose(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":999}`))
|
||||
require.Error(t, err)
|
||||
}
|
||||
|
||||
func TestIssueCloseAllowlistRejects(t *testing.T) {
|
||||
tool := tools.NewIssueClose(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x","number":1}`))
|
||||
require.Error(t, err)
|
||||
}
|
||||
83
internal/tools/issue_list.go
Normal file
83
internal/tools/issue_list.go
Normal file
@@ -0,0 +1,83 @@
|
||||
package tools
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
|
||||
)
|
||||
|
||||
type IssueList struct {
|
||||
c *gitea.Client
|
||||
a *allowlist.Allowlist
|
||||
}
|
||||
|
||||
func NewIssueList(c *gitea.Client, a *allowlist.Allowlist) *IssueList {
|
||||
return &IssueList{c: c, a: a}
|
||||
}
|
||||
|
||||
func (t *IssueList) Descriptor() registry.ToolDescriptor {
|
||||
return registry.ToolDescriptor{
|
||||
Name: "issue_list",
|
||||
Description: "List issues in a repo with optional filters. PRs are excluded (use pr_list for those).",
|
||||
InputSchema: json.RawMessage(`{
|
||||
"type":"object",
|
||||
"properties":{
|
||||
"owner":{"type":"string"},
|
||||
"name":{"type":"string"},
|
||||
"state":{"type":"string","enum":["open","closed","all"]},
|
||||
"labels":{"type":"string"},
|
||||
"since":{"type":"string"},
|
||||
"page":{"type":"integer","minimum":1},
|
||||
"limit":{"type":"integer","minimum":1,"maximum":50}
|
||||
},
|
||||
"required":["owner","name"]
|
||||
}`),
|
||||
}
|
||||
}
|
||||
|
||||
type issueListArgs struct {
|
||||
Owner string `json:"owner"`
|
||||
Name string `json:"name"`
|
||||
State string `json:"state"`
|
||||
Labels string `json:"labels"`
|
||||
Since string `json:"since"`
|
||||
Page int `json:"page"`
|
||||
Limit int `json:"limit"`
|
||||
}
|
||||
|
||||
func (t *IssueList) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
|
||||
var args issueListArgs
|
||||
if err := parseArgs(raw, &args); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if err := t.a.Check(args.Owner); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if args.State == "" {
|
||||
args.State = "open"
|
||||
}
|
||||
args.Limit = capLimit(args.Limit, 30)
|
||||
if args.Page < 1 {
|
||||
args.Page = 1
|
||||
}
|
||||
issues, err := t.c.ListIssues(ctx, args.Owner, args.Name, gitea.ListIssuesArgs{
|
||||
State: args.State,
|
||||
Labels: args.Labels,
|
||||
Since: args.Since,
|
||||
Page: args.Page,
|
||||
Limit: args.Limit,
|
||||
})
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
out := map[string]any{
|
||||
"issues": issues,
|
||||
}
|
||||
if len(issues) == args.Limit {
|
||||
out["next_page"] = args.Page + 1
|
||||
}
|
||||
return textOK(out)
|
||||
}
|
||||
88
internal/tools/issue_list_test.go
Normal file
88
internal/tools/issue_list_test.go
Normal file
@@ -0,0 +1,88 @@
|
||||
package tools_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
)
|
||||
|
||||
func TestIssueListTool(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
input string
|
||||
wantQuery map[string]string
|
||||
respBody string
|
||||
assert func(t *testing.T, out string)
|
||||
}{
|
||||
{
|
||||
name: "happy path defaults",
|
||||
input: `{"owner":"mathias","name":"infra"}`,
|
||||
wantQuery: map[string]string{"type": "issues", "state": "open", "page": "1", "limit": "30"},
|
||||
respBody: `[{"number":42,"title":"fix auth","state":"open","html_url":"http://gitea.example/m/infra/issues/42"},{"number":41,"title":"add tests","state":"open"}]`,
|
||||
assert: func(t *testing.T, out string) {
|
||||
assert.Contains(t, out, `"number":42`)
|
||||
assert.Contains(t, out, `"number":41`)
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "state filter",
|
||||
input: `{"owner":"mathias","name":"infra","state":"closed"}`,
|
||||
wantQuery: map[string]string{"type": "issues", "state": "closed"},
|
||||
respBody: `[]`,
|
||||
assert: func(t *testing.T, out string) {
|
||||
assert.Contains(t, out, `"issues":[]`)
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "label + since filter",
|
||||
input: `{"owner":"mathias","name":"infra","labels":"bug,critical","since":"2026-05-01T00:00:00Z"}`,
|
||||
wantQuery: map[string]string{"labels": "bug,critical", "since": "2026-05-01T00:00:00Z"},
|
||||
respBody: `[]`,
|
||||
assert: func(t *testing.T, out string) {},
|
||||
},
|
||||
{
|
||||
name: "empty result",
|
||||
input: `{"owner":"mathias","name":"infra"}`,
|
||||
wantQuery: map[string]string{"state": "open"},
|
||||
respBody: `[]`,
|
||||
assert: func(t *testing.T, out string) {
|
||||
assert.Contains(t, out, `"issues":[]`)
|
||||
assert.NotContains(t, out, `next_page`)
|
||||
},
|
||||
},
|
||||
}
|
||||
for _, tc := range tests {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
assert.Equal(t, http.MethodGet, r.Method)
|
||||
assert.Equal(t, "/api/v1/repos/mathias/infra/issues", r.URL.Path)
|
||||
q := r.URL.Query()
|
||||
for k, v := range tc.wantQuery {
|
||||
assert.Equal(t, v, q.Get(k), "query param %q", k)
|
||||
}
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write([]byte(tc.respBody))
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
tool := tools.NewIssueList(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
|
||||
out, err := tool.Call(context.Background(), json.RawMessage(tc.input))
|
||||
require.NoError(t, err)
|
||||
tc.assert(t, string(out))
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestIssueListAllowlistRejects(t *testing.T) {
|
||||
tool := tools.NewIssueList(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x"}`))
|
||||
require.Error(t, err)
|
||||
}
|
||||
56
internal/tools/issue_reopen.go
Normal file
56
internal/tools/issue_reopen.go
Normal file
@@ -0,0 +1,56 @@
|
||||
package tools
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
|
||||
)
|
||||
|
||||
type IssueReopen struct {
|
||||
c *gitea.Client
|
||||
a *allowlist.Allowlist
|
||||
}
|
||||
|
||||
func NewIssueReopen(c *gitea.Client, a *allowlist.Allowlist) *IssueReopen {
|
||||
return &IssueReopen{c: c, a: a}
|
||||
}
|
||||
|
||||
func (t *IssueReopen) Descriptor() registry.ToolDescriptor {
|
||||
return registry.ToolDescriptor{
|
||||
Name: "issue_reopen",
|
||||
Description: "Reopen a closed issue. Reversible via issue_close.",
|
||||
InputSchema: json.RawMessage(`{
|
||||
"type":"object",
|
||||
"properties":{
|
||||
"owner":{"type":"string"},
|
||||
"name":{"type":"string"},
|
||||
"number":{"type":"integer","minimum":1}
|
||||
},
|
||||
"required":["owner","name","number"]
|
||||
}`),
|
||||
}
|
||||
}
|
||||
|
||||
type issueReopenArgs struct {
|
||||
Owner string `json:"owner"`
|
||||
Name string `json:"name"`
|
||||
Number int `json:"number"`
|
||||
}
|
||||
|
||||
func (t *IssueReopen) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
|
||||
var args issueReopenArgs
|
||||
if err := parseArgs(raw, &args); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if err := t.a.Check(args.Owner); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
iss, err := t.c.SetIssueState(ctx, args.Owner, args.Name, args.Number, "open")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return textOK(iss)
|
||||
}
|
||||
40
internal/tools/issue_reopen_test.go
Normal file
40
internal/tools/issue_reopen_test.go
Normal file
@@ -0,0 +1,40 @@
|
||||
package tools_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"io"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
)
|
||||
|
||||
func TestIssueReopenTool(t *testing.T) {
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
assert.Equal(t, http.MethodPatch, r.Method)
|
||||
assert.Equal(t, "/api/v1/repos/mathias/infra/issues/26", r.URL.Path)
|
||||
b, _ := io.ReadAll(r.Body)
|
||||
assert.JSONEq(t, `{"state":"open"}`, string(b))
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write([]byte(`{"number":26,"title":"feat: ntfy via NPM","state":"open","html_url":"http://gitea.example.com/mathias/infra/issues/26"}`))
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
tool := tools.NewIssueReopen(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
|
||||
out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","number":26}`))
|
||||
require.NoError(t, err)
|
||||
assert.Contains(t, string(out), `"number":26`)
|
||||
assert.Contains(t, string(out), `"state":"open"`)
|
||||
}
|
||||
|
||||
func TestIssueReopenAllowlistRejects(t *testing.T) {
|
||||
tool := tools.NewIssueReopen(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x","number":1}`))
|
||||
require.Error(t, err)
|
||||
}
|
||||
@@ -143,7 +143,13 @@ func splitUnifiedDiff(d []byte) map[string][]byte {
|
||||
|
||||
flush := func() {
|
||||
if currentFile != "" {
|
||||
m[currentFile] = current.Bytes()
|
||||
// Copy: bytes.Buffer.Bytes() returns the internal slice,
|
||||
// which Reset() then reuses. Without the copy, every map
|
||||
// entry ends up aliased to the last file's data.
|
||||
b := current.Bytes()
|
||||
cp := make([]byte, len(b))
|
||||
copy(cp, b)
|
||||
m[currentFile] = cp
|
||||
current.Reset()
|
||||
}
|
||||
}
|
||||
|
||||
@@ -97,6 +97,47 @@ func TestPRFilesDiffSmall(t *testing.T) {
|
||||
assert.ElementsMatch(t, fileNames, paths)
|
||||
}
|
||||
|
||||
// Regression for issue #25: every file's diff entry must contain its OWN diff,
|
||||
// not a shared buffer pointing at the last file. Prior bug: splitUnifiedDiff
|
||||
// flushed bytes.Buffer.Bytes() into the map without copying, so every entry
|
||||
// aliased the buffer's backing array and showed the last file's content.
|
||||
func TestPRFilesDiffPerFileIsolation(t *testing.T) {
|
||||
fileNames := []string{"alpha.go", "beta.go", "gamma.go", "delta.go"}
|
||||
rawDiff := buildDiff(fileNames, 5)
|
||||
filesJSON := buildFilesJSON(fileNames, 5)
|
||||
|
||||
srv := newPRFilesDiffServer(t, filesJSON, rawDiff)
|
||||
defer srv.Close()
|
||||
|
||||
tool := tools.NewPRFilesDiff(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"o"}))
|
||||
result, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"o","name":"r","number":1}`))
|
||||
require.NoError(t, err)
|
||||
|
||||
var out struct {
|
||||
Files []struct {
|
||||
Path string `json:"path"`
|
||||
Diff string `json:"diff"`
|
||||
} `json:"files"`
|
||||
}
|
||||
require.NoError(t, json.Unmarshal(result, &out))
|
||||
require.Len(t, out.Files, len(fileNames))
|
||||
|
||||
for _, f := range out.Files {
|
||||
expected := fmt.Sprintf("diff --git a/%s b/%s", f.Path, f.Path)
|
||||
assert.Contains(t, f.Diff, expected,
|
||||
"file %s diff must contain its own header, got: %.80q", f.Path, f.Diff)
|
||||
// No other file's header should leak in.
|
||||
for _, other := range fileNames {
|
||||
if other == f.Path {
|
||||
continue
|
||||
}
|
||||
otherHeader := fmt.Sprintf("diff --git a/%s b/%s", other, other)
|
||||
assert.NotContains(t, f.Diff, otherHeader,
|
||||
"file %s diff must NOT contain %s's header", f.Path, other)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestPRFilesDiffPerFileTruncated(t *testing.T) {
|
||||
// One file with a 30KB diff (each "+abcdefghij\n" = 12 bytes; 30KB / 12 ≈ 2560 lines).
|
||||
fileNames := []string{"bigfile.go"}
|
||||
|
||||
@@ -22,16 +22,20 @@ func NewRepoUpdate(c *gitea.Client, a *allowlist.Allowlist) *RepoUpdate {
|
||||
func (t *RepoUpdate) Descriptor() registry.ToolDescriptor {
|
||||
return registry.ToolDescriptor{
|
||||
Name: "repo_update",
|
||||
Description: "Update repository metadata (description, visibility, default branch, website).",
|
||||
Description: "Update repository metadata (description, visibility, default branch, website, archived, template). " +
|
||||
"Only fields explicitly set in the call are patched. " +
|
||||
"WARNING: private=false exposes the repo publicly — verify intent before calling.",
|
||||
InputSchema: json.RawMessage(`{
|
||||
"type":"object",
|
||||
"properties":{
|
||||
"owner":{"type":"string"},
|
||||
"name":{"type":"string"},
|
||||
"description":{"type":"string"},
|
||||
"private":{"type":"boolean"},
|
||||
"website":{"type":"string"},
|
||||
"default_branch":{"type":"string"},
|
||||
"private":{"type":"boolean","description":"Toggle visibility. false makes the repo public."},
|
||||
"website":{"type":"string","description":"Homepage URL"},
|
||||
"default_branch":{"type":"string","description":"Rename the default branch"},
|
||||
"archived":{"type":"boolean","description":"Mark repo as archived (read-only)."},
|
||||
"template":{"type":"boolean","description":"Toggle template-repo flag"},
|
||||
"confirm":{"type":"string","description":"Required when setting private=false. Must equal the repo name."}
|
||||
},
|
||||
"required":["owner","name"]
|
||||
@@ -42,10 +46,12 @@ func (t *RepoUpdate) Descriptor() registry.ToolDescriptor {
|
||||
type repoUpdateArgs struct {
|
||||
Owner string `json:"owner"`
|
||||
Name string `json:"name"`
|
||||
Description *string `json:"description"`
|
||||
Private *bool `json:"private"`
|
||||
Website *string `json:"website"`
|
||||
DefaultBranch *string `json:"default_branch"`
|
||||
Description *string `json:"description,omitempty"`
|
||||
Private *bool `json:"private,omitempty"`
|
||||
Website *string `json:"website,omitempty"`
|
||||
DefaultBranch *string `json:"default_branch,omitempty"`
|
||||
Archived *bool `json:"archived,omitempty"`
|
||||
Template *bool `json:"template,omitempty"`
|
||||
Confirm string `json:"confirm"`
|
||||
}
|
||||
|
||||
@@ -57,17 +63,26 @@ func (t *RepoUpdate) Call(ctx context.Context, raw json.RawMessage) (json.RawMes
|
||||
if err := t.a.Check(args.Owner); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
// Making a repo public is a significant action — require explicit confirmation.
|
||||
if args.Private != nil && !*args.Private {
|
||||
if args.Confirm != args.Name {
|
||||
return nil, fmt.Errorf("setting private=false makes the repo public: set confirm=%q to proceed", args.Name)
|
||||
}
|
||||
}
|
||||
|
||||
if args.Description == nil && args.Private == nil && args.Website == nil &&
|
||||
args.DefaultBranch == nil && args.Archived == nil && args.Template == nil {
|
||||
return nil, fmt.Errorf("at least one updatable field must be set: %w", gitea.ErrValidation)
|
||||
}
|
||||
|
||||
r, err := t.c.UpdateRepo(ctx, args.Owner, args.Name, gitea.UpdateRepoArgs{
|
||||
Description: args.Description,
|
||||
Private: args.Private,
|
||||
Website: args.Website,
|
||||
DefaultBranch: args.DefaultBranch,
|
||||
Archived: args.Archived,
|
||||
Template: args.Template,
|
||||
})
|
||||
if err != nil {
|
||||
return nil, err
|
||||
|
||||
@@ -3,6 +3,7 @@ package tools_test
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"io"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
@@ -14,43 +15,139 @@ import (
|
||||
"github.com/stretchr/testify/require"
|
||||
)
|
||||
|
||||
func TestRepoUpdateTool(t *testing.T) {
|
||||
func newRepoUpdateTool(srvURL string) *tools.RepoUpdate {
|
||||
return tools.NewRepoUpdate(gitea.NewClient(srvURL, "tok"), allowlist.New([]string{"mathias"}))
|
||||
}
|
||||
|
||||
// TestRepoUpdateArchive: happy path — set archived=true.
|
||||
func TestRepoUpdateArchive(t *testing.T) {
|
||||
var patchedBody []byte
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
assert.Equal(t, http.MethodPatch, r.Method)
|
||||
assert.Equal(t, "/api/v1/repos/mathias/infra", r.URL.Path)
|
||||
require.Equal(t, http.MethodPatch, r.Method)
|
||||
require.Equal(t, "/api/v1/repos/mathias/old-svc", r.URL.Path)
|
||||
patchedBody, _ = io.ReadAll(r.Body)
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write([]byte(`{"name":"infra","full_name":"mathias/infra","default_branch":"main","description":"updated","private":true,"clone_url":"https://gitea.example.com/mathias/infra.git","html_url":"https://gitea.example.com/mathias/infra"}`))
|
||||
_, _ = w.Write([]byte(`{"name":"old-svc","full_name":"mathias/old-svc","default_branch":"main","template":false,"private":false}`))
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
tool := tools.NewRepoUpdate(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
|
||||
out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","description":"updated"}`))
|
||||
tool := newRepoUpdateTool(srv.URL)
|
||||
result, err := tool.Call(context.Background(), json.RawMessage(
|
||||
`{"owner":"mathias","name":"old-svc","archived":true}`,
|
||||
))
|
||||
require.NoError(t, err)
|
||||
assert.Contains(t, string(out), `"description":"updated"`)
|
||||
|
||||
// Wire payload only contains the field that was actually set.
|
||||
var sent map[string]any
|
||||
require.NoError(t, json.Unmarshal(patchedBody, &sent))
|
||||
assert.Equal(t, true, sent["archived"])
|
||||
assert.NotContains(t, sent, "description")
|
||||
assert.NotContains(t, sent, "private")
|
||||
assert.NotContains(t, sent, "website")
|
||||
assert.NotContains(t, sent, "template")
|
||||
|
||||
var repo gitea.Repo
|
||||
require.NoError(t, json.Unmarshal(result, &repo))
|
||||
assert.Equal(t, "mathias/old-svc", repo.FullName)
|
||||
}
|
||||
|
||||
func TestRepoUpdateTool_MakePublicRequiresConfirm(t *testing.T) {
|
||||
tool := tools.NewRepoUpdate(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","private":false}`))
|
||||
// TestRepoUpdateMultipleFields: set description + template flag in one call.
|
||||
func TestRepoUpdateMultipleFields(t *testing.T) {
|
||||
var patchedBody []byte
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
patchedBody, _ = io.ReadAll(r.Body)
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write([]byte(`{"name":"template-go-agent","full_name":"mathias/template-go-agent","description":"Go agent template","template":true}`))
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
tool := newRepoUpdateTool(srv.URL)
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(
|
||||
`{"owner":"mathias","name":"template-go-agent","description":"Go agent template","template":true}`,
|
||||
))
|
||||
require.NoError(t, err)
|
||||
|
||||
var sent map[string]any
|
||||
require.NoError(t, json.Unmarshal(patchedBody, &sent))
|
||||
assert.Equal(t, "Go agent template", sent["description"])
|
||||
assert.Equal(t, true, sent["template"])
|
||||
assert.NotContains(t, sent, "archived")
|
||||
assert.NotContains(t, sent, "private")
|
||||
}
|
||||
|
||||
// TestRepoUpdateNoFieldsRejected: zero updatable fields → validation error before network.
|
||||
func TestRepoUpdateNoFieldsRejected(t *testing.T) {
|
||||
tool := tools.NewRepoUpdate(
|
||||
gitea.NewClient("http://unused", ""),
|
||||
allowlist.New([]string{"mathias"}),
|
||||
)
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(
|
||||
`{"owner":"mathias","name":"some-repo"}`,
|
||||
))
|
||||
require.Error(t, err)
|
||||
assert.ErrorIs(t, err, gitea.ErrValidation)
|
||||
}
|
||||
|
||||
// TestRepoUpdateMakePublic: private=false requires confirm=<repo name> as a safety
|
||||
// gate (kept from main #21 during the v02-patch merge). With confirm matching, the
|
||||
// patch goes through.
|
||||
func TestRepoUpdateMakePublic(t *testing.T) {
|
||||
var patchedBody []byte
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
patchedBody, _ = io.ReadAll(r.Body)
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write([]byte(`{"name":"open-repo","full_name":"mathias/open-repo","private":false}`))
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
tool := newRepoUpdateTool(srv.URL)
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(
|
||||
`{"owner":"mathias","name":"open-repo","private":false,"confirm":"open-repo"}`,
|
||||
))
|
||||
require.NoError(t, err)
|
||||
|
||||
var sent map[string]any
|
||||
require.NoError(t, json.Unmarshal(patchedBody, &sent))
|
||||
assert.Equal(t, false, sent["private"])
|
||||
}
|
||||
|
||||
// TestRepoUpdateMakePublicWithoutConfirm: confirm gate blocks private=false without confirmation.
|
||||
func TestRepoUpdateMakePublicWithoutConfirm(t *testing.T) {
|
||||
tool := tools.NewRepoUpdate(
|
||||
gitea.NewClient("http://unused", ""),
|
||||
allowlist.New([]string{"mathias"}),
|
||||
)
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(
|
||||
`{"owner":"mathias","name":"open-repo","private":false}`,
|
||||
))
|
||||
require.Error(t, err)
|
||||
assert.Contains(t, err.Error(), "confirm")
|
||||
}
|
||||
|
||||
func TestRepoUpdateTool_MakePublicWithConfirm(t *testing.T) {
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write([]byte(`{"name":"infra","full_name":"mathias/infra","default_branch":"main","private":false,"clone_url":"","html_url":""}`))
|
||||
// TestRepoUpdateAllowlistRejects: owner outside allowlist denied without network call.
|
||||
func TestRepoUpdateAllowlistRejects(t *testing.T) {
|
||||
tool := tools.NewRepoUpdate(
|
||||
gitea.NewClient("http://unused", ""),
|
||||
allowlist.New([]string{"mathias"}),
|
||||
)
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(
|
||||
`{"owner":"evil","name":"some-repo","archived":true}`,
|
||||
))
|
||||
require.Error(t, err)
|
||||
}
|
||||
|
||||
// TestRepoUpdateUpstreamError: server 500 propagates as ErrUpstream.
|
||||
func TestRepoUpdateUpstreamError(t *testing.T) {
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
|
||||
w.WriteHeader(http.StatusInternalServerError)
|
||||
_, _ = w.Write([]byte(`{"message":"internal"}`))
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
tool := tools.NewRepoUpdate(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
|
||||
out, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"mathias","name":"infra","private":false,"confirm":"infra"}`))
|
||||
require.NoError(t, err)
|
||||
assert.Contains(t, string(out), `"full_name":"mathias/infra"`)
|
||||
}
|
||||
|
||||
func TestRepoUpdateAllowlistRejects(t *testing.T) {
|
||||
tool := tools.NewRepoUpdate(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x"}`))
|
||||
tool := newRepoUpdateTool(srv.URL)
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(
|
||||
`{"owner":"mathias","name":"some-repo","archived":true}`,
|
||||
))
|
||||
require.Error(t, err)
|
||||
assert.ErrorIs(t, err, gitea.ErrUpstream)
|
||||
}
|
||||
|
||||
87
internal/tools/workflow_run_list.go
Normal file
87
internal/tools/workflow_run_list.go
Normal file
@@ -0,0 +1,87 @@
|
||||
package tools
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/registry"
|
||||
)
|
||||
|
||||
type WorkflowRunList struct {
|
||||
c *gitea.Client
|
||||
a *allowlist.Allowlist
|
||||
}
|
||||
|
||||
func NewWorkflowRunList(c *gitea.Client, a *allowlist.Allowlist) *WorkflowRunList {
|
||||
return &WorkflowRunList{c: c, a: a}
|
||||
}
|
||||
|
||||
func (t *WorkflowRunList) Descriptor() registry.ToolDescriptor {
|
||||
return registry.ToolDescriptor{
|
||||
Name: "workflow_run_list",
|
||||
Description: "List recent Gitea Actions workflow runs with optional filters (branch, head_sha, status, event, workflow).",
|
||||
InputSchema: json.RawMessage(`{
|
||||
"type":"object",
|
||||
"properties":{
|
||||
"owner":{"type":"string"},
|
||||
"name":{"type":"string"},
|
||||
"branch":{"type":"string"},
|
||||
"head_sha":{"type":"string"},
|
||||
"status":{"type":"string","enum":["queued","in_progress","completed","all"]},
|
||||
"event":{"type":"string","enum":["push","pull_request","schedule","workflow_dispatch","all"]},
|
||||
"workflow":{"type":"string"},
|
||||
"page":{"type":"integer","minimum":1},
|
||||
"limit":{"type":"integer","minimum":1,"maximum":50}
|
||||
},
|
||||
"required":["owner","name"]
|
||||
}`),
|
||||
}
|
||||
}
|
||||
|
||||
type workflowRunListArgs struct {
|
||||
Owner string `json:"owner"`
|
||||
Name string `json:"name"`
|
||||
Branch string `json:"branch"`
|
||||
HeadSHA string `json:"head_sha"`
|
||||
Status string `json:"status"`
|
||||
Event string `json:"event"`
|
||||
Workflow string `json:"workflow"`
|
||||
Page int `json:"page"`
|
||||
Limit int `json:"limit"`
|
||||
}
|
||||
|
||||
func (t *WorkflowRunList) Call(ctx context.Context, raw json.RawMessage) (json.RawMessage, error) {
|
||||
var args workflowRunListArgs
|
||||
if err := parseArgs(raw, &args); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if err := t.a.Check(args.Owner); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
args.Limit = capLimit(args.Limit, 10)
|
||||
if args.Page < 1 {
|
||||
args.Page = 1
|
||||
}
|
||||
resp, err := t.c.ListWorkflowRuns(ctx, args.Owner, args.Name, gitea.ListWorkflowRunsArgs{
|
||||
Branch: args.Branch,
|
||||
HeadSHA: args.HeadSHA,
|
||||
Status: args.Status,
|
||||
Event: args.Event,
|
||||
Workflow: args.Workflow,
|
||||
Page: args.Page,
|
||||
Limit: args.Limit,
|
||||
})
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
out := map[string]any{
|
||||
"runs": resp.WorkflowRuns,
|
||||
"total": resp.TotalCount,
|
||||
}
|
||||
if len(resp.WorkflowRuns) == args.Limit {
|
||||
out["next_page"] = args.Page + 1
|
||||
}
|
||||
return textOK(out)
|
||||
}
|
||||
98
internal/tools/workflow_run_list_test.go
Normal file
98
internal/tools/workflow_run_list_test.go
Normal file
@@ -0,0 +1,98 @@
|
||||
package tools_test
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/allowlist"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/gitea"
|
||||
"gitea.d-ma.be/mathias/gitea-mcp/internal/tools"
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
)
|
||||
|
||||
func TestWorkflowRunListTool(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
input string
|
||||
wantQuery map[string]string
|
||||
notQuery []string
|
||||
respBody string
|
||||
assert func(t *testing.T, out string)
|
||||
}{
|
||||
{
|
||||
name: "happy path defaults",
|
||||
input: `{"owner":"mathias","name":"gitea-mcp"}`,
|
||||
wantQuery: map[string]string{"page": "1", "limit": "10"},
|
||||
respBody: `{"total_count":2,"workflow_runs":[{"id":823,"status":"completed","conclusion":"success","head_sha":"dc907fb"},{"id":822,"status":"completed","conclusion":"success","head_sha":"c4bd339"}]}`,
|
||||
assert: func(t *testing.T, out string) {
|
||||
assert.Contains(t, out, `"id":823`)
|
||||
assert.Contains(t, out, `"total":2`)
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "head_sha short filter",
|
||||
input: `{"owner":"mathias","name":"gitea-mcp","head_sha":"dc907fb"}`,
|
||||
wantQuery: map[string]string{"head_sha": "dc907fb"},
|
||||
respBody: `{"total_count":1,"workflow_runs":[{"id":823,"status":"completed","conclusion":"success","head_sha":"dc907fb"}]}`,
|
||||
assert: func(t *testing.T, out string) {
|
||||
assert.Contains(t, out, `"id":823`)
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "status filter",
|
||||
input: `{"owner":"mathias","name":"gitea-mcp","status":"in_progress"}`,
|
||||
wantQuery: map[string]string{"status": "in_progress"},
|
||||
respBody: `{"total_count":0,"workflow_runs":[]}`,
|
||||
assert: func(t *testing.T, out string) {
|
||||
assert.Contains(t, out, `"runs":[]`)
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "status=all is no-op",
|
||||
input: `{"owner":"mathias","name":"gitea-mcp","status":"all"}`,
|
||||
notQuery: []string{"status"},
|
||||
respBody: `{"total_count":0,"workflow_runs":[]}`,
|
||||
assert: func(t *testing.T, out string) {},
|
||||
},
|
||||
{
|
||||
name: "branch filter",
|
||||
input: `{"owner":"mathias","name":"gitea-mcp","branch":"main"}`,
|
||||
wantQuery: map[string]string{"branch": "main"},
|
||||
respBody: `{"total_count":0,"workflow_runs":[]}`,
|
||||
assert: func(t *testing.T, out string) {},
|
||||
},
|
||||
}
|
||||
for _, tc := range tests {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
assert.Equal(t, http.MethodGet, r.Method)
|
||||
assert.Equal(t, "/api/v1/repos/mathias/gitea-mcp/actions/runs", r.URL.Path)
|
||||
q := r.URL.Query()
|
||||
for k, v := range tc.wantQuery {
|
||||
assert.Equal(t, v, q.Get(k), "query param %q", k)
|
||||
}
|
||||
for _, k := range tc.notQuery {
|
||||
assert.Equal(t, "", q.Get(k), "query param %q should be absent", k)
|
||||
}
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write([]byte(tc.respBody))
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
tool := tools.NewWorkflowRunList(gitea.NewClient(srv.URL, "tok"), allowlist.New([]string{"mathias"}))
|
||||
out, err := tool.Call(context.Background(), json.RawMessage(tc.input))
|
||||
require.NoError(t, err)
|
||||
tc.assert(t, string(out))
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestWorkflowRunListAllowlistRejects(t *testing.T) {
|
||||
tool := tools.NewWorkflowRunList(gitea.NewClient("http://unused", ""), allowlist.New([]string{"mathias"}))
|
||||
_, err := tool.Call(context.Background(), json.RawMessage(`{"owner":"evil","name":"x"}`))
|
||||
require.Error(t, err)
|
||||
}
|
||||
Reference in New Issue
Block a user