fix(install): surface unclaimed environments honestly (#234)

* fix(install): surface unclaimed environments honestly

A friction log of the AuthKit getting-started path found the
installer describing a zero-auth environment it had just minted
itself as "the WorkOS credentials you provided". The tester went
to the dashboard to reconcile a client ID that did not match, and
only found the claim prompt by accident after starting a dev
server.

The provenance gate added in #200 was correct; the label feeding
it was not. runWithCore backfills credentials from the project's
.env.local before the machine starts, and that is the path a
freshly provisioned environment takes, so checkingCliFlags
short-circuited and called them 'cli'. Reading the machine's own
transitions exonerates it -- the mislabeling happens one level up,
in whoever builds the initial context.

Claiming is the one step that cannot be recovered later, since an
unclaimed environment's credentials live only on this machine, so
it now leads the completion box instead of appearing once at
provision time and scrolling away behind the agent run.

Provisioning returns no environmentId or environmentName, so the
environment naming from #231 could never reach an unclaimed
environment and every status line degraded to generic copy.
Persisting authkitDomain gives it the one human-recognizable name
it has.

* fix(install): stop labeling mixed credential pairs as env-sourced

A pair where the user supplied one credential and the project env file
backfilled the other was labeled 'env' wholesale, so the installer
announced `.env.local` as the origin of a value typed on the command
line and stayed silent about the value the user did provide.

Only a pair the user supplied nothing toward is an env-file resolution —
the freshly provisioned unclaimed environment path this provenance was
added for. Mixed pairs keep the caller's source. Extracted the decision
into resolveCredentialSource() so it is covered directly.

Author: gjtorikian

src/lib/adapters/cli-adapter.spec.ts

@@ -523,5 +523,132 @@ describe('CLIAdapter', () => {
       expect(calls).toContain('Using your active WorkOS environment');
       expect(calls.join('\n')).not.toContain('Using environment:');
     });
+
+    it('unclaimed copy also covers the cli-flags path, which is where provisioning lands', async () => {
+      // runWithCore backfills options.apiKey/clientId from the .env.local that
+      // provisioning just wrote, so a freshly provisioned environment
+      // short-circuits at checkingCliFlags and never reaches staging
+      // resolution. The copy has to exist on this path or it never fires.
+      mockGetActiveEnvironment.mockReturnValue({
+        name: 'unclaimed',
+        type: 'unclaimed',
+        apiKey: 'sk_test_x',
+        clientId: 'client_x',
+        claimToken: 'ct_x',
+        authkitDomain: 'witty-rest-53.authkit.app',
+      });
+      await adapter.start();
+      const ui = await import('../../utils/ui.js');
+
+      emitter.emit('credentials:found', {
+        source: 'env',
+        credentials: { clientId: 'client_x', apiKey: 'sk_test_x' },
+      });
+
+      const calls = vi.mocked(ui.default.log.success).mock.calls.map((c) => String(c[0]));
+      expect(calls).toContain('Using a new WorkOS environment created for this install (witty-rest-53.authkit.app)');
+      expect(calls.join('\n')).not.toContain('Found existing WorkOS credentials');
+    });
+
+    it('names .env.local for an env-file backfill into a claimed environment', async () => {
+      mockGetActiveEnvironment.mockReturnValue({
+        name: 'staging-3',
+        type: 'sandbox',
+        apiKey: 'sk_test_x',
+        clientId: 'client_x',
+      });
+      await adapter.start();
+      const ui = await import('../../utils/ui.js');
+
+      emitter.emit('credentials:found', {
+        source: 'env',
+        credentials: { clientId: 'client_x', apiKey: 'sk_test_x' },
+      });
+
+      const calls = vi.mocked(ui.default.log.success).mock.calls.map((c) => String(c[0]));
+      expect(calls).toContain('Found existing WorkOS credentials in .env.local');
+    });
+
+    it('never claims .env.local for credentials passed as flags', async () => {
+      mockGetActiveEnvironment.mockReturnValue(null);
+      await adapter.start();
+      const ui = await import('../../utils/ui.js');
+
+      emitter.emit('credentials:found', {
+        source: 'cli',
+        credentials: { clientId: 'client_flag', apiKey: 'sk_test_flag' },
+      });
+
+      const calls = vi.mocked(ui.default.log.success).mock.calls.map((c) => String(c[0]));
+      expect(calls.join('\n')).not.toContain('.env.local');
+    });
+
+    it('says the environment is new and names it by AuthKit domain when unclaimed', async () => {
+      // Provisioning returns no environmentId/environmentName, so the generic
+      // "Using your active WorkOS environment" made a just-created environment
+      // read as one the user already had — the friction that sent people to the
+      // dashboard to compare client IDs.
+      mockGetActiveEnvironment.mockReturnValue({
+        name: 'unclaimed',
+        type: 'unclaimed',
+        apiKey: 'sk_test_x',
+        clientId: 'client_x',
+        claimToken: 'ct_x',
+        authkitDomain: 'witty-rest-53.authkit.app',
+      });
+      await adapter.start();
+      const ui = await import('../../utils/ui.js');
+
+      emitter.emit('staging:fetching', {});
+      emitter.emit('staging:success', { source: 'stored', credentials: { clientId: 'client_x', apiKey: 'sk_test_x' } });
+
+      const calls = vi.mocked(ui.default.log.success).mock.calls.map((c) => String(c[0]));
+      expect(calls).toContain('Using a new WorkOS environment created for this install (witty-rest-53.authkit.app)');
+      expect(calls.join('\n')).not.toContain('Using your active WorkOS environment');
+    });
+
+    it('drops the domain suffix for an unclaimed env provisioned before authkitDomain was stored', async () => {
+      mockGetActiveEnvironment.mockReturnValue({
+        name: 'unclaimed',
+        type: 'unclaimed',
+        apiKey: 'sk_test_x',
+        clientId: 'client_x',
+        claimToken: 'ct_x',
+      });
+      await adapter.start();
+      const ui = await import('../../utils/ui.js');
+
+      emitter.emit('staging:fetching', {});
+      emitter.emit('staging:success', { source: 'stored', credentials: { clientId: 'client_x', apiKey: 'sk_test_x' } });
+
+      const calls = vi.mocked(ui.default.log.success).mock.calls.map((c) => String(c[0]));
+      expect(calls).toContain('Using a new WorkOS environment created for this install');
+    });
+
+    it('keeps the generic copy when an unclaimed profile did not supply the credentials', async () => {
+      // A leftover unclaimed profile can sit active while the install used the
+      // project's own keys — calling that environment "created for this install"
+      // would be a lie about which environment the app now targets.
+      mockGetActiveEnvironment.mockReturnValue({
+        name: 'unclaimed',
+        type: 'unclaimed',
+        apiKey: 'sk_test_x',
+        clientId: 'client_x',
+        claimToken: 'ct_x',
+        authkitDomain: 'witty-rest-53.authkit.app',
+      });
+      await adapter.start();
+      const ui = await import('../../utils/ui.js');
+
+      emitter.emit('staging:fetching', {});
+      emitter.emit('staging:success', {
+        source: 'stored',
+        credentials: { clientId: 'client_x', apiKey: 'sk_test_project' },
+      });
+
+      const calls = vi.mocked(ui.default.log.success).mock.calls.map((c) => String(c[0]));
+      expect(calls).toContain('Using your active WorkOS environment');
+      expect(calls.join('\n')).not.toContain('created for this install');
+    });
   });
 });

