feat(activation): one-step maintainer activation preview + advisory ramp (#701)

[JSONbored]

What

Makes the maintainer payoff self-evident at install (#701): a repo-specific demo of what Gittensory would surface on the repo's recent PRs, plus a one-click advisory ramp.

• src/services/maintainer-activation.ts — buildMaintainerActivationPreview runs the deterministic advisory engine (buildPullRequestAdvisory) over the repo's most recent PRs and returns "Gittensory reviewed your N most recent PRs and would have surfaced guidance on M of them": per-PR findings, distinct finding-code counts, the current gate mode, whether AI review is already configured, and the single recommended next action. Pure over already-loaded data; never runs AI (no surprise cost) — it only reports whether AI review is on.
• recommendedAdvisoryActivationSettings() — the one-click patch: enables the gate + deterministic rules in advisory (non-blocking) mode, advisory-first per the roadmap: contribution quality & adoption wave #525 cross-cutting AC. AI review stays opt-in (separate ai-review route).
• Routes (maintainer-scoped via requireRepoMaintainer; new isRepoActivationPath in canSessionAccessPath):
  • GET /v1/repos/:owner/:repo/activation-preview
  • POST /v1/repos/:owner/:repo/activation — merges the advisory patch onto current settings, preserving unrelated fields.

Why / boundaries

Reuses the existing gate engine + repo-settings infra (#647/PR #648) — does not duplicate settings-preview (which previews one hypothetical PR; this previews the repo's real recent PRs). The dashboard rendering of this preview stays owner-led (visual). A live AI run over recent PRs + email remain out of scope (the live AI run would need cached diffs + incur cost).

Access boundary

Both routes are maintainer-scoped (requireRepoMaintainer → role check + per-repo requireSessionRepoAccess); operators and server-to-server tokens bypass per-repo scope by design. No public/miner surface added.

Tests

• maintainer-activation.test.ts (unit): finding summary + counts, recommended-action logic (off → enable / enabled → null), AI-config flag, empty repo, sample-size clamp + recency fallback, code-count tie-break.
• maintainer-activation.test.ts (integration): maintainer preview → one-click flip persists (getRepositorySettings reflects gateCheckMode: enabled) → preview now reports nothing to enable; non-maintainer session → 403; server-to-server token allowed.
• 97% coverage gate green; workers tests + git diff --check + ui:openapi:check pass.

Advances #701 (the non-visual activation-preview service + one-click ramp). Dashboard rendering is the remaining owner-led visual piece.

[ghost]

Note

Gittensory Gate skipped

PR closed before full evaluation. No late first comment was created.

Signal	Result	Evidence	Action
Gate result	⚠️ Skipped	#708 is no longer open.	No action.

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[ghost]

gittensory · advisory review

Reviewed 4 changed file(s) — two independent AI reviewers.

Suggested action: ✅ Safe to merge — both reviewers found no blocking issues.

Reviewer A · gpt-oss-120b — recommends ✅ merge
The PR adds a new maintainer activation preview service and corresponding API routes, along with comprehensive unit and integration tests. The implementation follows existing patterns, respects the maintainer‑only access model, and does not introduce forbidden public terminology.

Suggestions

• Verify that nowIso is imported or defined in the routes file to avoid a runtime ReferenceError.
• Add an integration test for the POST /activation endpoint to confirm that non‑maintainers receive a 403.
• Consider adding a comment noting the expected performance characteristics of listPullRequests for large repositories.

Worth double-checking

• Potential missing import of nowIso could cause the preview route to fail at runtime.
• The new activation routes are now allowed in canSessionAccessPath; ensure no other unintended paths match the regex.

Reviewer B · nemotron-3-120b-a12b — recommends ✅ merge
The PR adds a maintainer activation preview feature (#701) that allows repo maintainers to see what Gittensory would have flagged on recent PRs and one-click enable advisory mode. Changes include a new service file with types and logic, two new API routes (GET activation-preview, POST activation), updated access controls, and comprehensive unit/integration tests. The implementation respects the public/private boundary (maintainer-scoped, uses only public PR data and deterministic advisory engine), follows existing patterns, and is well-tested.

Suggestions

• Consider adding a comment in buildMaintainerActivationPreview explaining why we sort by recencyKey(right).localeCompare(recencyKey(left)) (descending order) for clarity.
• In the activation route, the response could include the full updated settings object for consistency with other settings endpoints, though the current partial response is acceptable.
• The integration test could assert the exact preview structure (e.g., findingCodeCounts empty when no PRs) to increase confidence, but current coverage is sufficient.

Worth double-checking

• Ensure the advisory engine (buildPullRequestAdvisory) used in the preview doesn't inadvertently access private data - but it's already used elsewhere and the preview is maintainer-only.
• Verify that the recencyKey fallback to empty string doesn't cause unexpected ordering when timestamps are missing (tested in unit tests).
• Confirm that the advisory-first settings (recommendedAdvisoryActivationSettings) don't conflict with any existing repository settings logic (they merge onto current settings).