@slates/cli 1.0.0-rc.6 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slates/cli",
-  "version": "1.0.0-rc.6",
+  "version": "1.0.0",
   "publishConfig": {
     "access": "public"
   },
@@ -20,14 +20,14 @@
   },
   "scripts": {
     "test": "vitest run --passWithNoTests",
-    "lint": "prettier src/**/*.ts --check",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "biome:check": "biome check --write src"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.4.0",
-    "@slates/client": "1.0.0-rc.8",
-    "@slates/oauth-microsoft": "1.0.0-rc.3",
-    "@slates/profiles": "1.0.0-rc.6",
+    "@slates/client": "1.0.0-rc.17",
+    "@slates/oauth-microsoft": "1.0.0-rc.6",
+    "@slates/profiles": "1.0.0-rc.15",
     "sade": "^1.8.1"
   },
   "devDependencies": {

package/src/cli.ts

@@ -193,6 +193,7 @@ if (isGlobalTestCommand) {
     .option('--client-id', 'OAuth client ID')
     .option('--client-secret', 'OAuth client secret')
     .option('--scopes', 'Comma-separated OAuth scopes')
+    .option('--incremental', 'Extend an existing OAuth grant with the supplied scope batch')
     .action((authMethodId: string | undefined, opts) =>
       printResult(() =>
         setupAuth({
@@ -203,7 +204,8 @@ if (isGlobalTestCommand) {
           oauthCredential: opts.oauthCredential,
           clientId: opts.clientId,
           clientSecret: opts.clientSecret,
-          scopes: opts.scopes
+          scopes: opts.scopes,
+          incremental: opts.incremental
         })
       )
     );

package/src/commands/auth.incremental.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, it, vi } from 'vitest';
+import { type AuthSetupRuntimeDependencies, runAuthSetupWithDependencies } from './auth';
+
+let authMethod = {
+  id: 'google_oauth',
+  name: 'Google OAuth',
+  type: 'auth.oauth',
+  inputSchema: {},
+  scopes: [
+    { id: 'scope:two', title: 'Scope two' },
+    { id: 'scope:denied', title: 'Denied scope' }
+  ],
+  capabilities: {
+    getDefaultInput: { enabled: false },
+    handleChangedInput: { enabled: false },
+    getProfile: { enabled: true }
+  }
+};
+
+let existingAuth = {
+  id: 'auth-1',
+  authMethodId: 'google_oauth',
+  authMethodName: 'Google OAuth',
+  authType: 'auth.oauth',
+  input: { developerToken: 'existing-developer-token' },
+  output: {
+    token: 'old-access-token',
+    refreshToken: 'existing-refresh-token',
+    developerToken: 'existing-developer-token'
+  },
+  scopes: ['openid', 'scope:one'],
+  clientId: 'client-id',
+  clientSecret: 'client-secret',
+  callbackState: null,
+  profile: { id: 'google-user-1', email: 'person@example.com' },
+  createdAt: '2026-09-02T10:00:00.000Z',
+  updatedAt: '2026-09-02T10:00:00.000Z'
+};
+
+let createScenario = (profile = existingAuth.profile) => {
+  let storedAuth: Record<string, unknown> | null = null;
+  let store = {
+    getAuth: vi.fn(() => existingAuth),
+    getOAuthCredential: vi.fn(() => null),
+    upsertAuth: vi.fn((_profileId: string, auth: Record<string, unknown>) => {
+      storedAuth = auth;
+      return auth;
+    }),
+    save: vi.fn(async () => undefined)
+  };
+  let client = {
+    clearAuth: vi.fn(),
+    getAuthorizationUrl: vi.fn(async () => ({
+      authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth'
+    })),
+    handleAuthorizationCallback: vi.fn(async () => ({
+      output: {
+        token: 'new-access-token',
+        refreshToken: undefined,
+        developerToken: 'existing-developer-token'
+      },
+      input: { developerToken: 'existing-developer-token' },
+      scopes: ['scope:two']
+    })),
+    getAuthProfile: vi.fn(async () => ({ profile }))
+  };
+  let callback = {
+    redirectUri: 'http://127.0.0.1:45873/callback',
+    state: 'oauth-state',
+    wait: vi.fn(async () => ({
+      code: 'authorization-code',
+      state: 'oauth-state',
+      callbackParams: { code: 'authorization-code', state: 'oauth-state' }
+    }))
+  };
+  let createClientContext = vi.fn(async () => ({
+    store,
+    profile: { id: 'profile-1' },
+    client
+  }));
+  let chooseAuthMethod = vi.fn(async () => authMethod);
+  let chooseScopes = vi.fn(async (_method, scopes: string[]) => scopes);
+  let createOAuthCallbackListener = vi.fn(async () => callback);
+  let printBrowserUrl = vi.fn();
+  let dependencies = {
+    createClientContext,
+    chooseAuthMethod,
+    chooseScopes,
+    createOAuthCallbackListener,
+    printBrowserUrl
+  } as unknown as AuthSetupRuntimeDependencies;
+
+  return {
+    store,
+    client,
+    callback,
+    dependencies,
+    createOAuthCallbackListener,
+    getStoredAuth: () => storedAuth
+  };
+};
+
+describe('incremental OAuth setup orchestration', () => {
+  it('reuses input and credentials, then stores only actually granted scopes', async () => {
+    let scenario = createScenario();
+
+    await runAuthSetupWithDependencies(
+      {
+        integration: 'super-booble-2',
+        authMethodId: 'google_oauth',
+        incremental: true,
+        scopes: 'scope:two,scope:denied'
+      },
+      scenario.dependencies
+    );
+
+    expect(scenario.client.getAuthorizationUrl).toHaveBeenCalledWith(
+      expect.objectContaining({
+        input: existingAuth.input,
+        clientId: 'client-id',
+        clientSecret: 'client-secret',
+        scopes: ['scope:two', 'scope:denied']
+      })
+    );
+    expect(scenario.client.handleAuthorizationCallback).toHaveBeenCalledWith(
+      expect.objectContaining({ input: existingAuth.input })
+    );
+    expect(scenario.getStoredAuth()).toEqual(
+      expect.objectContaining({
+        input: existingAuth.input,
+        output: {
+          token: 'new-access-token',
+          refreshToken: 'existing-refresh-token',
+          developerToken: 'existing-developer-token'
+        },
+        scopes: ['openid', 'scope:one', 'scope:two'],
+        profile: existingAuth.profile
+      })
+    );
+    expect(scenario.store.save).toHaveBeenCalledOnce();
+  });
+
+  it('rejects a different client ID before opening a callback listener or persisting', async () => {
+    let scenario = createScenario();
+
+    await expect(
+      runAuthSetupWithDependencies(
+        {
+          integration: 'super-booble-2',
+          authMethodId: 'google_oauth',
+          incremental: true,
+          scopes: 'scope:two',
+          clientId: 'different-client-id',
+          clientSecret: 'different-client-secret'
+        },
+        scenario.dependencies
+      )
+    ).rejects.toThrow('must use the same OAuth client ID');
+
+    expect(scenario.createOAuthCallbackListener).not.toHaveBeenCalled();
+    expect(scenario.store.upsertAuth).not.toHaveBeenCalled();
+    expect(scenario.store.save).not.toHaveBeenCalled();
+  });
+
+  it('rejects an auth input override before authorization begins', async () => {
+    let scenario = createScenario();
+
+    await expect(
+      runAuthSetupWithDependencies(
+        {
+          integration: 'super-booble-2',
+          authMethodId: 'google_oauth',
+          incremental: true,
+          scopes: 'scope:two',
+          input: JSON.stringify({ developerToken: 'replacement-developer-token' })
+        },
+        scenario.dependencies
+      )
+    ).rejects.toThrow('reuses the existing authentication input');
+
+    expect(scenario.createOAuthCallbackListener).not.toHaveBeenCalled();
+    expect(scenario.store.upsertAuth).not.toHaveBeenCalled();
+  });
+
+  it('rejects a different Google account without merging or persisting its token', async () => {
+    let scenario = createScenario({
+      id: 'google-user-2',
+      email: 'other@example.com'
+    });
+
+    await expect(
+      runAuthSetupWithDependencies(
+        {
+          integration: 'super-booble-2',
+          authMethodId: 'google_oauth',
+          incremental: true,
+          scopes: 'scope:two'
+        },
+        scenario.dependencies
+      )
+    ).rejects.toThrow('returned a different Google account');
+
+    expect(scenario.client.handleAuthorizationCallback).toHaveBeenCalledOnce();
+    expect(scenario.store.upsertAuth).not.toHaveBeenCalled();
+    expect(scenario.store.save).not.toHaveBeenCalled();
+  });
+});

package/src/commands/auth.test.ts

@@ -1,5 +1,210 @@
 import { describe, expect, it } from 'vitest';
-import { normalizeCallbackRedirectUriForIntegration } from './auth';
+import {
+  assertOAuthProfileContinuity,
+  completeIncrementalOAuthAuthorization,
+  mergeIncrementalOAuthAuthorization,
+  normalizeCallbackRedirectUriForIntegration,
+  resolveIncrementalOAuthCredentials,
+  validateIncrementalOAuthSetup
+} from './auth';
+
+let existingOAuthAuth = {
+  id: 'auth-1',
+  authMethodId: 'google_oauth',
+  authMethodName: 'Google OAuth',
+  authType: 'auth.oauth' as const,
+  input: {},
+  output: { token: 'access-token', refreshToken: 'refresh-token' },
+  scopes: ['openid'],
+  clientId: 'client-id',
+  clientSecret: 'client-secret',
+  profile: { id: 'google-user-1', email: 'person@example.com' },
+  createdAt: '2026-09-02T10:00:00.000Z',
+  updatedAt: '2026-09-02T10:00:00.000Z'
+};
+
+describe('validateIncrementalOAuthSetup', () => {
+  it('requires existing OAuth authentication', () => {
+    expect(() =>
+      validateIncrementalOAuthSetup({
+        enabled: true,
+        authMethodName: 'Google OAuth',
+        previousAuth: null,
+        scopes: ['scope:one']
+      })
+    ).toThrow('requires existing OAuth authentication');
+  });
+
+  it('requires an explicit scope batch', () => {
+    expect(() =>
+      validateIncrementalOAuthSetup({
+        enabled: true,
+        authMethodName: 'Google OAuth',
+        previousAuth: existingOAuthAuth,
+        scopes: []
+      })
+    ).toThrow('requires an explicit comma-separated scope batch');
+  });
+
+  it('returns the existing OAuth authentication for an incremental batch', () => {
+    expect(
+      validateIncrementalOAuthSetup({
+        enabled: true,
+        authMethodName: 'Google OAuth',
+        previousAuth: existingOAuthAuth,
+        scopes: ['scope:one']
+      })
+    ).toBe(existingOAuthAuth);
+  });
+
+  it('rejects input overrides so the existing auth input is preserved', () => {
+    expect(() =>
+      validateIncrementalOAuthSetup({
+        enabled: true,
+        authMethodName: 'Google OAuth',
+        previousAuth: existingOAuthAuth,
+        scopes: ['scope:one'],
+        inputProvided: true
+      })
+    ).toThrow('reuses the existing authentication input');
+  });
+});
+
+describe('mergeIncrementalOAuthAuthorization', () => {
+  it('accumulates granted scopes and preserves an omitted refresh token', () => {
+    expect(
+      mergeIncrementalOAuthAuthorization({
+        previousOutput: {
+          token: 'old-access-token',
+          refreshToken: 'existing-refresh-token',
+          developerToken: 'developer-token'
+        },
+        previousScopes: ['openid', 'scope:one'],
+        output: {
+          token: 'new-access-token',
+          refreshToken: undefined,
+          developerToken: 'developer-token',
+          expiresAt: '2026-09-02T12:00:00.000Z'
+        },
+        scopes: ['scope:one', 'scope:two']
+      })
+    ).toEqual({
+      output: {
+        token: 'new-access-token',
+        refreshToken: 'existing-refresh-token',
+        developerToken: 'developer-token',
+        expiresAt: '2026-09-02T12:00:00.000Z'
+      },
+      scopes: ['openid', 'scope:one', 'scope:two']
+    });
+  });
+
+  it('uses a replacement refresh token when the provider returns one', () => {
+    expect(
+      mergeIncrementalOAuthAuthorization({
+        previousOutput: {
+          token: 'old-access-token',
+          refreshToken: 'old-refresh-token'
+        },
+        previousScopes: ['scope:one'],
+        output: {
+          token: 'new-access-token',
+          refreshToken: 'new-refresh-token'
+        },
+        scopes: ['scope:two']
+      }).output.refreshToken
+    ).toBe('new-refresh-token');
+  });
+});
+
+describe('resolveIncrementalOAuthCredentials', () => {
+  let linkedCredential = {
+    id: 'credential-1',
+    name: 'Google credentials',
+    authMethodId: 'google_oauth',
+    clientId: 'client-id',
+    clientSecret: 'credential-secret',
+    createdAt: '2026-09-02T10:00:00.000Z',
+    updatedAt: '2026-09-02T10:00:00.000Z'
+  };
+
+  it('derives the prior client identity from its linked OAuth credential', () => {
+    expect(
+      resolveIncrementalOAuthCredentials({
+        previousAuth: { ...existingOAuthAuth, clientId: undefined, clientSecret: undefined },
+        linkedCredential
+      })
+    ).toEqual({
+      credential: linkedCredential,
+      clientId: 'client-id',
+      clientSecret: 'credential-secret'
+    });
+  });
+
+  it('rejects a selected credential for a different client', () => {
+    expect(() =>
+      resolveIncrementalOAuthCredentials({
+        previousAuth: existingOAuthAuth,
+        linkedCredential: null,
+        selectedCredential: { ...linkedCredential, clientId: 'different-client-id' },
+        selectedCredentialRequested: true
+      })
+    ).toThrow('must use the same OAuth client ID');
+  });
+
+  it('rejects setup when the prior client identity is unavailable', () => {
+    expect(() =>
+      resolveIncrementalOAuthCredentials({
+        previousAuth: { ...existingOAuthAuth, clientId: undefined },
+        linkedCredential: null
+      })
+    ).toThrow('cannot determine the OAuth client ID');
+  });
+});
+
+describe('completeIncrementalOAuthAuthorization', () => {
+  it('checks account continuity before merging a partial grant', () => {
+    expect(
+      completeIncrementalOAuthAuthorization({
+        previousAuth: existingOAuthAuth,
+        output: {
+          token: 'new-access-token',
+          refreshToken: undefined,
+          developerToken: 'developer-token'
+        },
+        grantedScopes: ['scope:two'],
+        profile: { id: 'google-user-1', email: 'renamed@example.com' }
+      })
+    ).toEqual({
+      output: {
+        token: 'new-access-token',
+        refreshToken: 'refresh-token',
+        developerToken: 'developer-token'
+      },
+      scopes: ['openid', 'scope:two']
+    });
+  });
+
+  it('rejects a different account', () => {
+    expect(() =>
+      completeIncrementalOAuthAuthorization({
+        previousAuth: existingOAuthAuth,
+        output: { token: 'new-access-token' },
+        grantedScopes: ['scope:two'],
+        profile: { id: 'google-user-2', email: 'other@example.com' }
+      })
+    ).toThrow('returned a different Google account');
+  });
+
+  it('compares normalized email when the previous profile has no stable ID', () => {
+    expect(() =>
+      assertOAuthProfileContinuity(
+        { email: 'Person@Example.com' },
+        { email: 'person@example.com' }
+      )
+    ).not.toThrow();
+  });
+});
 
 describe('normalizeCallbackRedirectUriForIntegration', () => {
   it('normalizes Notion loopback redirects to localhost', () => {
@@ -14,6 +219,15 @@ describe('normalizeCallbackRedirectUriForIntegration', () => {
     ).toBe('http://localhost:45873/callback');
   });
 
+  it('normalizes QuickBooks loopback redirects to localhost', () => {
+    expect(
+      normalizeCallbackRedirectUriForIntegration(
+        'quickbooks',
+        'http://127.0.0.1:45873/callback'
+      )
+    ).toBe('http://localhost:45873/callback');
+  });
+
   it('normalizes Typeform loopback redirects to localhost', () => {
     expect(
       normalizeCallbackRedirectUriForIntegration('typeform', 'http://127.0.0.1:45873/callback')

package/src/commands/auth.ts

@@ -3,7 +3,7 @@ import {
   normalizeMicrosoftRedirectUri,
   normalizeMicrosoftRedirectUriForIntegration
 } from '@slates/oauth-microsoft';
-import { SlatesOAuthCredentialRecord, SlatesStoredAuth } from '@slates/profiles';
+import type { SlatesOAuthCredentialRecord, SlatesStoredAuth } from '@slates/profiles';
 import {
   chooseAuthMethod,
   createClientContext,
@@ -17,7 +17,7 @@ import {
   promptForObjectSchema,
   promptForString
 } from '../lib/prompts';
-import { JsonInput, WithProfile } from '../lib/types';
+import type { JsonInput, WithProfile } from '../lib/types';
 
 type JsonObject = Record<string, any>;
 let NOTION_INTEGRATION_KEY = 'notion';
@@ -26,11 +26,13 @@ let INTERCOM_INTEGRATION_KEY = 'intercom';
 let TYPEFORM_INTEGRATION_KEY = 'typeform';
 let XERO_INTEGRATION_KEY = 'xero';
 let ZENDESK_INTEGRATION_KEY = 'zendesk';
+let QUICKBOOKS_INTEGRATION_KEY = 'quickbooks';
 let HUBSPOT_INTEGRATION_KEY = 'hubspot';
 let HUBSPOT_DEVELOPER_PLATFORM_OAUTH_METHOD_ID = 'developer_platform_oauth';
 let LOOPBACK_REDIRECT_NORMALIZED_INTEGRATIONS = new Set([
   INTERCOM_INTEGRATION_KEY,
   NOTION_INTEGRATION_KEY,
+  QUICKBOOKS_INTEGRATION_KEY,
   SALESFORCE_INTEGRATION_KEY,
   TYPEFORM_INTEGRATION_KEY,
   XERO_INTEGRATION_KEY,
@@ -44,8 +46,181 @@ type AuthSetupOptions = WithProfile &
     clientSecret?: string;
     oauthCredential?: string;
     scopes?: string;
+    incremental?: boolean;
   };
 
+export type AuthSetupRuntimeDependencies = {
+  createClientContext: typeof createClientContext;
+  chooseAuthMethod: typeof chooseAuthMethod;
+  chooseScopes: typeof chooseScopes;
+  createOAuthCallbackListener: typeof createOAuthCallbackListener;
+  printBrowserUrl: typeof printBrowserUrl;
+};
+
+let authSetupRuntimeDependencies: AuthSetupRuntimeDependencies = {
+  createClientContext,
+  chooseAuthMethod,
+  chooseScopes,
+  createOAuthCallbackListener,
+  printBrowserUrl
+};
+
+export let mergeIncrementalOAuthAuthorization = (d: {
+  previousOutput: JsonObject;
+  previousScopes: string[];
+  output: JsonObject;
+  scopes: string[];
+}) => {
+  let output = { ...d.output };
+  if (
+    (d.output.refreshToken === undefined || d.output.refreshToken === null) &&
+    typeof d.previousOutput.refreshToken === 'string'
+  ) {
+    output.refreshToken = d.previousOutput.refreshToken;
+  }
+
+  return {
+    output,
+    scopes: [...new Set([...d.previousScopes, ...d.scopes])]
+  };
+};
+
+export let validateIncrementalOAuthSetup = (d: {
+  enabled?: boolean;
+  authMethodName: string;
+  previousAuth: SlatesStoredAuth | null;
+  scopes: string[];
+  inputProvided?: boolean;
+}) => {
+  if (!d.enabled) return null;
+
+  if (!d.previousAuth || d.previousAuth.authType !== 'auth.oauth') {
+    throw new Error(
+      `Incremental OAuth setup requires existing OAuth authentication for ${d.authMethodName}. Run auth setup once without --incremental first.`
+    );
+  }
+  if (d.scopes.length === 0) {
+    throw new Error(
+      'Incremental OAuth setup requires an explicit comma-separated scope batch via --scopes.'
+    );
+  }
+  if (d.inputProvided) {
+    throw new Error(
+      'Incremental OAuth setup reuses the existing authentication input. Remove --input and retry.'
+    );
+  }
+
+  return d.previousAuth;
+};
+
+export let resolveIncrementalOAuthCredentials = (d: {
+  previousAuth: SlatesStoredAuth;
+  linkedCredential: SlatesOAuthCredentialRecord | null;
+  selectedCredential?: SlatesOAuthCredentialRecord | null;
+  selectedCredentialRequested?: boolean;
+  clientId?: string;
+  clientSecret?: string;
+}) => {
+  let storedClientId = d.previousAuth.clientId;
+  let linkedClientId = d.linkedCredential?.clientId;
+  if (storedClientId && linkedClientId && storedClientId !== linkedClientId) {
+    throw new Error(
+      'The existing authentication and its saved OAuth credential use different client IDs. Reconnect before using incremental OAuth setup.'
+    );
+  }
+
+  let previousClientId = storedClientId ?? linkedClientId;
+  if (!previousClientId) {
+    throw new Error(
+      'Incremental OAuth setup cannot determine the OAuth client ID used by the existing authentication. Reconnect before using --incremental.'
+    );
+  }
+  if (d.selectedCredentialRequested && !d.selectedCredential) {
+    throw new Error(
+      'The selected OAuth credential was not found for this authentication method.'
+    );
+  }
+
+  if (
+    (d.clientId && d.clientId !== previousClientId) ||
+    (d.selectedCredential && d.selectedCredential.clientId !== previousClientId)
+  ) {
+    throw new Error(
+      'Incremental OAuth setup must use the same OAuth client ID as the existing authentication.'
+    );
+  }
+
+  let clientSecret =
+    d.clientSecret ??
+    d.selectedCredential?.clientSecret ??
+    d.linkedCredential?.clientSecret ??
+    d.previousAuth.clientSecret;
+  if (!clientSecret) {
+    throw new Error(
+      'The existing authentication does not have a reusable OAuth client secret. Supply the secret for the same client with --client-secret.'
+    );
+  }
+
+  return {
+    credential:
+      d.selectedCredential ?? (d.clientSecret === undefined ? d.linkedCredential : null),
+    clientId: previousClientId,
+    clientSecret
+  };
+};
+
+let getOAuthProfileId = (profile: JsonObject | null | undefined) => {
+  let id = profile?.id;
+  return typeof id === 'string' && id.trim() ? id : null;
+};
+
+let getOAuthProfileEmail = (profile: JsonObject | null | undefined) => {
+  let email = profile?.email;
+  return typeof email === 'string' && email.trim() ? email.trim().toLowerCase() : null;
+};
+
+export let assertOAuthProfileContinuity = (
+  previousProfile: JsonObject | null | undefined,
+  currentProfile: JsonObject | null | undefined
+) => {
+  let previousId = getOAuthProfileId(previousProfile);
+  if (previousId) {
+    if (getOAuthProfileId(currentProfile) !== previousId) {
+      throw new Error(
+        'Incremental OAuth setup returned a different Google account. The existing authentication was left unchanged.'
+      );
+    }
+    return;
+  }
+
+  let previousEmail = getOAuthProfileEmail(previousProfile);
+  if (!previousEmail) {
+    throw new Error(
+      'Incremental OAuth setup cannot verify the Google account used by the existing authentication. Reconnect before using --incremental.'
+    );
+  }
+  if (getOAuthProfileEmail(currentProfile) !== previousEmail) {
+    throw new Error(
+      'Incremental OAuth setup returned a different Google account. The existing authentication was left unchanged.'
+    );
+  }
+};
+
+export let completeIncrementalOAuthAuthorization = (d: {
+  previousAuth: SlatesStoredAuth;
+  output: JsonObject;
+  grantedScopes: string[];
+  profile: JsonObject | null | undefined;
+}) => {
+  assertOAuthProfileContinuity(d.previousAuth.profile, d.profile);
+  return mergeIncrementalOAuthAuthorization({
+    previousOutput: d.previousAuth.output,
+    previousScopes: d.previousAuth.scopes,
+    output: d.output,
+    scopes: d.grantedScopes
+  });
+};
+
 export let normalizeCallbackRedirectUriForIntegration = (
   integration: string,
   redirectUri: string,
@@ -266,26 +441,46 @@ let chooseOAuthCredentialsForSetup = async (opts: {
   };
 };
 
-let runAuthSetup = async (opts: AuthSetupOptions): Promise<SlatesStoredAuth> => {
-  let { store, profile, client } = await createClientContext({
+export let runAuthSetupWithDependencies = async (
+  opts: AuthSetupOptions,
+  dependencies: AuthSetupRuntimeDependencies
+): Promise<SlatesStoredAuth> => {
+  let { store, profile, client } = await dependencies.createClientContext({
     ...opts,
     autoRefresh: false
   });
   client.clearAuth();
-  let authMethod = await chooseAuthMethod({
+  let authMethod = await dependencies.chooseAuthMethod({
     client,
     authMethodId: opts.authMethodId,
     forcePrompt: !opts.authMethodId
   });
+  let scopes = parseList(opts.scopes);
+  let previousAuth = validateIncrementalOAuthSetup({
+    enabled: opts.incremental,
+    authMethodName: authMethod.name,
+    previousAuth: opts.incremental ? store.getAuth(profile.id, authMethod.id) : null,
+    scopes,
+    inputProvided: opts.input !== undefined
+  });
+  if (opts.incremental && !authMethod.capabilities.getProfile?.enabled) {
+    throw new Error(
+      'Incremental OAuth setup requires this authentication method to expose a profile for account verification.'
+    );
+  }
+  if (previousAuth) {
+    assertOAuthProfileContinuity(previousAuth.profile, previousAuth.profile);
+  }
 
   let defaultInput = authMethod.capabilities.getDefaultInput?.enabled
     ? ((await client.getDefaultAuthInput(authMethod.id)).input ?? {})
     : {};
   let authInput =
+    previousAuth?.input ??
     parseJsonObject(opts.input, 'auth input') ??
     (await promptForObjectSchema(authMethod.inputSchema, defaultInput));
 
-  if (authMethod.capabilities.handleChangedInput?.enabled) {
+  if (!previousAuth && authMethod.capabilities.handleChangedInput?.enabled) {
     authInput =
       (
         await client.updateAuthInput({
@@ -299,31 +494,46 @@ let runAuthSetup = async (opts: AuthSetupOptions): Promise<SlatesStoredAuth> =>
   let output: JsonObject;
   let finalInput = authInput;
   let callbackState: JsonObject | null = null;
-  let scopes = parseList(opts.scopes);
 
   if (authMethod.type === 'auth.oauth') {
-    let callback = await createOAuthCallbackListener();
-    let redirectUri = normalizeCallbackRedirectUriForIntegration(
-      opts.integration,
-      callback.redirectUri,
-      authMethod.id
-    );
-    console.log(`OAuth redirect URL: ${redirectUri}`);
-
-    let resolvedOAuthCredentials = await chooseOAuthCredentialsForSetup({
-      store,
-      authMethod,
-      clientId: opts.clientId,
-      clientSecret: opts.clientSecret,
-      oauthCredential: opts.oauthCredential
-    });
+    let previousOAuthCredential = previousAuth?.oauthCredentialId
+      ? store.getOAuthCredential(previousAuth.oauthCredentialId, authMethod.id)
+      : null;
+    let selectedOAuthCredential = opts.oauthCredential
+      ? store.getOAuthCredential(opts.oauthCredential, authMethod.id)
+      : null;
+    let resolvedOAuthCredentials =
+      opts.incremental && previousAuth
+        ? resolveIncrementalOAuthCredentials({
+            previousAuth,
+            linkedCredential: previousOAuthCredential,
+            selectedCredential: selectedOAuthCredential,
+            selectedCredentialRequested: opts.oauthCredential !== undefined,
+            clientId: opts.clientId,
+            clientSecret: opts.clientSecret
+          })
+        : await chooseOAuthCredentialsForSetup({
+            store,
+            authMethod,
+            clientId: opts.clientId,
+            clientSecret: opts.clientSecret,
+            oauthCredential: opts.oauthCredential
+          });
     if (!resolvedOAuthCredentials) {
       throw new Error(`Authentication method ${authMethod.id} is not OAuth.`);
     }
 
     let clientId = resolvedOAuthCredentials.clientId;
     let clientSecret = resolvedOAuthCredentials.clientSecret;
-    scopes = await chooseScopes(authMethod, scopes);
+    scopes = await dependencies.chooseScopes(authMethod, scopes);
+
+    let callback = await dependencies.createOAuthCallbackListener();
+    let redirectUri = normalizeCallbackRedirectUriForIntegration(
+      opts.integration,
+      callback.redirectUri,
+      authMethod.id
+    );
+    console.log(`OAuth redirect URL: ${redirectUri}`);
 
     let authorizationUrl = await client.getAuthorizationUrl({
       authenticationMethodId: authMethod.id,
@@ -336,9 +546,9 @@ let runAuthSetup = async (opts: AuthSetupOptions): Promise<SlatesStoredAuth> =>
     });
 
     callbackState = authorizationUrl.callbackState ?? null;
-    finalInput = authorizationUrl.input ?? authInput;
+    finalInput = previousAuth?.input ?? authorizationUrl.input ?? authInput;
 
-    printBrowserUrl(authorizationUrl.authorizationUrl);
+    dependencies.printBrowserUrl(authorizationUrl.authorizationUrl);
     let callbackResult = await callback.wait();
     if (callbackResult.state !== callback.state) {
       throw new Error('OAuth state mismatch.');
@@ -357,18 +567,27 @@ let runAuthSetup = async (opts: AuthSetupOptions): Promise<SlatesStoredAuth> =>
       callbackState: callbackState ?? undefined
     });
 
-    output = authOutput.output;
-    finalInput = authOutput.input ?? finalInput;
-    scopes = authOutput.scopes ?? scopes;
-
+    let grantedScopes = authOutput.scopes ?? scopes;
     let profileInfo = authMethod.capabilities.getProfile?.enabled
       ? await client.getAuthProfile({
           authenticationMethodId: authMethod.id,
-          output,
-          input: finalInput,
-          scopes
+          output: authOutput.output,
+          input: previousAuth?.input ?? authOutput.input ?? finalInput,
+          scopes: grantedScopes
         })
       : null;
+    let accumulatedAuthorization =
+      opts.incremental && previousAuth
+        ? completeIncrementalOAuthAuthorization({
+            previousAuth,
+            output: authOutput.output,
+            grantedScopes,
+            profile: profileInfo?.profile
+          })
+        : { output: authOutput.output, scopes: grantedScopes };
+    output = accumulatedAuthorization.output;
+    finalInput = previousAuth?.input ?? authOutput.input ?? finalInput;
+    scopes = accumulatedAuthorization.scopes;
 
     let stored = store.upsertAuth(profile.id, {
       authMethodId: authMethod.id,
@@ -388,12 +607,12 @@ let runAuthSetup = async (opts: AuthSetupOptions): Promise<SlatesStoredAuth> =>
     return stored;
   }
 
-  output = (
-    await client.getAuthOutput({
-      authenticationMethodId: authMethod.id,
-      input: authInput
-    })
-  ).output;
+  let authOutput = await client.getAuthOutput({
+    authenticationMethodId: authMethod.id,
+    input: authInput
+  });
+  output = authOutput.output;
+  scopes = authOutput.scopes ?? scopes;
 
   let profileInfo = authMethod.capabilities.getProfile?.enabled
     ? await client.getAuthProfile({
@@ -418,6 +637,9 @@ let runAuthSetup = async (opts: AuthSetupOptions): Promise<SlatesStoredAuth> =>
   return stored;
 };
 
+export let runAuthSetup = async (opts: AuthSetupOptions): Promise<SlatesStoredAuth> =>
+  runAuthSetupWithDependencies(opts, authSetupRuntimeDependencies);
+
 export let setupAuth = async (opts: AuthSetupOptions) => runAuthSetup(opts);
 
 export let refreshAuth = async (opts: WithProfile & { authMethodId?: string }) => {

package/src/commands/config.ts

@@ -1,6 +1,6 @@
 import { createClientContext } from '../lib/context';
 import { parseJsonObject, promptForObjectSchema } from '../lib/prompts';
-import { JsonInput, WithProfile } from '../lib/types';
+import type { JsonInput, WithProfile } from '../lib/types';
 
 export let getConfig = async (opts: WithProfile) => {
   let { profile } = await createClientContext(opts);

package/src/commands/profiles.ts

@@ -1,8 +1,8 @@
 import { input } from '@inquirer/prompts';
-import { createSlatesClientFromProfile, openSlatesCliStore } from '@slates/profiles';
+import { createSlatesClientFromProfile, type openSlatesCliStore } from '@slates/profiles';
 import path from 'path';
 import { chooseProfile, openIntegrationStore, syncProfileMetadata } from '../lib/context';
-import { WithProfile } from '../lib/types';
+import type { WithProfile } from '../lib/types';
 
 let normalizeEntry = (rootDir: string, entry: string) => {
   let absolute = path.isAbsolute(entry) ? entry : path.resolve(process.cwd(), entry);
@@ -12,7 +12,9 @@ let normalizeEntry = (rootDir: string, entry: string) => {
     : absolute;
 };
 
-let getNextSetupProfileName = async (store: Awaited<ReturnType<typeof openSlatesCliStore>>) => {
+let getNextSetupProfileName = async (
+  store: Awaited<ReturnType<typeof openSlatesCliStore>>
+) => {
   let names = new Set(store.listProfiles().map(profile => profile.name));
   if (!names.has('default')) {
     return 'default';
@@ -41,10 +43,14 @@ let createProfile = async (
 
   let defaultName =
     opts.name ??
-    (opts.initializeConfig ? await getNextSetupProfileName(store) : `profile-${store.listProfiles().length + 1}`);
+    (opts.initializeConfig
+      ? await getNextSetupProfileName(store)
+      : `profile-${store.listProfiles().length + 1}`);
   let name =
     opts.name ??
-    (interactive ? await input({ message: 'Profile name', default: defaultName }) : defaultName);
+    (interactive
+      ? await input({ message: 'Profile name', default: defaultName })
+      : defaultName);
   let defaultEntry = opts.entry ?? integration.entry;
   let entry =
     opts.entry ??
@@ -56,7 +62,9 @@ let createProfile = async (
       : defaultEntry);
   let exportName =
     opts.exportName ??
-    (interactive ? await input({ message: 'Export name (optional)', default: 'provider' }) : 'provider');
+    (interactive
+      ? await input({ message: 'Export name (optional)', default: 'provider' })
+      : 'provider');
 
   let profile = store.upsertProfile({
     name,

package/src/commands/repl.ts

@@ -1,6 +1,6 @@
 import { input } from '@inquirer/prompts';
 import { print } from '../lib/prompts';
-import { WithProfile } from '../lib/types';
+import type { WithProfile } from '../lib/types';
 import { listAuth, setupAuth } from './auth';
 import { getConfig, setConfig } from './config';
 import { getProfile } from './profiles';

package/src/commands/test.ts

@@ -3,7 +3,7 @@ import { writeFile } from 'fs/promises';
 import path from 'path';
 import { chooseProfile } from '../lib/context';
 import { listWorkspaceIntegrations } from '../lib/integration';
-import { WithProfile } from '../lib/types';
+import type { WithProfile } from '../lib/types';
 
 let runVitest = async (opts: {
   cwd: string;
@@ -43,7 +43,7 @@ export let runVitestWithProfile = async (opts: WithProfile & { vitestArgs: strin
 
   await writeFile(
     contextPath,
-    JSON.stringify(
+    `${JSON.stringify(
       {
         integration: integration.relativeDir,
         profileId: profile.id,
@@ -53,7 +53,7 @@ export let runVitestWithProfile = async (opts: WithProfile & { vitestArgs: strin
       },
       null,
       2
-    ) + '\n',
+    )}\n`,
     'utf-8'
   );
 

package/src/commands/tools.ts

@@ -5,7 +5,7 @@ import {
   syncProfileMetadata
 } from '../lib/context';
 import { parseJsonObject, promptForObjectSchema } from '../lib/prompts';
-import { JsonInput, WithProfile } from '../lib/types';
+import type { JsonInput, WithProfile } from '../lib/types';
 
 export let listTools = async (opts: WithProfile) => {
   let { store, profile, client } = await createClientContext(opts);

package/src/lib/context.ts

@@ -1,10 +1,10 @@
 import { select } from '@inquirer/prompts';
-import { SlatesProtocolClient } from '@slates/client';
+import type { SlatesProtocolClient } from '@slates/client';
 import {
   createSlatesClientFromProfile,
   openSlatesCliStore,
-  SlatesProfileRecord,
-  type SlatesCliStore
+  type SlatesCliStore,
+  type SlatesProfileRecord
 } from '@slates/profiles';
 import { resolveIntegration } from './integration';
 import { promptForObjectSchema } from './prompts';

package/src/lib/integration.test.ts

@@ -26,7 +26,11 @@ describe('resolveIntegration', () => {
       JSON.stringify({ main: 'src/index.ts' }, null, 2),
       'utf-8'
     );
-    await writeFile(path.join(integrationDir, 'src', 'index.ts'), 'export let provider = {};\n', 'utf-8');
+    await writeFile(
+      path.join(integrationDir, 'src', 'index.ts'),
+      'export let provider = {};\n',
+      'utf-8'
+    );
 
     let resolved = await resolveIntegration('demo', { cwd });
 
@@ -44,7 +48,11 @@ describe('resolveIntegration', () => {
       JSON.stringify({ source: 'src/index.ts' }, null, 2),
       'utf-8'
     );
-    await writeFile(path.join(integrationDir, 'src', 'index.ts'), 'export let provider = {};\n', 'utf-8');
+    await writeFile(
+      path.join(integrationDir, 'src', 'index.ts'),
+      'export let provider = {};\n',
+      'utf-8'
+    );
 
     let resolved = await resolveIntegration('./custom/demo', { cwd });
 

package/src/lib/integration.ts

@@ -1,6 +1,6 @@
-import { access, readFile, readdir } from 'fs/promises';
-import path from 'path';
 import { resolveSlatesCliRoot } from '@slates/profiles';
+import { access, readdir, readFile } from 'fs/promises';
+import path from 'path';
 
 export interface ResolvedIntegration {
   input: string;
@@ -142,7 +142,9 @@ export let listWorkspaceIntegrations = async (opts: { cwd?: string } = {}) => {
     );
 
     integrations.push(
-      ...chunk.filter((integration): integration is WorkspaceIntegrationSummary => integration !== null)
+      ...chunk.filter(
+        (integration): integration is WorkspaceIntegrationSummary => integration !== null
+      )
     );
   }
 

package/src/lib/oauth.test.ts

@@ -0,0 +1,126 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createOAuthCallbackListener, getOAuthCallbackCode } from './oauth';
+
+let originalOAuthPort = process.env.SLATES_OAUTH_PORT;
+let originalOAuthCallbackOverride = process.env.OAUTH_CALLBACK_OVERRIDE;
+
+beforeEach(() => {
+  process.env.SLATES_OAUTH_PORT = '0';
+  delete process.env.OAUTH_CALLBACK_OVERRIDE;
+});
+
+afterEach(() => {
+  if (originalOAuthPort === undefined) {
+    delete process.env.SLATES_OAUTH_PORT;
+  } else {
+    process.env.SLATES_OAUTH_PORT = originalOAuthPort;
+  }
+
+  if (originalOAuthCallbackOverride === undefined) {
+    delete process.env.OAUTH_CALLBACK_OVERRIDE;
+  } else {
+    process.env.OAUTH_CALLBACK_OVERRIDE = originalOAuthCallbackOverride;
+  }
+});
+
+describe('getOAuthCallbackCode', () => {
+  it('returns an OAuth 2 code', () => {
+    expect(getOAuthCallbackCode(new URLSearchParams({ code: 'oauth2-code' }))).toBe(
+      'oauth2-code'
+    );
+  });
+
+  it('returns an OAuth 1.0a verifier', () => {
+    expect(
+      getOAuthCallbackCode(new URLSearchParams({ oauth_verifier: 'oauth1-verifier' }))
+    ).toBe('oauth1-verifier');
+  });
+
+  it('prefers an OAuth 2 code when both callback values are present', () => {
+    expect(
+      getOAuthCallbackCode(
+        new URLSearchParams({ code: 'oauth2-code', oauth_verifier: 'oauth1-verifier' })
+      )
+    ).toBe('oauth2-code');
+  });
+
+  it('returns null when neither callback value is present', () => {
+    expect(getOAuthCallbackCode(new URLSearchParams({ state: 'callback-state' }))).toBeNull();
+  });
+});
+
+describe('createOAuthCallbackListener', () => {
+  it('resolves OAuth 1.0a verifier callbacks with all callback parameters', async () => {
+    let listener = await createOAuthCallbackListener();
+    let callbackUrl = new URL(listener.redirectUri);
+    callbackUrl.search = new URLSearchParams({
+      state: listener.state,
+      oauth_verifier: 'oauth1-verifier',
+      oauth_token: 'request-token'
+    }).toString();
+
+    let [response, result] = await Promise.all([fetch(callbackUrl), listener.wait()]);
+
+    expect(response.status).toBe(200);
+    expect(result).toEqual({
+      code: 'oauth1-verifier',
+      state: listener.state,
+      callbackParams: {
+        state: listener.state,
+        oauth_verifier: 'oauth1-verifier',
+        oauth_token: 'request-token'
+      }
+    });
+  });
+
+  it('continues to resolve OAuth 2 code callbacks', async () => {
+    let listener = await createOAuthCallbackListener();
+    let callbackUrl = new URL(listener.redirectUri);
+    callbackUrl.search = new URLSearchParams({
+      state: listener.state,
+      code: 'oauth2-code'
+    }).toString();
+
+    let [response, result] = await Promise.all([fetch(callbackUrl), listener.wait()]);
+
+    expect(result).toMatchObject({
+      code: 'oauth2-code',
+      state: listener.state,
+      callbackParams: { state: listener.state, code: 'oauth2-code' }
+    });
+    expect(response.status).toBe(200);
+  });
+
+  it('rejects callbacks without state', async () => {
+    let listener = await createOAuthCallbackListener();
+    let callbackUrl = new URL(listener.redirectUri);
+    callbackUrl.search = new URLSearchParams({ code: 'oauth2-code' }).toString();
+
+    let result = expect(listener.wait()).rejects.toThrow(
+      'OAuth callback did not include the required query parameters.'
+    );
+    let response = await fetch(callbackUrl);
+
+    expect(response.status).toBe(400);
+    await result;
+  });
+
+  it('rejects OAuth error callbacks', async () => {
+    let listener = await createOAuthCallbackListener();
+    let callbackUrl = new URL(listener.redirectUri);
+    callbackUrl.search = new URLSearchParams({
+      state: listener.state,
+      error: 'access_denied',
+      error_description: 'The user denied access.',
+      error_uri: 'https://example.com/oauth-error'
+    }).toString();
+
+    let result = expect(listener.wait()).rejects.toThrow(
+      'OAuth callback returned "access_denied": The user denied access. (https://example.com/oauth-error)'
+    );
+    let response = await fetch(callbackUrl);
+
+    expect(response.status).toBe(400);
+    await result;
+  });
+});

package/src/lib/oauth.ts

@@ -4,6 +4,21 @@ import { createServer } from 'http';
 
 let DEFAULT_OAUTH_CALLBACK_PORT = 45873;
 
+let resolveAdvertisedRedirectUri = (localPort: number) => {
+  let override = process.env.OAUTH_CALLBACK_OVERRIDE;
+  if (!override) return `http://127.0.0.1:${localPort}/callback`;
+
+  let url: URL;
+  try {
+    url = new URL(override);
+  } catch {
+    throw new Error(`OAUTH_CALLBACK_OVERRIDE must be an absolute URL, received: ${override}`);
+  }
+
+  if (url.pathname === '' || url.pathname === '/') url.pathname = '/callback';
+  return url.toString();
+};
+
 export let chooseScopes = async (
   authMethod: any,
   initialScopes: string[]
@@ -18,10 +33,7 @@ export let chooseScopes = async (
     choices: authMethod.scopes.map((scope: any) => ({
       name: `${scope.title} (${scope.id})`,
       value: scope.id,
-      checked:
-        initialScopes.length > 0
-          ? initialScopes.includes(scope.id)
-          : (scope.defaultChecked ?? true)
+      checked: initialScopes.length > 0 ? initialScopes.includes(scope.id) : true
     }))
   })) as string[];
 };
@@ -30,6 +42,9 @@ export let printBrowserUrl = (url: string) => {
   console.log(`Open this URL in your browser:\n${url}`);
 };
 
+export let getOAuthCallbackCode = (params: URLSearchParams) =>
+  params.get('code') ?? params.get('oauth_verifier');
+
 export let createOAuthCallbackListener = async () => {
   return new Promise<{
     redirectUri: string;
@@ -47,7 +62,7 @@ export let createOAuthCallbackListener = async () => {
     let server = createServer((req, res) => {
       try {
         let url = new URL(req.url ?? '/', 'http://127.0.0.1');
-        let code = url.searchParams.get('code');
+        let code = getOAuthCallbackCode(url.searchParams);
         let state = url.searchParams.get('state');
         let oauthError = url.searchParams.get('error');
         let oauthErrorDescription = url.searchParams.get('error_description');
@@ -153,7 +168,7 @@ export let createOAuthCallbackListener = async () => {
       }
 
       resolve({
-        redirectUri: `http://127.0.0.1:${address.port}/callback`,
+        redirectUri: resolveAdvertisedRedirectUri(address.port),
         state: expectedState,
         wait: () => waiter.promise
       });

package/src/lib/prompts.ts

@@ -1,5 +1,5 @@
 import { checkbox, confirm, input, password, select } from '@inquirer/prompts';
-import { JsonObject } from './types';
+import type { JsonObject } from './types';
 
 export let prettyJson = (value: unknown) => JSON.stringify(value, null, 2);