From 34c259f1897f497286439c70b9e5a951983847e8 Mon Sep 17 00:00:00 2001 From: Vlad Mocanu Date: Wed, 25 Feb 2026 20:13:57 +0200 Subject: [PATCH] docs(prd): create PRDs #5, #6, #7 for Forgejo hardening [skip ci] - PRD #5: Dedicated Forgejo user for Claude bot (dedicated identity, scoped token) - PRD #6: E2E test all 5 untested Forgejo trigger scenarios - PRD #7: Senior developer review of all Forgejo platform support code - Defined 5, 7, and 6 milestones respectively - All three can be parallelized (#7 is read-only, runs alongside #5) Co-Authored-By: Claude Opus 4.6 --- prds/5-dedicated-forgejo-user.md | 88 +++++++++++++++++++ prds/6-e2e-test-forgejo-triggers.md | 98 +++++++++++++++++++++ prds/7-senior-review-forgejo.md | 130 ++++++++++++++++++++++++++++ 3 files changed, 316 insertions(+) create mode 100644 prds/5-dedicated-forgejo-user.md create mode 100644 prds/6-e2e-test-forgejo-triggers.md create mode 100644 prds/7-senior-review-forgejo.md diff --git a/prds/5-dedicated-forgejo-user.md b/prds/5-dedicated-forgejo-user.md new file mode 100644 index 0000000..ed11cd0 --- /dev/null +++ b/prds/5-dedicated-forgejo-user.md @@ -0,0 +1,88 @@ +# PRD #5: Dedicated Forgejo User for Claude Bot + +**Issue**: [#5](https://git.wxs.ro/actions/claude-code-action/issues/5) +**Priority**: High +**Created**: 2026-02-25 + +--- + +## Problem + +Claude currently runs under the human operator's personal Forgejo token (`FORGEJO_TOKEN` / `github_token`). This causes: + +1. **Attribution confusion**: Commits and comments appear as the human user, not as a bot +2. **Over-privileged access**: The bot inherits all permissions of the human account +3. **Audit trail**: No clear separation between human actions and bot actions in repo history +4. **Security**: If the action is compromised, the human's full token is exposed + +On GitHub, this is solved by the GitHub App OIDC token exchange (bot gets its own `claude[bot]` identity). On Forgejo, there's no such mechanism — we need a manual equivalent. + +## Solution + +Create a dedicated `claude-bot` user on the Forgejo instance (git.wxs.ro), generate a scoped API token for it, and configure the action workflow to use that token. This gives Claude its own identity for commits, comments, and API operations. + +## Milestones + +### Phase 1: Forgejo Admin Setup + +- [ ] **M1: Create dedicated `claude-bot` user on git.wxs.ro** + + - Create user via Forgejo admin panel or API (`POST /admin/users`) + - Set appropriate display name (e.g., "Claude Bot") + - Set avatar to distinguish from human users + - User should NOT have admin privileges + - **Validation**: User exists and can log in + +- [ ] **M2: Configure bot user permissions and token** + - Add `claude-bot` to the `actions` org (and any other orgs where the action runs) + - Grant `write` permission on repos where Claude needs to operate + - Generate a scoped API token for the bot user with minimal required permissions: + - `repo` (read/write issues, PRs, comments, branches, commits) + - `packages` (if needed for container operations) + - NO admin scope, NO user scope beyond what's needed + - **Validation**: Token can create comments and push branches on a test repo + +### Phase 2: Action Configuration + +- [ ] **M3: Update workflow to use bot token** + + - Store the bot token as a Forgejo Actions secret (e.g., `CLAUDE_BOT_TOKEN`) + - Update `claude.yml` workflow to pass `github_token: ${{ secrets.CLAUDE_BOT_TOKEN }}` instead of the human token + - Update `bot_id` and `bot_name` inputs to match the new Forgejo user's ID and username + - Document the token rotation procedure + - **Validation**: Action runs with bot token, comments appear as `claude-bot` + +- [ ] **M4: Verify git commit attribution** + - Ensure `git config user.name` and `user.email` use the bot user's identity + - Verify that `src/github/operations/git-config.ts` correctly picks up the bot user info from the token + - Test that pushed commits show the bot user as author in Forgejo UI + - **Validation**: A tag-mode response that creates a branch shows `claude-bot` as commit author + +### Phase 3: Documentation & Hardening + +- [ ] **M5: Update documentation and test across repos** + - Update `docs/forgejo.md` with bot user setup instructions + - Document token rotation procedure (tokens expire, need renewal plan) + - Test the bot user setup on at least one additional repo beyond `claude-code-action` + - Update `CLAUDE.md` if any workflow changes affect development + - **Validation**: Another developer can follow the docs to set up the bot user on a new Forgejo instance + +## Dependencies + +- Forgejo admin access to git.wxs.ro (to create the user) +- Understanding of Forgejo's permission model (org membership, repo access) + +## Risks + +| Risk | Mitigation | +| --------------------------------------- | ---------------------------------------------------------------------- | +| Token expiration | Document rotation procedure, set long-lived token or calendar reminder | +| Bot user locked out | Keep admin access to reset password/token | +| Permission too narrow | Start with `write` on repos, expand only if needed | +| Bot user confused with human in reviews | Set clear display name and avatar | + +## Success Criteria + +- All Claude comments and commits on Forgejo repos appear as `claude-bot`, not the human user +- The bot token has minimal scoped permissions (no admin access) +- Documentation allows reproducing the setup on a fresh Forgejo instance diff --git a/prds/6-e2e-test-forgejo-triggers.md b/prds/6-e2e-test-forgejo-triggers.md new file mode 100644 index 0000000..060a765 --- /dev/null +++ b/prds/6-e2e-test-forgejo-triggers.md @@ -0,0 +1,98 @@ +# PRD #6: E2E Test All Untested Forgejo Trigger Scenarios + +**Issue**: [#6](https://git.wxs.ro/actions/claude-code-action/issues/6) +**Priority**: High +**Created**: 2026-02-25 + +--- + +## Problem + +The Forgejo platform support (PRD #1) was validated for the two most common scenarios (agent mode via `workflow_dispatch` and tag mode via `issue_comment`). However, 5 trigger scenarios remain untested in a live environment: + +1. PR review comment triggers (`pull_request_review_comment`) +2. PR review triggers (`pull_request_review`) +3. Label triggers (`issues` with `labeled` action) +4. Assignee triggers (`issues` with `assigned` action) +5. Branch creation + code changes from tag mode (the initial test only asked a question, no code was generated) + +These untested paths could have silent failures — the code may look correct but break on Forgejo's subtly different webhook payloads, API responses, or event structures. + +## Solution + +Systematically exercise each untested scenario on the live Forgejo instance (git.wxs.ro), document results, fix any issues discovered, and update the E2E status table in `docs/forgejo.md`. + +## Milestones + +- [ ] **M1: Ensure workflow covers all trigger types** + + - Review `.forgejo/workflows/claude.yml` to confirm all 5 trigger types are listed + - Add any missing triggers to the workflow file + - Ensure the workflow has the correct permissions for each trigger type + - **Validation**: Workflow YAML includes all required `on:` triggers + +- [ ] **M2: Test PR review comment trigger** + + - Create a test PR on the repo + - Post a review comment with `@claude` mention + - Verify: platform detection, context fetching (PR diff, review comment body), tracking comment, Claude response + - Document any issues and fix them + - **Validation**: Claude responds correctly to `@claude` in a PR review comment + +- [ ] **M3: Test PR review trigger** + + - Create a test PR on the repo + - Submit a review with `@claude` mention in the review body + - Verify: platform detection, context fetching, tracking comment, Claude response + - Document any issues and fix them + - **Validation**: Claude responds correctly to `@claude` in a PR review + +- [ ] **M4: Test label trigger** + + - Create a label (e.g., `claude`) that triggers the action when applied to an issue + - Apply the label to a test issue + - Verify: trigger detection, context fetching (issue body/title), Claude response + - Document any issues and fix them + - **Validation**: Claude responds when the configured label is applied to an issue + +- [ ] **M5: Test assignee trigger** + + - Assign a user to an issue to trigger the action + - Verify: trigger detection, context fetching, Claude response + - Document any issues and fix them + - **Validation**: Claude responds when assigned to an issue + +- [ ] **M6: Test tag mode with code changes (branch creation)** + + - Create an issue requesting a code change (e.g., "add a comment to file X") + - Trigger Claude via `@claude` mention + - Verify: Claude creates a branch, pushes commits, links the branch in tracking comment + - Verify the Forgejo-specific PR compare URL format is correct + - **Validation**: Claude successfully creates a branch with code changes on Forgejo + +- [ ] **M7: Update documentation with E2E results** + - Update `docs/forgejo.md` E2E status table with results for all 5 scenarios + - Move tested items from "Not Yet E2E Tested" to the validated table + - Document any Forgejo-specific quirks or limitations discovered + - Add troubleshooting entries for any issues encountered + - **Validation**: `docs/forgejo.md` accurately reflects the current E2E validation status + +## Dependencies + +- PRD #5 (Dedicated Forgejo User) is recommended but not strictly required — tests can run with the current token setup +- A test repository on git.wxs.ro with the action workflow configured + +## Risks + +| Risk | Mitigation | +| -------------------------------------------------------- | ----------------------------------------------------------- | +| Forgejo webhook payloads differ from expected | Log raw payloads, compare with GitHub format, adapt parsing | +| Trigger type not supported by Forgejo Actions | Document as known limitation, skip gracefully | +| Action creates unwanted branches/comments during testing | Use a dedicated test repo or clean up after each test | + +## Success Criteria + +- All 5 previously untested scenarios have been exercised on a live Forgejo instance +- Any bugs discovered are fixed and tested +- `docs/forgejo.md` E2E status table is fully up-to-date +- "Not Yet E2E Tested" section is empty (all items moved to validated or documented as unsupported) diff --git a/prds/7-senior-review-forgejo.md b/prds/7-senior-review-forgejo.md new file mode 100644 index 0000000..4d7279d --- /dev/null +++ b/prds/7-senior-review-forgejo.md @@ -0,0 +1,130 @@ +# PRD #7: Senior Developer Review of Forgejo Platform Support + +**Issue**: [#7](https://git.wxs.ro/actions/claude-code-action/issues/7) +**Priority**: Medium +**Created**: 2026-02-25 + +--- + +## Problem + +The Forgejo platform support was implemented across multiple sessions (PRD #1). While it works for the validated scenarios, a comprehensive senior-level review is needed to: + +- Catch architectural issues that may cause problems at scale or during upstream merges +- Identify edge cases and error handling gaps +- Assess test coverage adequacy +- Verify security posture (token handling, input sanitization, permission checks) +- Ensure maintainability and code quality standards + +This review should treat the codebase as if it were being submitted for a production readiness review. + +## Solution + +Perform a thorough, documented code review of all Forgejo-related changes. The review should cover every new file, every modified file, and the overall architecture. Findings should be categorized by severity and each issue should be either fixed or documented as an accepted risk. + +## Review Scope + +### New Files (Forgejo-Specific) + +- `src/platform/detector.ts` — Platform detection logic +- `src/forgejo/token.ts` — Token handling +- `src/forgejo/data/fetcher.ts` — REST data fetching (replaces GraphQL) +- `src/forgejo/comment-logic.ts` — URL patterns for tracking comments + +### Modified Files (Platform Branches) + +- `src/entrypoints/run.ts` — Token setup platform branch +- `src/modes/tag/index.ts` — Data fetcher swap +- `src/github/operations/comments/create-initial.ts` — Platform-aware spinner/URL +- `src/github/operations/comments/update-with-branch.ts` — PR compare URL +- `src/github/operations/branch.ts` — `repos.getBranch()` on Forgejo +- `src/github/validation/actor.ts` — Skipped on Forgejo +- `src/mcp/install-mcp-server.ts` — Skip GitHub MCP on Forgejo +- `action.yml` — New inputs, env vars, platform support + +### Test Files + +- All `__tests__/` files related to Forgejo functionality +- Test coverage gaps + +### CI/CD + +- `.forgejo/workflows/` — All workflow files + +### Documentation + +- `docs/forgejo.md` — Accuracy and completeness +- `CLAUDE.md` — Forgejo section accuracy + +## Milestones + +- [ ] **M1: Architecture & design review** + + - Review the lean adapter pattern: is it the right abstraction level? + - Assess merge-conflict surface with upstream: are platform branches minimal? + - Check for code duplication that could be consolidated + - Review the platform detection logic (3-tier: explicit > env > heuristic) + - Evaluate whether the `src/forgejo/` directory structure scales + - **Deliverable**: Architecture findings document with severity ratings + +- [ ] **M2: Error handling & edge case review** + + - Review every `try/catch` block in Forgejo code paths + - Check for unhandled promise rejections + - Verify graceful degradation when Forgejo APIs behave differently + - Check error messages — are they actionable for users? + - Review fallback behavior (e.g., `repos.get()` fallback for permissions) + - **Deliverable**: List of error handling gaps with fixes + +- [ ] **M3: Security review** + + - Token handling: is the token properly scoped and never logged? + - Input sanitization: can webhook payloads inject content? + - Permission checks: are they sufficient on Forgejo? + - Secrets in logs: review all `core.info()` / `core.debug()` calls + - **Deliverable**: Security findings with severity ratings + +- [ ] **M4: Test coverage review & improvements** + + - Assess existing unit test coverage for Forgejo code paths + - Identify critical paths without test coverage + - Write or improve tests for the most critical gaps + - Verify mocks accurately represent Forgejo API responses + - **Deliverable**: Test coverage improved, gaps documented + +- [ ] **M5: Code quality & maintainability review** + + - TypeScript strictness: are types accurate or using `any` / type assertions? + - Naming conventions: consistent with the rest of the codebase? + - Dead code: any unused imports, unreachable branches, commented-out code? + - Magic strings/numbers: should any be extracted to constants? + - Code comments: are complex decisions documented? + - **Deliverable**: Code quality fixes applied + +- [ ] **M6: Documentation accuracy review** + - Cross-check `docs/forgejo.md` against actual code behavior + - Verify all "Known Limitations" are still accurate + - Check that code examples and configuration snippets work + - Ensure `CLAUDE.md` Forgejo section matches current state + - **Deliverable**: Documentation corrections applied + +## Deliverables + +Each milestone produces a findings document (can be inline in a PR or as comments on issue #7) with: + +- **Critical**: Must fix before production use +- **Major**: Should fix, risk of user-facing issues +- **Minor**: Nice to have, code quality improvements +- **Note**: Observations, not necessarily actionable + +## Dependencies + +- None — this is a review of existing code + +## Success Criteria + +- All Forgejo-related code has been reviewed by the criteria above +- All Critical and Major findings are resolved +- Minor findings are either fixed or documented as accepted +- Test coverage is adequate for critical paths +- Documentation accurately reflects the implementation