feat(auth): add guided Google setup

[steipete]

Summary

Adds gog auth setup, a guided path through the Google Cloud and OAuth prerequisites that currently require users to assemble several commands and Console pages themselves.

The command can:

• discover the active gcloud account and project;
• create a selected project after confirmation;
• enable the exact Google APIs needed by selected gog services;
• open the project-specific OAuth consent/client pages;
• install a downloaded Desktop OAuth client JSON;
• continue directly into gog auth add with matching account/client resolution;
• emit a complete non-mutating plan through --dry-run --json --no-input.

When gcloud is unavailable, the command remains useful: it emits ordered manual next steps and direct project-scoped Console URLs instead of failing unless a gcloud-only action was explicitly requested.

Design details

• Uses argv-based exec.CommandContext; no shell interpolation.
• Sets CLOUDSDK_CORE_DISABLE_PROMPTS=1 for deterministic automation.
• Validates every incompatible or incomplete flag combination before credentials, project, API, browser, or OAuth side effects.
• Resolves the credential client exactly as auth add does when an email is supplied, preventing a saved-client/login-client mismatch.
• Centralizes service-to-Google-API mappings, with sorting and deduplication for composite services such as Docs and Sheets.
• Avoids the root --project selector alias collision by naming the Cloud flag --gcloud-project (--project-id alias).

User-visible examples

gog auth setup you@gmail.com --gcloud-project my-gog-project --enable-apis --open-console

gog auth setup you@gmail.com --gcloud-project my-gog-project \
  --credentials ~/Downloads/client_secret_*.json --login

gog auth setup --gcloud-project my-gog-project --services gmail,drive \
  --enable-apis --dry-run --json --no-input

Validation

• make ci
• focused command and Google-auth unit tests
• generated 695 command-reference pages; docs coverage passed
• live E2E on clawmac.local: built the branch binary and ran auth setup --services gmail,drive --json --no-input; verified guided fallback status, two mapped APIs, and actionable next steps
• live gcloud probe: gcloud is not installed on that host, confirming the supported no-gcloud fallback without external mutations
• autoreview: clean after fixing two accepted findings (early --open-console validation and shared client resolution)

Safety

The live proof was read-only. No Cloud project was created, no API was enabled, no credentials were stored, and no OAuth flow or browser was started.

[clawsweeper]

Codex review: needs changes before merge. Reviewed June 22, 2026, 12:19 PM ET / 16:19 UTC.

Summary
The PR adds a new gog auth setup CLI subcommand, generated command docs, quickstart examples, service-to-Google-API mapping, and focused unit tests for guided Google Cloud/OAuth setup.

Reproducibility: not applicable. as a bug report, but the PR defect is source-reproducible: with gcloud installed and an active project configured, --create-project is validated after that active project is copied into project.

Review metrics: 3 noteworthy metrics.

• Diff size: 11 files changed, +566/-1. The PR is a moderate user-facing auth feature touching command code, generated docs, quickstart docs, and tests.
• Command surface: 1 auth subcommand added. A new setup command adds names, flags, and side-effect behavior that need maintainer acceptance.
• External mutation paths: 2 gcloud mutation paths added. --create-project and --enable-apis can mutate Google Cloud state, so validation and proof matter beyond normal unit coverage.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🐚 platinum hermit
Patch quality: 🦐 gold shrimp
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Fix the --create-project explicit-project validation and add the active-gcloud regression test.
• Let maintainers decide whether read-only fallback proof is enough for the mutating gcloud paths.

Risk before merge

• [P1] Merging as-is can make gog auth setup --create-project use the active gcloud project when no explicit new project ID was supplied, so the command may fail after confirmation or target an unintended configured value.
• [P2] The PR body proves the read-only no-gcloud fallback, but the mutating gcloud paths for project creation and API enablement still depend on source review and focused tests rather than live side-effect proof.

Maintainer options:

1. Patch creation validation first (recommended)
   Require an explicit --gcloud-project or --project-id for --create-project while still allowing active-gcloud fallback for non-creation guidance and API enablement.
2. Accept active-project creation intentionally
   Maintainers could decide active-gcloud project creation is acceptable, but then the docs, help text, and tests should explicitly describe that behavior before merge.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Fix `gog auth setup --create-project` so project creation requires an explicit `--gcloud-project`/`--project-id` value before any active gcloud project fallback is used, and add a regression test that simulates an active gcloud project with no explicit project flag.

Next step before merge

• [P2] A narrow validation repair can be attempted mechanically before maintainer product review of the new command continues.

Security
Cleared: No concrete security or supply-chain regression was found; the new gcloud calls use argv-based execution and credential storage uses the existing OAuth credential store.

Review findings

• [P2] Require an explicit project before creation — internal/cmd/auth_setup.go:65