src/lib/adapters/cli-adapter.ts

@@ -4,7 +4,7 @@ import { relative } from 'node:path';
 import ui, { PromptUnavailableError } from '../../utils/ui.js';
 import chalk from 'chalk';
 import { getConfig } from '../settings.js';
-import { getActiveEnvironment, profileEnvironmentLabel } from '../config-store.js';
+import { getActiveEnvironment, isUnclaimedEnvironment, profileEnvironmentLabel } from '../config-store.js';
 import { ProgressTracker } from '../progress-tracker.js';
 import { renderCompletionSummary, renderBrandMark } from '../../utils/summary-box.js';
 import { classifyAgentFailure, describeAgentFailure } from '../failure-classifier.js';
@@ -291,7 +291,39 @@ export class CLIAdapter implements InstallerAdapter {
     this.queueableLog(() => ui.log.warn('Could not detect framework automatically'));
   };
 
-  private handleCredentialsFound = (): void => {
+  /**
+   * Copy for an install running against a newly provisioned unclaimed
+   * environment, or undefined when it isn't.
+   *
+   * Provisioning returns no environmentId/environmentName, so
+   * `profileEnvironmentLabel` has nothing to build from and the generic copy
+   * reads as though the CLI picked up an environment the user already had —
+   * the ambiguity that sends people to the dashboard to compare client IDs.
+   *
+   * Requires an exact credential match: a leftover unclaimed profile can sit
+   * active while the install used the project's own keys, and calling that
+   * environment "created for this install" would misname what the app targets.
+   */
+  private newUnclaimedEnvironmentLine(credentials?: { clientId?: string; apiKey?: string }): string | undefined {
+    const active = getActiveEnvironment();
+    if (!active || !isUnclaimedEnvironment(active)) return undefined;
+    if (!credentials?.clientId || !credentials.apiKey) return undefined;
+    if (active.clientId !== credentials.clientId || active.apiKey !== credentials.apiKey) return undefined;
+    const domain = active.authkitDomain ? ` (${active.authkitDomain})` : '';
+    return `Using a new WorkOS environment created for this install${domain}`;
+  }
+
+  private handleCredentialsFound = ({ source, credentials }: InstallerEvents['credentials:found']): void => {
+    const newEnvironment = this.newUnclaimedEnvironmentLine(credentials);
+    if (newEnvironment) {
+      ui.log.success(newEnvironment);
+      return;
+    }
+    // Only the env-file backfill can honestly name .env.local. For credentials
+    // the user passed as flags, the integration installer announces them
+    // itself — naming a file they may never have touched is the same
+    // wrong-provenance claim in the other direction.
+    if (source === 'cli') return;
     ui.log.success('Found existing WorkOS credentials in .env.local');
   };
 
@@ -350,6 +382,18 @@ export class CLIAdapter implements InstallerAdapter {
     );
     const label = active && suppliedCredentials ? profileEnvironmentLabel(active) : undefined;
     const named = label ? `${label} (${active!.name})` : undefined;
+
+    // An unclaimed environment can never satisfy the naming above, so it gets
+    // its own copy (see newUnclaimedEnvironmentLine). Reachable here when
+    // .env.local was not pre-populated and checkStoredAuth routed an already
+    // active unclaimed profile through staging resolution.
+    const newEnvironment = this.newUnclaimedEnvironmentLine(credentials);
+    if (newEnvironment) {
+      this.stopSpinner('Environment ready');
+      ui.log.success(newEnvironment);
+      return;
+    }
+
     if (source === 'device') {
       this.stopSpinner('Environment ready');
       ui.log.success(named ? `Set up environment: ${named}` : 'Set up a WorkOS environment for this install');

src/lib/completion-data.spec.ts

@@ -111,4 +111,49 @@ describe('buildCompletionData', () => {
     expect(data.signInSnippet).toBeUndefined();
     expect(data.nextSteps.some((s) => /refreshAuth/.test(s))).toBe(false);
   });
+
+  describe('unclaimed-environment claim step', () => {
+    it('leads the next steps with the claim command when one is supplied', async () => {
+      writePackageJson({ scripts: { dev: 'next dev' }, dependencies: { next: '15.0.0' } });
+
+      const data = await buildCompletionData(
+        { integration: 'nextjs', changedFiles: [], installDir },
+        { ...baseDeps, claimCommand: 'workos profile claim' },
+      );
+
+      // First, not buried: the provision-time notice has already scrolled away
+      // behind scaffolding and the agent run by the time this box renders.
+      expect(data.nextSteps[0]).toBe('Run `workos profile claim` to link this environment to your WorkOS account');
+      // The concrete steps still follow, in order.
+      expect(data.nextSteps[1]).toContain('start your dev server');
+      expect(data.nextSteps[2]).toContain('test authentication');
+    });
+
+    it('omits the claim step for a claimed environment', async () => {
+      writePackageJson({ scripts: { dev: 'next dev' }, dependencies: { next: '15.0.0' } });
+
+      const data = await buildCompletionData({ integration: 'nextjs', changedFiles: [], installDir }, baseDeps);
+
+      expect(data.nextSteps.some((s) => /claim/i.test(s))).toBe(false);
+      expect(data.nextSteps[0]).toContain('start your dev server');
+    });
+
+    it('keeps the claim step ahead of framework steps too', async () => {
+      writePackageJson({ scripts: { dev: 'next dev' }, dependencies: { next: '15.0.0' } });
+
+      const data = await buildCompletionData(
+        { integration: 'nextjs', changedFiles: [], installDir },
+        {
+          ...baseDeps,
+          claimCommand: 'workos profile claim',
+          frameworkNextSteps: ['Visit the WorkOS Dashboard to manage users and settings'],
+        },
+      );
+
+      const claimIndex = data.nextSteps.findIndex((s) => /profile claim/.test(s));
+      const dashboardIndex = data.nextSteps.findIndex((s) => /WorkOS Dashboard/.test(s));
+      expect(claimIndex).toBe(0);
+      expect(dashboardIndex).toBeGreaterThan(claimIndex);
+    });
+  });
 });

