feat: add safe Google Search Console provider adapter

[mohanagy]

Closes #87

What changed

• adds a versioned, typed built-in provider-adapter contract for launch, credential/browser/token ownership, health, reauth, disconnect, identity evidence, diagnostics, manual setup, and destructive posture
• adds a bounded google-search-console preset using exact uvx mcp-search-console@0.3.2
• requires an absolute --oauth-client-secrets-file path, applies a read-only policy, and never enables GSC_ALLOW_DESTRUCTIVE
• prints an audit-safe init ownership summary without echoing the configured client-secrets path
• documents upstream-owned OAuth/token cache behavior, manual setup, and OAuth versus service-account trade-offs
• retains the native oauth.connections boundary for standards-compatible remote HTTPS MCP only

Security boundary

The GSC pilot launches and describes the upstream flow. It does not read, copy, export, delete, or reinterpret the upstream token cache; does not claim Google account identity; does not reimplement Google APIs; and does not expose arbitrary adapter execution.

TDD and validation

Focused red/green coverage was added for the adapter ownership union, exact preset, safe path validation, CLI parsing/help, init output redaction, documentation, and installed-tarball CLI path.

Green locally:

• focused [Extensions] Define a safe provider-adapter contract for non-standard and local OAuth MCPs #87 suites: 63 passed
• npm run test:core: 404 passed, 23 skipped
• npm run lint
• npm run typecheck
• npm run build
• npm run smoke:cli
• npm run check:pack
• npm run test:package: 18 passed, including installed tarball CLI

Known separate local runner behavior:

• exact npm test and npm run test:coverage reproduced the already-open test: diagnose multi-upstream availability cascade under coverage #122 unavailable-child/startup cascade after unrelated suites had passed
• isolated previously timed-out controls passed immediately; no timeouts, coverage, assertions, or subprocess containment were changed
• recurrence evidence is recorded in test: diagnose multi-upstream availability cascade under coverage #122; current-head CI is required before merge

Summary by CodeRabbit

• New Features

  • Added a Google Search Console preset with read-only defaults and guided setup.
  • Added support for providing an OAuth client secrets file during initialization.
  • Added safe provider-adapter guidance covering credentials, browser handoff, identity, reauthentication, and disconnect handling.
  • Added documentation for provider adapters, OAuth boundaries, compatibility, and setup requirements.

• Bug Fixes

  • Ensured sensitive client-secrets file paths are not displayed in command output.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 43 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ee38d3d4-3323-474e-b123-16fec89cf090

📥 Commits

Reviewing files that changed from the base of the PR and between 6e64264 and 50039c3.

📒 Files selected for processing (5)

• src/cli/init.ts
• src/config/presets.ts
• src/config/provider-adapters.ts
• tests/preset-catalog.test.ts
• tests/provider-adapter-contract.test.ts

📝 Walkthrough

Walkthrough

Adds a typed provider-adapter catalog and a bounded Google Search Console preset with exact-pinned upstream launch details, required OAuth client-secrets input, safe CLI guidance, documentation, and end-to-end contract tests.

Changes

Google Search Console provider adapter

Layer / File(s)	Summary
Adapter contract and preset src/config/provider-adapters.ts, src/config/presets.ts, tests/provider-adapter-contract.test.ts, tests/preset-catalog.test.ts	Defines the typed upstream-owned adapter, validates absolute secrets-file paths, adds the version 2 preset catalog entry, generates the pinned uvx configuration, and enforces readonly/destructive-tool defaults.
CLI option and init flow src/cli/parse.ts, src/cli/init.ts, tests/cli-parse.test.ts, tests/init-command.test.ts, tests/package-contract.test.ts	Adds --oauth-client-secrets-file, carries it through interactive and non-interactive initialization, prints ownership guidance, and verifies generated output does not expose the secrets path.
Documentation and package contracts docs/provider-adapters.md, docs/oauth-support.md, docs/presets-and-clients.md, docs/cli.md, README.md, docs/architecture.md, CHANGELOG.md, tests/preset-docs-contract.test.ts	Documents adapter ownership, lifecycle boundaries, the GSC pilot, catalog provenance, CLI requirements, and the packed documentation contract.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Operator
  participant MiftahInit
  participant PresetBuilder
  participant UpstreamMCP
  Operator->>MiftahInit: run init with OAuth client-secrets file
  MiftahInit->>PresetBuilder: build google-search-console preset
  PresetBuilder->>UpstreamMCP: configure pinned uvx launch
  PresetBuilder-->>MiftahInit: return readonly profile and environment mapping
  MiftahInit-->>Operator: print ownership guidance and safe snippets

