feat(github-app): add installation repair workflow

[mkdev5]

Summary

• Closes feat(github-app): add installation repair workflow #104.
• Adds protected installation repair diagnostics for GitHub App permissions, webhook events, mode-specific impacts, and repair steps.
• Adds a repair refresh endpoint that rechecks live GitHub App installation metadata and returns updated diagnostics.
• Updates the OpenAPI contract and UI OpenAPI artifact, with regression tests for repair output, refresh behavior, route errors, and sanitizer boundaries.
• Updates the UI known-latest MCP package version to 0.4.0 so the current base branch version-audit gate passes after the latest MCP release.

Scope

• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally; global coverage stays at or above 97% for lines, statements, functions, and branches (aim for 98%+ branch coverage locally so CI variance does not fail near the threshold)
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

If any required check was skipped, explain why:

• None. npm run test:ci passed locally after rebasing onto upstream main at bf45d0c.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.
• Visible UI changes include screenshots or a short recording.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

Notes

• API/OpenAPI: adds GET /v1/installations/{id}/repair and POST /v1/installations/{id}/repair/refresh, plus the InstallationRepair schema.
• No visible UI changes; no screenshots needed.
• Changelog intentionally unchanged per CONTRIBUTING.md ordinary feature PR guidance.
• The MCP version copy update is a one-line base-gate fix for the newly added ui:version-audit check on current main.

[dosubot]

Documentation Updates

1 document(s) were updated by changes in this PR:

For Maintainers

View Changes

@@ -61,7 +61,49 @@
 - Required webhook events are subscribed
 - Installation metadata is current
 
-When permissions or events are missing, the system shows remediation steps [[10]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/src/github/backfill.ts#L674-L682):
+When permissions or events are missing, use the new installation repair diagnostics endpoints to diagnose and resolve configuration issues systematically [[10]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/src/github/backfill.ts#L674-L682).
+
+#### Installation Repair Diagnostics
+
+The installation repair endpoints provide comprehensive diagnostics for GitHub App configuration issues, including mode-specific impact analysis and structured repair steps.
+
+**`GET /v1/installations/{id}/repair`** — Returns detailed diagnostics for the installation:
+
+- **Current installation health** — Status (`healthy`, `needs_attention`, `broken`), missing permissions, missing events, and installed repository count.
+- **Installed repositories** — List of repositories with their settings (`publicSurface`, `commentMode`, `checkRunMode`, `autoLabelEnabled`).
+- **Required and optional permissions** — Permission map showing which permissions are required given the current configuration. For example, if check run mode is enabled for any repo, `Checks: write` moves from optional to required.
+- **Required and optional webhook events** — Event lists showing which webhook subscriptions are needed.
+- **Mode-specific impact analysis** — For each mode (comment, label, check_run):
+  - Whether the mode is enabled across installed repos
+  - How many repos use the mode
+  - Which permissions the mode requires
+  - Whether those permissions are missing
+  - Actionable guidance for resolving missing permissions
+- **Event diagnostics** — For each webhook event:
+  - Whether the event subscription is missing
+  - Whether the event is optional or required
+  - Summary explaining why the event is needed
+  - Action guidance for subscribing to missing events
+- **Repair steps** — Structured list of steps tailored to the current health status:
+  1. Update the GitHub App permissions and subscribed events listed in diagnostics.
+  2. Approve the changed permissions or reinstall the app on the target account.
+  3. Run `POST /v1/installations/{id}/repair/refresh` after GitHub applies the changes.
+  4. Recheck `GET /v1/installations/{id}/repair`.
+
+**`POST /v1/installations/{id}/repair/refresh`** — Refreshes the installation health by rechecking live GitHub App metadata:
+
+- Calls the GitHub API to fetch the latest installation permissions and webhook events.
+- Updates the local installation health record.
+- Returns the same diagnostics structure as the GET endpoint with a `refreshed: true` flag.
+- Use this endpoint after updating GitHub App permissions or webhook subscriptions to verify that the changes have been applied and the installation is now healthy.
+
+The diagnostics are mode-aware: if you enable check run mode for any installed repository, the repair diagnostics will show `Checks: write` as a required permission rather than optional. Similarly, if comment or label modes are enabled, `Issues: write` is required. This mode-specific logic helps maintainers understand exactly why certain permissions are needed and which repos are driving those requirements.
+
+If the installation is healthy, the repair steps simply show "No repair needed."
+
+**Fallback remediation steps:**
+
+If the repair endpoints are unavailable, follow these manual steps:
 
 1. Update the GitHub App permissions and subscribed events.
 2. Approve the changed permissions or reinstall the app on the target account.

^{How did I do? Any feedback?}  

[mkdev5]

@JSONbored please check the PR

[JSONbored]

@MkDev11 please fix merge conflicts 👍🏻

@MkDev11

A few notes:

• The repair diagnostics are a strong fit for #104: they separate required permissions, optional check-run permissions, required events, and mode-specific impact.
• The refresh endpoint gives maintainers a clear recheck path after GitHub App settings change.
• OpenAPI and the generated UI artifact are updated with the new repair routes.

No code changes requested.

[JSONbored]

@MkDev11

A few notes:

• The repair diagnostics are a strong fit for #104: they separate required permissions, optional check-run permissions, required events, and mode-specific impact.
• The refresh endpoint gives maintainers a clear recheck path after GitHub App settings change.
• OpenAPI and the generated UI artifact are updated with the new repair routes.

No code changes requested.