feat(runner): add forge:runner-check adoption-readiness preflight (#245) - #250
Merged
Conversation
Add a single go/no-go command that resolves the runner config (defaults applied) and reports an end-to-end READY / NOT READY verdict, so someone adopting the local self-hosted runner on another project can confirm their whole setup in one shot — broader than doctor's single runner-health line. New command /forge:runner-check (plugin/commands/runner-check.md → plugin/scripts/runner/check.mjs) checks, each ok/warn/fail + fix hint: private-repo guard (FAIL on public — fork-PR RCE), runner block present + enabled, host prerequisites (git/gh/node>=22.13 + docker reachable, native note for windows:native), PAT-store safety, runner registered + online for the configured labels (+ the windows label set when windows:native), scaffold present + verify workflow targets the label, and version staleness. Shared logic is extracted into plugin/scripts/lib/runner-checks.mjs and now reused by BOTH doctor.mjs and check.mjs (private-repo guard, registration probe, secret-store assertion, #233 version check) rather than copy-pasted. The probe gains an offlineLevel option so an offline/unregistered runner is a doctor warn but an adoption-gate FAIL, while a gh-api failure always degrades to a warn. The PAT value is never read or printed. Tests: tests/runner-check.test.mjs (16) — READY when green; NOT READY on public repo / missing block / absent prereq / unsafe store / no online runner; graceful-degrade when gh fails; windows:native two-leg probe. Docs: adoption guide step 5 + reference, runner/README + template. Closes #245 Refs #180 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SATRHKa6mDHDuirhP6QuwL
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Adds
/forge:runner-check— a single go/no-go adoption-readiness preflight for the local self-hosted runner (ADR-0005). It resolves therunnerblock inforge.json(defaults applied) and checks the whole setup end-to-end, so someone adopting the runner on another project can confirm their setup in one shot — broader than the single runner-health lineforge:doctorprints.Closes #245. Refs #180.
The command
plugin/commands/runner-check.md→plugin/scripts/runner/check.mjs. Each check printsok/warn/fail+ a fix hint, ending in a single READY / NOT READY verdict (nonzero exit when NOT READY):git,gh,node(>=22.13) on PATH;dockerreachable (docker info) for the Linux leg; native-runner note forwindows:native.~/.forge/runner.envgitignored + untracked, no committed PAT (never prints the token).windows:native).runner/assets + a verify workflow targeting the label.actions-runneris behind latest.Reuse, not copy-paste
Shared logic is extracted into
plugin/scripts/lib/runner-checks.mjs, now imported by bothdoctor.mjsandcheck.mjs: the private-repo guard, the registration/online probe, the secret-store assertion, and the #233 version check. The probe gained anofflineLeveloption so an offline/unregistered runner is a doctor warn but an adoption-gate fail, while a gh-api failure always degrades to a warn (graceful degradation, never a crash).Verification
pnpm verify— 451/451 green (16 new intests/runner-check.test.mjs; all existing doctor tests still pass against the refactor).claude plugin validate ./plugin --strict— passed.Docs
Adoption guide step 5 + reference/runbook rows;
runner/README.md+ template README get a "Confirm readiness" section.🤖 Generated with Claude Code