added .claude/skills: introduced on-demand skill guides for architecture, PR documentation, and testing conventions; updated AGENTS.md to reference new skills
This commit is contained in:
Michael Hoennig
@@ -0,0 +1,67 @@
|
||||
---
|
||||
name: architecture
|
||||
description: Detailed GitTally subsystem architecture — CLI wiring and exit codes, server mode, web UI, configuration system, git access, build execution (native and Docker), watcher poll cycle, and system metrics. Use when designing or modifying code in the commands, config, git, gitea, build, artifacts, watcher, metrics, or server packages, or when a question goes beyond the overview in AGENTS.md.
|
||||
---
|
||||
|
||||
# GitTally Architecture
|
||||
|
||||
GitTally is a lightweight, declarative CI/CD build system.
|
||||
It is a dual-mode application: **CLI** (interactive, status, config) and **Server** (HTTP, persistent).
|
||||
|
||||
## Entry Point and CLI Wiring
|
||||
|
||||
Spring Boot starts via `GitTallyApplication`. A separate `CliRunner` component (in the same file) implements both `CommandLineRunner` (runs picocli) and `ExitCodeGenerator` (returns the exit code). `exitProcess` is called only from `main()` via `SpringApplication.exit()` — **never** inside `run()`. This keeps the Spring context alive during tests.
|
||||
|
||||
Picocli commands are Spring `@Component` beans. The root command (`GitTallyCommand`) declares subcommands as class references in `@Command(subcommands = [...])`. Picocli resolves them from the Spring context via the auto-configured `IFactory` bean.
|
||||
|
||||
```
|
||||
GitTallyApplication ← @SpringBootApplication
|
||||
CliRunner ← CommandLineRunner + ExitCodeGenerator
|
||||
GitTallyCommand ← root @Command, delegates to subcommands
|
||||
commands/
|
||||
InitCommand ← "init [--systemd]"
|
||||
ServerCommand ← "server"
|
||||
StatusCommand ← "status [--history]"
|
||||
BuildCommand ← "build [<branch>]"
|
||||
RetryCommand ← "retry"
|
||||
ConfigPrintCommand ← "config:print [--full]"
|
||||
```
|
||||
|
||||
`status`, `build`, and `retry` implement `Callable<Int>` for their exit codes (0 success, 1 build failure, 2 usage/config errors).
|
||||
`build` and `retry` run builds through the async `BuildExecutor` but block until completion via `ConsoleBuildRunner`, which streams the live log to stdout and waits for the artifact persist before the JVM exits.
|
||||
Branch arguments resolve legacy-style name fragments (`BranchNameResolution`); the CLI reuses `UiFormats` so console and web UI display the same formats.
|
||||
|
||||
The web application type is set to `none` in `application.yml`, so plain CLI runs never start a web server. The `server` subcommand launches a **second** `SpringApplication` with `WebApplicationType.SERVLET` and the `server` profile, then blocks until shutdown. `application-server.yml` switches the web type (`spring.main.*` properties beat programmatic builder settings), `CliRunner` is `@Profile("!server")` so the second context does not run picocli again, and the watcher poll loop starts only in the `server` profile (`ServerWatcherLifecycle`). The JSON API, artifact serving, and the web UI live in the `server` package; mutating endpoints are guarded by a generated control token under `.git/gittally/control-token`.
|
||||
|
||||
## Web UI
|
||||
|
||||
The UI is server-rendered Thymeleaf (`UiController`, templates under `src/main/resources/templates/`) plus one hand-written JavaScript file (`static/gittally.js`) — no SPA framework, no frontend build pipeline. Pages render the full state server-side; the script then polls the JSON API and re-renders table bodies from data. Every fetch has a timeout and failures flip an explicit error badge — never re-fetch and diff whole HTML pages, and never leave a spinner without an error path (the legacy defect). Polling pauses while the tab is hidden. `UiFormats`/`gittally.js` must produce the same display formats (timestamps, durations).
|
||||
|
||||
## Configuration System
|
||||
|
||||
GitTally is configured by two YAML files, deep-merged by `ConfigLoader` (later wins):
|
||||
|
||||
1. `.gittally.yml` at the repo root — committed, shared team settings.
|
||||
2. `.git/gittally/.gittally.yml` — not committed; machine-specific overrides and secrets (`git.account`, `git.token`).
|
||||
|
||||
After merging, `branches.default` is merged into every other named branch entry as its fallback, then the result is bound to the `GitTallyConfig` data classes (`config/GitTallyConfig.kt`), which define the schema and all defaults.
|
||||
|
||||
Three places must stay in sync when config keys change: the `GitTallyConfig` data classes, the commented templates generated by `InitCommand`, and the reference in `docs/configuration.md`.
|
||||
|
||||
## Git Access
|
||||
|
||||
`GitService` shells out to the `git` CLI via `GitCommandRunner` (a thin `ProcessBuilder` wrapper; no JGit). Commands that need repo information take it as a constructor dependency so tests can mock it. HTTPS fetches authenticate via a temporary, secret-free `GIT_ASKPASS` script (`GitAskPass`) with credentials from config passed through environment variables.
|
||||
|
||||
## Build Execution
|
||||
|
||||
`BuildExecutor` runs builds asynchronously: up to `builds.maxConcurrent` branches concurrently (default 1), but never more than one build per branch at a time. Each branch builds in its own reusable git worktree at `.git/gittally/worktrees/<branchKey>` (`BranchWorkspaces`), checked out detached at the requested commit — the primary checkout is never used for builds. Status transitions are persisted via `BuildResultRepository` (JSON file under `.git/gittally/`), published to Gitea non-fatally, and emitted as `BuildStatusChangedEvent`s. Cancellation addresses a build by artifact key and terminates the whole process tree. Future code (watcher, server, UI) must not assume a single running build.
|
||||
|
||||
The runtime is selected per branch behind the `BuildRunner` interface: `DispatchingBuildRunner` (`@Primary`) routes to native `ProcessBuildRunner` (the default) or to `DockerBuildRunner` when `branches.<name>.docker.enabled`. The Docker runner shells out to the `docker` CLI (no SDK): it (re)builds the configured image when the Dockerfile inputs changed (tracked via the `org.gittally.build-inputs-sha256` image label), maintains a per-repo Gradle cache volume, mounts the worktree and the Docker socket into a labelled (`org.hoennig.gittally`) `--rm --init` container, and repairs workspace ownership in-container after each command. The returned `Process` is the attached `docker run` client, so log streaming and termination work exactly like native builds.
|
||||
|
||||
## Watcher
|
||||
|
||||
`Watcher` replaces the legacy blocking main loop with a non-blocking fixed-delay poll cycle: fetch origin, enqueue due branches (changed local, recent new origin, due auto-build slots) via `BuildExecutor`, then prune results, artifacts, and stale worktrees. Branches with `branches.<name>.requirePullRequest` are enqueued only while their head commit matches a pull-request head, detected without an API token by listing `refs/pull/*/head` via `git ls-remote` (lazily, at most once per poll cycle); manual `build` commands bypass this gate. Nothing is scheduled until `Watcher.start()` is called explicitly (server/watch mode) — CLI commands and tests never start the loop. "Already built" is tracked via the result repository, not by moving local branch refs. Auto-build slot state lives in `.git/gittally/auto-builds.json`; watcher health is exposed via `Watcher.state()`.
|
||||
|
||||
## System Metrics
|
||||
|
||||
`SystemMetricsCollector` samples CPU (`/proc/stat` deltas), RAM (`/proc/meminfo`), disk, and repository size every 60s, but only after `ServerMetricsLifecycle` (server profile) calls `start()` — like the watcher, nothing is scheduled in CLI runs or tests. Min/max/avg aggregation state persists as JSON in the artifact root (`ArtifactStore.rootDir()`), so restarts continue the series. Unavailable sources (e.g. no `/proc` outside Linux) yield null metrics served as HTTP 200 by `GET /api/system` — the `/system` page shows `n/a`, never an error.
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
name: pr-doc
|
||||
description: Write or update the pull-request documentation file (PR-doc) under docs/prs/ for the current change. Use when preparing or opening a pull request, when the user asks for a PR-doc, or after finishing a feature that will become a PR — every PR needs one.
|
||||
---
|
||||
|
||||
# Writing a PR-Doc
|
||||
|
||||
Every pull request needs one documentation file in `docs/prs/`.
|
||||
The authoritative convention is `docs/prs/README.md` — read it before writing.
|
||||
Copy the section skeleton from `docs/prs/TEAMPLATE.md`.
|
||||
|
||||
## Filename
|
||||
|
||||
`YYYY-MM-DD-PR#<number>-short-description-of-pr.md`
|
||||
|
||||
- Date of the PR, then `-PR#` and the Gitea PR number, then a dash-separated short description, then `.md`.
|
||||
- The PR number requires an open pull request; open it early with a `WIP: ` title prefix to reserve the number.
|
||||
- If the PR is not opened yet, use `PR#000` as a placeholder in the filename and in scenario IDs, and remind the user to rename both once the number exists.
|
||||
|
||||
## Structure
|
||||
|
||||
The main (`##`) sections must appear in exactly this order, omitting sections that do not apply:
|
||||
|
||||
1. The Problem
|
||||
2. Non-Goals
|
||||
3. The Scenarios
|
||||
4. The Solution
|
||||
5. Open Questions
|
||||
6. Additional Changes
|
||||
7. Prerequisite PRs
|
||||
8. Follow-up PRs
|
||||
|
||||
A `Related Links` section may precede `The Problem`; an `Attachments` section may follow at the very end.
|
||||
Do not reorder already-merged PR-docs.
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Keep the snapshot disclaimer blockquote from the template at the top of every PR-doc.
|
||||
- English, Markdown, one sentence per line, keep it short.
|
||||
- Explain the "why", not just the "what".
|
||||
- Scenarios use Markdown-native pseudo-Gherkin (no fenced Gherkin blocks) with IDs `Scenario#<pr-number>.<nn>`.
|
||||
- Each scenario gets a `##### Verified by` list linking the tests that cover it (relative links from `docs/prs/`).
|
||||
- Mark references to Taiga or other non-public tools as "Hostsharing-internal".
|
||||
- PR-docs document the change of that PR at that time; do not maintain historic PR-docs when later PRs change the behavior.
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
name: writing-tests
|
||||
description: GitTally testing conventions — Kotest FunSpec spec structure, MockK matchers, and the two patterns for mocking beans in Spring slice tests (springmockk @MockkBean or @TestConfiguration). Use when writing, extending, or refactoring tests.
|
||||
---
|
||||
|
||||
# Writing Tests for GitTally
|
||||
|
||||
Tests use **Kotest `FunSpec`** style. `SpringExtension` is registered globally in `io.kotest.provided.ProjectConfig` — do not add it per-spec.
|
||||
|
||||
```kotlin
|
||||
class MyTest : FunSpec() {
|
||||
init {
|
||||
test("description") { ... }
|
||||
beforeEach { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use `shouldBe`, `shouldNotBe`, `shouldThrow` etc. from `io.kotest.matchers`.
|
||||
|
||||
Tests mirror the production package structure under `src/test/kotlin`.
|
||||
|
||||
Run a single test class instead of the full suite while iterating:
|
||||
|
||||
```bash
|
||||
./gradlew test --tests "de.hoennig.gittally.ApplicationContextTest"
|
||||
```
|
||||
|
||||
## Mocking in Spring Slice Tests
|
||||
|
||||
Use `@MockkBean` from `springmockk` to inject MockK mocks into the Spring context:
|
||||
|
||||
```kotlin
|
||||
@WebMvcTest(SomeController::class)
|
||||
class SomeControllerTest : FunSpec() {
|
||||
@MockkBean
|
||||
lateinit var someService: SomeService
|
||||
init {
|
||||
beforeEach { clearMocks(someService) }
|
||||
// full MockK syntax: every { } / verify { }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, register mocks via `@TestConfiguration` without the springmockk dependency:
|
||||
|
||||
```kotlin
|
||||
@WebMvcTest(SomeController::class)
|
||||
@Import(SomeControllerTest.Mocks::class)
|
||||
class SomeControllerTest : FunSpec() {
|
||||
@TestConfiguration
|
||||
class Mocks {
|
||||
@Bean fun someService(): SomeService = mockk()
|
||||
}
|
||||
@Autowired lateinit var someService: SomeService
|
||||
init {
|
||||
beforeEach { clearMocks(someService) }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Pure unit tests (no Spring context) use MockK directly without any Spring wiring.
|
||||
|
||||
## Test Infrastructure by Layer
|
||||
|
||||
- Git-facing code: integration tests against local fixture repositories (bare origin + clones), see `GitServiceTest` — no network access, hermetic git environment variables.
|
||||
- HTTP clients (Gitea): WireMock.
|
||||
- Docker-dependent code: Testcontainers.
|
||||
- The `Watcher` and other schedulers never start their loops in tests; call `poll()`/lifecycle methods directly.
|
||||
Reference in New Issue
Block a user