Loading

Possibly related PRs

• mohanagy/miftah#58: Adds related CLI parsing and help handling for the OAuth client-secrets option.
• mohanagy/miftah#59: Covers related versioned preset-catalog and initialization changes.

Poem

A bunny pinned the upstream train,
With secrets tucked from sight;
The adapter hops through typed terrain,
Keeps destructive tools shut tight.
“Safe launch!” sings the rabbit bright.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Docstring Coverage	❌ Error	Docstring coverage is 36.36% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: adding a safe Google Search Console provider adapter.
Description check	✅ Passed	The description covers summary, security boundary, and validation results, with enough detail despite different headings than the template.
Linked Issues check	✅ Passed	The PR implements the #87 adapter contract, bounded GSC pilot, safety boundaries, tests, and docs required by the linked issue.
Out of Scope Changes check	✅ Passed	The changes stay focused on the provider-adapter contract, Google Search Console pilot, supporting docs, and tests.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/87-provider-adapters

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/config/provider-adapters.ts`:
- Around line 20-24: Update the ProviderAdapterOperation contract to a
discriminated union so operations with mechanism "mcp-tool" require a name,
while preserving the existing optional-name behavior for other mechanisms.
Adjust dependent usages such as the initialization flow in init.ts to honor the
required MCP-tool name, and add a compile-time negative test proving an MCP-tool
operation without name is rejected.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 2a50b754-10cb-4d4e-8554-9e577ac3bf1e

📥 Commits

Reviewing files that changed from the base of the PR and between 01a55d2 and 6e64264.

📒 Files selected for processing (17)

• CHANGELOG.md
• README.md
• docs/architecture.md
• docs/cli.md
• docs/oauth-support.md
• docs/presets-and-clients.md
• docs/provider-adapters.md
• src/cli/init.ts
• src/cli/parse.ts
• src/config/presets.ts
• src/config/provider-adapters.ts
• tests/cli-parse.test.ts
• tests/init-command.test.ts
• tests/package-contract.test.ts
• tests/preset-catalog.test.ts
• tests/preset-docs-contract.test.ts
• tests/provider-adapter-contract.test.ts

[mohanagy]

Current-head review fallback evidence for 50039c3d418fe86c8c86806844d56a84f855319b:

• CodeRabbit current-head status is green but explicitly reports Review rate limited.
• The sole CodeRabbit finding from old head 6e64264 was fixed in 89285db: mcp-tool operations now require a tool name, the init path uses the narrowed contract, and a compile-time negative test covers it. The inline thread is resolved.
• A read-only local Claude Opus review of origin/development...HEAD found two further actionable gaps: literal GSC paths could be reinterpreted by environment expansion, and identity evidence/assurance combinations were not type-constrained.
• Both fallback-review findings were fixed in 50039c3: GSC client-secret paths reject ${NAME} references, and identity evidence/assurance is a discriminated union with a compile-time negative test.
• Focused tests, typecheck, lint, 404-test core suite, build, CLI smoke, pack contract, installed-tarball package contract, and direct uvx mcp-search-console@0.3.2 --help resolution pass. No timeouts, coverage thresholds, Windows containment, or unrelated behavior were changed.

Dismissed as stale after the finding was fixed in 89285db, its thread was resolved, the current-head CodeRabbit check reported rate limited, and a local Opus fallback review was completed with both additional findings fixed in 50039c3.