update CLAUDE.md with rewrite plan documentation reference in docs/pland directory

2026-07-07 06:40:27 +02:00
parent 56208c061e
commit 38e080814e
15 changed files with 676 additions and 0 deletions
@@ -0,0 +1,49 @@
+# Step 04: Build Executor
+
+Prerequisites: steps 01, 02, 03.
+Read `README.md` and `00-legacy-analysis.md` first.
+
+## Goal
+
+Asynchronous build execution with log capture, cancellation, and immediately visible status transitions.
+This step fixes the legacy defect that nothing could observe status changes while a build ran.
+
+## Design
+
+Create package `de.hoennig.gittally.build` (extends step 01):
+
+- `BuildExecutor` service; one build at a time (a `ReentrantLock` or single-thread executor replaces the legacy flock file).
+- `startBuild(branch, commit)` runs asynchronously and returns immediately; expose `currentBuild(): RunningBuild?`.
+- Execution sequence per build:
+  1. Record `PENDING`, then `RUNNING` via `BuildResultRepository`; publish each transition to Gitea (non-fatal on failure).
+  2. Run the branch's `cleanCommand`, then `buildCommand` (from the merged `branches` config) via `ProcessBuilder` with the branch name in the environment as `branch`.
+  3. Stream stdout/stderr to the configured log files in a working/staging directory, plus a combined live log file.
+  4. On exit: record `SUCCESS`/`FAILED`, publish status, hand the staging directory to the artifact store (step 05 interface; use a stub interface now if 05 is not done).
+- Cancellation: `cancel()` flag checked by a monitor; destroy the process tree (`ProcessHandle.descendants()`, TERM-wait-KILL like legacy `terminate_process_tree`); record `CANCELLED`.
+- Status transitions must be readable at any time via the repository — no in-memory-only state.
+
+Emit a Spring `ApplicationEvent` on every status transition so the UI (step 08) can later push updates without polling internals.
+
+## Out of Scope
+
+- Docker execution (step 11); native `ProcessBuilder` only, but keep a `BuildRunner` interface so Docker can plug in.
+- Scheduling and branch selection (step 06).
+- Artifact index HTML (step 05/08).
+
+## Config
+
+Uses existing `branches.<name>.buildCommand/cleanCommand/stdoutLog/stderrLog`.
+Consider `builds.timeout` only if trivial; otherwise defer.
+
+## Tests
+
+- Fake commands (`sh -c 'echo ok'`, failing command, sleeping command) in temp dirs.
+- Status sequence assertions: pending → running → success/failed/cancelled, each persisted before/after execution.
+- Cancellation kills a sleeping process tree and records `CANCELLED`.
+- Log files contain captured output; live log grows during the build (poll in test).
+- Gitea publishing mocked with MockK; a Gitea failure must not fail the build.
+
+## Acceptance Criteria
+
+- `./gradlew ktlintFormat` then `./gradlew build` is green.
+- While a test build sleeps, the repository reports `RUNNING` — proven by a test.