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,45 @@
+# Step 02: Git Gateway
+
+Prerequisites: none.
+Read `README.md` and `00-legacy-analysis.md` first.
+
+## Goal
+
+Extend `GitService` into a complete, tested gateway for all git operations the watcher and builder need.
+
+## Design
+
+Keep the existing approach: shell out to the `git` CLI via `ProcessBuilder`.
+Extract a small `GitCommandRunner` (command + workingDir → exit code, stdout, stderr) so `GitService` becomes testable and readable.
+
+Operations to add (legacy references in parentheses):
+
+- `fetchOrigin()` and `fetchBranch(branch)` with authentication (legacy `git_with_gitea_token`, askpass).
+  Use the `GIT_ASKPASS` environment technique: write a temp script returning `git.account` / `git.token` from config; `GIT_TERMINAL_PROMPT=0`.
+  Only needed for HTTPS origins; skip auth setup for SSH origins.
+- `localBranches()`, `originBranches()` (legacy `branch_candidates`).
+- `hasNewCommits(branch)` — compare local head with upstream/origin (legacy `branch_has_new_commits`, `has_new_commits` via `rev-list`).
+- `newOriginBranches(maxAge)` — origin branches without local counterpart whose latest commit is younger than `watcher.newBranchMaxAge` (legacy `recent_new_origin_branches`).
+- `checkout(branch)` — switch, or create tracking branch from origin (legacy `switch_to_branch`).
+- `resetHardToOrigin(branch)` (legacy `pull_branch_if_possible`).
+- `commitTimestamp(sha)`, `currentBranch()`, `headCommit()`.
+
+Parse the `newBranchMaxAge` duration format (`5d`, `12h`) in a small dedicated parser with tests.
+
+## Out of Scope
+
+- No polling loop (step 06), no build triggering.
+- No Gitea API calls (step 03); only the askpass credential bridge is set up here.
+
+## Tests
+
+- `GitCommandRunner` unit tests.
+- Integration tests against local fixture repositories: create a bare "origin" repo and a clone in a temp dir via the runner itself, then exercise fetch/branch/commit operations.
+  No network access needed.
+- Duration parser edge cases.
+- Askpass script content test (do not test against a real remote).
+
+## Acceptance Criteria
+
+- `./gradlew ktlintFormat` then `./gradlew build` is green.
+- No temp askpass files leak (created per invocation or cleaned via try/finally; legacy leaked them).