feat(github-app): add command response previews

[mkdev5]

Summary

• Closes feat(github-app): add command response previews #103.
• Adds a protected /v1/app/commands/preview API that lets maintainer/owner/operator users preview sanitized @gittensory command responses without posting comments, labels, or checks.
• Renders command-specific public-safe preview bodies, decisions, sanitizer diagnostics, missing-permission diagnostics, and repo-scoped access checks.
• Extends the OpenAPI contract/UI OpenAPI artifact and adds regression coverage for miner/non-miner, maintainer, missing-permission, sanitizer, auth-scope, no-target, and no-mutation paths.

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 (Node 22 coverage: statements 99.05%, branches 97.05%, functions 98.28%, lines 99.65%)
• 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:mcp-pack was verified with Node 22.22.3 to match .nvmrc/CI.

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

• No visible UI surface changed; UI validation is for the refreshed OpenAPI artifact and app build.
• No changelog update: this is an ordinary feature PR, and CONTRIBUTING.md reserves changelog edits for release prep.
• Local untracked apps/gittensory-ui/public/downloads/ remains unstaged after npm run ui:build.

[dosubot]

Related Knowledge

1 document with suggested updates is ready for review.

gittensory

For Maintainers

View Suggested Changes

@@ -319,6 +319,82 @@
 
 Maintainers can interact with Gittensory directly in GitHub PR and issue threads by mentioning `@gittensory` with a command. These commands provide public-safe intelligence about PRs, contributors, and repository fit without exposing private scoring internals.
 
+### Command Response Preview API
+
+Before posting commands publicly on PR threads, maintainers can preview what Gittensory would respond using the protected `/v1/app/commands/preview` endpoint. This allows dry-running command responses to test output before comments, labels, or checks are posted to GitHub.
+
+**Access control:**
+
+- Protected endpoint requiring maintainer, owner, or operator role
+- Repository-scoped access checks: users can only preview commands for repositories they have access to
+- Operators can preview for any repository
+
+**Request:**
+
+```
+POST /v1/app/commands/preview
+```
+
+Request body:
+
+- `command` — The command to preview (e.g., "preflight", "help", "queue-summary")
+- `repoFullName` — Target repository (e.g., "entrius/allways-ui")
+- `pullNumber` — Target pull request number
+- `login` — Optional user login for context
+- `sample` — Optional sample context to simulate different scenarios:
+  - `authorLogin` — Simulate a specific PR author
+  - `authorType` — "User" or "Bot"
+  - `authorAssociation` — Simulated author association (OWNER, MEMBER, COLLABORATOR, CONTRIBUTOR, NONE)
+  - `commenterLogin` — Simulate a specific commenter
+  - `commenterAssociation` — Simulated commenter association
+  - `minerStatus` — "confirmed", "not_found", or "unavailable"
+  - `title`, `body`, `labels`, `linkedIssues` — Simulated PR metadata
+  - `permissions` — Simulated GitHub App permission map
+  - `missingPermissions` — Array of missing permissions to simulate
+
+**Response:**
+
+The API returns a `CommandPreviewResponse` with:
+
+- **Sanitized response body** — The exact comment text that would be posted to GitHub, with all forbidden terms (wallet, hotkey, payout, reward, farming, scoreability) removed
+- **Decision information:**
+  - `status` — "ready", "skipped", "missing_permission", or "private_api"
+  - `willComment`, `willLabel`, `willCheckRun` — Boolean flags indicating what Gittensory would do
+  - `skipReason` — Why the command would be skipped (if applicable)
+  - `actions` — Array of actions: "comment", "label", "check_run", "skip", or "none"
+  - `summary` — Human-readable decision summary
+- **Missing permissions diagnostics** — List of missing GitHub App permissions that would block the command, with specific remediation actions
+- **Sample context used** — Confirmation of the author, commenter, associations, miner status, PR details, and permissions used to generate the preview
+- **Sanitizer diagnostics** — Shows if any forbidden terms were detected in the response body
+
+**What can be previewed:**
+
+All `@gittensory` mention commands including:
+
+- Public commands: `help`, `preflight`, `blockers`, `duplicate-check`, `miner-context`, `next-action`, `reviewability`, `repo-fit`, `packet`
+- Maintainer-only commands: `queue-summary`, `review-now`, `needs-author`, `confirmed-miners`, `duplicate-clusters`
+- The `public-summary` command (simplified version of `help`)
+
+**What is NOT previewed:**
+
+Private API commands such as `plan-next-work`, `preflight-branch`, `prepare-pr-packet` show a simplified "private API preview only" response indicating the endpoint that would be called, with no GitHub comment, label, or check run.
+
+**Preview guarantees:**
+
+- No GitHub state is mutated: previews never post comments, create labels, update check runs, or call GitHub APIs
+- Responses are sanitized using the same public/private boundary enforcement as live commands
+- Missing GitHub App permissions are detected and reported before the preview is generated
+- Authorization checks are enforced: maintainer-only commands require maintainer associations in the sample context
+- Repo access scope is validated: users cannot preview commands for repositories they don't have access to (unless they have operator role)
+
+**Use cases:**
+
+- Test command responses before they're posted publicly on pull requests
+- Verify output text for maintainer-only digest commands before invoking them in PR threads
+- Simulate different contributor scenarios (confirmed miner vs. non-miner, maintainer vs. outside contributor) to understand how Gittensory would respond
+- Debug missing permissions or authorization issues before live invocation
+- Validate that forbidden terms are properly sanitized from responses
+
 ### How Commands Work
 
 Comment `@gittensory <command>` on any PR or issue thread in an installed repository [[45]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/src/github/commands.ts#L51-L58). Commands are case-insensitive and parsed using the pattern `/(?:^|\s)@gittensory(?:\s+([a-z-]+))?/i`. If no command is specified or an unknown command is provided, the system defaults to the `help` command.

✅ Accepted

^{How did I do? Any feedback?}  

[JSONbored]

@MkDev11 please fix failing CI

[mkdev5]

@MkDev11 please fix failing CI

@JSONbored please review the update

@MkDev11 no current code changes requested. CI is green, the branch is clean, and the previous blocker was stale CI state.