diff --git a/.github/workflows/reusable-code.yml b/.github/workflows/reusable-code.yml index fe494854b..b24d2923e 100644 --- a/.github/workflows/reusable-code.yml +++ b/.github/workflows/reusable-code.yml @@ -178,4 +178,4 @@ jobs: run-url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} status-repo: ${{ inputs.source_repo }} status-number: ${{ fromJSON(inputs.event_payload).issue.number }} - status-token: ${{ steps.app-token.outputs.token }} + mint-url: ${{ inputs.mint_url }} diff --git a/.github/workflows/reusable-fix.yml b/.github/workflows/reusable-fix.yml index 5968c784e..21e171b3d 100644 --- a/.github/workflows/reusable-fix.yml +++ b/.github/workflows/reusable-fix.yml @@ -380,4 +380,4 @@ jobs: run-url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} status-repo: ${{ inputs.source_repo }} status-number: ${{ steps.context.outputs.pr_number }} - status-token: ${{ steps.app-token.outputs.token }} + mint-url: ${{ inputs.mint_url }} diff --git a/.github/workflows/reusable-retro.yml b/.github/workflows/reusable-retro.yml index 8ddeb3589..fdccfa520 100644 --- a/.github/workflows/reusable-retro.yml +++ b/.github/workflows/reusable-retro.yml @@ -153,4 +153,4 @@ jobs: run-url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} status-repo: ${{ inputs.source_repo }} status-number: ${{ fromJSON(inputs.event_payload).pull_request.number || fromJSON(inputs.event_payload).issue.number }} - status-token: ${{ steps.app-token.outputs.token }} + mint-url: ${{ inputs.mint_url }} diff --git a/.github/workflows/reusable-review.yml b/.github/workflows/reusable-review.yml index 863681129..e3c77f09f 100644 --- a/.github/workflows/reusable-review.yml +++ b/.github/workflows/reusable-review.yml @@ -169,4 +169,4 @@ jobs: run-url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} status-repo: ${{ inputs.source_repo }} status-number: ${{ fromJSON(inputs.event_payload).pull_request.number || fromJSON(inputs.event_payload).issue.number }} - status-token: ${{ steps.app-token.outputs.token }} + mint-url: ${{ inputs.mint_url }} diff --git a/.github/workflows/reusable-triage.yml b/.github/workflows/reusable-triage.yml index ac9dd6aa0..a13d0a85a 100644 --- a/.github/workflows/reusable-triage.yml +++ b/.github/workflows/reusable-triage.yml @@ -149,4 +149,4 @@ jobs: run-url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} status-repo: ${{ inputs.source_repo }} status-number: ${{ fromJSON(inputs.event_payload).issue.number }} - status-token: ${{ steps.app-token.outputs.token }} + mint-url: ${{ inputs.mint_url }} diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 32b39573f..000000000 --- a/CLAUDE.md +++ /dev/null @@ -1,3 +0,0 @@ -# CLAUDE.md - -Project rules and instructions live in [AGENTS.md](AGENTS.md). Read that file now — it is the single source of truth for all agent-facing guidance in this repo. diff --git a/README.md b/README.md index 45b56b1ff..34c62065b 100644 --- a/README.md +++ b/README.md @@ -50,6 +50,7 @@ This is not a product spec. It's an evolving exploration of a hard problem space - [Vertex AI Inference Provisioning](docs/plans/vertex-inference-provisioning.md) — Provisioning and configuration for Vertex AI inference endpoints - [ADR-0045 Forge-Portable Harness Schema — Phase 1](docs/plans/adr-0045-forge-portable-harness-phase1.md) — Implementation plan for ADR-0045 forge-portable harness schema (Phase 1) - [ADR-0045 Forge-Portable Harness Schema — Phase 2](docs/plans/adr-0045-forge-portable-harness-phase2.md) — Implementation plan for ADR-0045 Phase 2: adopt new schema fields across install, scaffold, and lock flows + - [ADR-0045 Forge-Portable Harness Schema — Phase 3](docs/plans/adr-0045-forge-portable-harness-phase3.md) — Implementation plan for ADR-0045 Phase 3: deprecate config.yaml agents block, add Lint() diagnostics, migrate to harness-first discovery - [ADR-0046 Drift Scanner](docs/plans/2026-03-06-adr46-drift-scanner.md) — Implementation plan for ADR-0046 drift detection tool - **[docs/guides/](docs/guides/)** — Practical how-to documentation for administrators and developers (see [ADR 0023](docs/ADRs/0023-user-documentation-structure.md)) - **[docs/ADRs/](docs/ADRs/)** — Architecture Decision Records for crystallizing specific decisions (see [ADR 0001](docs/ADRs/0001-use-adrs-for-decision-making.md)) diff --git a/action.yml b/action.yml index a57044a0f..1fea40b04 100644 --- a/action.yml +++ b/action.yml @@ -36,8 +36,16 @@ inputs: status-number: description: Issue/PR number for status comments (optional). default: "" + mint-url: + description: >- + Mint service URL for on-demand status comment tokens. When set, the + binary mints a fresh short-lived token before each status API call + instead of using a static status-token. + default: "" status-token: - description: Token for status comments (defaults to GH_TOKEN env var). + description: >- + DEPRECATED — use mint-url instead. Static GitHub token for status + comments. Ignored when mint-url is set. default: "" runs: @@ -363,9 +371,13 @@ runs: STATUS_RUN_URL: ${{ inputs.run-url }} STATUS_REPO: ${{ inputs.status-repo }} STATUS_NUMBER: ${{ inputs.status-number }} + MINT_URL: ${{ inputs.mint-url }} STATUS_TOKEN: ${{ inputs.status-token }} run: | set -euo pipefail + if [[ -n "${STATUS_TOKEN}" ]]; then + echo "::add-mask::${STATUS_TOKEN}" + fi FULLSEND_DIR="${FULLSEND_DIR:-${GITHUB_WORKSPACE}}" TARGET_REPO="${TARGET_REPO:-${GITHUB_WORKSPACE}/target-repo}" mkdir -p "${GITHUB_WORKSPACE}/output" @@ -373,16 +385,17 @@ runs: # Post-scripts enforce secret scanning, protected-path blocks, # and review-downgrade controls. Skipping them in CI bypasses # all post-push security gates. - if [[ -n "${STATUS_TOKEN}" ]]; then - echo "::add-mask::${STATUS_TOKEN}" - fi STATUS_FLAGS=() if [[ -n "${STATUS_REPO}" && -n "${STATUS_NUMBER}" ]]; then STATUS_FLAGS+=(--status-repo "${STATUS_REPO}" --status-number "${STATUS_NUMBER}") if [[ -n "${STATUS_RUN_URL}" ]]; then STATUS_FLAGS+=(--run-url "${STATUS_RUN_URL}") fi + if [[ -n "${MINT_URL}" ]]; then + STATUS_FLAGS+=(--mint-url "${MINT_URL}") + fi if [[ -n "${STATUS_TOKEN}" ]]; then + echo "::warning::status-token is deprecated; use mint-url instead" STATUS_FLAGS+=(--status-token "${STATUS_TOKEN}") fi fi @@ -393,10 +406,12 @@ runs: "${STATUS_FLAGS[@]+"${STATUS_FLAGS[@]}"}" - name: Finalize orphaned status comment - if: always() && inputs.agent != '__install_only__' && inputs.status-repo != '' && inputs.status-number != '' + if: always() && inputs.agent != '__install_only__' && inputs.status-repo != '' && inputs.status-number != '' && (inputs.mint-url != '' || inputs.status-token != '') shell: bash env: + MINT_URL: ${{ inputs.mint-url }} STATUS_TOKEN: ${{ inputs.status-token }} + AGENT: ${{ inputs.agent }} STATUS_REPO: ${{ inputs.status-repo }} STATUS_NUMBER: ${{ inputs.status-number }} RUN_ID: ${{ github.run_id }} @@ -405,17 +420,19 @@ runs: JOB_STATUS: ${{ job.status }} run: | set -euo pipefail + if [[ -n "${STATUS_TOKEN}" ]]; then + echo "::add-mask::${STATUS_TOKEN}" + fi # When the fullsend process is hard-killed (SIGKILL, OOM, segfault), # the deferred PostCompletion call never runs and the status comment # remains in "Started" state. This step runs unconditionally (if: # always()) to detect and finalize orphaned comments. See #2149. - TOKEN="${STATUS_TOKEN:-${GITHUB_TOKEN:-}}" - if [[ -z "${TOKEN}" ]]; then - echo "::warning::No token available for status comment reconciliation" - exit 0 + RECONCILE_FLAGS=(--repo "${STATUS_REPO}" --number "${STATUS_NUMBER}" --run-id "${RUN_ID}") + if [[ -n "${MINT_URL}" ]]; then + RECONCILE_FLAGS+=(--mint-url "${MINT_URL}" --role "${AGENT}") + elif [[ -n "${STATUS_TOKEN}" ]]; then + RECONCILE_FLAGS+=(--token "${STATUS_TOKEN}") fi - echo "::add-mask::${TOKEN}" - RECONCILE_FLAGS=(--repo "${STATUS_REPO}" --number "${STATUS_NUMBER}" --run-id "${RUN_ID}" --token "${TOKEN}") if [[ -n "${RUN_URL}" ]]; then RECONCILE_FLAGS+=(--run-url "${RUN_URL}") fi diff --git a/docs/ADRs/0045-forge-portable-harness-schema.md b/docs/ADRs/0045-forge-portable-harness-schema.md index 1b1597e6b..4b62a481a 100644 --- a/docs/ADRs/0045-forge-portable-harness-schema.md +++ b/docs/ADRs/0045-forge-portable-harness-schema.md @@ -142,8 +142,9 @@ agent definition `.md` file). `agent` describes *how* the agent behaves; `role` describes *what function* the agent serves in the pipeline; `slug` describes *who* the agent authenticates as. During Phase 1-2, `role` and `slug` are optional — `Validate()` does not require them. In Phase 3, -`Validate()` emits warnings when `role` is missing. In Phase 4, -`Validate()` requires `role`. +`Validate()` continues to allow missing `role`, but `Lint()` emits +warnings when `role` is missing. In Phase 4, `Validate()` requires +`role`. `base` references another harness file whose fields serve as defaults for this harness. Any field set in the child overrides the corresponding base @@ -516,11 +517,10 @@ func (h *Harness) ResolveForge(platform string) error { ... } Note: `role`/`slug` becoming required is independent of the `forge:` section — a harness that only targets one platform still needs `role` and `slug` but does not need `forge:`. - Implementation note: the current `Validate()` method returns hard errors - only — there is no warning/advisory path. Phase 3 will need a separate - `Lint()` method or log-level warnings to emit non-fatal diagnostics - without breaking existing callers that treat any `Validate()` error as - a hard stop. + Implementation note: `Validate()` returns hard errors only. Phase 3 + adds a separate `Lint()` method that returns non-fatal `[]Diagnostic` + warnings without breaking existing callers that treat any `Validate()` + error as a hard stop. 4. **Phase 4 (remove):** Require `role` in all harness files. Remove the `agents:` block from config.yaml entirely. Agent identity and diff --git a/docs/agents/triage.md b/docs/agents/triage.md index aa526068a..a14dbb3ce 100644 --- a/docs/agents/triage.md +++ b/docs/agents/triage.md @@ -40,7 +40,7 @@ outcome and the post-script applies the corresponding label. | `ready-to-code` | The issue is fully specified and low-risk (bug, documentation, performance). Triggers the [code agent](code.md). | | `triaged` | The issue is fully specified but is a feature or other category that requires human prioritization before coding. | | `duplicate` | The issue duplicates an existing one. The agent identified the original and the post-script closes the issue. | -| `blocked` | The issue depends on another issue or external condition. The agent identified the blocker. | +| `blocked` | The issue depends on prerequisites — existing issues/PRs or newly created upstream issues. The agent identified or created the blockers. | | `question` | The issue is a support request or question, not an actionable bug or feature. The agent attempted to answer it. | The `issue-labels` skill may also apply contextual labels (e.g., `area/api`, @@ -48,6 +48,37 @@ The `issue-labels` skill may also apply contextual labels (e.g., `area/api`, ## Configuration and extension +### Cross-repo issue creation + +The triage agent can create prerequisite issues in other repositories when it +identifies upstream dependencies that don't have tracking issues yet. This is +controlled by the `create_issues` section in `config.yaml`: + +```yaml +create_issues: + allow_targets: + orgs: + - my-org + repos: + - upstream-org/specific-repo +``` + +**Defaults:** At install time, fullsend populates this with your org (in org mode) +or your repo (in per-repo mode), plus `fullsend-ai/fullsend` as an upstream target. + +**When to expand the allowlist:** If your project depends on libraries or services +in other GitHub orgs and you want the triage agent to automatically file +prerequisite issues there, add those orgs or repos to `allow_targets`. + +**When to restrict the allowlist:** If you don't want agents creating issues +outside your org, remove entries. If `allow_targets` is empty, automatic +prerequisite creation is disabled entirely — the agent will still identify +the dependency and include a draft issue body in its comment for a human to +file manually. + +The source repo (where triage is running) is always implicitly allowed +regardless of the allowlist. + ### Skill: `issue-labels` The triage agent includes a built-in `issue-labels` skill that discovers your diff --git a/docs/architecture.md b/docs/architecture.md index 7a0bfa0f2..c6f229b0b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -236,7 +236,7 @@ ADR 0002: [Building block 3](ADRs/0002-initial-fullsend-design.md#3-label-state- ### 4. triage agent runtime -Runs triage from issue `title`/`body` + GitHub-native attachments only; each run starts with **`duplicate`** and other reset labels cleared; duplicate detection, blocking dependency detection (cross-repo), readiness, reproducibility, test handoff; can close as duplicate again if still a match, or label **`blocked`** when progress depends on another open issue or PR. +Runs triage from issue `title`/`body` + GitHub-native attachments only; each run starts with **`duplicate`** and other reset labels cleared; duplicate detection, prerequisite detection (cross-repo), readiness, reproducibility, test handoff; can close as duplicate again if still a match, label **`blocked`** when progress depends on another open issue or PR, or create upstream prerequisite issues when no tracking issue exists (controlled by `create_issues.allow_targets` config). ADR 0002: [Building block 4](ADRs/0002-initial-fullsend-design.md#4-triage-agent-runtime). ### 5. Duplicate / similarity search diff --git a/docs/guides/dev/cli-internals.md b/docs/guides/dev/cli-internals.md index c4b51914c..97af2fd96 100644 --- a/docs/guides/dev/cli-internals.md +++ b/docs/guides/dev/cli-internals.md @@ -58,7 +58,7 @@ fullsend │ ├── --run-url # CI/CD run URL for status comments │ ├── --status-repo # Repository for status comments │ ├── --status-number # Issue/PR number for status comments -│ └── --status-token # Token for status comments (default: GH_TOKEN) +│ └── --mint-url # Mint service URL for on-demand status tokens ├── fetch-skill # Fetch a skill at runtime (in-sandbox) ├── scan # Run security scanner on input/output │ ├── input # Scan event payload for prompt injection @@ -74,7 +74,8 @@ fullsend ├── --run-url # Workflow run URL (optional) ├── --sha # Commit SHA (optional) ├── --reason # Termination reason: terminated or cancelled (default: terminated) - └── --token # GitHub token (default: $GITHUB_TOKEN) + ├── --mint-url # Mint service URL for on-demand token (default: $FULLSEND_MINT_URL) + └── --role # Agent role for minting (required with --mint-url) ``` ### Command Decomposition diff --git a/docs/guides/user/bugfix-workflow.md b/docs/guides/user/bugfix-workflow.md index b5ec7594e..6124121f0 100644 --- a/docs/guides/user/bugfix-workflow.md +++ b/docs/guides/user/bugfix-workflow.md @@ -102,7 +102,7 @@ Every push to a PR in the review stage triggers a new review round. This means ` The triage agent: 1. **Checks for duplicates.** Searches existing issues by title, body, and metadata. If it finds a match with high confidence, it labels `duplicate`, posts a comment linking the canonical issue, and closes this one. -2. **Checks for blocking dependencies.** Searches for open issues or PRs (in this repo or upstream) that must be resolved before work can start. If a blocker is found, it labels `blocked` and posts a comment linking to the blocking issue or PR. On re-triage, it checks whether existing blockers have been resolved. +2. **Checks for blocking dependencies.** Searches for open issues or PRs (in this repo or upstream) that must be resolved before work can start. If a prerequisite is found, it labels `blocked` and posts a comment linking to it. When no upstream tracking issue exists, the triage agent can also create one in the upstream repo (controlled by `create_issues.allow_targets` in config). On re-triage, it checks whether existing prerequisites have been resolved. 3. **Checks information sufficiency.** If the issue body is missing steps to reproduce, expected behavior, or other critical details, it labels `needs-info` and posts a comment explaining what's missing. 4. **Produces a test artifact.** When possible, writes a failing test case aligned with the repo's test framework. 5. **Hands off.** Labels `ready-to-code` with a summary comment. diff --git a/docs/guides/user/running-agents-locally.md b/docs/guides/user/running-agents-locally.md index 969f47689..33a83dbc6 100644 --- a/docs/guides/user/running-agents-locally.md +++ b/docs/guides/user/running-agents-locally.md @@ -235,7 +235,7 @@ target issue/PR. These flags mirror what the CI workflows pass automatically: | `--run-url` | URL of the CI/CD run shown in the status comment | | `--status-repo` | Repository (`owner/repo`) to post status comments on | | `--status-number` | Issue or PR number for status comments | -| `--status-token` | Token for posting comments (defaults to `GH_TOKEN`) | +| `--mint-url` | Mint service URL for on-demand status comment tokens (default: `$FULLSEND_MINT_URL`) | Example: diff --git a/docs/plans/adr-0045-forge-portable-harness-phase3.md b/docs/plans/adr-0045-forge-portable-harness-phase3.md new file mode 100644 index 000000000..e880be9b0 --- /dev/null +++ b/docs/plans/adr-0045-forge-portable-harness-phase3.md @@ -0,0 +1,339 @@ +# Implementation Plan: ADR-0045 Forge-Portable Harness Schema — Phase 3 (Deprecate) + +## Context + +Phase 2 (shipped) completed the "Adopt" milestone: `fullsend install` generates thin wrapper harness files with `base:`, `role:`, and `slug:` in the `.fullsend` config repo. Scaffold templates use `forge.github:` blocks for platform-specific fields. `harness.DiscoverAgents()` scans local harness directories for agent identity. `fullsend lock --all` locks all harnesses in a single pass. Both the `config.yaml` `agents:` block and harness wrapper files now contain role/slug (dual-write). + +Phase 3 completes the "Deprecate" milestone from the ADR migration path. Specifically: + +1. **`Lint()` diagnostic method warns on missing `role`** — today `Validate()` returns hard errors only. Phase 3 adds a separate `Lint()` method that returns non-fatal diagnostics (warnings), starting with "role is not set; it will be required in a future version." This keeps `Validate()` callers (which treat all errors as hard stops) unaffected. + +2. **Consumers migrate to harness-first discovery** — today `loadKnownSlugs()`, `runUninstall`, and `runGitHubUninstall` read agent identity exclusively from `config.yaml`'s `agents:` block. Phase 3 adds remote harness discovery via `forge.Client.ListDirectoryContents` + `GetFileContentAtRef`, and migrates these consumers to check harness files first, falling back to the `agents:` block. + +3. **`OrgConfig.Agents` becomes optional** — the `Agents` field gains `omitempty` so config.yaml can omit the `agents:` block. When present during load, a deprecation notice is logged. The dual-write during install continues (Phase 4 stops it). + +ADR: `docs/ADRs/0045-forge-portable-harness-schema.md` +Phase 1 plan: `docs/plans/adr-0045-forge-portable-harness-phase1.md` +Phase 2 plan: `docs/plans/adr-0045-forge-portable-harness-phase2.md` + +### Relationship to Phase 2 + +Phase 3 builds on Phase 2's deliverables: + +| Phase 2 artifact | Phase 3 usage | +|---|---| +| `Harness.Role`, `Harness.Slug` fields | `Lint()` warns when `role` is absent | +| `DiscoverAgents()` + `LoadRaw()` | Foundation for remote harness discovery (same parse logic, different I/O) | +| Wrapper harness files in config repo | Remote discovery reads these instead of `config.yaml` `agents:` block | +| `forge.github:` blocks in scaffold templates | Lint can validate forge section completeness in future phases | +| `HarnessWrappersLayer` dual-write | Ensures both sources exist during Phase 3 transition; Phase 4 removes the `agents:` write | + +### Key design insight: remote vs local discovery + +All current consumers of `OrgConfig.Agents` operate on **remote config repo data** (fetched via `forge.Client`) during install/uninstall CLI commands. `harness.DiscoverAgents()` operates on **local harness files on disk**. These are fundamentally different data sources: + +- **Local discovery** (`DiscoverAgents`): used at agent runtime — the runner reads harness files from the cloned `.fullsend/` directory. No migration needed here; the runner already loads harness files directly. +- **Remote discovery** (new): used during install/uninstall CLI commands — the CLI reads the `.fullsend` config repo via the forge API. Phase 2 writes wrapper harness files there, so remote discovery can now read them instead of the `agents:` block. + +All three remote consumers (`loadKnownSlugs`, `runUninstall`, `runGitHubUninstall`) already have fallback paths that derive slugs from `DefaultAgentRoles()` + naming convention, making the migration lower-risk. + +### What Phase 3 does NOT do + +- Does NOT require `role` in `Validate()` (Phase 4) +- Does NOT remove `AgentSlugs()` or the `Agents` field from `OrgConfig` (Phase 4) +- Does NOT stop the dual-write in install (Phase 4) +- Does NOT remove the fallback to `agents:` block (Phase 4) + +## PR Dependency Graph + +``` +PR 1 (Lint diagnostic infra) ──> PR 3 (wire Lint into CLI) + \ +PR 2 (remote harness discovery) ──> PR 4 (migrate loadKnownSlugs) ──> PR 6 (OrgConfig.Agents omitempty) + \ / + └──> PR 5 (migrate uninstall) ──┘ +``` + +PRs 1 and 2 can start in parallel (no dependencies on each other or on Phase 2 PR 6). PR 3 depends on PR 1. PRs 4 and 5 depend on PR 2. PR 6 depends on PRs 4 and 5 (all consumers migrated before making the field optional). + +--- + +## PR 1: Lint() diagnostic infrastructure and role warning + +**Scope:** New diagnostic type, `Lint()` method on Harness, and a "missing role" warning. No callers — pure library code. + +**Create `internal/harness/lint.go`:** + +- `DiagnosticSeverity` type: + ```go + type DiagnosticSeverity int + + const ( + SeverityWarning DiagnosticSeverity = iota + SeverityError + ) + ``` +- `Diagnostic` struct: + ```go + type Diagnostic struct { + Severity DiagnosticSeverity + Field string // e.g. "role", "forge.github.pre_script" + Message string + } + ``` +- `(d Diagnostic) String() string` — formats as `"warning: role: "` or `"error: role: "` +- `(h *Harness) Lint() []Diagnostic`: + - If `h.Role == ""`: append warning `{SeverityWarning, "role", "role is not set; it will be required in a future version"}` + - Returns nil when no diagnostics are found (not an empty slice — callers can do `if diags := h.Lint(); len(diags) > 0`) + - Called AFTER `Validate()` / `LoadWithBase()` — operates on the post-merge, post-forge-resolution harness. `Lint()` assumes the harness is already valid; callers should not call `Lint()` if `Validate()` failed. + - Unlike `Validate()`, `Lint()` never returns an error — it returns a slice of diagnostics that callers can print or ignore. + +**Design note:** `Lint()` is intentionally separate from `Validate()` rather than adding a "warnings" return channel to `Validate()`. This avoids changing `Validate()`'s signature (`error` → `([]Diagnostic, error)`) which would require updating every caller. The two methods serve different purposes: `Validate()` gates execution (hard stop), `Lint()` provides advisory feedback. + +**Future lint rules** (not in this PR, but the infrastructure supports them): +- `slug` is missing +- `forge:` section has only one platform (informational) +- `base:` uses a pinned commit SHA that differs from the running CLI version + +**Create `internal/harness/lint_test.go`:** +- Harness with role → no diagnostics +- Harness without role → one warning diagnostic with field "role" +- Harness with role and slug → no diagnostics +- Diagnostic.String() formats correctly for warning and error severities +- `Lint()` returns nil (not empty slice) when no issues found + +**After merge:** `Lint()` and `Diagnostic` exist as tested library code. No callers yet. `Validate()` is unchanged. + +--- + +## PR 2: Remote harness agent discovery + +**Scope:** Add a function that discovers agent identity (role, slug) from harness files in a remote config repo via the forge API. Analogous to `DiscoverAgents()` but reads via `forge.Client` instead of the local filesystem. + +**Create `internal/harness/discover_remote.go`:** + +- `DiscoverRemoteAgents(ctx context.Context, client forge.Client, owner, repo, ref string) ([]AgentInfo, error)`: + - Calls `client.ListDirectoryContents(ctx, owner, repo, "harness", ref, false)` to list files in the `harness/` directory + - Filters for `.yaml` and `.yml` extensions (same as `DiscoverAgents`) + - For each YAML file: calls `client.GetFileContentAtRef(ctx, owner, repo, entry.Path, ref)` to read the file content + - Unmarshals each file into a `Harness` struct using the same minimal parse as `LoadRaw` — but from bytes rather than a file path. Extract a helper: `ParseRaw(data []byte) (*Harness, error)` that does `yaml.Unmarshal` without file I/O, validation, or forge resolution. `LoadRaw` can be refactored to call `ParseRaw` internally. + - Extracts `h.Role` and `h.Slug`; skips files where both are empty + - Returns sorted by `Role` then `Filename` (same ordering as `DiscoverAgents`) + - If `ListDirectoryContents` returns `forge.ErrNotFound` (no `harness/` directory), returns `(nil, nil)` — same convention as `DiscoverAgents` for non-existent directories + - Per-file errors (parse failures, `GetFileContentAtRef` failures) are collected into a multi-error; valid files are still returned. Same partial-result semantics as `DiscoverAgents`. + +**Refactor `internal/harness/harness.go`:** + +- Extract `ParseRaw(data []byte) (*Harness, error)` from `LoadRaw`: + ```go + func ParseRaw(data []byte) (*Harness, error) { + var h Harness + if err := yaml.Unmarshal(data, &h); err != nil { + return nil, err + } + return &h, nil + } + + func LoadRaw(path string) (*Harness, error) { + data, err := os.ReadFile(path) + if err != nil { + return nil, err + } + return ParseRaw(data) + } + ``` +- `ParseRaw` is exported for use by `DiscoverRemoteAgents` and any other caller that has raw YAML bytes (e.g., test helpers). `LoadRaw` remains the convenience wrapper for file-based loading. + +**Create `internal/harness/discover_remote_test.go`:** +- Mock forge client (implement `forge.Client` interface with in-memory file map) +- Directory with multiple harness files → returns sorted AgentInfo list +- No `harness/` directory (`ErrNotFound`) → `(nil, nil)` +- File without role/slug → skipped +- Malformed YAML → multi-error, other files still returned +- `GetFileContentAtRef` failure for one file → multi-error, other files returned +- Empty `harness/` directory → empty list, no error +- Results match what `DiscoverAgents` would return for the same content on disk + +**After merge:** `DiscoverRemoteAgents` and `ParseRaw` exist as tested library functions. No production callers. The forge API surface required (`ListDirectoryContents`, `GetFileContentAtRef`) already exists. + +--- + +## PR 3: Wire Lint() into fullsend run and lock + +**Scope:** Call `Lint()` after harness loading in `fullsend run` and `fullsend lock`, printing warnings to stderr. Non-fatal — commands still succeed. + +**Modify `internal/cli/run.go`:** + +- After `LoadWithBase()` returns successfully, call `h.Lint()` +- For each diagnostic, print via `printer.Warning(diag.String())` +- No early exit — lint diagnostics are informational only +- Example output: + ``` + ⚠ warning: role: role is not set; it will be required in a future version + ``` + +**Modify `internal/cli/lock.go`:** + +- Same pattern: call `h.Lint()` after `LoadWithBase()` in `runLock()` +- For `--all` mode: lint each harness after loading, print diagnostics with the harness filename as context: `printer.Warning(fmt.Sprintf("%s: %s", harnessName, diag.String()))` + +**Check `internal/ui/printer.go`:** + +- Verify `Warning(msg string)` method exists (or `Warn`). If not, add it — print to stderr with a `⚠` prefix, colored yellow if terminal supports it. Follow existing `printer.Error()` / `printer.Info()` patterns. + +**Create/modify test files:** + +- `internal/cli/run_test.go`: test that a harness without `role` produces a warning line in output but command succeeds +- `internal/cli/lock_test.go` (or `lock_all_test.go`): same for lock path + +**After merge:** `fullsend run` and `fullsend lock` emit warnings for harnesses missing `role`. No behavioral change — commands succeed regardless. + +**Depends on:** PR 1 + +--- + +## PR 4: Migrate loadKnownSlugs to harness-first discovery + +**Scope:** Change `loadKnownSlugs()` in `internal/cli/admin.go` to prefer harness wrapper files over the `config.yaml` `agents:` block. Emits a deprecation notice when falling back to the `agents:` block. + +**Modify `internal/cli/admin.go`:** + +- Rename `loadKnownSlugs` → `loadKnownSlugsLegacy` (unexported, kept as fallback) +- New `loadKnownSlugs(ctx context.Context, client forge.Client, owner, configRepo, ref string, printer *ui.Printer) map[string]string`: + 1. Call `harness.DiscoverRemoteAgents(ctx, client, owner, configRepo, ref)` + 2. If result is non-empty: build `map[role]slug` from `[]AgentInfo`, return it + 3. If result is empty (no harness files or no role/slug in them): call `loadKnownSlugsLegacy` (reads `config.yaml` `agents:` block) + 4. If legacy returns non-empty: emit deprecation notice via `printer.Warning("agent identity read from config.yaml agents: block; migrate to harness files with role/slug fields")` + 5. If legacy also empty: return nil (existing behavior — falls through to `DefaultAgentRoles()` convention in appsetup) +- Update the call site at line ~1349 (`runOrgInstall`) to pass `ctx` and `printer` to the new signature + +**Handling duplicate roles:** `DiscoverRemoteAgents` can return multiple entries with the same role (e.g., `code.yaml` and `fix.yaml` both have `role: coder`). When building the `map[role]slug`, the first entry wins (sorted order: `code.yaml` before `fix.yaml`). This matches the existing behavior where `AgentSlugs()` returns one slug per role. Log at debug level when a duplicate role is encountered. + +**Modify `internal/cli/admin_test.go`:** + +- Test: config repo has harness wrappers with role/slug → `loadKnownSlugs` returns slugs from harness files, no deprecation warning +- Test: config repo has no `harness/` dir but has `config.yaml` with `agents:` → falls back, emits deprecation warning +- Test: config repo has harness wrappers WITHOUT role/slug (legacy format) → falls back to `agents:` block +- Test: neither harness files nor `agents:` block → returns nil + +**After merge:** `loadKnownSlugs` prefers harness wrapper files in the config repo. Existing installs with only `config.yaml` agents: block continue to work but see a deprecation notice. + +**Depends on:** PR 2 + +--- + +## PR 5: Migrate uninstall flows to harness-first discovery + +**Scope:** Change `runUninstall` and `runGitHubUninstall` to discover agent slugs from harness wrapper files before falling back to the `agents:` block. + +**Modify `internal/cli/admin.go` — `runUninstall` (line ~1600):** + +- Before reading `parsedCfg.Agents`, call `harness.DiscoverRemoteAgents(ctx, client, owner, configRepo, ref)` +- If harness discovery returns results: build slug list from `AgentInfo.Slug` values +- If harness discovery returns empty: fall back to `parsedCfg.Agents` (existing behavior) with deprecation notice +- If both empty: fall back to `DefaultAgentRoles()` convention (existing behavior) +- The three-tier fallback chain is: + ``` + harness files → config.yaml agents: block → DefaultAgentRoles() convention + ``` + +**Modify `internal/cli/github.go` — `runGitHubUninstall` (line ~822):** + +- Same three-tier fallback chain as `runUninstall` +- Extract a shared helper to avoid duplicating the fallback logic: + ```go + func discoverAgentSlugs(ctx context.Context, client forge.Client, owner, configRepo, ref string, cfg *config.OrgConfig, printer *ui.Printer) []string + ``` + This helper encapsulates the three-tier discovery and deprecation warning. Both `runUninstall` and `runGitHubUninstall` call it. + +**Create `internal/cli/discover_slugs.go`:** + +- `discoverAgentSlugs` helper function (unexported) +- Returns `[]string` (slug list, deduplicated) +- Logs which discovery tier was used at debug level +- Emits deprecation warning when falling back to `agents:` block + +**Tests:** + +- `internal/cli/admin_test.go`: uninstall with harness wrappers → uses harness slugs +- `internal/cli/admin_test.go`: uninstall with only `agents:` block → falls back, deprecation warning +- `internal/cli/github_test.go`: same scenarios for `runGitHubUninstall` +- Both: empty harness and empty agents → falls back to `DefaultAgentRoles()` convention + +**After merge:** Uninstall flows prefer harness wrapper files for agent discovery. Existing installations without harness wrappers continue to work via fallback. + +**Depends on:** PR 2 + +--- + +## PR 6: Make OrgConfig.Agents optional with deprecation notice + +**Scope:** Allow `config.yaml` to omit the `agents:` block entirely. When present, log a deprecation notice during config load. The install flow continues to dual-write (Phase 4 stops it). + +**Modify `internal/config/config.go`:** + +- Change `Agents` yaml tag from `yaml:"agents"` to `yaml:"agents,omitempty"` +- `AgentSlugs()` already handles nil `Agents` (returns empty map) — verify with a test +- Add `HasAgentsBlock() bool` — returns `len(c.Agents) > 0`. Used by CLI commands to decide whether to emit a deprecation notice. + +**Modify `internal/config/config_test.go`:** + +- Test: config YAML without `agents:` block → `OrgConfig.Agents` is nil, `AgentSlugs()` returns empty map +- Test: config YAML with empty `agents: []` → `AgentSlugs()` returns empty map +- Test: config YAML with populated `agents:` → existing behavior unchanged +- Test: `HasAgentsBlock()` returns correct values for each case +- Test: serializing `OrgConfig` with nil `Agents` omits the `agents:` key from YAML output + +**Modify `internal/cli/admin.go`:** + +- After loading config in `runOrgInstall`: if `cfg.HasAgentsBlock()`, emit deprecation notice: + ``` + ⚠ config.yaml contains an agents: block. Agent identity is now managed in harness files. + The agents: block will be removed in a future version. + Run 'fullsend install' to migrate. + ``` +- The install flow still writes the `agents:` block (dual-write continues). Phase 4 will remove it. + +**Modify `internal/cli/admin.go` — `runPerRepoInstall`:** + +- Check for `cfg.HasAgentsBlock()` and emit the same deprecation notice if present. + +**After merge:** `config.yaml` can omit `agents:` without errors. When present, a deprecation notice encourages migration. Install continues dual-writing for backward compatibility. + +**Depends on:** PRs 4, 5 (consumers migrated before making the field optional) + +--- + +## Verification + +After all PRs merge, verify Phase 3 end-to-end: + +1. `make go-test` — all new and existing tests pass +2. `make go-vet` — no issues +3. `make lint` — passes +4. **Lint diagnostics:** `fullsend run` on a harness without `role` emits a warning but succeeds +5. **Lint diagnostics:** `fullsend lock` and `fullsend lock --all` emit warnings for harnesses missing `role` +6. **No warning for valid harnesses:** `fullsend run` on a harness with `role` produces no lint output +7. **Remote discovery:** `loadKnownSlugs` reads role/slug from remote harness wrapper files in the config repo +8. **Remote discovery fallback:** when no harness files exist, `loadKnownSlugs` falls back to `config.yaml` `agents:` block with deprecation notice +9. **Uninstall discovery:** `runUninstall` discovers agent slugs from remote harness files +10. **Uninstall fallback:** when no harness files exist, uninstall falls back to `agents:` block then `DefaultAgentRoles()` +11. **OrgConfig optional agents:** config.yaml without `agents:` block loads without error; `AgentSlugs()` returns empty map +12. **OrgConfig omitempty:** serializing `OrgConfig` with nil `Agents` omits the key from YAML output +13. **Deprecation notice:** loading config.yaml with an `agents:` block emits deprecation warning +14. **Backward compat:** existing config.yaml with `agents:` block continues to work identically (dual-write still active, all consumers still check `agents:` as fallback) +15. **Dual-write intact:** `fullsend install` still writes both harness wrapper files and `config.yaml` `agents:` block + +--- + +## Future: Phase 4 (Remove) + +Phase 4 is not planned in detail here, but its scope is: + +- Require `role` in `Validate()` (move from `Lint()` warning to hard error) +- Stop writing `agents:` block during install (remove the dual-write from `HarnessWrappersLayer` and config generation) +- Remove `OrgConfig.Agents` field and `AgentSlugs()` method +- Remove `loadKnownSlugsLegacy` and the fallback tier in `discoverAgentSlugs` +- Remove `HasAgentsBlock()` and all deprecation notice code +- Consider config schema version bump to "v2" (per ADR open question) +- Audit all consumers (2-3 PRs estimated) diff --git a/docs/reference/installation.md b/docs/reference/installation.md index a1364a4f9..ea92333b5 100644 --- a/docs/reference/installation.md +++ b/docs/reference/installation.md @@ -732,7 +732,8 @@ The composite action accepts four optional inputs for status notifications: | `run-url` | URL of the CI/CD run shown in the status comment | | `status-repo` | Repository (`owner/repo`) to post status comments on | | `status-number` | Issue or PR number for status comments | -| `status-token` | Token for posting comments (defaults to `GH_TOKEN`) | +| `mint-url` | URL of the token mint service used to obtain fresh tokens for posting comments | +| `status-token` | **Deprecated.** Static token for posting comments; use `mint-url` instead | All reusable workflows pass these inputs automatically. diff --git a/docs/superpowers/plans/2026-06-11-triage-prerequisites.md b/docs/superpowers/plans/2026-06-11-triage-prerequisites.md new file mode 100644 index 000000000..777c65fd2 --- /dev/null +++ b/docs/superpowers/plans/2026-06-11-triage-prerequisites.md @@ -0,0 +1,865 @@ +# Triage Prerequisites Action Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace the triage agent's `blocked` action with a `prerequisites` action that can both reference existing blockers and create new upstream issues. + +**Architecture:** Add `CreateIssuesConfig` to the config structs, update the triage result JSON schema, modify the agent prompt, and extend the post-script to create issues and handle the allowlist. The post-script reads `config.yaml` from `$GITHUB_WORKSPACE` (the config repo checkout) via `yq`. + +**Tech Stack:** Go (config structs + tests), JSON Schema, bash (post-script), markdown (agent prompt + docs) + +--- + +### Task 1: Add `CreateIssuesConfig` to config structs + +**Files:** +- Modify: `internal/config/config.go` +- Test: `internal/config/config_test.go` + +- [ ] **Step 1: Write failing tests for the new config types** + +Add to `internal/config/config_test.go`: + +```go +func TestOrgConfig_CreateIssues_ParseYAML(t *testing.T) { + yamlData := ` +version: "1" +dispatch: + platform: github-actions +defaults: + roles: + - fullsend + max_implementation_retries: 2 +agents: [] +repos: {} +create_issues: + allow_targets: + orgs: + - my-org + - upstream-org + repos: + - other-org/specific-repo +` + cfg, err := ParseOrgConfig([]byte(yamlData)) + require.NoError(t, err) + require.NotNil(t, cfg.CreateIssues) + assert.Equal(t, []string{"my-org", "upstream-org"}, cfg.CreateIssues.AllowTargets.Orgs) + assert.Equal(t, []string{"other-org/specific-repo"}, cfg.CreateIssues.AllowTargets.Repos) +} + +func TestOrgConfig_CreateIssues_OmittedWhenEmpty(t *testing.T) { + cfg := &OrgConfig{ + Version: "1", + Dispatch: DispatchConfig{Platform: "github-actions"}, + Defaults: RepoDefaults{ + Roles: []string{"fullsend"}, + MaxImplementationRetries: 2, + }, + Agents: []AgentEntry{}, + Repos: map[string]RepoConfig{}, + } + data, err := cfg.Marshal() + require.NoError(t, err) + assert.NotContains(t, string(data), "create_issues") +} + +func TestOrgConfig_CreateIssues_Marshal(t *testing.T) { + cfg := &OrgConfig{ + Version: "1", + Dispatch: DispatchConfig{Platform: "github-actions"}, + Defaults: RepoDefaults{ + Roles: []string{"fullsend"}, + MaxImplementationRetries: 2, + }, + Agents: []AgentEntry{}, + Repos: map[string]RepoConfig{}, + CreateIssues: &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Orgs: []string{"my-org"}, + Repos: []string{"fullsend-ai/fullsend"}, + }, + }, + } + data, err := cfg.Marshal() + require.NoError(t, err) + assert.Contains(t, string(data), "create_issues:") + assert.Contains(t, string(data), "my-org") + assert.Contains(t, string(data), "fullsend-ai/fullsend") +} + +func TestOrgConfigValidate_CreateIssues_InvalidRepoFormat(t *testing.T) { + cfg := &OrgConfig{ + Version: "1", + Dispatch: DispatchConfig{Platform: "github-actions"}, + Defaults: RepoDefaults{ + Roles: []string{"fullsend"}, + MaxImplementationRetries: 2, + }, + CreateIssues: &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Repos: []string{"no-slash"}, + }, + }, + } + err := cfg.Validate() + assert.Error(t, err) + assert.Contains(t, err.Error(), "create_issues") +} + +func TestOrgConfigValidate_CreateIssues_EmptyOrg(t *testing.T) { + cfg := &OrgConfig{ + Version: "1", + Dispatch: DispatchConfig{Platform: "github-actions"}, + Defaults: RepoDefaults{ + Roles: []string{"fullsend"}, + MaxImplementationRetries: 2, + }, + CreateIssues: &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Orgs: []string{""}, + }, + }, + } + err := cfg.Validate() + assert.Error(t, err) + assert.Contains(t, err.Error(), "create_issues") +} + +func TestOrgConfigValidate_CreateIssues_Valid(t *testing.T) { + cfg := &OrgConfig{ + Version: "1", + Dispatch: DispatchConfig{Platform: "github-actions"}, + Defaults: RepoDefaults{ + Roles: []string{"fullsend"}, + MaxImplementationRetries: 2, + }, + CreateIssues: &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Orgs: []string{"my-org"}, + Repos: []string{"other/repo"}, + }, + }, + } + assert.NoError(t, cfg.Validate()) +} + +func TestOrgConfigValidate_CreateIssues_Nil(t *testing.T) { + cfg := &OrgConfig{ + Version: "1", + Dispatch: DispatchConfig{Platform: "github-actions"}, + Defaults: RepoDefaults{ + Roles: []string{"fullsend"}, + MaxImplementationRetries: 2, + }, + } + assert.NoError(t, cfg.Validate()) +} + +func TestNewOrgConfig_CreateIssuesDefaults(t *testing.T) { + cfg := NewOrgConfig([]string{"repo-a"}, []string{"repo-a"}, []string{"fullsend"}, nil, "", "my-org") + require.NotNil(t, cfg.CreateIssues) + assert.Contains(t, cfg.CreateIssues.AllowTargets.Orgs, "my-org") + assert.Contains(t, cfg.CreateIssues.AllowTargets.Repos, "fullsend-ai/fullsend") +} + +func TestPerRepoConfig_CreateIssues_ParseYAML(t *testing.T) { + yamlData := ` +version: "1" +roles: + - triage +create_issues: + allow_targets: + repos: + - owner/target-repo + - fullsend-ai/fullsend +` + cfg, err := ParsePerRepoConfig([]byte(yamlData)) + require.NoError(t, err) + require.NotNil(t, cfg.CreateIssues) + assert.Equal(t, []string{"owner/target-repo", "fullsend-ai/fullsend"}, cfg.CreateIssues.AllowTargets.Repos) +} + +func TestNewPerRepoConfig_CreateIssuesDefaults(t *testing.T) { + cfg := NewPerRepoConfig(nil, "owner/my-repo") + require.NotNil(t, cfg.CreateIssues) + assert.Contains(t, cfg.CreateIssues.AllowTargets.Repos, "owner/my-repo") + assert.Contains(t, cfg.CreateIssues.AllowTargets.Repos, "fullsend-ai/fullsend") +} +``` + +- [ ] **Step 2: Run tests to verify they fail** + +Run: `cd internal/config && go test -v -run 'CreateIssues' ./...` +Expected: compilation errors — types `CreateIssuesConfig`, `AllowTargets` not defined, `NewOrgConfig`/`NewPerRepoConfig` wrong arg count. + +- [ ] **Step 3: Add the new types and update struct fields** + +In `internal/config/config.go`, add the new types: + +```go +// AllowTargets defines which orgs and repos agents may create issues in. +type AllowTargets struct { + Orgs []string `yaml:"orgs,omitempty"` + Repos []string `yaml:"repos,omitempty"` +} + +// CreateIssuesConfig controls cross-repo issue creation by agents. +type CreateIssuesConfig struct { + AllowTargets AllowTargets `yaml:"allow_targets"` +} +``` + +Add `CreateIssues` field to `OrgConfig`: + +```go +CreateIssues *CreateIssuesConfig `yaml:"create_issues,omitempty"` +``` + +Add `CreateIssues` field to `PerRepoConfig`: + +```go +CreateIssues *CreateIssuesConfig `yaml:"create_issues,omitempty"` +``` + +- [ ] **Step 4: Update `NewOrgConfig` to accept org name and set defaults** + +Change `NewOrgConfig` signature to add `org string` parameter: + +```go +func NewOrgConfig(allRepos, enabledRepos, roles []string, agents []AgentEntry, inferenceProvider, org string) *OrgConfig { +``` + +Inside the function, after the existing config construction, add: + +```go +if org != "" { + cfg.CreateIssues = &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Orgs: []string{org}, + Repos: []string{"fullsend-ai/fullsend"}, + }, + } +} +``` + +- [ ] **Step 5: Update `NewPerRepoConfig` to accept target repo and set defaults** + +Change `NewPerRepoConfig` signature: + +```go +func NewPerRepoConfig(roles []string, targetRepo string) *PerRepoConfig { +``` + +Inside the function, after the existing config construction, add: + +```go +if targetRepo != "" { + cfg.CreateIssues = &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Repos: []string{targetRepo, "fullsend-ai/fullsend"}, + }, + } +} +``` + +- [ ] **Step 6: Add validation for CreateIssues in `OrgConfig.Validate()`** + +Before the `return nil` at the end of `Validate()`: + +```go +if err := validateCreateIssues(c.CreateIssues); err != nil { + return err +} +``` + +Add the helper: + +```go +func validateCreateIssues(cfg *CreateIssuesConfig) error { + if cfg == nil { + return nil + } + for _, org := range cfg.AllowTargets.Orgs { + if org == "" { + return fmt.Errorf("create_issues.allow_targets.orgs contains empty string") + } + } + for _, repo := range cfg.AllowTargets.Repos { + if repo == "" || !strings.Contains(repo, "/") { + return fmt.Errorf("create_issues.allow_targets.repos entry %q must be owner/name format", repo) + } + } + return nil +} +``` + +Add the same `validateCreateIssues` call to `PerRepoConfig.Validate()`. + +- [ ] **Step 7: Run tests to verify they pass** + +Run: `cd internal/config && go test -v ./...` +Expected: all tests pass including new `CreateIssues` tests. + +- [ ] **Step 8: Commit** + +```bash +git add internal/config/config.go internal/config/config_test.go +git commit -S -s -m "feat(config): add create_issues allowlist config (#401) + +Add CreateIssuesConfig and AllowTargets types to both OrgConfig and +PerRepoConfig. NewOrgConfig populates defaults with the org and +fullsend-ai/fullsend. NewPerRepoConfig populates with the target repo +and fullsend-ai/fullsend. + +Assisted-by: Claude Opus 4.6 " +``` + +### Task 2: Fix callers of `NewOrgConfig` and `NewPerRepoConfig` + +**Files:** +- Modify: `internal/cli/admin.go` +- Modify: `internal/cli/github.go` +- Modify: `internal/cli/admin_test.go` +- Modify: `internal/cli/github_test.go` +- Modify: `internal/layers/configrepo_test.go` + +Task 1 changed the signatures of `NewOrgConfig` (added `org string`) and `NewPerRepoConfig` (added `targetRepo string`). All callers must be updated. + +- [ ] **Step 1: Find all call sites and update them** + +Update each `NewOrgConfig(...)` call to pass the `org` variable as the final argument. The `org` variable is already in scope at every call site in `admin.go` and `github.go`. + +In `internal/cli/github.go:464`: +```go +orgCfg := config.NewOrgConfig(repoNames, enabledRepos, roles, dummyAgents, inferenceProviderName, org) +``` + +In `internal/cli/github.go:513`: +```go +orgCfg = config.NewOrgConfig(repoNames, enabledRepos, roles, agents, inferenceProviderName, org) +``` + +In `internal/cli/admin.go:1174`: +```go +cfg := config.NewOrgConfig(repoNames, enabledRepos, roles, nil, inferenceProviderName, org) +``` + +In `internal/cli/admin.go:1502`: +```go +cfg := config.NewOrgConfig(repoNames, enabledRepos, roles, agents, inferenceProviderName, org) +``` + +In `internal/cli/admin.go:1640`: +```go +emptyCfg := config.NewOrgConfig(nil, nil, nil, nil, "", "") +``` + +In `internal/cli/admin.go:1781`: +```go +cfg := config.NewOrgConfig(repoNames, nil, defaultRoles, nil, "", org) +``` + +Update each `NewPerRepoConfig(...)` call to pass `cfg.target` (the `owner/repo` string): + +In `internal/cli/github.go:210`: +```go +perRepoCfg := config.NewPerRepoConfig(roles, cfg.target) +``` + +In `internal/cli/admin.go:647`: +```go +cfg := config.NewPerRepoConfig(roles, target) +``` +(Check the variable name — it may be `cfg.target` or `target` depending on the function scope.) + +Update test call sites — these typically pass `""` for the new parameters since tests don't care about create_issues defaults: + +In `internal/cli/admin_test.go:583`: +```go +return config.NewOrgConfig(repoNames, enabledRepos, []string{"triage"}, nil, "", "") +``` + +In `internal/cli/admin_test.go:1082`, `1123`: +```go +config.NewOrgConfig(..., "") +``` + +In `internal/cli/github_test.go:395`: +```go +cfg := config.NewOrgConfig([]string{"widget"}, []string{"widget"}, []string{"triage"}, nil, "", "") +``` + +In `internal/config/config_test.go`, update existing tests that call `NewOrgConfig` without the org param: + +`TestNewOrgConfig`: add `""` as last arg. +`TestNewOrgConfig_WithInferenceProvider`: change to `NewOrgConfig(nil, nil, nil, nil, "vertex", "")`. +`TestNewOrgConfig_WithoutInferenceProvider`: change to `NewOrgConfig(nil, nil, nil, nil, "", "")`. +`TestNewOrgConfig_KillSwitchDefaultFalse`: change to `NewOrgConfig(nil, nil, []string{"fullsend"}, nil, "", "")`. + +In `internal/config/config_test.go`, update existing tests for `NewPerRepoConfig`: + +`TestNewPerRepoConfig_DefaultRoles`: change to `NewPerRepoConfig(nil, "")`. +`TestNewPerRepoConfig_CustomRoles`: change to `NewPerRepoConfig([]string{"triage", "review"}, "")`. +`TestPerRepoConfig_RoundTrip`: change to `NewPerRepoConfig([]string{...}, "")`. + +In `internal/layers/configrepo_test.go`, update any `NewOrgConfig` / `NewPerRepoConfig` calls similarly. + +- [ ] **Step 2: Run full test suite to verify** + +Run: `make go-test` +Expected: all tests pass. + +- [ ] **Step 3: Commit** + +```bash +git add internal/cli/admin.go internal/cli/github.go internal/cli/admin_test.go internal/cli/github_test.go internal/config/config_test.go internal/layers/configrepo_test.go +git commit -S -s -m "refactor: update NewOrgConfig/NewPerRepoConfig callers for create_issues (#401) + +Pass org name and target repo to config constructors so create_issues +defaults are populated at install time. + +Assisted-by: Claude Opus 4.6 " +``` + +### Task 3: Update triage result JSON schema + +**Files:** +- Modify: `internal/scaffold/fullsend-repo/schemas/triage-result.schema.json` +- Test: `internal/scaffold/fullsend-repo/scripts/validate-output-schema-test.sh` (if it exists) + +- [ ] **Step 1: Replace `blocked` with `prerequisites` in action enum** + +In `triage-result.schema.json`, change line 12: + +```json +"enum": ["insufficient", "duplicate", "sufficient", "prerequisites", "question"] +``` + +- [ ] **Step 2: Remove the `blocked_by` property** + +Delete lines 33-37 (the `blocked_by` property). + +- [ ] **Step 3: Add the `prerequisites` property definition** + +Add to the `properties` object: + +```json +"prerequisites": { + "type": "object", + "required": ["existing", "create"], + "properties": { + "existing": { + "type": "array", + "items": { + "type": "object", + "required": ["url"], + "properties": { + "url": { + "type": "string", + "pattern": "^https://github\\.com/[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+/(issues|pull)/[0-9]+$" + } + }, + "additionalProperties": false + } + }, + "create": { + "type": "array", + "items": { + "type": "object", + "required": ["repo", "title", "body"], + "properties": { + "repo": { + "type": "string", + "pattern": "^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$" + }, + "title": { + "type": "string", + "minLength": 1 + }, + "body": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false + } + } + }, + "additionalProperties": false +} +``` + +- [ ] **Step 4: Update the conditional validation** + +Replace the `blocked` conditional (the `allOf` entry at lines 55-58): + +```json +{ + "if": { "properties": { "action": { "const": "prerequisites" } }, "required": ["action"] }, + "then": { + "required": ["prerequisites"], + "properties": { + "prerequisites": { + "anyOf": [ + { "properties": { "existing": { "minItems": 1 } } }, + { "properties": { "create": { "minItems": 1 } } } + ] + } + } + } +} +``` + +- [ ] **Step 5: Validate the schema is valid JSON** + +Run: `jq empty internal/scaffold/fullsend-repo/schemas/triage-result.schema.json` +Expected: no output (valid JSON). + +- [ ] **Step 6: Test with sample inputs** + +Create a temp file `/tmp/test-prereq.json`: + +```json +{ + "action": "prerequisites", + "reasoning": "Blocked by upstream work", + "comment": "This needs upstream changes first.", + "prerequisites": { + "existing": [{"url": "https://github.com/org/repo/issues/42"}], + "create": [{"repo": "org/upstream", "title": "Add X", "body": "Need X for downstream."}] + } +} +``` + +Run the schema validator if available: +```bash +fullsend-check-output /tmp/test-prereq.json 2>&1 || echo "Manual validation needed" +``` + +Also test that a `prerequisites` result with both arrays empty is rejected, and that the old `blocked` action is rejected. + +- [ ] **Step 7: Commit** + +```bash +git add internal/scaffold/fullsend-repo/schemas/triage-result.schema.json +git commit -S -s -m "feat(schema): replace blocked with prerequisites action (#401) + +Replace the blocked action and blocked_by field with a prerequisites +action containing existing[] and create[] arrays. At least one array +must be non-empty. + +Assisted-by: Claude Opus 4.6 " +``` + +### Task 4: Update the triage agent prompt + +**Files:** +- Modify: `internal/scaffold/fullsend-repo/agents/triage.md` + +- [ ] **Step 1: Replace the `blocked` action section** + +Replace the "Action: `blocked`" section (lines 182-195) with: + +```markdown +### Action: `prerequisites` + +Progress on this issue depends on work that must happen first — either in this repository or another. Use this action when you identify specific blocking dependencies: existing issues/PRs that must be resolved, or upstream work that needs a tracking issue created. + +**HARD CONSTRAINT:** Never emit `sufficient` if unresolved prerequisites exist. Use `prerequisites` instead. + +The `prerequisites` object contains two arrays: + +- `existing` — issues or PRs that already exist and block this work. Include the full HTML URL. +- `create` — issues that need to be filed in other repos before this work can proceed. Include the target `repo` (owner/name format), a `title`, and a `body`. Write the body for the target repo's audience — include enough technical context for upstream maintainers to understand what is needed. Use your judgment on whether to include a back-reference to the originating issue; sometimes it provides helpful context, sometimes it leaks internal details. + +At least one of the two arrays must have entries. + +```json +{ + "action": "prerequisites", + "reasoning": "Brief explanation of the dependencies and why this issue cannot proceed", + "prerequisites": { + "existing": [ + { "url": "https://github.com/org/repo/issues/99" } + ], + "create": [ + { + "repo": "org/upstream-lib", + "title": "Add support for X", + "body": "Technical description of what is needed and why, written for the upstream repo's maintainers." + } + ] + }, + "comment": "A professional comment explaining the blocking dependencies. Link to existing blockers and describe what new issues need to be created upstream. Be specific about why each dependency must be resolved before this issue can proceed." +} +``` +``` + +- [ ] **Step 2: Update the anti-premature-resolution rule** + +In the "Anti-premature-resolution rule" paragraph (line 125), add after the existing hard constraint: + +```markdown +**Anti-premature-prerequisites rule (HARD CONSTRAINT):** If your assessment identifies unresolved prerequisites — dependencies on work in other repos or unmerged changes that must land first — you MUST use `action: "prerequisites"`. Do NOT emit `action: "sufficient"` when prerequisites exist. The `sufficient` action means there are zero blockers and zero open questions. +``` + +- [ ] **Step 3: Update Step 3 Phase 3 to reference prerequisites** + +In Phase 3 (line 108), update the last bullet: + +```markdown +- **Is progress blocked on other work?** Consider whether the fix depends on an unresolved issue or unmerged PR — in this repo or another. If a developer cannot meaningfully start work until some other issue is resolved, this issue has prerequisites regardless of how clear the problem description is. If the blocking work has no tracking issue yet, you can recommend creating one via the `prerequisites` action's `create` array. +``` + +- [ ] **Step 4: Update Step 2c to reference prerequisites instead of blocked** + +In section 2c (line 66-77), update the heading and text to say "Check existing prerequisites" instead of "Check existing blockers", and reference the `prerequisites` action instead of `blocked`. + +- [ ] **Step 5: Commit** + +```bash +git add internal/scaffold/fullsend-repo/agents/triage.md +git commit -S -s -m "feat(triage): replace blocked action with prerequisites in agent prompt (#401) + +The triage agent can now recommend creating upstream issues via the +prerequisites action's create array, in addition to referencing existing +blockers. Adds hard constraint against emitting sufficient when +prerequisites exist. + +Assisted-by: Claude Opus 4.6 " +``` + +### Task 5: Update the post-script to handle `prerequisites` + +**Files:** +- Modify: `internal/scaffold/fullsend-repo/scripts/post-triage.sh` + +- [ ] **Step 1: Replace the `blocked)` case with `prerequisites)`** + +Replace the entire `blocked)` case (lines 122-141) with: + +```bash + prerequisites) + if [[ -z "${COMMENT}" ]]; then + echo "ERROR: action is 'prerequisites' but no comment provided" + exit 1 + fi + + # Read the allowlist from config.yaml. The config repo is checked out + # at $GITHUB_WORKSPACE by the reusable workflow. + CONFIG_FILE="${GITHUB_WORKSPACE}/config.yaml" + if [[ ! -f "${CONFIG_FILE}" ]]; then + # Per-repo mode: config is under .fullsend/ + CONFIG_FILE="${GITHUB_WORKSPACE}/.fullsend/config.yaml" + fi + + ALLOWED_ORGS="" + ALLOWED_REPOS="" + if [[ -f "${CONFIG_FILE}" ]] && command -v yq &>/dev/null; then + ALLOWED_ORGS=$(yq -r '.create_issues.allow_targets.orgs // [] | .[]' "${CONFIG_FILE}" 2>/dev/null || true) + ALLOWED_REPOS=$(yq -r '.create_issues.allow_targets.repos // [] | .[]' "${CONFIG_FILE}" 2>/dev/null || true) + fi + + # The source repo is always implicitly allowed. + SOURCE_ORG="${REPO%%/*}" + + is_target_allowed() { + local target_repo="$1" + local target_org="${target_repo%%/*}" + + # Source repo is always allowed. + if [[ "${target_repo}" == "${REPO}" ]]; then + return 0 + fi + + # Check org allowlist. + if [[ -n "${ALLOWED_ORGS}" ]] && echo "${ALLOWED_ORGS}" | grep -qFx "${target_org}"; then + return 0 + fi + + # Check repo allowlist. + if [[ -n "${ALLOWED_REPOS}" ]] && echo "${ALLOWED_REPOS}" | grep -qFx "${target_repo}"; then + return 0 + fi + + return 1 + } + + # Process create entries: create issues, collect URLs. + CREATE_COUNT=$(jq '.prerequisites.create // [] | length' "${RESULT_FILE}") + CREATED_URLS="" + FAILED_CREATES="" + + for i in $(seq 0 $((CREATE_COUNT - 1))); do + TARGET_REPO=$(jq -r ".prerequisites.create[${i}].repo" "${RESULT_FILE}") + ISSUE_TITLE=$(jq -r ".prerequisites.create[${i}].title" "${RESULT_FILE}") + ISSUE_BODY=$(jq -r ".prerequisites.create[${i}].body" "${RESULT_FILE}") + + if ! is_target_allowed "${TARGET_REPO}"; then + echo "::warning::Skipping issue creation in '${TARGET_REPO}' — not in create_issues.allow_targets" + FAILED_CREATES="${FAILED_CREATES} +
+Prerequisite: ${TARGET_REPO} — ${ISSUE_TITLE} + +${ISSUE_BODY} + +
" + continue + fi + + echo "Creating prerequisite issue in ${TARGET_REPO}..." + CREATED_URL=$(gh issue create --repo "${TARGET_REPO}" --title "${ISSUE_TITLE}" --body "${ISSUE_BODY}" 2>&1) || { + echo "::warning::Failed to create issue in '${TARGET_REPO}': ${CREATED_URL}" + FAILED_CREATES="${FAILED_CREATES} +
+Prerequisite: ${TARGET_REPO} — ${ISSUE_TITLE} + +${ISSUE_BODY} + +
" + continue + } + echo "Created: ${CREATED_URL}" + CREATED_URLS="${CREATED_URLS} ${CREATED_URL}" + done + + # Collect existing URLs. + EXISTING_COUNT=$(jq '.prerequisites.existing // [] | length' "${RESULT_FILE}") + EXISTING_URLS="" + for i in $(seq 0 $((EXISTING_COUNT - 1))); do + URL=$(jq -r ".prerequisites.existing[${i}].url" "${RESULT_FILE}") + EXISTING_URLS="${EXISTING_URLS} ${URL}" + done + + # Merge all blocker URLs for the comment. + ALL_URLS="${EXISTING_URLS} ${CREATED_URLS}" + ALL_URLS=$(echo "${ALL_URLS}" | xargs) # trim whitespace + + if [[ -n "${ALL_URLS}" ]]; then + BLOCKER_LIST="" + for url in ${ALL_URLS}; do + BLOCKER_LIST="${BLOCKER_LIST} +- ${url}" + done + COMMENT="${COMMENT} + +**Blocked by:**${BLOCKER_LIST}" + fi + + if [[ -n "${FAILED_CREATES}" ]]; then + COMMENT="${COMMENT} + +**Could not create automatically** (file manually or update \`create_issues.allow_targets\` in config.yaml): +${FAILED_CREATES}" + fi + + remove_label "ready-to-code" + remove_label "needs-info" + add_label "blocked" + ;; +``` + +- [ ] **Step 2: Verify the script is syntactically valid** + +Run: `bash -n internal/scaffold/fullsend-repo/scripts/post-triage.sh` +Expected: no output (valid syntax). + +- [ ] **Step 3: Commit** + +```bash +git add internal/scaffold/fullsend-repo/scripts/post-triage.sh +git commit -S -s -m "feat(triage): handle prerequisites action in post-script (#401) + +Replace the blocked handler with prerequisites. The post-script reads +the create_issues allowlist from config.yaml, creates permitted upstream +issues via gh, and includes collapsed draft bodies for disallowed or +failed creates so humans can file them manually. + +Assisted-by: Claude Opus 4.6 " +``` + +### Task 6: Update user-facing triage docs + +**Files:** +- Modify: `docs/agents/triage.md` + +- [ ] **Step 1: Update control labels table** + +Replace the `blocked` row: + +```markdown +| `blocked` | The issue depends on prerequisites — existing issues/PRs or newly created upstream issues. The agent identified or created the blockers. | +``` + +- [ ] **Step 2: Add new section on `create_issues` configuration** + +After the "Configuration and extension" heading, add: + +```markdown +### Cross-repo issue creation + +The triage agent can create prerequisite issues in other repositories when it +identifies upstream dependencies that don't have tracking issues yet. This is +controlled by the `create_issues` section in `config.yaml`: + +```yaml +create_issues: + allow_targets: + orgs: + - my-org + repos: + - upstream-org/specific-repo +``` + +**Defaults:** At install time, fullsend populates this with your org (in org mode) +or your repo (in per-repo mode), plus `fullsend-ai/fullsend` as an upstream target. + +**When to expand the allowlist:** If your project depends on libraries or services +in other GitHub orgs and you want the triage agent to automatically file +prerequisite issues there, add those orgs or repos to `allow_targets`. + +**When to restrict the allowlist:** If you don't want agents creating issues +outside your org, remove entries. If `allow_targets` is empty, automatic +prerequisite creation is disabled entirely — the agent will still identify +the dependency and include a draft issue body in its comment for a human to +file manually. + +The source repo (where triage is running) is always implicitly allowed +regardless of the allowlist. +``` + +- [ ] **Step 3: Commit** + +```bash +git add docs/agents/triage.md +git commit -S -s -m "docs: document prerequisites action and create_issues config (#401) + +Update triage agent docs to explain the new prerequisites action and the +create_issues.allow_targets configuration surface. + +Assisted-by: Claude Opus 4.6 " +``` + +### Task 7: Run linters and full test suite + +**Files:** +- All modified files from Tasks 1-6 + +- [ ] **Step 1: Run linter** + +Run: `make lint` +Expected: no failures. + +- [ ] **Step 2: Run Go tests** + +Run: `make go-test` +Expected: all tests pass. + +- [ ] **Step 3: Run vet** + +Run: `make go-vet` +Expected: no issues. + +- [ ] **Step 4: Fix any issues found and commit fixes** + +If lint or tests reveal issues, fix them and commit. diff --git a/docs/superpowers/specs/2026-06-11-triage-prerequisites-design.md b/docs/superpowers/specs/2026-06-11-triage-prerequisites-design.md new file mode 100644 index 000000000..899deebf5 --- /dev/null +++ b/docs/superpowers/specs/2026-06-11-triage-prerequisites-design.md @@ -0,0 +1,147 @@ +# Triage Agent Prerequisites Action + +**Date:** 2026-06-11 +**Issue:** [#401](https://github.com/fullsend-ai/fullsend/issues/401) +**Status:** Draft + +## Problem + +The triage agent can detect that an issue is blocked by existing work elsewhere, but it cannot create the missing tracking issue when no such issue exists yet. A common scenario: triage evaluates a bug in a Tekton task and determines the root cause is a missing feature in an upstream container image defined in a different repo. Today the agent can only say "blocked" and point to an existing issue. If no upstream issue exists, the agent has no way to express "this needs to be filed first." + +This forces humans to manually identify, draft, and file prerequisite issues in other repos before the original issue can make progress. + +## Scope + +This design covers **one** of three decomposition strategies identified during brainstorming: + +| Strategy | Description | This design? | +|---|---|---| +| **Spin out dependency** | Original stays open + `blocked`. Agent creates upstream prerequisite issues. | Yes | +| **Split muddled issue** | Original closed. N independent successor issues replace it. | No (future work) | +| **Parent/child decompose** | Original stays open as parent. N child issues for incremental delivery. | No (future work) | + +## Key discovery: cross-repo issue creation works today + +A GitHub App installation token scoped to one repository can create issues in any public repo on GitHub, including repos in orgs where the app is not installed. GitHub confirmed this as a known behavior (not a vulnerability). This means the triage agent's existing token already supports cross-repo issue creation without any changes to the mint or auth infrastructure. See #402 for the original assumption that cross-installation auth would be needed. + +## Design + +### New `prerequisites` action + +The existing `blocked` action is replaced by `prerequisites`. The triage agent's action set becomes five actions: `sufficient`, `insufficient`, `duplicate`, `question`, `prerequisites`. + +The `prerequisites` action unifies two cases: +- **Existing blockers** the agent found during its search (today's `blocked` behavior) +- **New blockers** that need to be filed as issues before progress can happen + +The triage result schema: + +```json +{ + "action": "prerequisites", + "prerequisites": { + "existing": [ + { "url": "https://github.com/org/repo/issues/42" } + ], + "create": [ + { + "repo": "org/upstream-lib", + "title": "Add support for X", + "body": "Technical description for the upstream audience..." + } + ] + }, + "comment": "This issue requires upstream changes before it can proceed.", + "label_actions": [] +} +``` + +Constraints: +- At least one of `existing` or `create` must be non-empty. +- Both arrays can be populated in the same result (mixed existing + new blockers). +- The `blocked_by` field (singular URL, current schema) is removed. + +### Hard constraint in agent prompt + +> Never emit `sufficient` if unresolved prerequisites exist. Use `prerequisites` instead. + +This mirrors the existing constraint: "Never emit `sufficient` with open questions." + +### Agent prompt guidance for `create` entries + +The agent uses its judgment on issue body content. Sometimes a back-reference to the originating issue is helpful for upstream maintainers; sometimes it leaks internal context. The agent writes the body for the upstream repo's audience, not the source repo's. + +### Allowlist configuration + +A new `create_issues` config field controls which repos and orgs agents are permitted to create issues in. This applies to both triage and retro agents. + +```yaml +create_issues: + allow_targets: + orgs: + - "my-org" + - "upstream-org" + repos: + - "other-org/specific-repo" +``` + +Validation rules: +- If `allow_targets` is absent or empty, prerequisite creation is disabled (safe default). +- A target repo is permitted if its org appears in `orgs` OR the exact `owner/repo` appears in `repos`. +- The source repo (where triage is running) is always implicitly allowed. +- Entries in `repos` must be `owner/name` format. Empty strings are rejected. + +### Install-time defaults + +The admin setup flow populates `create_issues.allow_targets` with sensible defaults: + +- **Org mode:** `allow_targets.orgs` includes the org. `allow_targets.repos` includes `fullsend-ai/fullsend`. +- **Per-repo mode:** `allow_targets.repos` includes the target repo and `fullsend-ai/fullsend`. + +### Post-script behavior + +When the post-script receives `action: "prerequisites"`: + +1. **Process `create` entries:** For each entry, validate `repo` against `create_issues.allow_targets`. If allowed, create the issue using existing `forge.Client.CreateIssue` plumbing. Collect the resulting URL. If disallowed or the API call fails, record the failure. + +2. **Merge URLs:** Combine URLs from successfully created issues with the `existing` array to produce the full blocker list. + +3. **Apply labels:** Remove `ready-to-code` and `needs-info`. Add `blocked` label. (Same as current `blocked` action behavior.) + +4. **Post comment:** Sticky comment (via `fullsend post-comment`) summarizing the prerequisites. Links to all blockers (existing and newly created). For entries that could not be filed (allowlist rejection or API failure), include the agent's draft in a collapsed section so a human can file it manually: + + ```html +
+ Prerequisite: org_a/repo -- Add support for X + + [the full body the agent drafted for the upstream issue] + +
+ ``` + +5. **Partial success:** If some creates succeed and others fail, the issue still gets `blocked` with whatever blockers were established. The comment notes which prerequisites could not be created and why. + +The existing `blocked` action handler in the post-script is removed. `prerequisites` fully replaces it. + +### Re-triage flow + +When a prerequisite issue is resolved and the original issue is re-triaged, the agent discovers blocker URLs from the sticky comment posted by the post-script (which contains links to all prerequisite issues). The existing blocker-checking logic in the agent prompt (Step 2) already inspects linked issues and checks their state. If all prerequisites are resolved, the agent can emit `sufficient` or another appropriate action. No changes needed to the re-triage flow. + +## Changes required + +| Component | File | Change | +|---|---|---| +| Config structs | `internal/config/config.go` | Add `CreateIssues` struct with `AllowTargets` (Orgs `[]string`, Repos `[]string`) to both `OrgConfig` and `PerRepoConfig`. Update constructors with install-time defaults. Add validation. | +| Triage result schema | `internal/scaffold/fullsend-repo/schemas/triage-result.schema.json` | Replace `blocked` with `prerequisites` in action enum. Add `prerequisites` object schema. Remove `blocked_by`. | +| Agent prompt | `internal/scaffold/fullsend-repo/agents/triage.md` | Replace `blocked` action with `prerequisites`. Add hard constraint. Add guidance for `create` entry content. | +| Post-script | `internal/scaffold/fullsend-repo/scripts/post-triage.sh` | Replace `blocked` handler with `prerequisites` handler. Add allowlist validation, issue creation, degraded path with collapsed draft. | +| Pre-script | `internal/scaffold/fullsend-repo/scripts/pre-triage.sh` | No change. `blocked` label stripping stays the same. | +| User docs | `docs/agents/triage.md` | New section documenting `create_issues` config surface: what it does, defaults, when to expand or restrict. | +| Config constructors | `internal/config/config.go` | `NewOrgConfig` and `NewPerRepoConfig` populate `create_issues.allow_targets` defaults. Callers in `internal/cli/admin.go` and `internal/cli/github.go` pass the org/repo context. | + +## Out of scope + +- **Split muddled issues** (close original, create N independent successors) +- **Parent/child decomposition** (original stays open, create N children) +- **Cross-repo issue editing** (GitHub enforces scope on edits, only creation bypasses it) +- **Retro agent integration** (uses the same `create_issues` config, but prompt/post-script changes are separate work) diff --git a/internal/cli/admin.go b/internal/cli/admin.go index fcc9af3fc..c9c99cc9e 100644 --- a/internal/cli/admin.go +++ b/internal/cli/admin.go @@ -644,7 +644,7 @@ func runPerRepoInstall(ctx context.Context, c perRepoInstallConfig) error { printer.StepWarn("Using provided WIF provider value — skipping inference provider auto-provisioning") } - cfg := config.NewPerRepoConfig(roles) + cfg := config.NewPerRepoConfig(roles, repoFullName) if err := cfg.Validate(); err != nil { return fmt.Errorf("invalid config: %w", err) } @@ -1188,7 +1188,7 @@ func runDryRun(ctx context.Context, client forge.Client, printer *ui.Printer, or } // Build config with empty agents for analysis. - cfg := config.NewOrgConfig(repoNames, enabledRepos, roles, nil, inferenceProviderName) + cfg := config.NewOrgConfig(repoNames, enabledRepos, roles, nil, inferenceProviderName, org) cfg.Dispatch.Mode = "oidc-mint" user, err := client.GetAuthenticatedUser(ctx) @@ -1524,7 +1524,7 @@ func runInstall(ctx context.Context, client forge.Client, printer *ui.Printer, o agents[i] = ac.AgentEntry } - cfg := config.NewOrgConfig(repoNames, enabledRepos, roles, agents, inferenceProviderName) + cfg := config.NewOrgConfig(repoNames, enabledRepos, roles, agents, inferenceProviderName, org) cfg.Dispatch.Mode = "oidc-mint" user, err := client.GetAuthenticatedUser(ctx) @@ -1663,7 +1663,8 @@ func runUninstall(ctx context.Context, client forge.Client, printer *ui.Printer, } // Build a minimal stack for uninstall. - emptyCfg := config.NewOrgConfig(nil, nil, nil, nil, "") + // Only ConfigRepoLayer matters for uninstall since other layers are no-ops. + emptyCfg := config.NewOrgConfig(nil, nil, nil, nil, "", "") stack := layers.NewStack( layers.NewConfigRepoLayer(org, client, emptyCfg, printer, false), layers.NewWorkflowsLayer(org, client, printer, "", version), @@ -1804,7 +1805,7 @@ func runAnalyze(ctx context.Context, client forge.Client, printer *ui.Printer, o }) } - cfg := config.NewOrgConfig(repoNames, nil, defaultRoles, nil, "") + cfg := config.NewOrgConfig(repoNames, nil, defaultRoles, nil, "", org) user, err := client.GetAuthenticatedUser(ctx) if err != nil { diff --git a/internal/cli/admin_test.go b/internal/cli/admin_test.go index 3363b574f..14deaa012 100644 --- a/internal/cli/admin_test.go +++ b/internal/cli/admin_test.go @@ -580,7 +580,7 @@ func setupTestConfig(repos map[string]bool) *config.OrgConfig { // Sort to ensure deterministic order despite map iteration being non-deterministic. sort.Strings(repoNames) sort.Strings(enabledRepos) - return config.NewOrgConfig(repoNames, enabledRepos, []string{"triage"}, nil, "") + return config.NewOrgConfig(repoNames, enabledRepos, []string{"triage"}, nil, "", "") } func setupTestClient(org string, cfg *config.OrgConfig, orgRepos []string) *forge.FakeClient { @@ -1085,6 +1085,7 @@ func TestBuildLayerStack_NilEnabledRepos_SkipsDisabledRepos(t *testing.T) { []string{"triage"}, nil, "", + "", ) printer := ui.New(&discardWriter{}) @@ -1127,6 +1128,7 @@ func TestBuildLayerStack_EmptyEnabledRepos_IncludesDisabledRepos(t *testing.T) { []string{"triage"}, nil, "", + "", ) printer := ui.New(&discardWriter{}) diff --git a/internal/cli/github.go b/internal/cli/github.go index 2dd31b06a..bfc475199 100644 --- a/internal/cli/github.go +++ b/internal/cli/github.go @@ -207,7 +207,7 @@ func runGitHubSetupPerRepo(ctx context.Context, client forge.Client, printer *ui printer.StepInfo("Reusing existing FULLSEND_GCP_WIF_PROVIDER from " + cfg.target) } - perRepoCfg := config.NewPerRepoConfig(roles) + perRepoCfg := config.NewPerRepoConfig(roles, cfg.target) if err := perRepoCfg.Validate(); err != nil { return fmt.Errorf("invalid config: %w", err) } @@ -434,7 +434,7 @@ func runGitHubSetupPerOrg(ctx context.Context, client forge.Client, printer *ui. for i, ac := range agentCreds { dummyAgents[i] = ac.AgentEntry } - orgCfg := config.NewOrgConfig(repoNames, enabledRepos, roles, dummyAgents, inferenceProviderName) + orgCfg := config.NewOrgConfig(repoNames, enabledRepos, roles, dummyAgents, inferenceProviderName, org) orgCfg.Dispatch.Mode = "oidc-mint" user, err := client.GetAuthenticatedUser(ctx) @@ -483,7 +483,7 @@ func runGitHubSetupPerOrg(ctx context.Context, client forge.Client, printer *ui. for i, ac := range agentCreds { agents[i] = ac.AgentEntry } - orgCfg = config.NewOrgConfig(repoNames, enabledRepos, roles, agents, inferenceProviderName) + orgCfg = config.NewOrgConfig(repoNames, enabledRepos, roles, agents, inferenceProviderName, org) orgCfg.Dispatch.Mode = "oidc-mint" stack = buildLayerStack(org, client, orgCfg, printer, user, privateRepo, enabledRepos, agentCreds, enrolledRepoIDs, inferenceProvider, cfg.vendorBinary, vendorFn, dispatcher, commitSHA) diff --git a/internal/cli/github_test.go b/internal/cli/github_test.go index 105f588dc..99804e2c9 100644 --- a/internal/cli/github_test.go +++ b/internal/cli/github_test.go @@ -392,7 +392,7 @@ func TestRunGitHubStatus_BasicReport(t *testing.T) { client.Repos = []forge.Repository{ {Name: ".fullsend", FullName: "acme/.fullsend"}, } - cfg := config.NewOrgConfig([]string{"widget"}, []string{"widget"}, []string{"triage"}, nil, "") + cfg := config.NewOrgConfig([]string{"widget"}, []string{"widget"}, []string{"triage"}, nil, "", "") cfgData, _ := cfg.Marshal() client.FileContents["acme/.fullsend/config.yaml"] = cfgData client.OrgVariables = map[string]bool{"acme/FULLSEND_MINT_URL": true} diff --git a/internal/cli/mint.go b/internal/cli/mint.go index 6588bf5e1..7c7808d4b 100644 --- a/internal/cli/mint.go +++ b/internal/cli/mint.go @@ -40,9 +40,10 @@ func defaultMintRoles() []string { } // roleAlias maps role aliases to their canonical names. -// The fix role reuses the coder app — same PEM, same app ID. +// The code and fix roles both reuse the coder app — same PEM, same app ID. var roleAlias = map[string]string{ - "fix": "coder", + "code": "coder", + "fix": "coder", } // resolveRole returns the canonical role name, resolving aliases. diff --git a/internal/cli/mint_test.go b/internal/cli/mint_test.go index 9652e2418..7f009aa9e 100644 --- a/internal/cli/mint_test.go +++ b/internal/cli/mint_test.go @@ -588,6 +588,7 @@ func TestMintStatusCmd_TooManyArgs(t *testing.T) { // --- role aliasing tests --- func TestResolveRole(t *testing.T) { + assert.Equal(t, "coder", resolveRole("code")) assert.Equal(t, "coder", resolveRole("fix")) assert.Equal(t, "coder", resolveRole("coder")) assert.Equal(t, "triage", resolveRole("triage")) diff --git a/internal/cli/qf_reconcilestatus_test.go b/internal/cli/qf_reconcilestatus_test.go new file mode 100644 index 000000000..2478d48e1 --- /dev/null +++ b/internal/cli/qf_reconcilestatus_test.go @@ -0,0 +1,111 @@ +package cli + +// QualityFlow generated tests for GH-72 +// Suite: TS-GH72-007 — Reconcile-status command mint-url authentication +// STD: outputs/std/GH-72/GH-72_test_description.yaml + +import ( + "net/http" + "net/http/httptest" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/fullsend-ai/fullsend/internal/forge" + gh "github.com/fullsend-ai/fullsend/internal/forge/github" +) + +// TC-GH72-040: Mint-url flag and role flags exist on reconcilestatus command +func TestQFNewReconcileStatusCmd_MintURLFlags(t *testing.T) { + cmd := newReconcileStatusCmd() + + for _, name := range []string{"mint-url", "role"} { + f := cmd.Flags().Lookup(name) + require.NotNil(t, f, "flag %q should exist", name) + } + + mintURL := cmd.Flags().Lookup("mint-url") + assert.Equal(t, "", mintURL.DefValue, "mint-url should default to empty") + + role := cmd.Flags().Lookup("role") + assert.Equal(t, "", role.DefValue, "role should default to empty") +} + +// TC-GH72-041: FULLSEND_MINT_URL env var fallback when --mint-url not provided +func TestQFNewReconcileStatusCmd_MintURLFromEnv(t *testing.T) { + t.Setenv("FULLSEND_MINT_URL", "https://mint.example.com") + + cmd := newReconcileStatusCmd() + cmd.SetArgs([]string{"--repo", "org/repo", "--number", "7", "--run-id", "run-1", "--role", "review"}) + err := cmd.Execute() + // Will fail at OIDC exchange (no ACTIONS_ID_TOKEN_REQUEST_URL), + // but proves the env var was picked up and --role validation passed. + require.Error(t, err) + assert.Contains(t, err.Error(), "minting status token", + "error proves env var was picked up for token minting") +} + +// TC-GH72-042: Error when --role missing with --mint-url +func TestQFNewReconcileStatusCmd_ValidationErrors_MintURLWithoutRole(t *testing.T) { + cmd := newReconcileStatusCmd() + cmd.SetArgs([]string{ + "--repo", "org/repo", + "--number", "7", + "--run-id", "run-1", + "--mint-url", "https://mint.example.com", + }) + + err := cmd.Execute() + require.Error(t, err) + assert.Contains(t, err.Error(), "--role is required when using --mint-url", + "should produce clear validation error") +} + +// TC-GH72-043: Deprecated --token flag still works for backward compatibility +func TestQFNewReconcileStatusCmd_DeprecatedTokenExecution(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("[]")) + })) + defer srv.Close() + + origNew := newForgeClient + newForgeClient = func(token string) forge.Client { + return gh.New(token).WithBaseURL(srv.URL) + } + defer func() { newForgeClient = origNew }() + + t.Setenv("FULLSEND_MINT_URL", "") + + cmd := newReconcileStatusCmd() + cmd.SetArgs([]string{ + "--repo", "org/repo", + "--number", "7", + "--run-id", "run-1", + "--token", "test-token", + }) + + err := cmd.Execute() + require.NoError(t, err, "deprecated --token flag should still function") + + f := cmd.Flags().Lookup("token") + assert.NotEmpty(t, f.Deprecated, "--token flag should be marked as deprecated") +} + +// TC-GH72-044: Error when neither --mint-url nor --token provided +func TestQFNewReconcileStatusCmd_ValidationErrors_MissingMintURL(t *testing.T) { + t.Setenv("FULLSEND_MINT_URL", "") + + cmd := newReconcileStatusCmd() + cmd.SetArgs([]string{ + "--repo", "org/repo", + "--number", "7", + "--run-id", "run-1", + }) + + err := cmd.Execute() + require.Error(t, err) + assert.Contains(t, err.Error(), "--mint-url or FULLSEND_MINT_URL required", + "should fail with clear authentication error") +} diff --git a/internal/cli/qf_run_test.go b/internal/cli/qf_run_test.go new file mode 100644 index 000000000..15be1bfed --- /dev/null +++ b/internal/cli/qf_run_test.go @@ -0,0 +1,114 @@ +package cli + +// QualityFlow generated tests for GH-72 +// Suite: TS-GH72-008 — Run command mint-url for status comment authentication +// STD: outputs/std/GH-72/GH-72_test_description.yaml + +import ( + "io" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/fullsend-ai/fullsend/internal/ui" +) + +// TC-GH72-045: Client factory set from --mint-url flag +func TestQFSetupStatusNotifier_MintURL(t *testing.T) { + tmpDir := t.TempDir() + printer := ui.New(io.Discard) + + sOpts := statusOpts{ + statusRepo: "org/repo", + statusNum: 7, + mintURL: "https://mint.example.com", + } + + t.Setenv("GITHUB_RUN_ID", "run-42") + + n, err := setupStatusNotifier(tmpDir, "review", sOpts, printer) + require.NoError(t, err) + assert.NotNil(t, n) + assert.True(t, n.HasClientFactory(), + "client factory should be set when mint URL provided") +} + +// TC-GH72-046: FULLSEND_MINT_URL env var picked up by run command +func TestQFSetupStatusNotifier_MintURLFromEnv(t *testing.T) { + tmpDir := t.TempDir() + printer := ui.New(io.Discard) + + sOpts := statusOpts{ + statusRepo: "org/repo", + statusNum: 7, + } + + t.Setenv("FULLSEND_MINT_URL", "https://mint.example.com") + t.Setenv("GITHUB_RUN_ID", "run-42") + + n, err := setupStatusNotifier(tmpDir, "code", sOpts, printer) + require.NoError(t, err) + assert.NotNil(t, n) + assert.True(t, n.HasClientFactory(), + "client factory should be set from FULLSEND_MINT_URL env var") +} + +// TC-GH72-047: Error when no mint-url or token available +func TestQFSetupStatusNotifier_NoMintURL(t *testing.T) { + tmpDir := t.TempDir() + printer := ui.New(io.Discard) + + sOpts := statusOpts{ + statusRepo: "org/repo", + statusNum: 7, + } + + t.Setenv("GITHUB_RUN_ID", "run-42") + t.Setenv("FULLSEND_MINT_URL", "") + t.Setenv("GITHUB_TOKEN", "") + + _, err := setupStatusNotifier(tmpDir, "review", sOpts, printer) + require.Error(t, err) + assert.Contains(t, err.Error(), "no mint URL available", + "should error when neither mint URL nor token available") +} + +// TC-GH72-048: Deprecated static token creates client directly without factory +func TestQFSetupStatusNotifier_DeprecatedToken(t *testing.T) { + tmpDir := t.TempDir() + printer := ui.New(io.Discard) + + sOpts := statusOpts{ + statusRepo: "org/repo", + statusNum: 7, + statusToken: "test-static-token", + } + + t.Setenv("GITHUB_RUN_ID", "run-42") + t.Setenv("FULLSEND_MINT_URL", "") + + n, err := setupStatusNotifier(tmpDir, "code", sOpts, printer) + require.NoError(t, err) + assert.NotNil(t, n) + assert.False(t, n.HasClientFactory(), + "client factory should not be set when using deprecated static token") +} + +// TC-GH72-049: Run command has --mint-url flag +func TestQFRunCommand_HasMintURLFlag(t *testing.T) { + cmd := newRunCmd() + + f := cmd.Flags().Lookup("mint-url") + require.NotNil(t, f, "run command should have --mint-url flag") + assert.Equal(t, "", f.DefValue) +} + +// TC-GH72-050: Run command --status-token flag is marked deprecated +func TestQFRunCommand_StatusTokenFlagDeprecated(t *testing.T) { + cmd := newRunCmd() + + f := cmd.Flags().Lookup("status-token") + require.NotNil(t, f, "run command should have --status-token flag for backwards compatibility") + assert.NotEmpty(t, f.Deprecated, "--status-token flag should be marked deprecated") +} diff --git a/internal/cli/reconcilestatus.go b/internal/cli/reconcilestatus.go index 3e3b78653..c636fff82 100644 --- a/internal/cli/reconcilestatus.go +++ b/internal/cli/reconcilestatus.go @@ -7,19 +7,27 @@ import ( "github.com/spf13/cobra" + "github.com/fullsend-ai/fullsend/internal/forge" gh "github.com/fullsend-ai/fullsend/internal/forge/github" + "github.com/fullsend-ai/fullsend/internal/mintclient" "github.com/fullsend-ai/fullsend/internal/statuscomment" ) +var newForgeClient = func(token string) forge.Client { + return gh.New(token) +} + func newReconcileStatusCmd() *cobra.Command { var ( - repo string - number int - runID string - runURL string - sha string - token string - reason string + repo string + number int + runID string + runURL string + sha string + reason string + mintURL string + role string + token string // deprecated: use mintURL ) cmd := &cobra.Command{ @@ -35,13 +43,6 @@ terminal tag (). If found, updates it to an "Interrupted" state and adds the terminal tag. If already finalized, this is a no-op.`, RunE: func(cmd *cobra.Command, args []string) error { - if token == "" { - token = os.Getenv("GITHUB_TOKEN") - } - if token == "" { - return fmt.Errorf("--token or GITHUB_TOKEN required") - } - if number <= 0 { return fmt.Errorf("--number must be a positive integer, got %d", number) } @@ -52,6 +53,34 @@ finalized, this is a no-op.`, } owner, repoName := parts[0], parts[1] + if mintURL == "" { + mintURL = os.Getenv("FULLSEND_MINT_URL") + } + + var client forge.Client + if mintURL != "" { + if role == "" { + return fmt.Errorf("--role is required when using --mint-url") + } + result, err := mintclient.MintToken(cmd.Context(), mintclient.MintRequest{ + MintURL: mintURL, + Role: resolveRole(role), + Repos: []string{repoName}, + }) + if err != nil { + return fmt.Errorf("minting status token: %w", err) + } + if os.Getenv("GITHUB_ACTIONS") == "true" && mintTokenPattern.MatchString(result.Token) { + fmt.Fprintf(os.Stderr, "::add-mask::%s\n", result.Token) + } + client = newForgeClient(result.Token) + } else if token != "" { + fmt.Fprintf(os.Stderr, "WARNING: --token is deprecated; use --mint-url instead\n") + client = newForgeClient(token) + } else { + return fmt.Errorf("--mint-url or FULLSEND_MINT_URL required (--token is deprecated)") + } + var termReason statuscomment.TerminationReason switch reason { case "cancelled": @@ -59,8 +88,6 @@ finalized, this is a no-op.`, default: termReason = statuscomment.ReasonTerminated } - - client := gh.New(token) return statuscomment.ReconcileOrphaned(cmd.Context(), client, owner, repoName, number, runID, runURL, sha, termReason) }, } @@ -70,8 +97,12 @@ finalized, this is a no-op.`, cmd.Flags().StringVar(&runID, "run-id", "", "workflow run ID used in the status comment marker (required)") cmd.Flags().StringVar(&runURL, "run-url", "", "URL to the workflow run (optional)") cmd.Flags().StringVar(&sha, "sha", "", "commit SHA (optional, shown as short hash)") - cmd.Flags().StringVar(&token, "token", "", "GitHub token (default: $GITHUB_TOKEN)") cmd.Flags().StringVar(&reason, "reason", "terminated", "termination reason: terminated or cancelled") + cmd.Flags().StringVar(&mintURL, "mint-url", "", "mint service URL for on-demand token (default: $FULLSEND_MINT_URL)") + cmd.Flags().StringVar(&role, "role", "", "agent role for minting (required with --mint-url)") + cmd.Flags().StringVar(&token, "token", "", "DEPRECATED: use --mint-url instead") + _ = cmd.Flags().MarkDeprecated("token", "use --mint-url instead") + _ = cmd.Flags().MarkHidden("token") _ = cmd.MarkFlagRequired("repo") _ = cmd.MarkFlagRequired("number") _ = cmd.MarkFlagRequired("run-id") diff --git a/internal/cli/reconcilestatus_test.go b/internal/cli/reconcilestatus_test.go index 93875cedd..5c201dfa4 100644 --- a/internal/cli/reconcilestatus_test.go +++ b/internal/cli/reconcilestatus_test.go @@ -1,10 +1,15 @@ package cli import ( + "net/http" + "net/http/httptest" "testing" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + + "github.com/fullsend-ai/fullsend/internal/forge" + gh "github.com/fullsend-ai/fullsend/internal/forge/github" ) func TestNewReconcileStatusCmd_RequiredFlags(t *testing.T) { @@ -31,20 +36,25 @@ func TestNewReconcileStatusCmd_ValidationErrors(t *testing.T) { wantErr string }{ { - name: "missing token", + name: "missing mint-url", args: []string{"--repo", "org/repo", "--number", "7", "--run-id", "run-1"}, - wantErr: "--token or GITHUB_TOKEN required", + wantErr: "--mint-url or FULLSEND_MINT_URL required", }, { name: "invalid number", - args: []string{"--repo", "org/repo", "--number", "0", "--run-id", "run-1", "--token", "tok"}, + args: []string{"--repo", "org/repo", "--number", "0", "--run-id", "run-1"}, wantErr: "--number must be a positive integer", }, { name: "invalid repo format", - args: []string{"--repo", "noslash", "--number", "7", "--run-id", "run-1", "--token", "tok"}, + args: []string{"--repo", "noslash", "--number", "7", "--run-id", "run-1"}, wantErr: "--repo must be in owner/repo format", }, + { + name: "mint-url without role", + args: []string{"--repo", "org/repo", "--number", "7", "--run-id", "run-1", "--mint-url", "https://mint.example.com"}, + wantErr: "--role is required when using --mint-url", + }, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { @@ -56,3 +66,92 @@ func TestNewReconcileStatusCmd_ValidationErrors(t *testing.T) { }) } } + +func TestNewReconcileStatusCmd_MintURLFlags(t *testing.T) { + cmd := newReconcileStatusCmd() + + for _, name := range []string{"mint-url", "role"} { + f := cmd.Flags().Lookup(name) + require.NotNil(t, f, "flag %q should exist", name) + } + + mintURL := cmd.Flags().Lookup("mint-url") + assert.Equal(t, "", mintURL.DefValue) + + role := cmd.Flags().Lookup("role") + assert.Equal(t, "", role.DefValue) +} + +func TestNewReconcileStatusCmd_MintURLFromEnv(t *testing.T) { + t.Setenv("FULLSEND_MINT_URL", "https://mint.example.com") + + cmd := newReconcileStatusCmd() + cmd.SetArgs([]string{"--repo", "org/repo", "--number", "7", "--run-id", "run-1", "--role", "review"}) + err := cmd.Execute() + // Will fail at the OIDC exchange (no ACTIONS_ID_TOKEN_REQUEST_URL), but + // proves the env var was picked up and --role validation passed. + require.Error(t, err) + assert.Contains(t, err.Error(), "minting status token") +} + +func TestNewReconcileStatusCmd_TokenFlagDeprecated(t *testing.T) { + cmd := newReconcileStatusCmd() + f := cmd.Flags().Lookup("token") + require.NotNil(t, f, "--token flag should exist for backwards compatibility") + assert.NotEmpty(t, f.Deprecated, "--token flag should be marked deprecated") +} + +func TestNewReconcileStatusCmd_DeprecatedTokenExecution(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("[]")) + })) + defer srv.Close() + + origNew := newForgeClient + newForgeClient = func(token string) forge.Client { + return gh.New(token).WithBaseURL(srv.URL) + } + defer func() { newForgeClient = origNew }() + + t.Setenv("FULLSEND_MINT_URL", "") + + cmd := newReconcileStatusCmd() + cmd.SetArgs([]string{ + "--repo", "org/repo", + "--number", "7", + "--run-id", "run-1", + "--token", "test-token", + }) + + err := cmd.Execute() + require.NoError(t, err) +} + +func TestNewReconcileStatusCmd_DeprecatedTokenCancelledReason(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("[]")) + })) + defer srv.Close() + + origNew := newForgeClient + newForgeClient = func(token string) forge.Client { + return gh.New(token).WithBaseURL(srv.URL) + } + defer func() { newForgeClient = origNew }() + + t.Setenv("FULLSEND_MINT_URL", "") + + cmd := newReconcileStatusCmd() + cmd.SetArgs([]string{ + "--repo", "org/repo", + "--number", "7", + "--run-id", "run-1", + "--reason", "cancelled", + "--token", "test-token", + }) + + err := cmd.Execute() + require.NoError(t, err) +} diff --git a/internal/cli/run.go b/internal/cli/run.go index a5ff8cd35..ad9d6153f 100644 --- a/internal/cli/run.go +++ b/internal/cli/run.go @@ -26,6 +26,7 @@ import ( gh "github.com/fullsend-ai/fullsend/internal/forge/github" "github.com/fullsend-ai/fullsend/internal/harness" "github.com/fullsend-ai/fullsend/internal/lock" + "github.com/fullsend-ai/fullsend/internal/mintclient" "github.com/fullsend-ai/fullsend/internal/resolve" agentruntime "github.com/fullsend-ai/fullsend/internal/runtime" "github.com/fullsend-ai/fullsend/internal/sandbox" @@ -63,7 +64,8 @@ type statusOpts struct { runURL string statusRepo string statusNum int - statusToken string + mintURL string + statusToken string // deprecated: use mintURL } func newRunCmd() *cobra.Command { @@ -107,7 +109,10 @@ func newRunCmd() *cobra.Command { cmd.Flags().StringVar(&sOpts.runURL, "run-url", "", "URL of the CI/CD run for status comments") cmd.Flags().StringVar(&sOpts.statusRepo, "status-repo", "", "repository (owner/repo) for status comments") cmd.Flags().IntVar(&sOpts.statusNum, "status-number", 0, "issue/PR number for status comments") - cmd.Flags().StringVar(&sOpts.statusToken, "status-token", "", "token for status comments (defaults to GH_TOKEN)") + cmd.Flags().StringVar(&sOpts.mintURL, "mint-url", "", "mint service URL for on-demand status tokens (default: $FULLSEND_MINT_URL)") + cmd.Flags().StringVar(&sOpts.statusToken, "status-token", "", "DEPRECATED: use --mint-url instead") + _ = cmd.Flags().MarkDeprecated("status-token", "use --mint-url instead") + _ = cmd.Flags().MarkHidden("status-token") _ = cmd.MarkFlagRequired("fullsend-dir") _ = cmd.MarkFlagRequired("target-repo") @@ -400,7 +405,7 @@ func runAgent(ctx context.Context, agentName, fullsendDir, outputBase, targetRep // post-script — and can report cancellation/failure even when the // sandbox never starts. See #1859. if sOpts.statusRepo != "" && sOpts.statusNum > 0 { - notifier, notifyErr := setupStatusNotifier(absFullsendDir, sOpts, printer) + notifier, notifyErr := setupStatusNotifier(absFullsendDir, agentName, sOpts, printer) if notifyErr != nil { printer.StepWarn("Status notifications disabled: " + notifyErr.Error()) } else { @@ -1840,19 +1845,22 @@ func titleCase(s string) string { return strings.Join(words, " ") } -func setupStatusNotifier(fullsendDir string, sOpts statusOpts, printer *ui.Printer) (*statuscomment.Notifier, error) { +func setupStatusNotifier(fullsendDir string, agentName string, sOpts statusOpts, printer *ui.Printer) (*statuscomment.Notifier, error) { parts := strings.SplitN(sOpts.statusRepo, "/", 2) if len(parts) != 2 { return nil, fmt.Errorf("--status-repo must be in owner/repo format, got %q", sOpts.statusRepo) } owner, repo := parts[0], parts[1] - token := sOpts.statusToken - if token == "" { - token = os.Getenv("GH_TOKEN") + mintURL := sOpts.mintURL + if mintURL == "" { + mintURL = os.Getenv("FULLSEND_MINT_URL") } - if token == "" { - return nil, fmt.Errorf("no status token available (set --status-token or GH_TOKEN)") + + staticToken := sOpts.statusToken + + if mintURL == "" && staticToken == "" { + return nil, fmt.Errorf("no mint URL available (set --mint-url or FULLSEND_MINT_URL)") } var notifyCfg config.StatusNotificationConfig @@ -1868,8 +1876,6 @@ func setupStatusNotifier(fullsendDir string, sOpts statusOpts, printer *ui.Print printer.StepWarn("Failed to read config.yaml for status notifications: " + err.Error()) } - client := gh.New(token) - sha := os.Getenv("GITHUB_SHA") // In cross-repo workflow_dispatch mode, GITHUB_SHA is the dispatching // repo's default branch HEAD — not the PR's head commit. Prefer the @@ -1882,10 +1888,34 @@ func setupStatusNotifier(fullsendDir string, sOpts statusOpts, printer *ui.Print runID = fmt.Sprintf("%d", time.Now().UnixNano()) } - n := statuscomment.New(client, notifyCfg, owner, repo, sOpts.statusNum, sOpts.runURL, sha, runID) + var initialClient forge.Client + if staticToken != "" { + initialClient = gh.New(staticToken) + } + + n := statuscomment.New(initialClient, notifyCfg, owner, repo, sOpts.statusNum, sOpts.runURL, sha, runID) n.SetWarnFunc(func(format string, args ...any) { printer.StepWarn(fmt.Sprintf(format, args...)) }) + + if mintURL != "" { + role := resolveRole(agentName) + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + result, err := mintclient.MintToken(ctx, mintclient.MintRequest{ + MintURL: mintURL, + Role: role, + Repos: []string{repo}, + }) + if err != nil { + return nil, fmt.Errorf("minting status token: %w", err) + } + if os.Getenv("GITHUB_ACTIONS") == "true" && mintTokenPattern.MatchString(result.Token) { + fmt.Fprintf(os.Stderr, "::add-mask::%s\n", result.Token) + } + return gh.New(result.Token), nil + }) + } + return n, nil } diff --git a/internal/cli/run_test.go b/internal/cli/run_test.go index 10fdb2a76..e939c9850 100644 --- a/internal/cli/run_test.go +++ b/internal/cli/run_test.go @@ -1311,7 +1311,6 @@ func TestSetupFetchService_ResolvesTokenWhenNoForgeClient(t *testing.T) { h := &harness.Harness{ Agent: "agents/test.md", AllowedRemoteResources: []string{"https://github.com/org/"}, - AllowRuntimeFetch: true, } tokenResolved := false @@ -1356,63 +1355,62 @@ func TestSetupFetchService_NoForgeClientNoRemoteResources(t *testing.T) { assert.NotEmpty(t, env.addr) } -func TestSetupFetchService_CustomMaxFetches(t *testing.T) { +func TestSetupFetchService_TokenResolutionFails(t *testing.T) { tmpDir := t.TempDir() - maxFetches := 50 h := &harness.Harness{ Agent: "agents/test.md", - AllowRuntimeFetch: true, AllowedRemoteResources: []string{"https://github.com/org/"}, - MaxRuntimeFetches: &maxFetches, - } - - cfg := fetchsvc.ServiceConfig{ - Harness: h, - WorkspaceRoot: tmpDir, - MaxFetches: h.EffectiveMaxRuntimeFetches(), } - assert.Equal(t, 50, cfg.MaxFetches) + var warned string env, shutdown, err := setupFetchService( context.Background(), nil, h, - func() (string, error) { return "ghp_test", nil }, - cfg, - func(string) {}, + func() (string, error) { return "", fmt.Errorf("no token available") }, + fetchsvc.ServiceConfig{ + Harness: h, + WorkspaceRoot: tmpDir, + MaxFetches: 10, + }, + func(msg string) { warned = msg }, ) require.NoError(t, err) defer shutdown() assert.NotEmpty(t, env.addr) + assert.Contains(t, warned, "no token available") } -func TestSetupFetchService_TokenResolutionFails(t *testing.T) { +func TestSetupFetchService_CustomMaxFetches(t *testing.T) { tmpDir := t.TempDir() + maxFetches := 50 h := &harness.Harness{ Agent: "agents/test.md", - AllowedRemoteResources: []string{"https://github.com/org/"}, AllowRuntimeFetch: true, + AllowedRemoteResources: []string{"https://github.com/org/"}, + MaxRuntimeFetches: &maxFetches, } - var warned string + cfg := fetchsvc.ServiceConfig{ + Harness: h, + WorkspaceRoot: tmpDir, + MaxFetches: h.EffectiveMaxRuntimeFetches(), + } + assert.Equal(t, 50, cfg.MaxFetches) + env, shutdown, err := setupFetchService( context.Background(), nil, h, - func() (string, error) { return "", fmt.Errorf("no token available") }, - fetchsvc.ServiceConfig{ - Harness: h, - WorkspaceRoot: tmpDir, - MaxFetches: 10, - }, - func(msg string) { warned = msg }, + func() (string, error) { return "ghp_test", nil }, + cfg, + func(string) {}, ) require.NoError(t, err) defer shutdown() assert.NotEmpty(t, env.addr) - assert.Contains(t, warned, "no token available") } func TestEffectiveMaxRuntimeFetches_MatchesFetchsvcDefault(t *testing.T) { @@ -1426,3 +1424,186 @@ func TestEffectiveMaxRuntimeFetches_MatchesFetchsvcDefault(t *testing.T) { type mockForgeClient struct { forge.Client } + +func TestSetupStatusNotifier_MintURL(t *testing.T) { + tmpDir := t.TempDir() + printer := ui.New(io.Discard) + + sOpts := statusOpts{ + statusRepo: "org/repo", + statusNum: 7, + mintURL: "https://mint.example.com", + } + + t.Setenv("GITHUB_RUN_ID", "run-42") + + n, err := setupStatusNotifier(tmpDir, "review", sOpts, printer) + require.NoError(t, err) + assert.NotNil(t, n) + assert.True(t, n.HasClientFactory(), "client factory should be set when mint URL provided") +} + +func TestSetupStatusNotifier_MintURLFromEnv(t *testing.T) { + tmpDir := t.TempDir() + printer := ui.New(io.Discard) + + sOpts := statusOpts{ + statusRepo: "org/repo", + statusNum: 7, + } + + t.Setenv("FULLSEND_MINT_URL", "https://mint.example.com") + t.Setenv("GITHUB_RUN_ID", "run-42") + + n, err := setupStatusNotifier(tmpDir, "code", sOpts, printer) + require.NoError(t, err) + assert.NotNil(t, n) + assert.True(t, n.HasClientFactory(), "client factory should be set from FULLSEND_MINT_URL env var") +} + +func TestSetupStatusNotifier_NoMintURL(t *testing.T) { + tmpDir := t.TempDir() + printer := ui.New(io.Discard) + + sOpts := statusOpts{ + statusRepo: "org/repo", + statusNum: 7, + } + + t.Setenv("GITHUB_RUN_ID", "run-42") + t.Setenv("FULLSEND_MINT_URL", "") + t.Setenv("GITHUB_TOKEN", "") + + _, err := setupStatusNotifier(tmpDir, "review", sOpts, printer) + require.Error(t, err) + assert.Contains(t, err.Error(), "no mint URL available") +} + +func TestSetupStatusNotifier_DeprecatedToken(t *testing.T) { + tmpDir := t.TempDir() + printer := ui.New(io.Discard) + + sOpts := statusOpts{ + statusRepo: "org/repo", + statusNum: 7, + statusToken: "test-static-token", + } + + t.Setenv("GITHUB_RUN_ID", "run-42") + t.Setenv("FULLSEND_MINT_URL", "") + + n, err := setupStatusNotifier(tmpDir, "code", sOpts, printer) + require.NoError(t, err) + assert.NotNil(t, n) + assert.False(t, n.HasClientFactory(), "client factory should not be set when using deprecated static token") +} + +func TestSetupStatusNotifier_InvalidRepo(t *testing.T) { + tmpDir := t.TempDir() + printer := ui.New(io.Discard) + + sOpts := statusOpts{ + statusRepo: "noslash", + statusNum: 7, + } + + _, err := setupStatusNotifier(tmpDir, "review", sOpts, printer) + require.Error(t, err) + assert.Contains(t, err.Error(), "--status-repo must be in owner/repo format") +} + +func TestRunCommand_HasMintURLFlag(t *testing.T) { + cmd := newRunCmd() + + f := cmd.Flags().Lookup("mint-url") + require.NotNil(t, f, "run command should have --mint-url flag") + assert.Equal(t, "", f.DefValue) +} + +func TestRunCommand_StatusTokenFlagDeprecated(t *testing.T) { + cmd := newRunCmd() + + f := cmd.Flags().Lookup("status-token") + require.NotNil(t, f, "run command should have --status-token flag for backwards compatibility") + assert.NotEmpty(t, f.Deprecated, "--status-token flag should be marked deprecated") +} + +func TestTitleCase(t *testing.T) { + tests := []struct { + in, want string + }{ + {"hello world", "Hello World"}, + {"code", "Code"}, + {"", ""}, + {"already Title", "Already Title"}, + } + for _, tt := range tests { + assert.Equal(t, tt.want, titleCase(tt.in)) + } +} + +func TestSetupStatusNotifier_ConfigYAML(t *testing.T) { + tmpDir := t.TempDir() + printer := ui.New(io.Discard) + + configData := `defaults: + status_notifications: + comment: + start: enabled + completion: disabled +` + require.NoError(t, os.WriteFile(filepath.Join(tmpDir, "config.yaml"), []byte(configData), 0o644)) + + sOpts := statusOpts{ + statusRepo: "org/repo", + statusNum: 7, + mintURL: "https://mint.example.com", + } + + t.Setenv("GITHUB_RUN_ID", "run-42") + + n, err := setupStatusNotifier(tmpDir, "review", sOpts, printer) + require.NoError(t, err) + assert.NotNil(t, n) +} + +func TestSetupStatusNotifier_RunIDFallback(t *testing.T) { + tmpDir := t.TempDir() + printer := ui.New(io.Discard) + + sOpts := statusOpts{ + statusRepo: "org/repo", + statusNum: 7, + statusToken: "test-static-token", + } + + t.Setenv("GITHUB_RUN_ID", "") + t.Setenv("FULLSEND_MINT_URL", "") + + n, err := setupStatusNotifier(tmpDir, "code", sOpts, printer) + require.NoError(t, err) + assert.NotNil(t, n) +} + +func TestSetupStatusNotifier_PRHeadSHA(t *testing.T) { + tmpDir := t.TempDir() + printer := ui.New(io.Discard) + + eventPayload := `{"inputs":{"event_payload":"{\"pull_request\":{\"head\":{\"sha\":\"abc123def456\"}}}"}}` + eventFile := filepath.Join(tmpDir, "event.json") + require.NoError(t, os.WriteFile(eventFile, []byte(eventPayload), 0o644)) + + sOpts := statusOpts{ + statusRepo: "org/repo", + statusNum: 7, + statusToken: "test-static-token", + } + + t.Setenv("GITHUB_EVENT_PATH", eventFile) + t.Setenv("GITHUB_RUN_ID", "run-42") + t.Setenv("FULLSEND_MINT_URL", "") + + n, err := setupStatusNotifier(tmpDir, "code", sOpts, printer) + require.NoError(t, err) + assert.NotNil(t, n) +} diff --git a/internal/config/config.go b/internal/config/config.go index 01340cb5d..276f3f802 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -58,6 +58,17 @@ type RepoConfig struct { Enabled bool `yaml:"enabled"` } +// AllowTargets defines which orgs and repos agents may create issues in. +type AllowTargets struct { + Orgs []string `yaml:"orgs,omitempty"` + Repos []string `yaml:"repos,omitempty"` +} + +// CreateIssuesConfig controls cross-repo issue creation by agents. +type CreateIssuesConfig struct { + AllowTargets AllowTargets `yaml:"allow_targets"` +} + // OrgConfig is the top-level configuration for a fullsend organization. type OrgConfig struct { Version string `yaml:"version"` @@ -68,6 +79,7 @@ type OrgConfig struct { Agents []AgentEntry `yaml:"agents"` Repos map[string]RepoConfig `yaml:"repos"` AllowedRemoteResources []string `yaml:"allowed_remote_resources,omitempty"` + CreateIssues *CreateIssuesConfig `yaml:"create_issues,omitempty"` } // ValidRoles returns the set of recognized agent roles. @@ -95,7 +107,7 @@ func PerRepoDefaultRoles() []string { } // NewOrgConfig creates a new OrgConfig with sensible defaults. -func NewOrgConfig(allRepos, enabledRepos, roles []string, agents []AgentEntry, inferenceProvider string) *OrgConfig { +func NewOrgConfig(allRepos, enabledRepos, roles []string, agents []AgentEntry, inferenceProvider, org string) *OrgConfig { repos := make(map[string]RepoConfig, len(allRepos)) for _, r := range allRepos { repos[r] = RepoConfig{ @@ -123,6 +135,14 @@ func NewOrgConfig(allRepos, enabledRepos, roles []string, agents []AgentEntry, i if inferenceProvider != "" { cfg.Inference = InferenceConfig{Provider: inferenceProvider} } + if org != "" { + cfg.CreateIssues = &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Orgs: []string{org}, + Repos: []string{"fullsend-ai/fullsend"}, + }, + } + } return cfg } @@ -184,6 +204,9 @@ func (c *OrgConfig) Validate() error { if err := validateStatusNotifications(c.Defaults.StatusNotifications); err != nil { return err } + if err := validateCreateIssues(c.CreateIssues); err != nil { + return err + } return nil } @@ -242,9 +265,10 @@ func (c *OrgConfig) DefaultRoles() []string { // PerRepoConfig holds configuration for per-repo installation mode. // Stored in .fullsend/config.yaml within the target repository. type PerRepoConfig struct { - Version string `yaml:"version"` - KillSwitch bool `yaml:"kill_switch,omitempty"` - Roles []string `yaml:"roles,omitempty"` + Version string `yaml:"version"` + KillSwitch bool `yaml:"kill_switch,omitempty"` + Roles []string `yaml:"roles,omitempty"` + CreateIssues *CreateIssuesConfig `yaml:"create_issues,omitempty"` } const perRepoConfigHeader = `# fullsend per-repo configuration @@ -255,14 +279,22 @@ const perRepoConfigHeader = `# fullsend per-repo configuration ` // NewPerRepoConfig creates a new PerRepoConfig with the given roles. -func NewPerRepoConfig(roles []string) *PerRepoConfig { +func NewPerRepoConfig(roles []string, targetRepo string) *PerRepoConfig { if roles == nil { roles = DefaultAgentRoles() } - return &PerRepoConfig{ + cfg := &PerRepoConfig{ Version: "1", Roles: roles, } + if targetRepo != "" { + cfg.CreateIssues = &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Repos: []string{targetRepo, "fullsend-ai/fullsend"}, + }, + } + } + return cfg } // ParsePerRepoConfig parses YAML bytes into a PerRepoConfig. @@ -299,5 +331,26 @@ func (c *PerRepoConfig) Validate() error { } seen[role] = true } + if err := validateCreateIssues(c.CreateIssues); err != nil { + return err + } + return nil +} + +func validateCreateIssues(cfg *CreateIssuesConfig) error { + if cfg == nil { + return nil + } + for _, org := range cfg.AllowTargets.Orgs { + if org == "" { + return fmt.Errorf("create_issues: empty org in allow_targets.orgs") + } + } + for _, repo := range cfg.AllowTargets.Repos { + parts := strings.SplitN(repo, "/", 2) + if len(parts) != 2 || parts[0] == "" || parts[1] == "" { + return fmt.Errorf("create_issues: repo %q in allow_targets.repos must contain owner/name", repo) + } + } return nil } diff --git a/internal/config/config_test.go b/internal/config/config_test.go index c1145ac40..a9ce98b57 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -41,7 +41,7 @@ func TestNewOrgConfig(t *testing.T) { {Role: "fullsend", Name: "test", Slug: "test-slug"}, } - cfg := NewOrgConfig(allRepos, enabledRepos, roles, agents, "") + cfg := NewOrgConfig(allRepos, enabledRepos, roles, agents, "", "") assert.Equal(t, "1", cfg.Version) assert.Equal(t, "github-actions", cfg.Dispatch.Platform) @@ -285,12 +285,12 @@ repos: } func TestNewOrgConfig_WithInferenceProvider(t *testing.T) { - cfg := NewOrgConfig(nil, nil, nil, nil, "vertex") + cfg := NewOrgConfig(nil, nil, nil, nil, "vertex", "") assert.Equal(t, "vertex", cfg.Inference.Provider) } func TestNewOrgConfig_WithoutInferenceProvider(t *testing.T) { - cfg := NewOrgConfig(nil, nil, nil, nil, "") + cfg := NewOrgConfig(nil, nil, nil, nil, "", "") assert.Empty(t, cfg.Inference.Provider) } @@ -447,7 +447,7 @@ func TestOrgConfigValidate_FixRole(t *testing.T) { } func TestNewOrgConfig_KillSwitchDefaultFalse(t *testing.T) { - cfg := NewOrgConfig(nil, nil, []string{"fullsend"}, nil, "") + cfg := NewOrgConfig(nil, nil, []string{"fullsend"}, nil, "", "") assert.False(t, cfg.KillSwitch) } @@ -563,14 +563,14 @@ func TestOrgConfigMarshal_WithDispatchMode(t *testing.T) { } func TestNewPerRepoConfig_DefaultRoles(t *testing.T) { - cfg := NewPerRepoConfig(nil) + cfg := NewPerRepoConfig(nil, "") assert.Equal(t, "1", cfg.Version) assert.Equal(t, DefaultAgentRoles(), cfg.Roles) assert.False(t, cfg.KillSwitch) } func TestNewPerRepoConfig_CustomRoles(t *testing.T) { - cfg := NewPerRepoConfig([]string{"triage", "review"}) + cfg := NewPerRepoConfig([]string{"triage", "review"}, "") assert.Equal(t, []string{"triage", "review"}, cfg.Roles) } @@ -666,7 +666,7 @@ func TestPerRepoConfigMarshal_KillSwitchOmitted(t *testing.T) { } func TestPerRepoConfig_RoundTrip(t *testing.T) { - original := NewPerRepoConfig([]string{"fullsend", "triage", "coder", "review", "fix"}) + original := NewPerRepoConfig([]string{"fullsend", "triage", "coder", "review", "fix"}, "") data, err := original.Marshal() require.NoError(t, err) @@ -881,3 +881,195 @@ func TestOrgConfigMarshal_WithoutStatusNotifications(t *testing.T) { require.NoError(t, err) assert.NotContains(t, string(data), "status_notifications") } + +// --- CreateIssues tests --- + +func TestOrgConfig_CreateIssues_ParseYAML(t *testing.T) { + yamlData := ` +version: "1" +dispatch: + platform: github-actions +defaults: + roles: + - fullsend + max_implementation_retries: 2 +agents: [] +repos: {} +create_issues: + allow_targets: + orgs: + - my-org + - other-org + repos: + - external-org/some-repo +` + cfg, err := ParseOrgConfig([]byte(yamlData)) + require.NoError(t, err) + require.NotNil(t, cfg.CreateIssues) + assert.Equal(t, []string{"my-org", "other-org"}, cfg.CreateIssues.AllowTargets.Orgs) + assert.Equal(t, []string{"external-org/some-repo"}, cfg.CreateIssues.AllowTargets.Repos) +} + +func TestOrgConfig_CreateIssues_OmittedWhenEmpty(t *testing.T) { + cfg := &OrgConfig{ + Version: "1", + Dispatch: DispatchConfig{Platform: "github-actions"}, + Defaults: RepoDefaults{ + Roles: []string{"fullsend"}, + MaxImplementationRetries: 2, + }, + Agents: []AgentEntry{}, + Repos: map[string]RepoConfig{}, + } + data, err := cfg.Marshal() + require.NoError(t, err) + assert.NotContains(t, string(data), "create_issues") +} + +func TestOrgConfig_CreateIssues_Marshal(t *testing.T) { + cfg := &OrgConfig{ + Version: "1", + Dispatch: DispatchConfig{Platform: "github-actions"}, + Defaults: RepoDefaults{ + Roles: []string{"fullsend"}, + MaxImplementationRetries: 2, + }, + Agents: []AgentEntry{}, + Repos: map[string]RepoConfig{}, + CreateIssues: &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Orgs: []string{"my-org"}, + Repos: []string{"other/repo"}, + }, + }, + } + data, err := cfg.Marshal() + require.NoError(t, err) + assert.Contains(t, string(data), "create_issues:") + assert.Contains(t, string(data), "allow_targets:") + assert.Contains(t, string(data), "my-org") + assert.Contains(t, string(data), "other/repo") +} + +func TestOrgConfigValidate_CreateIssues_InvalidRepoFormat(t *testing.T) { + cfg := &OrgConfig{ + Version: "1", + Dispatch: DispatchConfig{Platform: "github-actions"}, + Defaults: RepoDefaults{ + Roles: []string{"fullsend"}, + MaxImplementationRetries: 2, + }, + CreateIssues: &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Repos: []string{"no-slash-here"}, + }, + }, + } + err := cfg.Validate() + assert.Error(t, err) + assert.Contains(t, err.Error(), "no-slash-here") +} + +func TestOrgConfigValidate_CreateIssues_MalformedRepoFormat(t *testing.T) { + malformed := []string{"/", "/repo", "owner/", "//"} + for _, repo := range malformed { + cfg := &OrgConfig{ + Version: "1", + Dispatch: DispatchConfig{Platform: "github-actions"}, + Defaults: RepoDefaults{ + Roles: []string{"fullsend"}, + MaxImplementationRetries: 2, + }, + CreateIssues: &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Repos: []string{repo}, + }, + }, + } + err := cfg.Validate() + assert.Error(t, err, "expected error for repo %q", repo) + assert.Contains(t, err.Error(), "owner/name", "expected owner/name message for repo %q", repo) + } +} + +func TestOrgConfigValidate_CreateIssues_EmptyOrg(t *testing.T) { + cfg := &OrgConfig{ + Version: "1", + Dispatch: DispatchConfig{Platform: "github-actions"}, + Defaults: RepoDefaults{ + Roles: []string{"fullsend"}, + MaxImplementationRetries: 2, + }, + CreateIssues: &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Orgs: []string{"valid-org", ""}, + }, + }, + } + err := cfg.Validate() + assert.Error(t, err) + assert.Contains(t, err.Error(), "empty org") +} + +func TestOrgConfigValidate_CreateIssues_Valid(t *testing.T) { + cfg := &OrgConfig{ + Version: "1", + Dispatch: DispatchConfig{Platform: "github-actions"}, + Defaults: RepoDefaults{ + Roles: []string{"fullsend"}, + MaxImplementationRetries: 2, + }, + CreateIssues: &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Orgs: []string{"my-org"}, + Repos: []string{"other/repo"}, + }, + }, + } + err := cfg.Validate() + assert.NoError(t, err) +} + +func TestOrgConfigValidate_CreateIssues_Nil(t *testing.T) { + cfg := &OrgConfig{ + Version: "1", + Dispatch: DispatchConfig{Platform: "github-actions"}, + Defaults: RepoDefaults{ + Roles: []string{"fullsend"}, + MaxImplementationRetries: 2, + }, + } + err := cfg.Validate() + assert.NoError(t, err) +} + +func TestNewOrgConfig_CreateIssuesDefaults(t *testing.T) { + cfg := NewOrgConfig(nil, nil, []string{"fullsend"}, nil, "", "my-org") + require.NotNil(t, cfg.CreateIssues) + assert.Equal(t, []string{"my-org"}, cfg.CreateIssues.AllowTargets.Orgs) + assert.Equal(t, []string{"fullsend-ai/fullsend"}, cfg.CreateIssues.AllowTargets.Repos) +} + +func TestPerRepoConfig_CreateIssues_ParseYAML(t *testing.T) { + yamlData := ` +version: "1" +roles: + - fullsend + - triage +create_issues: + allow_targets: + repos: + - my-org/my-repo + - fullsend-ai/fullsend +` + cfg, err := ParsePerRepoConfig([]byte(yamlData)) + require.NoError(t, err) + require.NotNil(t, cfg.CreateIssues) + assert.Equal(t, []string{"my-org/my-repo", "fullsend-ai/fullsend"}, cfg.CreateIssues.AllowTargets.Repos) +} + +func TestNewPerRepoConfig_CreateIssuesDefaults(t *testing.T) { + cfg := NewPerRepoConfig(nil, "my-org/my-repo") + require.NotNil(t, cfg.CreateIssues) + assert.Equal(t, []string{"my-org/my-repo", "fullsend-ai/fullsend"}, cfg.CreateIssues.AllowTargets.Repos) +} diff --git a/internal/config/qf_config_test.go b/internal/config/qf_config_test.go new file mode 100644 index 000000000..2793267c8 --- /dev/null +++ b/internal/config/qf_config_test.go @@ -0,0 +1,46 @@ +package config + +// QualityFlow generated tests for GH-72 +// Suite: TS-GH72-006 — Config types for triage prerequisites +// STD: outputs/std/GH-72/GH-72_test_description.yaml + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TC-GH72-037: AllowTargets YAML parsing and defaults — nil config passes validation +func TestQFValidateCreateIssues_NilConfig(t *testing.T) { + err := validateCreateIssues(nil) + require.NoError(t, err, "nil CreateIssuesConfig should pass validation") +} + +// TC-GH72-038: Validation rejects invalid repo format +func TestQFValidateCreateIssues_InvalidRepoFormat(t *testing.T) { + cfg := &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Repos: []string{"invalid-format"}, + }, + } + + err := validateCreateIssues(cfg) + require.Error(t, err) + assert.Contains(t, err.Error(), "must contain owner/name", + "error should identify the problematic repo format") +} + +// TC-GH72-039: Validation rejects empty org +func TestQFValidateCreateIssues_EmptyOrg(t *testing.T) { + cfg := &CreateIssuesConfig{ + AllowTargets: AllowTargets{ + Orgs: []string{""}, + }, + } + + err := validateCreateIssues(cfg) + require.Error(t, err) + assert.Contains(t, err.Error(), "empty org", + "error should catch empty org entries") +} diff --git a/internal/forge/fake.go b/internal/forge/fake.go index 2b9863277..8eb540945 100644 --- a/internal/forge/fake.go +++ b/internal/forge/fake.go @@ -400,6 +400,24 @@ func (f *FakeClient) DeleteFile(_ context.Context, owner, repo, path, message st return nil } +func (f *FakeClient) ListRepositoryFiles(_ context.Context, owner, repo string) ([]string, error) { + f.mu.Lock() + defer f.mu.Unlock() + + if e := f.err("ListRepositoryFiles"); e != nil { + return nil, e + } + + prefix := owner + "/" + repo + "/" + var paths []string + for key := range f.FileContents { + if len(key) > len(prefix) && key[:len(prefix)] == prefix { + paths = append(paths, key[len(prefix):]) + } + } + return paths, nil +} + func (f *FakeClient) ListDirectoryContents(_ context.Context, owner, repo, path, ref string, _ bool) ([]DirectoryEntry, error) { f.mu.Lock() defer f.mu.Unlock() diff --git a/internal/forge/fake_test.go b/internal/forge/fake_test.go index 42bdf4ac6..ab7a90ef1 100644 --- a/internal/forge/fake_test.go +++ b/internal/forge/fake_test.go @@ -471,6 +471,10 @@ func TestFakeClient_ErrorInjection(t *testing.T) { _, err := fc.ListDirectoryContents(ctx, "o", "r", "p", "main", false) return err }}, + {"ListRepositoryFiles", func(fc *FakeClient) error { + _, err := fc.ListRepositoryFiles(ctx, "o", "r") + return err + }}, {"GetFileContentAtRef", func(fc *FakeClient) error { _, err := fc.GetFileContentAtRef(ctx, "o", "r", "p", "main") return err @@ -544,6 +548,7 @@ func TestFakeClient_ThreadSafety(t *testing.T) { _, _ = fc.GetOrgVariableRepos(ctx, "o", "n") _ = fc.DeleteIssueComment(ctx, "o", "r", 1) _, _ = fc.ListDirectoryContents(ctx, "o", "r", "p", "main", false) + _, _ = fc.ListRepositoryFiles(ctx, "o", "r") _, _ = fc.GetFileContentAtRef(ctx, "o", "r", "p", "main") }(i) } diff --git a/internal/forge/forge.go b/internal/forge/forge.go index b6b295aca..e994b33ad 100644 --- a/internal/forge/forge.go +++ b/internal/forge/forge.go @@ -192,6 +192,12 @@ type Client interface { // Returns forge.ErrNotFound if the path does not exist or is not a directory. ListDirectoryContents(ctx context.Context, owner, repo, path, ref string, recursive bool) ([]DirectoryEntry, error) + // ListRepositoryFiles returns all file paths in the repository's default + // branch using the Git Trees API. This retrieves the entire tree in a + // single API call, making it efficient for batch path-existence checks. + // Returns ErrNotFound if the repository does not exist. + ListRepositoryFiles(ctx context.Context, owner, repo string) ([]string, error) + // GetFileContentAtRef retrieves the content of a file at a specific ref // (commit SHA, branch, or tag). Unlike GetFileContent which reads from // the default branch, this reads from the specified ref. diff --git a/internal/forge/github/github.go b/internal/forge/github/github.go index b110b55c3..587c59b23 100644 --- a/internal/forge/github/github.go +++ b/internal/forge/github/github.go @@ -952,6 +952,84 @@ func (c *LiveClient) listDirContents(ctx context.Context, owner, repo, path, ref return result, nil } +// ListRepositoryFiles returns all file paths in the default branch using +// the Git Trees API (single recursive call). +func (c *LiveClient) ListRepositoryFiles(ctx context.Context, owner, repo string) ([]string, error) { + // 1. Get default branch. + repoResp, err := c.get(ctx, fmt.Sprintf("/repos/%s/%s", owner, repo)) + if err != nil { + return nil, fmt.Errorf("get repo: %w", err) + } + var repoInfo struct { + DefaultBranch string `json:"default_branch"` + } + if err := decodeJSON(repoResp, &repoInfo); err != nil { + return nil, fmt.Errorf("decode repo info: %w", err) + } + + // 2. Get branch ref → commit SHA. + var commitSHA string + if err := c.retryOnTransient(ctx, "get branch ref", func() error { + refResp, refErr := c.get(ctx, fmt.Sprintf("/repos/%s/%s/git/ref/heads/%s", owner, repo, repoInfo.DefaultBranch)) + if refErr != nil { + return fmt.Errorf("get branch ref: %w", refErr) + } + var ref struct { + Object struct { + SHA string `json:"sha"` + } `json:"object"` + } + if decErr := decodeJSON(refResp, &ref); decErr != nil { + return fmt.Errorf("decode ref: %w", decErr) + } + commitSHA = ref.Object.SHA + return nil + }); err != nil { + return nil, err + } + + // 3. Get commit → tree SHA. + cResp, err := c.get(ctx, fmt.Sprintf("/repos/%s/%s/git/commits/%s", owner, repo, commitSHA)) + if err != nil { + return nil, fmt.Errorf("get commit: %w", err) + } + var commitObj struct { + Tree struct { + SHA string `json:"sha"` + } `json:"tree"` + } + if err := decodeJSON(cResp, &commitObj); err != nil { + return nil, fmt.Errorf("decode commit: %w", err) + } + + // 4. Get recursive tree → file paths. + treeResp, err := c.get(ctx, fmt.Sprintf("/repos/%s/%s/git/trees/%s?recursive=1", owner, repo, commitObj.Tree.SHA)) + if err != nil { + return nil, fmt.Errorf("get tree: %w", err) + } + var tree struct { + Tree []struct { + Path string `json:"path"` + Type string `json:"type"` // "blob" or "tree" + } `json:"tree"` + Truncated bool `json:"truncated"` + } + if err := decodeJSON(treeResp, &tree); err != nil { + return nil, fmt.Errorf("decode tree: %w", err) + } + if tree.Truncated { + return nil, fmt.Errorf("repository tree too large (truncated)") + } + + paths := make([]string, 0, len(tree.Tree)) + for _, entry := range tree.Tree { + if entry.Type == "blob" { + paths = append(paths, entry.Path) + } + } + return paths, nil +} + // DeleteFile deletes a file from the repository's default branch. // It first fetches the file to obtain its SHA (required by the GitHub Contents // API), then issues the DELETE. Retries on transient 404/409 errors. diff --git a/internal/forge/github/qf_github_test.go b/internal/forge/github/qf_github_test.go new file mode 100644 index 000000000..b225410c0 --- /dev/null +++ b/internal/forge/github/qf_github_test.go @@ -0,0 +1,71 @@ +package github + +// QualityFlow generated tests for GH-72 +// Suite: TS-GH72-009 — Git Trees API truncation error handling +// STD: outputs/std/GH-72/GH-72_test_description.yaml + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TC-GH72-051: ListRepositoryFiles returns error on truncated tree response +func TestQFListRepositoryFiles_Truncated(t *testing.T) { + callCount := 0 + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + callCount++ + w.Header().Set("Content-Type", "application/json") + + switch { + // Step 1: Get repo info (default branch) + case r.URL.Path == "/repos/org/large-repo": + json.NewEncoder(w).Encode(map[string]any{ + "default_branch": "main", + }) + + // Step 2: Get branch ref → commit SHA + case r.URL.Path == "/repos/org/large-repo/git/ref/heads/main": + json.NewEncoder(w).Encode(map[string]any{ + "object": map[string]any{ + "sha": "abc123", + }, + }) + + // Step 3: Get commit → tree SHA + case r.URL.Path == "/repos/org/large-repo/git/commits/abc123": + json.NewEncoder(w).Encode(map[string]any{ + "tree": map[string]any{ + "sha": "tree456", + }, + }) + + // Step 4: Get recursive tree — return truncated response + case r.URL.Path == "/repos/org/large-repo/git/trees/tree456": + json.NewEncoder(w).Encode(map[string]any{ + "tree": []map[string]any{ + {"path": "file1.go", "type": "blob"}, + {"path": "file2.go", "type": "blob"}, + }, + "truncated": true, + }) + + default: + w.WriteHeader(http.StatusNotFound) + } + })) + defer srv.Close() + + client := newTestClient(t, srv) + files, err := client.ListRepositoryFiles(context.Background(), "org", "large-repo") + + require.Error(t, err, "should return error on truncated tree response") + assert.Contains(t, err.Error(), "truncated", + "error message should be descriptive for operators") + assert.Nil(t, files, "no partial file list should be returned") +} diff --git a/internal/forge/qf_fake_test.go b/internal/forge/qf_fake_test.go new file mode 100644 index 000000000..205532a1a --- /dev/null +++ b/internal/forge/qf_fake_test.go @@ -0,0 +1,57 @@ +package forge + +// QualityFlow generated tests for GH-72 +// Suite: TS-GH72-002 — FakeClient ListRepositoryFiles implementation +// STD: outputs/std/GH-72/GH-72_test_description.yaml + +import ( + "context" + "errors" + "sync" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// TC-GH72-007: FakeClient ListRepositoryFiles error injection +func TestQFFakeClient_ErrorInjection_ListRepositoryFiles(t *testing.T) { + ctx := context.Background() + injected := errors.New("injected error") + + fc := &FakeClient{ + Errors: map[string]error{ + "ListRepositoryFiles": injected, + }, + } + + _, err := fc.ListRepositoryFiles(ctx, "o", "r") + require.Error(t, err) + assert.ErrorIs(t, err, injected, "injected error should be returned via errors.Is") +} + +// TC-GH72-008: FakeClient thread safety for ListRepositoryFiles +func TestQFFakeClient_ThreadSafety_ListRepositoryFiles(t *testing.T) { + ctx := context.Background() + fc := &FakeClient{ + FileContents: map[string][]byte{ + "o/r/file1.txt": []byte("content1"), + "o/r/file2.txt": []byte("content2"), + }, + } + + var wg sync.WaitGroup + const goroutines = 20 + + for range goroutines { + wg.Add(1) + go func() { + defer wg.Done() + files, err := fc.ListRepositoryFiles(ctx, "o", "r") + assert.NoError(t, err) + assert.Len(t, files, 2, "should return 2 files from concurrent access") + }() + } + + wg.Wait() +} diff --git a/internal/harness/discover_remote.go b/internal/harness/discover_remote.go new file mode 100644 index 000000000..641c36ccc --- /dev/null +++ b/internal/harness/discover_remote.go @@ -0,0 +1,76 @@ +package harness + +import ( + "context" + "errors" + "fmt" + "path" + "sort" + "strings" + + "github.com/fullsend-ai/fullsend/internal/forge" +) + +// DiscoverRemoteAgents discovers agent identity (role, slug) from harness files +// in a remote config repo via the forge API. It is the remote counterpart of +// DiscoverAgents, which reads from the local filesystem. +// +// Files where both role and slug are empty are skipped. Per-file errors (parse +// failures, GetFileContentAtRef failures) are collected into a multi-error; +// valid files are still returned alongside the error. +// +// Results are sorted by Role, then by Filename for deterministic output. +// Returns (nil, nil) when the harness/ directory does not exist. +func DiscoverRemoteAgents(ctx context.Context, client forge.Client, owner, repo, ref string) ([]AgentInfo, error) { + entries, err := client.ListDirectoryContents(ctx, owner, repo, "harness", ref, false) + if forge.IsNotFound(err) { + return nil, nil + } + if err != nil { + return nil, fmt.Errorf("listing harness directory: %w", err) + } + + var agents []AgentInfo + var errs []error + + for _, e := range entries { + if e.Type != "file" { + continue + } + name := path.Base(e.Path) + if !strings.HasSuffix(name, ".yaml") && !strings.HasSuffix(name, ".yml") { + continue + } + + data, err := client.GetFileContentAtRef(ctx, owner, repo, "harness/"+name, ref) + if err != nil { + errs = append(errs, fmt.Errorf("%s: %w", name, err)) + continue + } + + h, err := parseRaw(data) + if err != nil { + errs = append(errs, fmt.Errorf("%s: %w", name, err)) + continue + } + + if h.Role == "" && h.Slug == "" { + continue + } + + agents = append(agents, AgentInfo{ + Role: h.Role, + Slug: h.Slug, + Filename: name, + }) + } + + sort.Slice(agents, func(i, j int) bool { + if agents[i].Role != agents[j].Role { + return agents[i].Role < agents[j].Role + } + return agents[i].Filename < agents[j].Filename + }) + + return agents, errors.Join(errs...) +} diff --git a/internal/harness/discover_remote_test.go b/internal/harness/discover_remote_test.go new file mode 100644 index 000000000..6b4960401 --- /dev/null +++ b/internal/harness/discover_remote_test.go @@ -0,0 +1,226 @@ +package harness + +import ( + "context" + "fmt" + "testing" + + "github.com/fullsend-ai/fullsend/internal/forge" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestDiscoverRemoteAgents(t *testing.T) { + ctx := context.Background() + const ( + owner = "acme" + repo = ".fullsend" + ref = "main" + ) + + t.Run("multiple harnesses sorted by role", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref)] = []forge.DirectoryEntry{ + {Path: "triage.yaml", Type: "file"}, + {Path: "code.yaml", Type: "file"}, + {Path: "review.yaml", Type: "file"}, + } + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/triage.yaml@%s", owner, repo, ref)] = []byte("agent: agents/triage.md\nrole: triage\nslug: fs-triage\n") + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/code.yaml@%s", owner, repo, ref)] = []byte("agent: agents/code.md\nrole: coder\nslug: fs-coder\n") + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/review.yaml@%s", owner, repo, ref)] = []byte("agent: agents/review.md\nrole: review\nslug: fs-review\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 3) + + assert.Equal(t, "coder", agents[0].Role) + assert.Equal(t, "fs-coder", agents[0].Slug) + assert.Equal(t, "code.yaml", agents[0].Filename) + + assert.Equal(t, "review", agents[1].Role) + assert.Equal(t, "triage", agents[2].Role) + }) + + t.Run("no harness directory returns nil nil", func(t *testing.T) { + fc := forge.NewFakeClient() + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + assert.Nil(t, agents) + }) + + t.Run("skips files without role or slug", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref)] = []forge.DirectoryEntry{ + {Path: "legacy.yaml", Type: "file"}, + {Path: "modern.yaml", Type: "file"}, + } + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/legacy.yaml@%s", owner, repo, ref)] = []byte("agent: agents/legacy.md\n") + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/modern.yaml@%s", owner, repo, ref)] = []byte("agent: agents/modern.md\nrole: triage\nslug: fs-triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1) + assert.Equal(t, "triage", agents[0].Role) + }) + + t.Run("role only without slug is included", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref)] = []forge.DirectoryEntry{ + {Path: "partial.yaml", Type: "file"}, + } + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/partial.yaml@%s", owner, repo, ref)] = []byte("agent: agents/partial.md\nrole: triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1) + assert.Equal(t, "triage", agents[0].Role) + assert.Empty(t, agents[0].Slug) + }) + + t.Run("slug only without role is included", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref)] = []forge.DirectoryEntry{ + {Path: "slug-only.yaml", Type: "file"}, + } + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/slug-only.yaml@%s", owner, repo, ref)] = []byte("agent: agents/slug.md\nslug: fs-triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1) + assert.Equal(t, "fs-triage", agents[0].Slug) + assert.Empty(t, agents[0].Role) + }) + + t.Run("malformed YAML returns multi-error with valid files", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref)] = []forge.DirectoryEntry{ + {Path: "good.yaml", Type: "file"}, + {Path: "bad.yaml", Type: "file"}, + } + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/good.yaml@%s", owner, repo, ref)] = []byte("agent: agents/good.md\nrole: triage\nslug: fs-triage\n") + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/bad.yaml@%s", owner, repo, ref)] = []byte(":\n :\n - [invalid yaml") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.Error(t, err) + assert.Contains(t, err.Error(), "bad.yaml") + require.Len(t, agents, 1) + assert.Equal(t, "triage", agents[0].Role) + }) + + t.Run("GetFileContentAtRef failure for one file returns multi-error", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref)] = []forge.DirectoryEntry{ + {Path: "good.yaml", Type: "file"}, + {Path: "missing.yaml", Type: "file"}, + } + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/good.yaml@%s", owner, repo, ref)] = []byte("agent: agents/good.md\nrole: triage\nslug: fs-triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.Error(t, err) + assert.Contains(t, err.Error(), "missing.yaml") + require.Len(t, agents, 1) + assert.Equal(t, "triage", agents[0].Role) + }) + + t.Run("empty harness directory returns empty list", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref)] = []forge.DirectoryEntry{} + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + assert.Empty(t, agents) + }) + + t.Run("yml extension is discovered", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref)] = []forge.DirectoryEntry{ + {Path: "agent.yml", Type: "file"}, + } + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/agent.yml@%s", owner, repo, ref)] = []byte("agent: agents/agent.md\nrole: triage\nslug: fs-triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1) + assert.Equal(t, "agent.yml", agents[0].Filename) + }) + + t.Run("skips subdirectories", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref)] = []forge.DirectoryEntry{ + {Path: "triage.yaml", Type: "file"}, + {Path: "subdir", Type: "dir"}, + } + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/triage.yaml@%s", owner, repo, ref)] = []byte("agent: agents/triage.md\nrole: triage\nslug: fs-triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1) + }) + + t.Run("skips non-YAML files", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref)] = []forge.DirectoryEntry{ + {Path: "triage.yaml", Type: "file"}, + {Path: "readme.md", Type: "file"}, + {Path: "notes.txt", Type: "file"}, + } + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/triage.yaml@%s", owner, repo, ref)] = []byte("agent: agents/triage.md\nrole: triage\nslug: fs-triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1) + }) + + t.Run("same role sorted by filename", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref)] = []forge.DirectoryEntry{ + {Path: "fix.yaml", Type: "file"}, + {Path: "code.yaml", Type: "file"}, + } + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/fix.yaml@%s", owner, repo, ref)] = []byte("agent: agents/fix.md\nrole: coder\nslug: fs-coder\n") + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/code.yaml@%s", owner, repo, ref)] = []byte("agent: agents/code.md\nrole: coder\nslug: fs-coder-2\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 2) + assert.Equal(t, "code.yaml", agents[0].Filename) + assert.Equal(t, "fix.yaml", agents[1].Filename) + }) + + t.Run("path field is empty for remote agents", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref)] = []forge.DirectoryEntry{ + {Path: "triage.yaml", Type: "file"}, + } + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/triage.yaml@%s", owner, repo, ref)] = []byte("agent: agents/triage.md\nrole: triage\nslug: fs-triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1) + assert.Empty(t, agents[0].Path) + }) + + t.Run("path prefix in entry is stripped to bare filename", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref)] = []forge.DirectoryEntry{ + {Path: "harness/triage.yaml", Type: "file"}, + } + fc.FileContentsRef[fmt.Sprintf("%s/%s/harness/triage.yaml@%s", owner, repo, ref)] = []byte("agent: agents/triage.md\nrole: triage\nslug: fs-triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1) + assert.Equal(t, "triage.yaml", agents[0].Filename) + }) + + t.Run("ListDirectoryContents error propagates", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.Errors["ListDirectoryContents"] = fmt.Errorf("network error") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.Error(t, err) + assert.Contains(t, err.Error(), "listing harness directory") + assert.Nil(t, agents) + }) +} diff --git a/internal/harness/harness.go b/internal/harness/harness.go index b4002e02d..9c7630bdd 100644 --- a/internal/harness/harness.go +++ b/internal/harness/harness.go @@ -273,6 +273,17 @@ func LoadWithOpts(path string, opts LoadOpts) (*Harness, error) { return h, nil } +// parseRaw unmarshals raw YAML bytes into a Harness without validation or +// forge resolution. Use this when you already have the bytes (e.g. from a +// forge API call); use LoadRaw for filesystem-based loading. +func parseRaw(data []byte) (*Harness, error) { + var h Harness + if err := yaml.Unmarshal(data, &h); err != nil { + return nil, fmt.Errorf("parsing harness YAML: %w", err) + } + return &h, nil +} + // LoadRaw reads and unmarshals a harness YAML file without calling Validate // or ResolveForge. Used by base composition to load base harnesses without // consuming their forge maps before merging, and by the lock command to @@ -282,13 +293,7 @@ func LoadRaw(path string) (*Harness, error) { if err != nil { return nil, fmt.Errorf("reading harness file: %w", err) } - - var h Harness - if err := yaml.Unmarshal(data, &h); err != nil { - return nil, fmt.Errorf("parsing harness YAML: %w", err) - } - - return &h, nil + return parseRaw(data) } // Validate checks that required fields are present. diff --git a/internal/harness/lint.go b/internal/harness/lint.go new file mode 100644 index 000000000..85a3f0aef --- /dev/null +++ b/internal/harness/lint.go @@ -0,0 +1,52 @@ +package harness + +import "fmt" + +// DiagnosticSeverity indicates whether a diagnostic is a warning or an error. +type DiagnosticSeverity int + +const ( + SeverityWarning DiagnosticSeverity = iota + SeverityError +) + +// String returns a human-readable description of the diagnostic severity. +func (s DiagnosticSeverity) String() string { + switch s { + case SeverityWarning: + return "warning" + case SeverityError: + return "error" + default: + return fmt.Sprintf("DiagnosticSeverity(%d)", int(s)) + } +} + +// Diagnostic represents a non-fatal issue found by Lint. +type Diagnostic struct { + Severity DiagnosticSeverity + Field string + Message string +} + +func (d Diagnostic) String() string { + return fmt.Sprintf("%s: %s: %s", d.Severity, d.Field, d.Message) +} + +// Lint returns non-fatal diagnostics for the harness. Call only after a +// successful Validate — Lint does not re-check structural validity, and its +// results are meaningless on an invalid harness. +// Returns nil when no diagnostics are found. +func (h *Harness) Lint() []Diagnostic { + var diags []Diagnostic + + if h.Role == "" { + diags = append(diags, Diagnostic{ + Severity: SeverityWarning, + Field: "role", + Message: "role is not set; it will be required in a future version", + }) + } + + return diags +} diff --git a/internal/harness/lint_test.go b/internal/harness/lint_test.go new file mode 100644 index 000000000..14680b2bd --- /dev/null +++ b/internal/harness/lint_test.go @@ -0,0 +1,46 @@ +package harness + +import ( + "testing" + + "github.com/stretchr/testify/assert" +) + +func TestLint(t *testing.T) { + t.Run("role set", func(t *testing.T) { + h := &Harness{Role: "triage"} + assert.Nil(t, h.Lint()) + }) + + t.Run("role empty", func(t *testing.T) { + h := &Harness{} + diags := h.Lint() + assert.NotNil(t, diags) + assert.Len(t, diags, 1) + assert.Equal(t, SeverityWarning, diags[0].Severity) + assert.Equal(t, "role", diags[0].Field) + assert.Contains(t, diags[0].Message, "required in a future version") + }) + + t.Run("role and slug set", func(t *testing.T) { + h := &Harness{Role: "triage", Slug: "my-slug"} + assert.Nil(t, h.Lint()) + }) +} + +func TestDiagnostic_String(t *testing.T) { + t.Run("warning", func(t *testing.T) { + d := Diagnostic{Severity: SeverityWarning, Field: "role", Message: "msg"} + assert.Equal(t, "warning: role: msg", d.String()) + }) + + t.Run("error", func(t *testing.T) { + d := Diagnostic{Severity: SeverityError, Field: "role", Message: "msg"} + assert.Equal(t, "error: role: msg", d.String()) + }) + + t.Run("unknown severity", func(t *testing.T) { + d := Diagnostic{Severity: DiagnosticSeverity(99), Field: "x", Message: "msg"} + assert.Equal(t, "DiagnosticSeverity(99): x: msg", d.String()) + }) +} diff --git a/internal/harness/qf_discover_remote_test.go b/internal/harness/qf_discover_remote_test.go new file mode 100644 index 000000000..30def71d0 --- /dev/null +++ b/internal/harness/qf_discover_remote_test.go @@ -0,0 +1,205 @@ +package harness + +// QualityFlow generated tests for GH-72 +// Suite: TS-GH72-005 — DiscoverRemoteAgents harness discovery via forge API +// STD: outputs/std/GH-72/GH-72_test_description.yaml + +import ( + "context" + "fmt" + "testing" + + "github.com/fullsend-ai/fullsend/internal/forge" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestQFDiscoverRemoteAgents(t *testing.T) { + ctx := context.Background() + const ( + owner = "acme" + repo = ".fullsend" + ref = "main" + ) + + harnessKey := func() string { + return fmt.Sprintf("%s/%s/harness@%s", owner, repo, ref) + } + fileKey := func(name string) string { + return fmt.Sprintf("%s/%s/harness/%s@%s", owner, repo, name, ref) + } + + // TC-GH72-025: Multiple harnesses discovered and sorted by role + t.Run("multiple_harnesses_sorted_by_role", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[harnessKey()] = []forge.DirectoryEntry{ + {Path: "triage.yaml", Type: "file"}, + {Path: "code.yaml", Type: "file"}, + {Path: "review.yaml", Type: "file"}, + } + fc.FileContentsRef[fileKey("triage.yaml")] = []byte("agent: agents/triage.md\nrole: triage\nslug: fs-triage\n") + fc.FileContentsRef[fileKey("code.yaml")] = []byte("agent: agents/code.md\nrole: coder\nslug: fs-coder\n") + fc.FileContentsRef[fileKey("review.yaml")] = []byte("agent: agents/review.md\nrole: review\nslug: fs-review\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 3) + assert.Equal(t, "coder", agents[0].Role) + assert.Equal(t, "fs-coder", agents[0].Slug) + assert.Equal(t, "code.yaml", agents[0].Filename) + assert.Equal(t, "review", agents[1].Role) + assert.Equal(t, "triage", agents[2].Role) + }) + + // TC-GH72-026: Missing harness directory returns nil,nil + t.Run("no_harness_directory_returns_nil_nil", func(t *testing.T) { + fc := forge.NewFakeClient() + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err, "not-found is not an error") + assert.Nil(t, agents) + }) + + // TC-GH72-027: Files without role or slug are skipped + t.Run("skips_files_without_role_or_slug", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[harnessKey()] = []forge.DirectoryEntry{ + {Path: "legacy.yaml", Type: "file"}, + {Path: "modern.yaml", Type: "file"}, + } + fc.FileContentsRef[fileKey("legacy.yaml")] = []byte("agent: agents/legacy.md\n") + fc.FileContentsRef[fileKey("modern.yaml")] = []byte("agent: agents/modern.md\nrole: triage\nslug: fs-triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1, "legacy.yaml without role/slug should be excluded") + assert.Equal(t, "triage", agents[0].Role) + }) + + // TC-GH72-028: Malformed YAML returns partial results with multi-error + t.Run("malformed_YAML_returns_multi-error_with_valid_files", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[harnessKey()] = []forge.DirectoryEntry{ + {Path: "good.yaml", Type: "file"}, + {Path: "bad.yaml", Type: "file"}, + } + fc.FileContentsRef[fileKey("good.yaml")] = []byte("agent: agents/good.md\nrole: triage\nslug: fs-triage\n") + fc.FileContentsRef[fileKey("bad.yaml")] = []byte(":\n :\n - [invalid yaml") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.Error(t, err) + assert.Contains(t, err.Error(), "bad.yaml", "error should identify the problematic file") + require.Len(t, agents, 1, "valid files should still be returned") + assert.Equal(t, "triage", agents[0].Role) + }) + + // TC-GH72-029: Non-YAML files and subdirectories are skipped + t.Run("skips_subdirectories", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[harnessKey()] = []forge.DirectoryEntry{ + {Path: "triage.yaml", Type: "file"}, + {Path: "subdir", Type: "dir"}, + } + fc.FileContentsRef[fileKey("triage.yaml")] = []byte("agent: agents/triage.md\nrole: triage\nslug: fs-triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1, "only YAML files should be processed; subdirectory ignored") + }) + + // TC-GH72-030: ListDirectoryContents error propagates + t.Run("ListDirectoryContents_error_propagates", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.Errors["ListDirectoryContents"] = fmt.Errorf("network error") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.Error(t, err) + assert.Contains(t, err.Error(), "listing harness directory") + assert.Nil(t, agents) + }) + + // TC-GH72-031: Same role sorted by filename + t.Run("same_role_sorted_by_filename", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[harnessKey()] = []forge.DirectoryEntry{ + {Path: "fix.yaml", Type: "file"}, + {Path: "code.yaml", Type: "file"}, + } + fc.FileContentsRef[fileKey("fix.yaml")] = []byte("agent: agents/fix.md\nrole: coder\nslug: fs-coder\n") + fc.FileContentsRef[fileKey("code.yaml")] = []byte("agent: agents/code.md\nrole: coder\nslug: fs-coder-2\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 2) + assert.Equal(t, "code.yaml", agents[0].Filename, "code.yaml should sort before fix.yaml") + assert.Equal(t, "fix.yaml", agents[1].Filename) + }) + + // TC-GH72-032: Role-only file (no slug) is included + t.Run("role_only_without_slug_is_included", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[harnessKey()] = []forge.DirectoryEntry{ + {Path: "partial.yaml", Type: "file"}, + } + fc.FileContentsRef[fileKey("partial.yaml")] = []byte("agent: agents/partial.md\nrole: triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1) + assert.Equal(t, "triage", agents[0].Role) + assert.Empty(t, agents[0].Slug, "slug should be empty when not set") + }) + + // TC-GH72-033: Slug-only file (no role) is included + t.Run("slug_only_without_role_is_included", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[harnessKey()] = []forge.DirectoryEntry{ + {Path: "slug-only.yaml", Type: "file"}, + } + fc.FileContentsRef[fileKey("slug-only.yaml")] = []byte("agent: agents/slug.md\nslug: fs-triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1) + assert.Equal(t, "fs-triage", agents[0].Slug) + assert.Empty(t, agents[0].Role, "role should be empty when not set") + }) + + // TC-GH72-034: .yml extension files are discovered + t.Run("yml_extension_is_discovered", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[harnessKey()] = []forge.DirectoryEntry{ + {Path: "agent.yml", Type: "file"}, + } + fc.FileContentsRef[fileKey("agent.yml")] = []byte("agent: agents/agent.md\nrole: triage\nslug: fs-triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1) + assert.Equal(t, "agent.yml", agents[0].Filename) + }) + + // TC-GH72-035: Empty harness directory returns empty list + t.Run("empty_harness_directory_returns_empty_list", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[harnessKey()] = []forge.DirectoryEntry{} + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + assert.Empty(t, agents, "empty directory should return empty but not nil") + }) + + // TC-GH72-036: Path field is empty for remote agents + t.Run("path_field_is_empty_for_remote_agents", func(t *testing.T) { + fc := forge.NewFakeClient() + fc.DirContents[harnessKey()] = []forge.DirectoryEntry{ + {Path: "triage.yaml", Type: "file"}, + } + fc.FileContentsRef[fileKey("triage.yaml")] = []byte("agent: agents/triage.md\nrole: triage\nslug: fs-triage\n") + + agents, err := DiscoverRemoteAgents(ctx, fc, owner, repo, ref) + require.NoError(t, err) + require.Len(t, agents, 1) + assert.Empty(t, agents[0].Path, "Path should be empty for remotely discovered agents") + }) +} diff --git a/internal/harness/qf_lint_test.go b/internal/harness/qf_lint_test.go new file mode 100644 index 000000000..b26e2bf49 --- /dev/null +++ b/internal/harness/qf_lint_test.go @@ -0,0 +1,54 @@ +package harness + +// QualityFlow generated tests for GH-72 +// Suite: TS-GH72-004 — Harness Lint non-fatal diagnostics +// STD: outputs/std/GH-72/GH-72_test_description.yaml + +import ( + "testing" + + "github.com/stretchr/testify/assert" +) + +// TC-GH72-019: Lint returns nil when role is set +func TestQFLint_RoleSet(t *testing.T) { + h := &Harness{Role: "triage"} + assert.Nil(t, h.Lint(), "no diagnostics when role is set") +} + +// TC-GH72-020: Lint warns on missing role field +func TestQFLint_RoleEmpty(t *testing.T) { + h := &Harness{} + diags := h.Lint() + assert.NotNil(t, diags) + assert.Len(t, diags, 1) + assert.Equal(t, SeverityWarning, diags[0].Severity) + assert.Equal(t, "role", diags[0].Field) + assert.Contains(t, diags[0].Message, "required in a future version", + "diagnostic should warn about future requirement") +} + +// TC-GH72-021: Lint returns nil when role and slug both set +func TestQFLint_RoleAndSlugSet(t *testing.T) { + h := &Harness{Role: "triage", Slug: "my-slug"} + assert.Nil(t, h.Lint(), "no diagnostics when both role and slug are set") +} + +// TC-GH72-022: Diagnostic String formatting for warning +func TestQFDiagnostic_String_Warning(t *testing.T) { + d := Diagnostic{Severity: SeverityWarning, Field: "role", Message: "msg"} + assert.Equal(t, "warning: role: msg", d.String()) +} + +// TC-GH72-023: Diagnostic String formatting for error +func TestQFDiagnostic_String_Error(t *testing.T) { + d := Diagnostic{Severity: SeverityError, Field: "role", Message: "msg"} + assert.Equal(t, "error: role: msg", d.String()) +} + +// TC-GH72-024: Diagnostic String formatting for unknown severity +func TestQFDiagnostic_String_UnknownSeverity(t *testing.T) { + d := Diagnostic{Severity: DiagnosticSeverity(99), Field: "x", Message: "msg"} + assert.Equal(t, "DiagnosticSeverity(99): x: msg", d.String(), + "unknown severity should use Go stringer format") +} diff --git a/internal/harness/scaffold_integration_test.go b/internal/harness/scaffold_integration_test.go new file mode 100644 index 000000000..519355f03 --- /dev/null +++ b/internal/harness/scaffold_integration_test.go @@ -0,0 +1,344 @@ +package harness + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "os" + "path/filepath" + "sort" + "testing" + + "github.com/fullsend-ai/fullsend/internal/scaffold" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// extractScaffoldHarnessDir writes all embedded scaffold files to dir and +// returns the harness subdirectory path. +func extractScaffoldHarnessDir(t *testing.T, dir string) string { + t.Helper() + err := scaffold.WalkFullsendRepoAll(func(path string, content []byte) error { + dest := filepath.Join(dir, path) + if mkErr := os.MkdirAll(filepath.Dir(dest), 0o755); mkErr != nil { + return mkErr + } + return os.WriteFile(dest, content, 0o644) + }) + require.NoError(t, err, "extracting scaffold") + return filepath.Join(dir, "harness") +} + +// TestLoadWithBase_WrapperMergesScaffold verifies the full pipeline: a thin +// wrapper harness with base: pointing to a local scaffold harness loads and +// merges correctly, producing the expected role/slug overrides and inherited fields. +func TestLoadWithBase_WrapperMergesScaffold(t *testing.T) { + dir := t.TempDir() + harnessDir := extractScaffoldHarnessDir(t, dir) + + wrapperPath := writeTestHarness(t, harnessDir, "wrapper-triage.yaml", ` +base: triage.yaml +role: triage +slug: test-triage +`) + + h, deps, err := LoadWithBase(context.Background(), wrapperPath, ComposeOpts{ + ForgePlatform: "github", + }) + require.NoError(t, err) + + // Role and slug come from wrapper (overrides base). + assert.Equal(t, "triage", h.Role) + assert.Equal(t, "test-triage", h.Slug) + + // Agent, model, image, policy inherited from base. + assert.Equal(t, "agents/triage.md", h.Agent) + assert.Equal(t, "opus", h.Model) + assert.Equal(t, "ghcr.io/fullsend-ai/fullsend-sandbox:latest", h.Image) + assert.Equal(t, "policies/triage.yaml", h.Policy) + + // PreScript and PostScript populated after forge.github resolution. + assert.NotEmpty(t, h.PreScript, "PreScript should be set after forge resolution") + assert.NotEmpty(t, h.PostScript, "PostScript should be set after forge resolution") + + // RunnerEnv contains both top-level keys and forge.github keys after merge. + assert.Contains(t, h.RunnerEnv, "FULLSEND_OUTPUT_SCHEMA", "should have top-level runner_env key") + assert.Contains(t, h.RunnerEnv, "GH_TOKEN", "should have forge.github runner_env key") + assert.Contains(t, h.RunnerEnv, "GITHUB_ISSUE_URL", "should have forge.github runner_env key") + + // Skills includes base top-level skills (forge skills are concatenated by ResolveForge, + // but the triage template has no forge-specific skills — only runner_env and scripts). + assert.Contains(t, h.Skills, "skills/issue-labels") + + // Forge map is nil (consumed by ResolveForge). + assert.Nil(t, h.Forge) + + // Base field is empty (consumed by LoadWithBase). + assert.Empty(t, h.Base) + + // Local base -> no URL deps. + assert.Nil(t, deps) + + // ValidationLoop inherited from base. + assert.NotNil(t, h.ValidationLoop) + assert.Equal(t, "scripts/validate-output-schema.sh", h.ValidationLoop.Script) + assert.Equal(t, 2, h.ValidationLoop.MaxIterations) +} + +// TestLoadWithBase_WrapperOverridesBaseFields verifies that wrapper-level +// overrides (model, slug) take precedence over base values while other fields inherit. +func TestLoadWithBase_WrapperOverridesBaseFields(t *testing.T) { + dir := t.TempDir() + harnessDir := extractScaffoldHarnessDir(t, dir) + + wrapperPath := writeTestHarness(t, harnessDir, "wrapper-custom.yaml", ` +base: code.yaml +role: coder +slug: my-org-coder +model: sonnet +`) + + h, _, err := LoadWithBase(context.Background(), wrapperPath, ComposeOpts{ + ForgePlatform: "github", + }) + require.NoError(t, err) + + assert.Equal(t, "coder", h.Role) + assert.Equal(t, "my-org-coder", h.Slug) + assert.Equal(t, "sonnet", h.Model, "wrapper model should override base model") + assert.Equal(t, "agents/code.md", h.Agent, "agent should be inherited from base") + assert.Equal(t, "ghcr.io/fullsend-ai/fullsend-code:latest", h.Image, "image should be inherited from base") +} + +// TestLoadWithOpts_ScaffoldTemplatesForgeResolution loads every scaffold harness +// template with ForgePlatform: "github" and verifies the merged state is +// consistent — pre/post scripts populated, runner_env merged, forge consumed. +func TestLoadWithOpts_ScaffoldTemplatesForgeResolution(t *testing.T) { + dir := t.TempDir() + harnessDir := extractScaffoldHarnessDir(t, dir) + + names, err := scaffold.HarnessNames() + require.NoError(t, err) + require.NotEmpty(t, names) + + for _, name := range names { + t.Run(name, func(t *testing.T) { + path := filepath.Join(harnessDir, name+".yaml") + + h, loadErr := LoadWithOpts(path, LoadOpts{ForgePlatform: "github"}) + require.NoError(t, loadErr) + + assert.NotEmpty(t, h.PreScript, "PreScript should be set after forge resolution") + assert.NotEmpty(t, h.PostScript, "PostScript should be set after forge resolution") + assert.NotEmpty(t, h.RunnerEnv, "RunnerEnv should be non-empty after merge") + assert.Nil(t, h.Forge, "Forge should be nil after resolution") + assert.NotEmpty(t, h.Role, "Role should be set in scaffold template") + assert.NotEmpty(t, h.Slug, "Slug should be set in scaffold template") + }) + } +} + +// TestLoad_ScaffoldTemplatesBackwardCompat loads every scaffold harness template +// via Load() (no forge platform) and verifies backward compatibility: the +// harness loads without error, top-level defaults are present, and the forge +// map is retained (not consumed). +func TestLoad_ScaffoldTemplatesBackwardCompat(t *testing.T) { + dir := t.TempDir() + harnessDir := extractScaffoldHarnessDir(t, dir) + + names, err := scaffold.HarnessNames() + require.NoError(t, err) + + for _, name := range names { + t.Run(name, func(t *testing.T) { + path := filepath.Join(harnessDir, name+".yaml") + + h, loadErr := Load(path) + require.NoError(t, loadErr) + + // Top-level pre/post scripts serve as defaults. + assert.NotEmpty(t, h.PreScript, "PreScript should be set at top level as default") + assert.NotEmpty(t, h.PostScript, "PostScript should be set at top level as default") + + // Forge map is present and has "github" key. + assert.NotNil(t, h.Forge, "Forge map should be present") + assert.Contains(t, h.Forge, "github", "Forge should have a github key") + }) + } +} + +// TestDiscoverAgents_ScaffoldDirectory extracts the scaffold to a temp dir, +// runs DiscoverAgents on the harness directory, and verifies all agents are +// discovered with correct role/slug pairs. +func TestDiscoverAgents_ScaffoldDirectory(t *testing.T) { + dir := t.TempDir() + harnessDir := extractScaffoldHarnessDir(t, dir) + + agents, err := DiscoverAgents(harnessDir) + require.NoError(t, err) + + // Expect all 6 scaffold harnesses discovered. + require.Len(t, agents, 6, "should discover all 6 scaffold harnesses") + + // Build a map of filename -> AgentInfo for easier assertion. + byFilename := make(map[string]AgentInfo, len(agents)) + for _, a := range agents { + byFilename[a.Filename] = a + } + + expected := map[string]struct{ role, slug string }{ + "code.yaml": {"coder", "fullsend-ai-coder"}, + "fix.yaml": {"coder", "fullsend-ai-coder"}, + "prioritize.yaml": {"prioritize", "fullsend-ai-prioritize"}, + "retro.yaml": {"retro", "fullsend-ai-retro"}, + "review.yaml": {"review", "fullsend-ai-review"}, + "triage.yaml": {"triage", "fullsend-ai-triage"}, + } + + for filename, want := range expected { + got, ok := byFilename[filename] + require.True(t, ok, "should discover %s", filename) + assert.Equal(t, want.role, got.Role, "%s role", filename) + assert.Equal(t, want.slug, got.Slug, "%s slug", filename) + assert.True(t, filepath.IsAbs(got.Path), "%s path should be absolute", filename) + } + + // Verify sort order: by role, then by filename. + sorted := make([]AgentInfo, len(agents)) + copy(sorted, agents) + sort.Slice(sorted, func(i, j int) bool { + if sorted[i].Role != sorted[j].Role { + return sorted[i].Role < sorted[j].Role + } + return sorted[i].Filename < sorted[j].Filename + }) + assert.Equal(t, sorted, agents, "results should be sorted by role then filename") +} + +// TestHarnessContentHash_MatchesEmbeddedContent verifies that HarnessContentHash +// produces correct SHA-256 hashes matching the embedded file content, and that +// HarnessBaseURLWithHash produces well-formed URLs with matching hash fragments. +func TestHarnessContentHash_MatchesEmbeddedContent(t *testing.T) { + names, err := scaffold.HarnessNames() + require.NoError(t, err) + + fakeCommitSHA := "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" + + for _, name := range names { + t.Run(name, func(t *testing.T) { + // Compute hash via the scaffold package. + hash, err := scaffold.HarnessContentHash(name) + require.NoError(t, err) + assert.Len(t, hash, 64, "SHA-256 hex digest should be 64 characters") + + // Independently compute hash from the embedded file content. + content, err := scaffold.FullsendRepoFile("harness/" + name + ".yaml") + require.NoError(t, err) + sum := sha256.Sum256(content) + independentHash := hex.EncodeToString(sum[:]) + assert.Equal(t, independentHash, hash, + "HarnessContentHash should match sha256 of embedded file content") + + // Verify HarnessBaseURLWithHash produces a valid URL with matching hash. + fullURL, err := scaffold.HarnessBaseURLWithHash(name, fakeCommitSHA) + require.NoError(t, err) + assert.Contains(t, fullURL, fakeCommitSHA) + assert.Contains(t, fullURL, name+".yaml") + assert.Contains(t, fullURL, "#sha256="+hash) + }) + } +} + +// TestLoadRaw_GeneratedWrapperFormat verifies that the wrapper YAML format +// produced by HarnessWrappersLayer (base + role + slug) parses correctly via +// LoadRaw and contains the expected identity fields. +func TestLoadRaw_GeneratedWrapperFormat(t *testing.T) { + names, err := scaffold.HarnessNames() + require.NoError(t, err) + + fakeCommitSHA := "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" + + for _, name := range names { + t.Run(name, func(t *testing.T) { + baseURL, err := scaffold.HarnessBaseURLWithHash(name, fakeCommitSHA) + require.NoError(t, err) + + // Simulate the wrapper format produced by HarnessWrappersLayer. + wrapperYAML := "base: " + baseURL + "\n" + + "role: " + name + "\n" + + "slug: test-" + name + "\n" + + dir := t.TempDir() + path := writeTestHarness(t, dir, name+".yaml", wrapperYAML) + + h, err := LoadRaw(path) + require.NoError(t, err) + + assert.Equal(t, baseURL, h.Base, "base should be the full URL with hash") + assert.Equal(t, name, h.Role) + assert.Equal(t, "test-"+name, h.Slug) + }) + } +} + +// TestResolveForge_ScaffoldRunnerEnvMerge verifies that forge resolution +// produces the expected merged runner_env for each scaffold template, with +// both top-level (platform-neutral) and forge.github (platform-specific) +// keys present in the final merged state. +func TestResolveForge_ScaffoldRunnerEnvMerge(t *testing.T) { + dir := t.TempDir() + harnessDir := extractScaffoldHarnessDir(t, dir) + + tests := []struct { + file string + topLevelKeys []string + forgeGithubKeys []string + }{ + { + file: "triage.yaml", + topLevelKeys: []string{"FULLSEND_OUTPUT_SCHEMA"}, + forgeGithubKeys: []string{"GITHUB_ISSUE_URL", "GH_TOKEN"}, + }, + { + file: "code.yaml", + topLevelKeys: []string{"TARGET_BRANCH"}, + forgeGithubKeys: []string{"PUSH_TOKEN", "PUSH_TOKEN_SOURCE", "REPO_FULL_NAME", "ISSUE_NUMBER", "REPO_DIR"}, + }, + { + file: "review.yaml", + topLevelKeys: []string{"FULLSEND_OUTPUT_SCHEMA"}, + forgeGithubKeys: []string{"REVIEW_TOKEN", "REPO_FULL_NAME", "PR_NUMBER", "GITHUB_PR_URL"}, + }, + { + file: "fix.yaml", + topLevelKeys: []string{"TARGET_BRANCH", "TRIGGER_SOURCE", "HUMAN_INSTRUCTION", "FIX_ITERATION", "REVIEW_BODY_FILE", "PRE_AGENT_HEAD", "FULLSEND_OUTPUT_SCHEMA", "FULLSEND_OUTPUT_FILE"}, + forgeGithubKeys: []string{"PUSH_TOKEN", "PUSH_TOKEN_SOURCE", "REPO_FULL_NAME", "PR_NUMBER", "REPO_DIR"}, + }, + { + file: "retro.yaml", + topLevelKeys: []string{"FULLSEND_OUTPUT_SCHEMA"}, + forgeGithubKeys: []string{"ORIGINATING_URL", "REPO_FULL_NAME", "GH_TOKEN"}, + }, + { + file: "prioritize.yaml", + topLevelKeys: []string{"FULLSEND_OUTPUT_SCHEMA"}, + forgeGithubKeys: []string{"GITHUB_ISSUE_URL", "GH_TOKEN", "ORG", "PROJECT_NUMBER"}, + }, + } + + for _, tt := range tests { + t.Run(tt.file, func(t *testing.T) { + path := filepath.Join(harnessDir, tt.file) + + h, loadErr := LoadWithOpts(path, LoadOpts{ForgePlatform: "github"}) + require.NoError(t, loadErr) + + for _, key := range tt.topLevelKeys { + assert.Contains(t, h.RunnerEnv, key, "merged RunnerEnv should contain top-level key %s", key) + } + for _, key := range tt.forgeGithubKeys { + assert.Contains(t, h.RunnerEnv, key, "merged RunnerEnv should contain forge.github key %s", key) + } + }) + } +} diff --git a/internal/layers/configrepo_test.go b/internal/layers/configrepo_test.go index ebf807956..3277fa5e7 100644 --- a/internal/layers/configrepo_test.go +++ b/internal/layers/configrepo_test.go @@ -22,6 +22,7 @@ func newTestConfig(t *testing.T) *config.OrgConfig { []string{"coder"}, []config.AgentEntry{{Role: "coder", Name: "Bot", Slug: "bot-slug"}}, "", + "", ) } diff --git a/internal/scaffold/fullsend-repo/agents/triage.md b/internal/scaffold/fullsend-repo/agents/triage.md index 01f4dcf68..7749861fb 100644 --- a/internal/scaffold/fullsend-repo/agents/triage.md +++ b/internal/scaffold/fullsend-repo/agents/triage.md @@ -63,18 +63,18 @@ gh pr list --repo OTHER-ORG/OTHER-REPO --state open --search "relevant keywords" If a cross-repo search fails or returns an error (e.g., due to access restrictions), note this in your reasoning as an information gap rather than concluding no blocking work exists. -### 2c. Check existing blockers +### 2c. Check existing prerequisites -If the issue already has a `blocked` label, check whether the previously identified blocker (linked in prior triage comments) is still open. Fetch the full context of the blocking issue or PR to understand its current state: +If the issue already has a `blocked` label, check whether the previously identified prerequisites (linked in prior triage comments) are still open. Fetch the full context of each prerequisite issue or PR to understand its current state: ``` -# For blocking issues: -gh issue view BLOCKING_URL --json state,title,body,comments,labels -# For blocking PRs: -gh pr view BLOCKING_URL --json state,title,body,comments,labels,mergedAt +# For prerequisite issues: +gh issue view PREREQUISITE_URL --json state,title,body,comments,labels +# For prerequisite PRs: +gh pr view PREREQUISITE_URL --json state,title,body,comments,labels,mergedAt ``` -Use `gh issue view` for `/issues/` URLs and `gh pr view` for `/pull/` URLs. Review the blocker's state, recent comments, and labels to determine whether the dependency has been resolved, is making progress, or remains stalled. If the blocker has been closed or merged, the block may be resolved — proceed with a fresh assessment. +Use `gh issue view` for `/issues/` URLs and `gh pr view` for `/pull/` URLs. Review the prerequisite's state, recent comments, and labels to determine whether the dependency has been resolved, is making progress, or remains stalled. If the prerequisite has been closed or merged, the dependency may be resolved — proceed with a fresh assessment. ### 2d. Review prior triage analysis @@ -126,7 +126,7 @@ Before forming any clarifying question, classify it: ### Phase 3 — Hypothesis formation and dependency analysis - Can you form a plausible root cause hypothesis from the available information? - Could a developer start investigating without contacting the reporter? -- **Is progress blocked on other work?** Consider whether the fix depends on an unresolved issue or unmerged PR — in this repo or another. If a developer cannot meaningfully start work until some other issue is resolved, this issue is blocked regardless of how clear the problem description is. +- **Is progress blocked on other work?** Consider whether the fix depends on an unresolved issue or unmerged PR — in this repo or another. If a developer cannot meaningfully start work until some other issue is resolved, this issue has prerequisites regardless of how clear the problem description is. If the blocking work has no tracking issue yet, you can recommend creating one via the `prerequisites` action's `create` array. ### Clarity scoring @@ -145,6 +145,8 @@ Calculate overall clarity: `symptom*0.35 + cause*0.30 + reproduction*0.20 + impa **Anti-premature-resolution rule (HARD CONSTRAINT):** If your assessment identifies ANY open *user-facing* questions or information gaps — regardless of whether they seem minor — you MUST use `action: "insufficient"` and ask a clarifying question. Do NOT emit `action: "sufficient"` with user-facing information gaps. The `sufficient` action means there are zero open user-facing questions that could affect implementation. When in doubt, ask. Implementation-facing questions that cannot be self-resolved from repository context should be noted in `reasoning` but do not require `action: "insufficient"` unless they materially prevent triage — see the question classification rules above. +**Anti-premature-prerequisites rule (HARD CONSTRAINT):** If your assessment identifies unresolved prerequisites — dependencies on work in other repos or unmerged changes that must land first — you MUST use `action: "prerequisites"`. Do NOT emit `action: "sufficient"` when prerequisites exist. The `sufficient` action means there are zero blockers and zero open questions. + ## Step 4: Decide and write result Based on your assessment, choose exactly one action and write the result as JSON to `$FULLSEND_OUTPUT_DIR/agent-result.json`. @@ -200,18 +202,36 @@ This issue describes the same problem as an existing open issue. } ``` -### Action: `blocked` +### Action: `prerequisites` + +Progress on this issue depends on work that must happen first — either in this repository or another. Use this action when you identify specific blocking dependencies: existing issues/PRs that must be resolved, or upstream work that needs a tracking issue created. + +**HARD CONSTRAINT:** Never emit `sufficient` if unresolved prerequisites exist. Use `prerequisites` instead. -Progress on this issue is blocked by another issue or PR — either in this repository or a different one. The blocking issue must be resolved before work on this issue can proceed. Do NOT apply `ready-to-code` for blocked issues. +The `prerequisites` object contains two arrays: -Only use `blocked` when you can identify a specific open issue or PR that must be resolved first. If you suspect a dependency but cannot find a concrete blocking issue, use `insufficient` to ask the reporter whether there is a blocking dependency and to provide its URL. +- `existing` — issues or PRs that already exist and block this work. Include the full HTML URL. +- `create` — issues that need to be filed in other repos before this work can proceed. Include the target `repo` (owner/name format), a `title`, and a `body`. Write the body for the target repo's audience — include enough technical context for upstream maintainers to understand what is needed. Use your judgment on whether to include a back-reference to the originating issue; sometimes it provides helpful context, sometimes it leaks internal details. + +At least one of the two arrays must have entries. ```json { - "action": "blocked", - "reasoning": "Brief explanation of why this issue is blocked and what the dependency is", - "blocked_by": "https://github.com/org/repo/issues/99", - "comment": "A professional comment explaining the blocking dependency. Link to the blocking issue or PR and explain why this issue cannot proceed until it is resolved. Be specific about the dependency — what does the blocking issue provide or unblock?" + "action": "prerequisites", + "reasoning": "Brief explanation of the dependencies and why this issue cannot proceed", + "prerequisites": { + "existing": [ + { "url": "https://github.com/org/repo/issues/99" } + ], + "create": [ + { + "repo": "org/upstream-lib", + "title": "Add support for X", + "body": "Technical description of what is needed and why, written for the upstream repo's maintainers." + } + ] + }, + "comment": "A professional comment explaining the blocking dependencies. Link to existing blockers and describe what new issues need to be created upstream. Be specific about why each dependency must be resolved before this issue can proceed." } ``` diff --git a/internal/scaffold/fullsend-repo/schemas/triage-result.schema.json b/internal/scaffold/fullsend-repo/schemas/triage-result.schema.json index a80948d30..73616cab7 100644 --- a/internal/scaffold/fullsend-repo/schemas/triage-result.schema.json +++ b/internal/scaffold/fullsend-repo/schemas/triage-result.schema.json @@ -9,7 +9,7 @@ "properties": { "action": { "type": "string", - "enum": ["insufficient", "duplicate", "sufficient", "blocked", "question"] + "enum": ["insufficient", "duplicate", "sufficient", "prerequisites", "question"] }, "reasoning": { "type": "string", @@ -30,10 +30,48 @@ "triage_summary": { "$ref": "#/$defs/triage_summary" }, - "blocked_by": { - "type": "string", - "pattern": "^https://github\\.com/[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+/(issues|pull)/[0-9]+$", - "description": "HTML URL of the blocking issue or PR (e.g., https://github.com/org/repo/issues/99 or https://github.com/org/repo/pull/55)" + "prerequisites": { + "type": "object", + "required": ["existing", "create"], + "properties": { + "existing": { + "type": "array", + "items": { + "type": "object", + "required": ["url"], + "properties": { + "url": { + "type": "string", + "pattern": "^https://github\\.com/[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+/(issues|pull)/[0-9]+$" + } + }, + "additionalProperties": false + } + }, + "create": { + "type": "array", + "items": { + "type": "object", + "required": ["repo", "title", "body"], + "properties": { + "repo": { + "type": "string", + "pattern": "^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$" + }, + "title": { + "type": "string", + "minLength": 1 + }, + "body": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false + } + } + }, + "additionalProperties": false }, "label_actions": { "$ref": "#/$defs/label_actions" @@ -53,8 +91,18 @@ "then": { "required": ["clarity_scores", "triage_summary"] } }, { - "if": { "properties": { "action": { "const": "blocked" } }, "required": ["action"] }, - "then": { "required": ["blocked_by"] } + "if": { "properties": { "action": { "const": "prerequisites" } }, "required": ["action"] }, + "then": { + "required": ["prerequisites"], + "properties": { + "prerequisites": { + "anyOf": [ + { "properties": { "existing": { "minItems": 1 } } }, + { "properties": { "create": { "minItems": 1 } } } + ] + } + } + } } ], "$defs": { diff --git a/internal/scaffold/fullsend-repo/scripts/lib/github-api-csma.sh b/internal/scaffold/fullsend-repo/scripts/lib/github-api-csma.sh index a281397e2..f3870ad1a 100644 --- a/internal/scaffold/fullsend-repo/scripts/lib/github-api-csma.sh +++ b/internal/scaffold/fullsend-repo/scripts/lib/github-api-csma.sh @@ -14,6 +14,7 @@ # GITHUB_CSMA_MIN_REMAINING_GRAPHQL — default 100 # GITHUB_CSMA_SLOT_MIN_MS — default 250 # GITHUB_CSMA_SLOT_MAX_MS — default 750 (0 disables jitter) +# GITHUB_CSMA_SPREAD_MAX_SEC — default 60 (post-reset desync spread) # GITHUB_CSMA_BACKOFF_CAP_SEC — default 120 # shellcheck shell=bash @@ -41,10 +42,26 @@ _github_csma_slot_max_ms() { echo "${GITHUB_CSMA_SLOT_MAX_MS:-750}" } +_github_csma_spread_max_sec() { + echo "${GITHUB_CSMA_SPREAD_MAX_SEC:-60}" +} + _github_csma_backoff_cap_sec() { echo "${GITHUB_CSMA_BACKOFF_CAP_SEC:-120}" } +# Add a random spread delay after a rate-limit sleep to desynchronize runners. +# Called from both github_csma_sense and _github_csma_sleep_after_rate_limit. +_github_csma_post_reset_spread() { + local spread_max + spread_max=$(_github_csma_spread_max_sec) + if (( spread_max > 0 )); then + local spread_secs=$(( RANDOM % spread_max )) + echo "Rate limit reset — spreading ${spread_secs}s to desync from other runners..." >&2 + sleep "${spread_secs}" + fi +} + _github_csma_emit_failure() { printf '%s\n' "$1" >&2 } @@ -85,6 +102,10 @@ github_csma_sense() { echo "Rate limit sense: ${resource} remaining=${remaining} (min=${min_remaining}); waiting ${wait_secs}s until reset..." >&2 sleep "${wait_secs}" + + # After a rate-limit sleep, all runners wake at the same reset timestamp. + # Spread them over a wide window to avoid a thundering herd. + _github_csma_post_reset_spread } # Random inter-call delay (slot time) to reduce synchronized collisions. @@ -161,6 +182,9 @@ _github_csma_sleep_after_rate_limit() { fi echo "GitHub API rate limit (attempt $(( attempt + 1 ))); backing off ${delay}s..." >&2 sleep "${delay}" + + # After backing off, spread runners to avoid thundering herd on wake. + _github_csma_post_reset_spread } # Run gh with CSMA/CD. First argument: rate_limit resource (core|graphql). diff --git a/internal/scaffold/fullsend-repo/scripts/post-triage-test.sh b/internal/scaffold/fullsend-repo/scripts/post-triage-test.sh index c8b4eb29e..1cf26237e 100755 --- a/internal/scaffold/fullsend-repo/scripts/post-triage-test.sh +++ b/internal/scaffold/fullsend-repo/scripts/post-triage-test.sh @@ -27,6 +27,12 @@ if [[ "\$1" == "api" ]] && [[ "\$2" == *"/labels" ]] && [[ "\$*" == *"--paginate printf '%s\n' "area/api" "area/cli" "priority/high" "component/parser" exit 0 fi +# For issue create, return a fake URL on stdout so callers can capture it. +if [[ "\$1" == "issue" ]] && [[ "\$2" == "create" ]]; then + echo "gh \$*" >> "${GH_LOG}" + echo "https://github.com/mock-org/mock-repo/issues/999" + exit 0 +fi echo "gh \$*" >> "${GH_LOG}" MOCKEOF chmod +x "${MOCK_BIN}/gh" @@ -53,6 +59,22 @@ export PATH="${MOCK_BIN}:${PATH}" export GITHUB_ISSUE_URL="https://github.com/test-org/test-repo/issues/42" export GH_TOKEN="fake-token" +# prerequisites handler reads config.yaml from GITHUB_WORKSPACE. +# Create a minimal workspace with an allowlist so the test can exercise +# both the allowed and disallowed paths. +WORKSPACE="${TMPDIR}/workspace" +mkdir -p "${WORKSPACE}" +cat > "${WORKSPACE}/config.yaml" </dev/null; then + echo "::warning::yq not found — cannot read create_issues.allow_targets from config; cross-repo issue creation disabled" + fi + if [[ -f "${CONFIG_FILE}" ]] && command -v yq &>/dev/null; then + ALLOWED_ORGS=$(yq -r '.create_issues.allow_targets.orgs // [] | .[]' "${CONFIG_FILE}" 2>/dev/null || true) + ALLOWED_REPOS=$(yq -r '.create_issues.allow_targets.repos // [] | .[]' "${CONFIG_FILE}" 2>/dev/null || true) fi - echo "Blocked by: ${BLOCKED_BY}" + + # The source repo is always implicitly allowed. + is_target_allowed() { + local target_repo="$1" + local target_org="${target_repo%%/*}" + + # Source repo is always allowed. + if [[ "${target_repo}" == "${REPO}" ]]; then + return 0 + fi + + # Check org allowlist. + if [[ -n "${ALLOWED_ORGS}" ]] && echo "${ALLOWED_ORGS}" | grep -qFx "${target_org}"; then + return 0 + fi + + # Check repo allowlist. + if [[ -n "${ALLOWED_REPOS}" ]] && echo "${ALLOWED_REPOS}" | grep -qFx "${target_repo}"; then + return 0 + fi + + return 1 + } + + # Process create entries: create issues, collect URLs. + CREATE_COUNT=$(jq '.prerequisites.create // [] | length' "${RESULT_FILE}") + CREATED_URLS="" + FAILED_CREATES="" + + for i in $(seq 0 $((CREATE_COUNT - 1))); do + TARGET_REPO=$(jq -r ".prerequisites.create[${i}].repo" "${RESULT_FILE}") + ISSUE_TITLE=$(jq -r ".prerequisites.create[${i}].title" "${RESULT_FILE}") + ISSUE_BODY=$(jq -r ".prerequisites.create[${i}].body" "${RESULT_FILE}") + + if ! is_target_allowed "${TARGET_REPO}"; then + echo "::warning::Skipping issue creation in '${TARGET_REPO}' — not in create_issues.allow_targets" + FAILED_CREATES="${FAILED_CREATES} +
+Prerequisite: ${TARGET_REPO} — ${ISSUE_TITLE} + +${ISSUE_BODY} + +
" + continue + fi + + echo "Creating prerequisite issue in ${TARGET_REPO}..." + CREATED_URL=$(gh issue create --repo "${TARGET_REPO}" --title "${ISSUE_TITLE}" --body "${ISSUE_BODY}" 2>&1) || { + echo "::warning::Failed to create issue in '${TARGET_REPO}': ${CREATED_URL}" + FAILED_CREATES="${FAILED_CREATES} +
+Prerequisite: ${TARGET_REPO} — ${ISSUE_TITLE} + +${ISSUE_BODY} + +
" + continue + } + echo "Created: ${CREATED_URL}" + CREATED_URLS="${CREATED_URLS} ${CREATED_URL}" + done + + # Collect existing URLs. + EXISTING_COUNT=$(jq '.prerequisites.existing // [] | length' "${RESULT_FILE}") + EXISTING_URLS="" + for i in $(seq 0 $((EXISTING_COUNT - 1))); do + URL=$(jq -r ".prerequisites.existing[${i}].url" "${RESULT_FILE}") + EXISTING_URLS="${EXISTING_URLS} ${URL}" + done + + # Merge all blocker URLs for the comment. + ALL_URLS="${EXISTING_URLS} ${CREATED_URLS}" + ALL_URLS=$(echo "${ALL_URLS}" | xargs) # trim whitespace + + if [[ -n "${ALL_URLS}" ]]; then + BLOCKER_LIST="" + for url in ${ALL_URLS}; do + BLOCKER_LIST="${BLOCKER_LIST} +- ${url}" + done + COMMENT="${COMMENT} + +**Blocked by:**${BLOCKER_LIST}" + fi + + if [[ -n "${FAILED_CREATES}" ]]; then + COMMENT="${COMMENT} + +**Could not create automatically** (file manually or update \`create_issues.allow_targets\` in config.yaml): +${FAILED_CREATES}" + fi + remove_label "ready-to-code" remove_label "needs-info" add_label "blocked" diff --git a/internal/scaffold/fullsend-repo/scripts/validate-output-schema-test.sh b/internal/scaffold/fullsend-repo/scripts/validate-output-schema-test.sh index 6c43fe044..44bd813ac 100755 --- a/internal/scaffold/fullsend-repo/scripts/validate-output-schema-test.sh +++ b/internal/scaffold/fullsend-repo/scripts/validate-output-schema-test.sh @@ -70,12 +70,12 @@ run_test "valid-question" \ '{"action":"question","reasoning":"this is a support question","comment":"Based on the docs, Python 4 is not supported. Would you like to open a feature request?"}' \ "true" -run_test "valid-blocked-issue" \ - '{"action":"blocked","reasoning":"upstream dependency","blocked_by":"https://github.com/org/repo/issues/99","comment":"Blocked on upstream."}' \ +run_test "valid-prerequisites-existing" \ + '{"action":"prerequisites","reasoning":"upstream dependency","prerequisites":{"existing":[{"url":"https://github.com/org/repo/issues/99"}],"create":[]},"comment":"Blocked on upstream."}' \ "true" -run_test "valid-blocked-pr" \ - '{"action":"blocked","reasoning":"waiting on PR","blocked_by":"https://github.com/org/repo/pull/55","comment":"Blocked on a PR."}' \ +run_test "valid-prerequisites-create" \ + '{"action":"prerequisites","reasoning":"needs upstream issue","prerequisites":{"existing":[],"create":[{"repo":"org/upstream","title":"Add X","body":"Need X."}]},"comment":"Blocked on upstream."}' \ "true" # --- Conditional requirement failures --- @@ -92,12 +92,16 @@ run_test "sufficient-missing-triage-summary" \ '{"action":"sufficient","reasoning":"ok","clarity_scores":{"symptom":0.9,"cause":0.8,"reproduction":0.9,"impact":0.7,"overall":0.85},"comment":"Done."}' \ "false" -run_test "blocked-missing-blocked-by" \ - '{"action":"blocked","reasoning":"upstream dependency","comment":"Blocked."}' \ +run_test "prerequisites-missing-prerequisites-field" \ + '{"action":"prerequisites","reasoning":"upstream dependency","comment":"Blocked."}' \ "false" -run_test "blocked-malformed-url" \ - '{"action":"blocked","reasoning":"upstream dependency","blocked_by":"not-a-url","comment":"Blocked."}' \ +run_test "prerequisites-both-arrays-empty" \ + '{"action":"prerequisites","reasoning":"upstream dependency","prerequisites":{"existing":[],"create":[]},"comment":"Blocked."}' \ + "false" + +run_test "prerequisites-malformed-url-in-existing" \ + '{"action":"prerequisites","reasoning":"upstream dependency","prerequisites":{"existing":[{"url":"not-a-url"}],"create":[]},"comment":"Blocked."}' \ "false" # --- FULLSEND_OUTPUT_FILE override --- @@ -288,7 +292,7 @@ run_test_output "additional-properties-shows-allowed" \ run_test_output "additional-properties-lists-known-keys" \ '{"action":"sufficient","reasoning":"ok","clarity_scores":{"symptom":0.9,"cause":0.8,"reproduction":0.9,"impact":0.7,"overall":0.85},"triage_summary":{"title":"Bug","severity":"high","category":"bug","problem":"crash","root_cause_hypothesis":"null ptr","reproduction_steps":["step 1"],"impact":"all users","recommended_fix":"fix","proposed_test_case":"test"},"comment":"Done.","injected_field":"malicious"}' \ "false" \ - "action, blocked_by, clarity_scores, comment, duplicate_of, label_actions, reasoning, triage_summary" + "action, clarity_scores, comment, duplicate_of, label_actions, prerequisites, reasoning, triage_summary" run_test_output "valid-output-no-allowed-line" \ '{"action":"insufficient","reasoning":"missing repro","clarity_scores":{"symptom":0.6,"cause":0.3,"reproduction":0.1,"impact":0.5,"overall":0.39},"comment":"Can you share repro steps?"}' \ diff --git a/internal/scaffold/pathpresence.go b/internal/scaffold/pathpresence.go new file mode 100644 index 000000000..ccecb8212 --- /dev/null +++ b/internal/scaffold/pathpresence.go @@ -0,0 +1,37 @@ +package scaffold + +import ( + "context" + "fmt" + "sort" + + "github.com/fullsend-ai/fullsend/internal/forge" +) + +// ComparePathPresence checks which expected paths exist in the repo's +// default branch. It uses forge.Client.ListRepositoryFiles to fetch all +// file paths in a single Git Trees API call, then checks membership +// locally. This replaces O(N) GetFileContent calls with O(1) API calls. +func ComparePathPresence(ctx context.Context, client forge.Client, owner, repo string, expected []string) (missing []string, err error) { + if len(expected) == 0 { + return nil, nil + } + + allPaths, err := client.ListRepositoryFiles(ctx, owner, repo) + if err != nil { + return nil, fmt.Errorf("listing repository files: %w", err) + } + + existing := make(map[string]struct{}, len(allPaths)) + for _, p := range allPaths { + existing[p] = struct{}{} + } + + for _, path := range expected { + if _, ok := existing[path]; !ok { + missing = append(missing, path) + } + } + sort.Strings(missing) + return missing, nil +} diff --git a/internal/scaffold/pathpresence_test.go b/internal/scaffold/pathpresence_test.go new file mode 100644 index 000000000..cd0d76062 --- /dev/null +++ b/internal/scaffold/pathpresence_test.go @@ -0,0 +1,113 @@ +package scaffold + +import ( + "context" + "errors" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/fullsend-ai/fullsend/internal/forge" +) + +func TestComparePathPresence_AllPresent(t *testing.T) { + client := &forge.FakeClient{ + FileContents: map[string][]byte{ + "org/.fullsend/.defaults/action.yml": []byte("marker"), + "org/.fullsend/.github/workflows/reusable-triage.yml": []byte("wf"), + "org/.fullsend/bin/fullsend": []byte("binary"), + }, + } + + missing, err := ComparePathPresence(context.Background(), client, "org", ".fullsend", []string{ + ".defaults/action.yml", + ".github/workflows/reusable-triage.yml", + "bin/fullsend", + }) + require.NoError(t, err) + assert.Empty(t, missing) +} + +func TestComparePathPresence_SomeMissing(t *testing.T) { + client := &forge.FakeClient{ + FileContents: map[string][]byte{ + "org/.fullsend/.defaults/action.yml": []byte("marker"), + "org/.fullsend/bin/fullsend": []byte("binary"), + }, + } + + missing, err := ComparePathPresence(context.Background(), client, "org", ".fullsend", []string{ + ".defaults/action.yml", + ".github/workflows/reusable-triage.yml", + ".github/workflows/reusable-code.yml", + "bin/fullsend", + }) + require.NoError(t, err) + assert.Equal(t, []string{ + ".github/workflows/reusable-code.yml", + ".github/workflows/reusable-triage.yml", + }, missing) +} + +func TestComparePathPresence_AllMissing(t *testing.T) { + client := &forge.FakeClient{ + FileContents: map[string][]byte{}, + } + + missing, err := ComparePathPresence(context.Background(), client, "org", ".fullsend", []string{ + ".defaults/action.yml", + "bin/fullsend", + }) + require.NoError(t, err) + assert.Equal(t, []string{".defaults/action.yml", "bin/fullsend"}, missing) +} + +func TestComparePathPresence_EmptyExpected(t *testing.T) { + client := &forge.FakeClient{ + FileContents: map[string][]byte{ + "org/.fullsend/bin/fullsend": []byte("binary"), + }, + } + + missing, err := ComparePathPresence(context.Background(), client, "org", ".fullsend", nil) + require.NoError(t, err) + assert.Nil(t, missing) +} + +func TestComparePathPresence_ForgeError(t *testing.T) { + client := &forge.FakeClient{ + Errors: map[string]error{ + "ListRepositoryFiles": errors.New("network error"), + }, + } + + _, err := ComparePathPresence(context.Background(), client, "org", ".fullsend", []string{ + ".defaults/action.yml", + }) + require.Error(t, err) + assert.Contains(t, err.Error(), "listing repository files") +} + +func TestComparePathPresence_UsesOneAPICall(t *testing.T) { + // Verify that ComparePathPresence uses ListRepositoryFiles (batch) + // rather than per-path GetFileContent. We inject an error on + // GetFileContent to ensure it is never called. + client := &forge.FakeClient{ + FileContents: map[string][]byte{ + "org/repo/path-a": []byte("a"), + "org/repo/path-b": []byte("b"), + }, + Errors: map[string]error{ + "GetFileContent": errors.New("should not be called"), + }, + } + + missing, err := ComparePathPresence(context.Background(), client, "org", "repo", []string{ + "path-a", + "path-b", + "path-c", + }) + require.NoError(t, err) + assert.Equal(t, []string{"path-c"}, missing) +} diff --git a/internal/scaffold/qf_pathpresence_test.go b/internal/scaffold/qf_pathpresence_test.go new file mode 100644 index 000000000..3fe9006fa --- /dev/null +++ b/internal/scaffold/qf_pathpresence_test.go @@ -0,0 +1,124 @@ +package scaffold + +// QualityFlow generated tests for GH-72 +// Suite: TS-GH72-001 — ComparePathPresence batch path checking +// STD: outputs/std/GH-72/GH-72_test_description.yaml + +import ( + "context" + "errors" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/fullsend-ai/fullsend/internal/forge" +) + +// TC-GH72-001: All expected paths are present in repository +func TestQFComparePathPresence_AllPresent(t *testing.T) { + client := &forge.FakeClient{ + FileContents: map[string][]byte{ + "org/.fullsend/.defaults/action.yml": []byte("marker"), + "org/.fullsend/.github/workflows/reusable-triage.yml": []byte("wf"), + "org/.fullsend/bin/fullsend": []byte("binary"), + }, + } + + missing, err := ComparePathPresence(context.Background(), client, "org", ".fullsend", []string{ + ".defaults/action.yml", + ".github/workflows/reusable-triage.yml", + "bin/fullsend", + }) + require.NoError(t, err) + assert.Empty(t, missing, "all expected paths exist, missing should be empty") +} + +// TC-GH72-002: Some expected paths are missing from repository +func TestQFComparePathPresence_SomeMissing(t *testing.T) { + client := &forge.FakeClient{ + FileContents: map[string][]byte{ + "org/.fullsend/.defaults/action.yml": []byte("marker"), + "org/.fullsend/bin/fullsend": []byte("binary"), + }, + } + + missing, err := ComparePathPresence(context.Background(), client, "org", ".fullsend", []string{ + ".defaults/action.yml", + ".github/workflows/reusable-triage.yml", + ".github/workflows/reusable-code.yml", + "bin/fullsend", + }) + require.NoError(t, err) + assert.Equal(t, []string{ + ".github/workflows/reusable-code.yml", + ".github/workflows/reusable-triage.yml", + }, missing, "missing paths should be returned in sorted order") +} + +// TC-GH72-003: All expected paths are missing from empty repository +func TestQFComparePathPresence_AllMissing(t *testing.T) { + client := &forge.FakeClient{ + FileContents: map[string][]byte{}, + } + + missing, err := ComparePathPresence(context.Background(), client, "org", ".fullsend", []string{ + ".defaults/action.yml", + "bin/fullsend", + }) + require.NoError(t, err) + assert.Equal(t, []string{".defaults/action.yml", "bin/fullsend"}, missing, + "all expected paths should appear in missing list") +} + +// TC-GH72-004: Empty expected list returns no missing paths +func TestQFComparePathPresence_EmptyExpected(t *testing.T) { + client := &forge.FakeClient{ + FileContents: map[string][]byte{ + "org/.fullsend/bin/fullsend": []byte("binary"), + }, + } + + missing, err := ComparePathPresence(context.Background(), client, "org", ".fullsend", nil) + require.NoError(t, err) + assert.Nil(t, missing, "nil expected slice should return nil missing slice without API call") +} + +// TC-GH72-005: Forge client error is propagated +func TestQFComparePathPresence_ForgeError(t *testing.T) { + client := &forge.FakeClient{ + Errors: map[string]error{ + "ListRepositoryFiles": errors.New("network error"), + }, + } + + _, err := ComparePathPresence(context.Background(), client, "org", ".fullsend", []string{ + ".defaults/action.yml", + }) + require.Error(t, err) + assert.Contains(t, err.Error(), "listing repository files", + "error should wrap the original forge client error") +} + +// TC-GH72-006: Uses single batch API call instead of per-path GetFileContent +func TestQFComparePathPresence_UsesOneAPICall(t *testing.T) { + // Inject GetFileContent error as a trip-wire to prove it is never called. + // ComparePathPresence must use ListRepositoryFiles exclusively. + client := &forge.FakeClient{ + FileContents: map[string][]byte{ + "org/repo/path-a": []byte("a"), + "org/repo/path-b": []byte("b"), + }, + Errors: map[string]error{ + "GetFileContent": errors.New("should not be called"), + }, + } + + missing, err := ComparePathPresence(context.Background(), client, "org", "repo", []string{ + "path-a", + "path-b", + "path-c", + }) + require.NoError(t, err, "GetFileContent should never be called — only ListRepositoryFiles") + assert.Equal(t, []string{"path-c"}, missing) +} diff --git a/internal/statuscomment/qf_statuscomment_factory_test.go b/internal/statuscomment/qf_statuscomment_factory_test.go new file mode 100644 index 000000000..a42f6084f --- /dev/null +++ b/internal/statuscomment/qf_statuscomment_factory_test.go @@ -0,0 +1,252 @@ +package statuscomment + +// QualityFlow generated tests for GH-72 +// Suite: TS-GH72-003 — StatusComment Notifier ClientFactory pattern +// STD: outputs/std/GH-72/GH-72_test_description.yaml + +import ( + "context" + "fmt" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/fullsend-ai/fullsend/internal/config" + "github.com/fullsend-ai/fullsend/internal/forge" +) + +func qfFixedTime() time.Time { + return time.Date(2026, 6, 3, 14, 34, 0, 0, time.UTC) +} + +func newQFNotifier(fc *forge.FakeClient, cfg config.StatusNotificationConfig) *Notifier { + fc.AuthenticatedUser = "fullsend-bot[bot]" + n := New(fc, cfg, "org", "repo", 7, "https://ci/run/42", "a1b2c3d4e5f6789", "run-42") + n.now = qfFixedTime + return n +} + +// TC-GH72-009: ClientFactory called before PostStart API operations +func TestQFClientFactory_CalledBeforePostStart(t *testing.T) { + fc1 := forge.NewFakeClient() + fc2 := forge.NewFakeClient() + fc2.AuthenticatedUser = "mint-bot[bot]" + cfg := config.StatusNotificationConfig{} + + n := New(fc1, cfg, "org", "repo", 7, "https://ci/run/42", "a1b2c3d", "run-42") + n.now = qfFixedTime + + factoryCalled := false + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + factoryCalled = true + return fc2, nil + }) + + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + assert.True(t, factoryCalled, "factory should be called before PostStart API calls") + assert.Len(t, fc2.IssueComments["org/repo/7"], 1, "comment should be on factory-returned client") + assert.Empty(t, fc1.IssueComments, "original client should not be used") +} + +// TC-GH72-010: ClientFactory called before PostCompletion API operations +func TestQFClientFactory_CalledBeforePostCompletion(t *testing.T) { + fc := forge.NewFakeClient() + fc.AuthenticatedUser = "bot[bot]" + cfg := config.StatusNotificationConfig{ + Comment: config.CommentNotificationConfig{Start: "enabled", Completion: "enabled"}, + } + + n := newQFNotifier(fc, cfg) + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + + fc2 := forge.NewFakeClient() + fc2.AuthenticatedUser = "bot[bot]" + fc2.IssueComments = map[string][]forge.IssueComment{ + "org/repo/7": {fc.IssueComments["org/repo/7"][0]}, + } + + completionFactoryCalled := false + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + completionFactoryCalled = true + return fc2, nil + }) + + n.now = func() time.Time { return qfFixedTime().Add(5 * time.Minute) } + err = n.PostCompletion(context.Background(), "Working", "success") + require.NoError(t, err) + assert.True(t, completionFactoryCalled, "factory should be called before PostCompletion API calls") +} + +// TC-GH72-011: ClientFactory error propagated on PostStart +func TestQFClientFactory_ErrorPropagated(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{} + n := New(fc, cfg, "org", "repo", 7, "", "", "run-42") + n.now = qfFixedTime + + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + return nil, fmt.Errorf("mint service unavailable") + }) + + err := n.PostStart(context.Background(), "Working") + require.Error(t, err) + assert.Contains(t, err.Error(), "mint service unavailable", + "factory error should be propagated, not swallowed") +} + +// TC-GH72-012: Static client used when no factory is set +func TestQFClientFactory_NilUsesStaticClient(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{} + n := newQFNotifier(fc, cfg) + + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + assert.Len(t, fc.IssueComments["org/repo/7"], 1, + "static client should be used when no factory set") +} + +// TC-GH72-013: Completion-disabled path mints then deletes start comment +func TestQFClientFactory_CompletionDisabled_DeletePath(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{ + Comment: config.CommentNotificationConfig{Start: "enabled", Completion: "disabled"}, + } + n := newQFNotifier(fc, cfg) + + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + require.Equal(t, 1, n.startCommentID) + + fc2 := forge.NewFakeClient() + fc2.AuthenticatedUser = "fullsend-bot[bot]" + fc2.IssueComments = map[string][]forge.IssueComment{ + "org/repo/7": {fc.IssueComments["org/repo/7"][0]}, + } + + factoryCalled := false + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + factoryCalled = true + return fc2, nil + }) + + n.now = func() time.Time { return qfFixedTime().Add(time.Minute) } + err = n.PostCompletion(context.Background(), "Working", "success") + require.NoError(t, err) + assert.True(t, factoryCalled, "factory should be called even when completion disabled (for delete)") + require.Len(t, fc2.DeletedComments, 1) + assert.Equal(t, 1, fc2.DeletedComments[0]) +} + +// TC-GH72-014: HasClientFactory reports factory presence +func TestQFHasClientFactory(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{} + n := newQFNotifier(fc, cfg) + + assert.False(t, n.HasClientFactory(), "should be false when no factory set") + + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + return fc, nil + }) + assert.True(t, n.HasClientFactory(), "should be true after SetClientFactory") +} + +// TC-GH72-015: ClientFactory error on PostCompletion propagated +func TestQFClientFactory_ErrorOnPostCompletion(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{ + Comment: config.CommentNotificationConfig{Start: "enabled", Completion: "enabled"}, + } + n := newQFNotifier(fc, cfg) + + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + return nil, fmt.Errorf("token expired") + }) + + n.now = func() time.Time { return qfFixedTime().Add(5 * time.Minute) } + err = n.PostCompletion(context.Background(), "Working", "success") + require.Error(t, err) + assert.Contains(t, err.Error(), "token expired") +} + +// TC-GH72-016: Both disabled means no factory call +func TestQFClientFactory_BothDisabled_NoMint(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{ + Comment: config.CommentNotificationConfig{Start: "disabled", Completion: "disabled"}, + } + n := newQFNotifier(fc, cfg) + + factoryCalled := false + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + factoryCalled = true + return nil, fmt.Errorf("should not be called") + }) + + err := n.PostCompletion(context.Background(), "Working", "success") + require.NoError(t, err, "should not error when no API call is needed") + assert.False(t, factoryCalled, "factory should not be called when both disabled and no start comment") +} + +// TC-GH72-017: Completion-disabled mint error is fail-open with warning +func TestQFClientFactory_CompletionDisabled_MintError(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{ + Comment: config.CommentNotificationConfig{Start: "enabled", Completion: "disabled"}, + } + n := newQFNotifier(fc, cfg) + + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + require.NotZero(t, n.startCommentID) + + var warnings []string + n.SetWarnFunc(func(format string, args ...any) { + warnings = append(warnings, fmt.Sprintf(format, args...)) + }) + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + return nil, fmt.Errorf("mint service down") + }) + + err = n.PostCompletion(context.Background(), "Working", "success") + require.NoError(t, err, "should not return error — fail-open on cleanup") + require.Len(t, warnings, 1) + assert.Contains(t, warnings[0], "mint service down") +} + +// TC-GH72-018: Completion-disabled delete error is fail-open with warning +func TestQFClientFactory_CompletionDisabled_DeleteError(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{ + Comment: config.CommentNotificationConfig{Start: "enabled", Completion: "disabled"}, + } + n := newQFNotifier(fc, cfg) + + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + require.NotZero(t, n.startCommentID) + + fc2 := forge.NewFakeClient() + fc2.Errors["DeleteIssueComment"] = fmt.Errorf("forbidden") + + var warnings []string + n.SetWarnFunc(func(format string, args ...any) { + warnings = append(warnings, fmt.Sprintf(format, args...)) + }) + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + return fc2, nil + }) + + err = n.PostCompletion(context.Background(), "Working", "success") + require.NoError(t, err, "should not return error — fail-open on cleanup") + require.Len(t, warnings, 1) + assert.Contains(t, warnings[0], "forbidden") +} diff --git a/internal/statuscomment/statuscomment.go b/internal/statuscomment/statuscomment.go index fc24655fe..2cef62463 100644 --- a/internal/statuscomment/statuscomment.go +++ b/internal/statuscomment/statuscomment.go @@ -38,15 +38,20 @@ const ( // now is overridable in tests to fix the current time for ReconcileOrphaned. var now = time.Now +// ClientFactory returns a fresh forge.Client. It is called before each +// API operation so the underlying token is never stale. +type ClientFactory func(ctx context.Context) (forge.Client, error) + // Notifier manages status comment lifecycle for a single agent run. type Notifier struct { - client forge.Client - cfg config.StatusNotificationConfig - owner, repo string - number int - runURL string - sha string - marker string + client forge.Client + clientFactory ClientFactory + cfg config.StatusNotificationConfig + owner, repo string + number int + runURL string + sha string + marker string startCommentID int startTime time.Time @@ -79,6 +84,32 @@ func (n *Notifier) SetWarnFunc(f func(string, ...any)) { n.warnf = f } +// SetClientFactory sets a factory that mints a fresh forge.Client before +// each API operation. When set, the static client passed to New is only +// used if the factory is nil. +func (n *Notifier) SetClientFactory(f ClientFactory) { + n.clientFactory = f +} + +// HasClientFactory reports whether a client factory has been configured. +func (n *Notifier) HasClientFactory() bool { + return n.clientFactory != nil +} + +// refreshClient replaces n.client with a freshly minted client when a +// factory is configured. Returns an error only if the factory itself fails. +func (n *Notifier) refreshClient(ctx context.Context) error { + if n.clientFactory == nil { + return nil + } + c, err := n.clientFactory(ctx) + if err != nil { + return fmt.Errorf("minting fresh client: %w", err) + } + n.client = c + return nil +} + func commentEnabled(val string) bool { return val == "" || val == "enabled" } @@ -88,6 +119,9 @@ func (n *Notifier) PostStart(ctx context.Context, description string) error { n.startTime = n.now().UTC() if commentEnabled(n.cfg.Comment.Start) { + if err := n.refreshClient(ctx); err != nil { + return err + } body := n.buildStartBody(description) comment, err := n.client.CreateIssueComment(ctx, n.owner, n.repo, n.number, body) if err != nil { @@ -119,13 +153,19 @@ func (n *Notifier) PostCompletion(ctx context.Context, description, status strin // Completion comments disabled — clean up the start comment so it // doesn't remain orphaned in its "Started" state. if n.startCommentID != 0 { - if err := n.client.DeleteIssueComment(ctx, n.owner, n.repo, n.startCommentID); err != nil { + if err := n.refreshClient(ctx); err != nil { + n.warnf("failed to mint token for start comment cleanup: %v", err) + } else if err := n.client.DeleteIssueComment(ctx, n.owner, n.repo, n.startCommentID); err != nil { n.warnf("failed to delete start comment when completion disabled: %v", err) } } return nil } + if err := n.refreshClient(ctx); err != nil { + return err + } + body := n.buildCompletionBody(description, status, completionTime) if n.startCommentID != 0 { diff --git a/internal/statuscomment/statuscomment_test.go b/internal/statuscomment/statuscomment_test.go index 26e349a40..c68e9b895 100644 --- a/internal/statuscomment/statuscomment_test.go +++ b/internal/statuscomment/statuscomment_test.go @@ -869,3 +869,215 @@ func TestReconcileOrphaned_UnknownReasonDefaultsToTerminated(t *testing.T) { assert.Contains(t, body, "Started 6:43 AM UTC") assert.Contains(t, body, "Ended 2:47 PM UTC") } + +func TestClientFactory_CalledBeforePostStart(t *testing.T) { + fc1 := forge.NewFakeClient() + fc2 := forge.NewFakeClient() + fc2.AuthenticatedUser = "mint-bot[bot]" + cfg := config.StatusNotificationConfig{} + + n := New(fc1, cfg, "org", "repo", 7, "https://ci/run/42", "a1b2c3d", "run-42") + n.now = fixedTime + + factoryCalled := false + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + factoryCalled = true + return fc2, nil + }) + + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + assert.True(t, factoryCalled, "factory should be called before PostStart API calls") + assert.Len(t, fc2.IssueComments["org/repo/7"], 1, "comment should be on factory-returned client") + assert.Empty(t, fc1.IssueComments, "original client should not be used") +} + +func TestClientFactory_CalledBeforePostCompletion(t *testing.T) { + fc := forge.NewFakeClient() + fc.AuthenticatedUser = "bot[bot]" + cfg := config.StatusNotificationConfig{ + Comment: config.CommentNotificationConfig{Start: "enabled", Completion: "enabled"}, + } + + n := newTestNotifier(fc, cfg) + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + + fc2 := forge.NewFakeClient() + fc2.AuthenticatedUser = "bot[bot]" + // Pre-populate fc2 with the same comments so analyzeTimeline works. + fc2.IssueComments = map[string][]forge.IssueComment{ + "org/repo/7": {fc.IssueComments["org/repo/7"][0]}, + } + + completionFactoryCalled := false + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + completionFactoryCalled = true + return fc2, nil + }) + + n.now = func() time.Time { return fixedTime().Add(5 * time.Minute) } + err = n.PostCompletion(context.Background(), "Working", "success") + require.NoError(t, err) + assert.True(t, completionFactoryCalled, "factory should be called before PostCompletion API calls") +} + +func TestClientFactory_ErrorPropagated(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{} + n := New(fc, cfg, "org", "repo", 7, "", "", "run-42") + n.now = fixedTime + + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + return nil, fmt.Errorf("mint service unavailable") + }) + + err := n.PostStart(context.Background(), "Working") + require.Error(t, err) + assert.Contains(t, err.Error(), "mint service unavailable") +} + +func TestClientFactory_NilUsesStaticClient(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{} + n := newTestNotifier(fc, cfg) + + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + assert.Len(t, fc.IssueComments["org/repo/7"], 1, "static client should be used when no factory set") +} + +func TestClientFactory_ErrorOnPostCompletion(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{ + Comment: config.CommentNotificationConfig{Start: "enabled", Completion: "enabled"}, + } + n := newTestNotifier(fc, cfg) + + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + return nil, fmt.Errorf("token expired") + }) + + n.now = func() time.Time { return fixedTime().Add(5 * time.Minute) } + err = n.PostCompletion(context.Background(), "Working", "success") + require.Error(t, err) + assert.Contains(t, err.Error(), "token expired") +} + +func TestClientFactory_CompletionDisabled_DeletePath(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{ + Comment: config.CommentNotificationConfig{Start: "enabled", Completion: "disabled"}, + } + n := newTestNotifier(fc, cfg) + + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + require.Equal(t, 1, n.startCommentID) + + fc2 := forge.NewFakeClient() + fc2.AuthenticatedUser = "fullsend-bot[bot]" + fc2.IssueComments = map[string][]forge.IssueComment{ + "org/repo/7": {fc.IssueComments["org/repo/7"][0]}, + } + + factoryCalled := false + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + factoryCalled = true + return fc2, nil + }) + + n.now = func() time.Time { return fixedTime().Add(time.Minute) } + err = n.PostCompletion(context.Background(), "Working", "success") + require.NoError(t, err) + assert.True(t, factoryCalled, "factory should be called even when completion disabled (for delete)") + require.Len(t, fc2.DeletedComments, 1) + assert.Equal(t, 1, fc2.DeletedComments[0]) +} + +func TestClientFactory_BothDisabled_NoMint(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{ + Comment: config.CommentNotificationConfig{Start: "disabled", Completion: "disabled"}, + } + n := newTestNotifier(fc, cfg) + + factoryCalled := false + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + factoryCalled = true + return nil, fmt.Errorf("should not be called") + }) + + err := n.PostCompletion(context.Background(), "Working", "success") + require.NoError(t, err, "should not error when no API call is needed") + assert.False(t, factoryCalled, "factory should not be called when both disabled and no start comment") +} + +func TestHasClientFactory(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{} + n := newTestNotifier(fc, cfg) + + assert.False(t, n.HasClientFactory(), "should be false when no factory set") + + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + return fc, nil + }) + assert.True(t, n.HasClientFactory(), "should be true after SetClientFactory") +} + +func TestClientFactory_CompletionDisabled_MintError(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{ + Comment: config.CommentNotificationConfig{Start: "enabled", Completion: "disabled"}, + } + n := newTestNotifier(fc, cfg) + + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + require.NotZero(t, n.startCommentID) + + var warnings []string + n.SetWarnFunc(func(format string, args ...any) { + warnings = append(warnings, fmt.Sprintf(format, args...)) + }) + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + return nil, fmt.Errorf("mint service down") + }) + + err = n.PostCompletion(context.Background(), "Working", "success") + require.NoError(t, err, "should not return error — fail-open on cleanup") + require.Len(t, warnings, 1) + assert.Contains(t, warnings[0], "mint service down") +} + +func TestClientFactory_CompletionDisabled_DeleteError(t *testing.T) { + fc := forge.NewFakeClient() + cfg := config.StatusNotificationConfig{ + Comment: config.CommentNotificationConfig{Start: "enabled", Completion: "disabled"}, + } + n := newTestNotifier(fc, cfg) + + err := n.PostStart(context.Background(), "Working") + require.NoError(t, err) + require.NotZero(t, n.startCommentID) + + fc2 := forge.NewFakeClient() + fc2.Errors["DeleteIssueComment"] = fmt.Errorf("forbidden") + + var warnings []string + n.SetWarnFunc(func(format string, args ...any) { + warnings = append(warnings, fmt.Sprintf(format, args...)) + }) + n.SetClientFactory(func(ctx context.Context) (forge.Client, error) { + return fc2, nil + }) + + err = n.PostCompletion(context.Background(), "Working", "success") + require.NoError(t, err, "should not return error — fail-open on cleanup") + require.Len(t, warnings, 1) + assert.Contains(t, warnings[0], "forbidden") +} diff --git a/skills/e2e-health/SKILL.md b/skills/e2e-health/SKILL.md new file mode 100644 index 000000000..e2cb6b216 --- /dev/null +++ b/skills/e2e-health/SKILL.md @@ -0,0 +1,52 @@ +--- +name: e2e-health +description: > + Use when checking e2e test health or reviewing recent e2e failures on main. +allowed-tools: Bash(bash skills/e2e-health/scripts/list-runs.sh:*), Bash(gh run view:*) +--- + +# E2E Health + +Check the health of the E2E Tests workflow on `main` over the last 2 days, summarize results in a table, and explain any failures. + +## Procedure + +### 1. Fetch recent runs + +```bash +bash skills/e2e-health/scripts/list-runs.sh # default: last 2 days +bash skills/e2e-health/scripts/list-runs.sh "7 days ago" # custom lookback +``` + +The argument is any string `date -d` accepts. Returns JSON with fields: `databaseId`, `displayTitle`, `conclusion`, `status`, `createdAt`, `url`. + +### 2. Present a summary table + +Format the results as a markdown table with clickable links: + +| Status | Run | Commit Title | When | +|--------|-----|--------------|------| +| pass/fail/in_progress | run-id (linked) | displayTitle | relative time | + +Use a green checkmark for success, red X for failure, and a spinner for in-progress. + +To determine the Status column: check `status` first — if it is not `completed`, the run is in-progress (conclusion will be null). If `status` is `completed`, use `conclusion` (`success` or `failure`). + +### 3. Diagnose failures + +For each failed run, fetch the failed step logs: + +```bash +gh run view --log-failed 2>&1 | grep -iE "(FAIL|--- FAIL|Error|panic|timeout)" +``` + +Read the matched lines and provide a brief explanation of why the run failed. Common failure categories: + +- **Flaky test** — timing-dependent or non-deterministic failure +- **Session expired** — GitHub session token needs rotation +- **Infrastructure** — GCP auth, Playwright deps, runner issues +- **Real regression** — a code change broke e2e behavior + +### 4. Overall assessment + +End with a one-line verdict: whether `main` is healthy, degraded, or broken based on the pattern of results. diff --git a/skills/e2e-health/scripts/list-runs.sh b/skills/e2e-health/scripts/list-runs.sh new file mode 100755 index 000000000..7b9475e8c --- /dev/null +++ b/skills/e2e-health/scripts/list-runs.sh @@ -0,0 +1,11 @@ +#!/usr/bin/env bash +set -euo pipefail + +SINCE=$(date -d "${1:-2 days ago}" +%Y-%m-%d) + +gh run list \ + --workflow=e2e.yml \ + --branch=main \ + --created=">=$SINCE" \ + --limit=500 \ + --json databaseId,displayTitle,conclusion,status,createdAt,url