fix(install): configure and verify AuthKit application URLs

[nicknisi]

Summary

Follow-up to #243, which bundles @workos/skills@0.7.3. The skills explain the required application settings; this PR makes the installer create the sign-in route and configure supported settings itself, rather than relying on its restricted agent to run management commands.

• Include the shared AuthKit setup reference directly in the agent prompt. Keep the agent focused on app code and explicitly prohibit bypassing its shell restrictions.
• Require a dedicated Next.js /sign-in route using the SDK, separate from the callback. Include missing integration requirements in agent retries and fail validation instead of reporting incomplete code as installed.
• Configure Next.js callback, default Sign-out URI, and Initiate login URI through native installer code. Match the app client ID to a unique sandbox environment and its default application, preserve existing URLs/defaults, validate changes, and verify saved settings by reading them back.
• Preserve an existing homepage unless --homepage-url explicitly requests a change. Conflicting existing sign-out defaults or initiate-login URLs are left unchanged.
• Carry application setup results through the state machine into human and JSON completion output. Distinguish installed code, verified settings, and browser flows still needing tests.

Authentication and scope

• With a usable dashboard session, all three URL settings use the same client-ID-matched sandbox application. This step does not launch login.
• Without a dashboard session, API-key-only and unclaimed installs register the callback using their sandbox API key, then return immediately without any dashboard writes. The API key is the sole write target in this path. A failed callback registration fails the install instead of leaving sign-in broken behind a success result.
• The two write paths are exclusive. Dashboard failures, including partial writes, never fall back to API-key mutations. This avoids splitting one run's settings across environments without removing callback registration for logged-out users.
• API-only results report callbackRegistered: true but verified: false. Sign-out URI, Initiate login URI, and any requested homepage still need dashboard setup; browser flows remain untested.
• Production environments and non-default applications are not configured automatically.
• Native application setup is Next.js App Router-only. The SDK documents App Router support, not a Pages Router equivalent. CLI choices and human/JSON help now advertise only --router app; there is no Pages Router option in the interactive picker. Known Pages-only projects are declined before credential provisioning, including with --force. Explicit --router pages is rejected during argument parsing, and legacy programmatic Pages inputs are guarded too. Mixed-router projects use App Router without modifying the Pages tree. Shared prompt loading applies to other framework installers.
• The Next.js post-agent validation still runs with --no-validate so the installer does not configure a missing route.
• This does not change logout or the installer's initial credential-selection behavior.

Verification

• bun run test: 2,824 tests passed across 163 files with published skills 0.7.3 installed.
• bun run typecheck and bun run lint passed.
• Formatting passed for the changed source/spec files and validation rules.
• bun run build passed.
• Compiled workos internal verify-assets --json passed and reported bundled skills 0.7.3.
• Tests cover no pre-agent mutations from mixed credentials, exclusive API-key/dashboard write paths, logged-out callback registration and duplicate handling, fatal callback failures, production/unknown-key refusal, single-application dashboard targeting, early Pages Router refusal, preserving settings, rejected dry runs, concurrent edits, partial writes, read-back mismatches, route validation, and completion reporting.
• Regression tests reproduced the missing logged-out callback and unsupported router advertising before the latest fixes. Compiled help advertises only app, and compiled argument parsing rejects --router pages.
• Compiled offline command smoke passed, including install, integrate, and dashboard refusing Pages Router with structured unsupported_nextjs_router errors, no login, and no project writes. Authenticated smoke was not run.

End-to-end browser sign-in/sign-out and password-reset/invitation flows have not been verified for this PR. Unit tests use mocked dashboard responses; they do not prove a live dashboard configuration succeeds.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge based on the accepted findings, with no new non-duplicate issue requiring a review comment.

Summary

The latest changes restore callback registration for logged-out sandbox installs while keeping API-key and dashboard mutations mutually exclusive, and align the CLI with the Next.js SDK’s App Router-only support.

• Registers and reports the callback through the sandbox API key when no dashboard session exists.
• Keeps authenticated URL configuration scoped to the Client-ID-matched sandbox application.
• Removes Pages Router from CLI choices and rejects known Pages-only projects before provisioning.
• Propagates application-setup verification details through structured completion output.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Validate installed Next.js routes] --> B{Dashboard session available?}
  B -->|Yes| C[Match Client ID to one sandbox environment]
  C --> D[Configure callback, sign-out, and initiate-login URLs]
  D --> E[Read settings back and report verification]
  B -->|No| F{Sandbox API key available?}
  F -->|Yes| G[Register callback through API key]
  G --> H[Report callback registered; remaining settings unverified]
  F -->|No| I[Report manual dashboard setup required]

Loading

_{Reviews (3) · Last reviewed commit: "fix(install): restore API-only callbacks..."}

[nicknisi]

@greptileai Please re-review the latest commit d17ce80. It restores sandbox API-key-only callback registration after validation, keeps API-key and dashboard write paths exclusive, fails installation on callback registration failure, and removes unsupported Pages Router choices from CLI help and the picker. All CI checks pass; the current 3/5 summary still refers to 3366b2a.