fix(oauth): fix stale scope-descriptions.ts references and add test coverage

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: waleedlatif1

.claude/commands/add-block.md

@@ -125,7 +125,7 @@ export const {ServiceName}Block: BlockConfig = {
 
 **Scopes:** Always use `getScopesForService(serviceId)` from `@/lib/oauth/utils` for `requiredScopes`. Never hardcode scope arrays — the single source of truth is `OAUTH_PROVIDERS` in `lib/oauth/oauth.ts`.
 
-**Scope descriptions:** When adding a new OAuth provider, also add human-readable descriptions for all scopes in `lib/oauth/scope-descriptions.ts`.
+**Scope descriptions:** When adding a new OAuth provider, also add human-readable descriptions for all scopes in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`.
 
 ### Selectors (with dynamic options)
 ```typescript
@@ -801,7 +801,7 @@ All tool IDs referenced in `tools.access` and returned by `tools.config.tool` MU
 - [ ] DependsOn set for fields that need other values
 - [ ] Required fields marked correctly (boolean or condition)
 - [ ] OAuth inputs have correct `serviceId` and `requiredScopes: getScopesForService(serviceId)`
-- [ ] Scope descriptions added to `lib/oauth/scope-descriptions.ts` for any new scopes
+- [ ] Scope descriptions added to `SCOPE_DESCRIPTIONS` in `lib/oauth/utils.ts` for any new scopes
 - [ ] Tools.access lists all tool IDs (snake_case)
 - [ ] Tools.config.tool returns correct tool ID (snake_case)
 - [ ] Outputs match tool outputs

.claude/commands/add-integration.md

@@ -423,7 +423,7 @@ If creating V2 versions (API-aligned outputs):
 
 ### OAuth Scopes (if OAuth service)
 - [ ] Defined scopes in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS`
-- [ ] Added scope descriptions in `lib/oauth/scope-descriptions.ts`
+- [ ] Added scope descriptions in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
 - [ ] Used `getCanonicalScopesForProvider()` in `auth.ts` (never hardcode)
 - [ ] Used `getScopesForService()` in block `requiredScopes` (never hardcode)
 
@@ -730,7 +730,7 @@ Use `wandConfig` for fields that are hard to fill out manually:
 Scopes are maintained in a single source of truth and reused everywhere:
 
 1. **Define scopes** in `lib/oauth/oauth.ts` under `OAUTH_PROVIDERS[provider].services[service].scopes`
-2. **Add descriptions** in `lib/oauth/scope-descriptions.ts` for the OAuth modal UI
+2. **Add descriptions** in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts` for the OAuth modal UI
 3. **Reference in auth.ts** using `getCanonicalScopesForProvider(providerId)` from `@/lib/oauth/utils`
 4. **Reference in blocks** using `getScopesForService(serviceId)` from `@/lib/oauth/utils`
 
@@ -757,4 +757,4 @@ requiredScopes: getScopesForService('{service}'),
 9. **Optional fields use advanced mode** - Set `mode: 'advanced'` on rarely-used optional fields
 10. **Complex inputs need wandConfig** - Timestamps, JSON arrays, and other hard-to-type values should have `wandConfig` enabled
 11. **Never hardcode scopes** - Use `getScopesForService()` in blocks and `getCanonicalScopesForProvider()` in auth.ts
-12. **Always add scope descriptions** - New scopes must have entries in `lib/oauth/scope-descriptions.ts`
+12. **Always add scope descriptions** - New scopes must have entries in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`

.claude/commands/validate-integration.md

@@ -28,7 +28,7 @@ apps/sim/blocks/registry.ts         # Block registry entry for this service
 apps/sim/components/icons.tsx        # Icon definition
 apps/sim/lib/auth/auth.ts           # OAuth config — should use getCanonicalScopesForProvider()
 apps/sim/lib/oauth/oauth.ts         # OAuth provider config — single source of truth for scopes
-apps/sim/lib/oauth/scope-descriptions.ts  # Human-readable scope descriptions for modal UI
+apps/sim/lib/oauth/utils.ts               # Scope utilities, SCOPE_DESCRIPTIONS for modal UI
 ```
 
 ## Step 2: Pull API Documentation
@@ -206,7 +206,7 @@ Scopes are centralized — the single source of truth is `OAUTH_PROVIDERS` in `l
 - [ ] `auth.ts` uses `getCanonicalScopesForProvider(providerId)` — NOT a hardcoded array
 - [ ] Block `requiredScopes` uses `getScopesForService(serviceId)` — NOT a hardcoded array
 - [ ] No hardcoded scope arrays in `auth.ts` or block files (should all use utility functions)
-- [ ] Each scope has a human-readable description in `lib/oauth/scope-descriptions.ts`
+- [ ] Each scope has a human-readable description in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
 - [ ] No excess scopes that aren't needed by any tool
 
 ## Step 6: Validate Pagination Consistency
@@ -249,7 +249,7 @@ Group findings by severity:
 - Missing `?? null` on nullable response fields
 - Block condition array missing an operation that uses that field
 - Hardcoded scope arrays instead of using `getScopesForService()` / `getCanonicalScopesForProvider()`
-- Missing scope description in `lib/oauth/scope-descriptions.ts`
+- Missing scope description in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts`
 
 **Suggestion** (minor improvements):
 - Better description text
@@ -279,7 +279,7 @@ After fixing, confirm:
 - [ ] Validated tools.config mapping, tool selector, and type coercions
 - [ ] Validated block outputs match what tools return, with typed JSON where possible
 - [ ] Validated OAuth scopes use centralized utilities (getScopesForService, getCanonicalScopesForProvider) — no hardcoded arrays
-- [ ] Validated scope descriptions exist in `lib/oauth/scope-descriptions.ts` for all scopes
+- [ ] Validated scope descriptions exist in `SCOPE_DESCRIPTIONS` within `lib/oauth/utils.ts` for all scopes
 - [ ] Validated pagination consistency across tools and block
 - [ ] Validated error handling (error checks, meaningful messages)
 - [ ] Validated registry entries (tools and block, alphabetical, correct imports)

apps/sim/lib/oauth/utils.test.ts

@@ -3,7 +3,9 @@ import type { OAuthProvider, OAuthServiceMetadata } from './types'
 import {
   getAllOAuthServices,
   getCanonicalScopesForProvider,
+  getMissingRequiredScopes,
   getProviderIdFromServiceId,
+  getScopesForService,
   getServiceByProviderAndId,
   getServiceConfigByProviderId,
   parseProvider,
@@ -597,3 +599,111 @@ describe('parseProvider', () => {
     expect(config.featureType).toBe('sharepoint')
   })
 })