Review details

Best possible solution:

Fix the explicit-project validation for creation, add regression coverage for an active gcloud project fallback, then leave the new command surface for maintainer acceptance.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug report, but the PR defect is source-reproducible: with gcloud installed and an active project configured, --create-project is validated after that active project is copied into project.

Is this the best way to solve the issue?

No: the guided setup direction is plausible, but the current implementation should not allow project creation to rely on an inherited active gcloud project when the help and error text require an explicit new ID.

Full review comments:

• [P2] Require an explicit project before creation — internal/cmd/auth_setup.go:65
  Because project is backfilled from active gcloud config before this validation, gog auth setup --create-project can pass without an explicit --gcloud-project and then prompt/run gcloud projects create <active-project>. Creation should validate the raw flag value before falling back to active gcloud state for other actions.
  Confidence: 0.9

Overall correctness: patch is incorrect
Overall confidence: 0.88

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 861adbd73cb9.

Label changes

Label changes:

• add merge-risk: 🚨 auth-provider: The PR changes OAuth/Google Cloud setup behavior and can currently target the wrong gcloud project in the creation path.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: The external contributor proof gate does not apply to this collaborator PR; the body reports a live terminal run of the read-only no-gcloud fallback but not the mutating paths.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦐 gold shrimp, so this older rating label is no longer current.
• remove status: 👀 ready for maintainer look: Current PR status label is status: ⏳ waiting on author.

Label justifications:

• P2: This is a normal-priority auth onboarding feature with limited blast radius but a concrete pre-merge validation bug.
• merge-risk: 🚨 auth-provider: The PR changes OAuth/Google Cloud setup behavior and can currently target the wrong gcloud project in the creation path.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: The external contributor proof gate does not apply to this collaborator PR; the body reports a live terminal run of the read-only no-gcloud fallback but not the mutating paths.

Evidence reviewed

Acceptance criteria:

• [P1] go test ./internal/cmd -run 'TestAuthSetup'.
• [P1] go test ./internal/googleauth.
• [P1] make ci.

What I checked:

• Repository policy read: AGENTS.md was read fully and its PR review-mode guidance was applied by staying on main and using read-only PR inspection. (AGENTS.md:37, 861adbd73cb9)
• Current main lacks the command: Current main registers existing auth subcommands without an AuthSetupCmd or setup auth subcommand. (internal/cmd/auth.go:92, 861adbd73cb9)
• Current docs still describe manual setup: The current quickstart walks users through manual Google Cloud project, API enablement, OAuth consent/client creation, then separate credentials and auth-add commands. (docs/quickstart.md:24, 861adbd73cb9)
• PR implementation adds guided setup: The PR head adds AuthSetupCmd.Run, including service parsing, gcloud discovery, validation, dry-run planning, project/API actions, credential storage, console opening, and optional login continuation. (internal/cmd/auth_setup.go:45, 96d97188bf7b)
• Validation bug source: The PR backfills project from active gcloud config before the --create-project validation, so --create-project can proceed without an explicit new project ID. (internal/cmd/auth_setup.go:65, 96d97188bf7b)
• Existing review note confirms the blocker: A PR review comment on the current head identifies the same --create-project active-gcloud fallback problem at line 65. (internal/cmd/auth_setup.go:65, 96d97188bf7b)

Likely related people:

• steipete: GitHub metadata maps Peter Steinberger to steipete, and local blame/log show the current auth command surface, auth-add path, credential path, and service metadata in the v0.30.0 release commit by the same person. (role: recent auth area contributor and feature author; confidence: high; commits: 48db48b4f61f, 2d1fe50661d1, 96d97188bf7b; files: internal/cmd/auth.go, internal/cmd/auth_add.go, internal/cmd/auth_credentials.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 96d97188bf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Require an explicit project before creation

Because the project is backfilled from the active gcloud config before the --create-project validation, gog auth setup --create-project passes validation whenever the user already has an active gcloud project even though no new --gcloud-project was supplied. It then prompts and runs gcloud projects create <active-project>, which normally fails after confirmation or targets an unintended configured value instead of enforcing the documented new project ID requirement.

Useful? React with 👍 / 👎.

[steipete]

Landed as 635f773788a82576aed46cffaab7334c14b118d9.

Verification:

• make ci — passed locally after rebase.
• go test ./internal/cmd -run AuthSetup — passed after the client-guidance fix.
• Codex autoreview against current main — clean, no accepted/actionable findings.
• GitHub CI — all 9 checks passed, including Linux, macOS CGO, Windows, worker, and Docker checks.
• Existing live proof: no-gcloud guided fallback completed read-only; no Cloud project/API/OAuth mutation was performed.

Landing fix: setup guidance now preserves a selected root --client for both credential storage and the follow-up authorization command.