src/lib/completion-data.ts

@@ -24,6 +24,12 @@ export interface CompletionDataDeps {
   frameworkNextSteps?: string[];
   /** Per-framework "add a sign-in link" snippet */
   signInSnippet?: string;
+  /**
+   * Claim command for an unclaimed environment this install actually used
+   * (e.g. `workos profile claim`), or undefined for a claimed environment.
+   * Resolved by the caller, which owns the config lookup.
+   */
+  claimCommand?: string;
 }
 
 /**
@@ -49,12 +55,20 @@ export async function buildCompletionData(ctx: CompletionContext, deps: Completi
   // above already names the exact lockfile-aware command.
   const framework = (deps.frameworkNextSteps ?? []).filter((s) => !/start .*dev(elopment)? server/i.test(s));
 
+  // An unclaimed environment's credentials live only on this machine, so a
+  // missed claim loses the environment for good — it leads the next steps for
+  // that reason, and because the provision-time notice is printed before
+  // scaffolding and the agent run, minutes of output before the install ends.
+  const claim = deps.claimCommand
+    ? [`Run \`${deps.claimCommand}\` to link this environment to your WorkOS account`]
+    : [];
+
   return {
     integration: ctx.integration,
     devCommand,
     url,
     files,
-    nextSteps: [...concrete, ...framework],
+    nextSteps: [...claim, ...concrete, ...framework],
     docsUrl: deps.docsUrl,
     dashboardUrl: deps.dashboardUrl,
     signInSnippet: deps.signInSnippet,

src/lib/config-store.ts

@@ -37,6 +37,15 @@ interface BaseEnvironmentConfig {
    * disambiguate (e.g. "My Project > Staging").
    */
   projectName?: string;