+
+describe('getScopesForService', () => {
+  it.concurrent('should return scopes for a valid serviceId', () => {
+    const scopes = getScopesForService('gmail')
+
+    expect(Array.isArray(scopes)).toBe(true)
+    expect(scopes.length).toBeGreaterThan(0)
+    expect(scopes).toContain('https://www.googleapis.com/auth/gmail.send')
+  })
+
+  it.concurrent('should return empty array for unknown serviceId', () => {
+    const scopes = getScopesForService('nonexistent-service')
+
+    expect(Array.isArray(scopes)).toBe(true)
+    expect(scopes.length).toBe(0)
+  })
+
+  it.concurrent('should return new array instance (not reference)', () => {
+    const scopes1 = getScopesForService('gmail')
+    const scopes2 = getScopesForService('gmail')
+
+    expect(scopes1).not.toBe(scopes2)
+    expect(scopes1).toEqual(scopes2)
+  })
+
+  it.concurrent('should work for Microsoft services', () => {
+    const scopes = getScopesForService('outlook')
+
+    expect(scopes.length).toBeGreaterThan(0)
+    expect(scopes).toContain('Mail.ReadWrite')
+  })
+
+  it.concurrent('should return empty array for empty string', () => {
+    const scopes = getScopesForService('')
+
+    expect(Array.isArray(scopes)).toBe(true)
+    expect(scopes.length).toBe(0)
+  })
+})
+
+describe('getMissingRequiredScopes', () => {
+  it.concurrent('should return empty array when all scopes are granted', () => {
+    const credential = { scopes: ['read', 'write'] }
+    const missing = getMissingRequiredScopes(credential, ['read', 'write'])
+
+    expect(missing).toEqual([])
+  })
+
+  it.concurrent('should return missing scopes', () => {
+    const credential = { scopes: ['read'] }
+    const missing = getMissingRequiredScopes(credential, ['read', 'write'])
+
+    expect(missing).toEqual(['write'])
+  })
+
+  it.concurrent('should return all required scopes when credential is undefined', () => {
+    const missing = getMissingRequiredScopes(undefined, ['read', 'write'])
+
+    expect(missing).toEqual(['read', 'write'])
+  })
+
+  it.concurrent('should return all required scopes when credential has undefined scopes', () => {
+    const missing = getMissingRequiredScopes({ scopes: undefined }, ['read', 'write'])
+
+    expect(missing).toEqual(['read', 'write'])
+  })
+
+  it.concurrent('should ignore offline_access in required scopes', () => {
+    const credential = { scopes: ['read'] }
+    const missing = getMissingRequiredScopes(credential, ['read', 'offline_access'])
+
+    expect(missing).toEqual([])
+  })
+
+  it.concurrent('should ignore refresh_token in required scopes', () => {
+    const credential = { scopes: ['read'] }
+    const missing = getMissingRequiredScopes(credential, ['read', 'refresh_token'])
+
+    expect(missing).toEqual([])
+  })
+
+  it.concurrent('should ignore offline.access in required scopes', () => {
+    const credential = { scopes: ['read'] }
+    const missing = getMissingRequiredScopes(credential, ['read', 'offline.access'])
+
+    expect(missing).toEqual([])
+  })
+
+  it.concurrent('should filter ignored scopes even when credential is undefined', () => {
+    const missing = getMissingRequiredScopes(undefined, ['read', 'offline_access', 'refresh_token'])
+
+    expect(missing).toEqual(['read'])
+  })
+
+  it.concurrent('should return empty array when requiredScopes is empty', () => {
+    const credential = { scopes: ['read'] }
+    const missing = getMissingRequiredScopes(credential, [])
+
+    expect(missing).toEqual([])
+  })
+
+  it.concurrent('should return empty array when requiredScopes defaults to empty', () => {
+    const credential = { scopes: ['read'] }
+    const missing = getMissingRequiredScopes(credential)
+
+    expect(missing).toEqual([])
+  })
+})