+  /**
+   * The environment's AuthKit domain (e.g. `witty-rest-53.authkit.app`).
+   *
+   * The only human-recognizable identifier an unclaimed environment has:
+   * provisioning returns no `environmentId` or `environmentName`, so display
+   * paths that rely on `profileEnvironmentLabel` have nothing to print for a
+   * freshly provisioned environment. Cosmetic — never an identity key.
+   */
+  authkitDomain?: string;
 }
 
 export interface ClaimedEnvironmentConfig extends BaseEnvironmentConfig {

src/lib/events.ts

@@ -57,7 +57,14 @@ export interface InstallerEvents {
   'git:dirty:confirmed': Record<string, never>;
   'git:dirty:cancelled': Record<string, never>;
   'credentials:gathering': { requiresApiKey: boolean };
-  'credentials:found': Record<string, never>;
+  /**
+   * Credentials were already on `options` when the machine started. `source`
+   * separates the two ways that happens — flags the user typed ('cli') versus a
+   * pair `runWithCore` backfilled from the project's env file ('env') — because
+   * the two need different copy, and the payload lets a listener check whether
+   * the active profile is the one that supplied them.
+   */
+  'credentials:found': { source?: 'cli' | 'env'; credentials?: { clientId?: string; apiKey?: string } };
   // Credential discovery events
   'credentials:env:detected': { files: string[] };
   'credentials:env:prompt': { files: string[] };

src/lib/installer-core.spec.ts

@@ -414,6 +414,73 @@ describe('InstallerCore State Machine', () => {
       actor.stop();
     });
 
+    it('keeps an env-file provenance through the cli-flags short-circuit', async () => {
+      // runWithCore backfills options.apiKey/clientId from the project's
+      // .env.local — the path a freshly provisioned unclaimed environment takes.
+      // Those credentials must not be relabeled 'cli', or the installer tells
+      // the user it is using credentials they never provided.
+      const emitter = createInstallerEventEmitter();
+      const options: InstallerOptions = {
+        debug: false,
+        forceInstall: false,
+        installDir: '/test/project',
+        default: false,
+        local: true,
+        ci: false,
+        skipAuth: true,
+        dashboard: false,
+        emitter,
+        apiKey: 'sk_test_provisioned',
+        clientId: 'client_provisioned',
+        credentialSource: 'env',
+      };
+
+      const found: Array<{ source?: string }> = [];
+      emitter.on('credentials:found', (payload) => found.push(payload));
+
+      const actor = createActor(installerMachine.provide({ actors: baseMockActors }), {
+        input: { emitter, options },
+      });
+      actor.start();
+      actor.send({ type: 'START' });
+      await new Promise((r) => setTimeout(r, 200));
+
+      expect(found).toHaveLength(1);
+      expect(found[0].source).toBe('env');
+      actor.stop();
+    });
+
+    it('labels credentials that really came from flags as cli', async () => {
+      const emitter = createInstallerEventEmitter();
+      const options: InstallerOptions = {
+        debug: false,
+        forceInstall: false,
+        installDir: '/test/project',
+        default: false,
+        local: true,
+        ci: false,
+        skipAuth: true,
+        dashboard: false,
+        emitter,
+        apiKey: 'sk_test_flag',
+        clientId: 'client_flag',
+      };
+
+      const found: Array<{ source?: string }> = [];
+      emitter.on('credentials:found', (payload) => found.push(payload));
+
+      const actor = createActor(installerMachine.provide({ actors: baseMockActors }), {
+        input: { emitter, options },
+      });
+      actor.start();
+      actor.send({ type: 'START' });
+      await new Promise((r) => setTimeout(r, 200));
+
+      expect(found).toHaveLength(1);
+      expect(found[0].source).toBe('cli');
+      actor.stop();
+    });
+
     it('skips device auth when checkStoredAuth returns true (unclaimed env)', async () => {
       const emitter = createInstallerEventEmitter();
       const options: InstallerOptions = {