@mutagent/sdk 0.2.13

package/scripts/fix-openapi.ts

@@ -0,0 +1,894 @@
+#!/usr/bin/env bun
+/**
+ * OpenAPI Post-Processing Script for MutagenT SDK Generation
+ *
+ * This script fixes known issues in the Elysia-generated OpenAPI spec
+ * to ensure compatibility with Speakeasy SDK generator.
+ *
+ * Usage:
+ *    bun run scripts/fix-openapi.ts [input.json] [output.json]
+ *
+ *    Default: reads from ./openapi.json, writes back to same file
+ */
+
+// =============================================================================
+// TYPE DEFINITIONS
+// =============================================================================
+
+type AnyValue = any;
+
+interface OpenAPISpec {
+  paths?: Record<string, Record<string, AnyValue>>;
+  components?: {
+    securitySchemes?: Record<string, AnyValue>;
+    schemas?: Record<string, AnyValue>;
+  };
+  security?: Array<Record<string, string[]>>;
+}
+
+// =============================================================================
+// NULLABLE TYPE FIXES
+// =============================================================================
+
+function fixNullableTypes(obj: AnyValue): AnyValue {
+  /**
+   * Fix nullable types for OpenAPI 3.0 compliance.
+   *
+   * Problem: Elysia generates { "anyOf": [{ "type": "string" }, { "type": "null" }] }
+   * This is invalid in OpenAPI 3.0 because "type": "null" is not allowed.
+   *
+   * Solution: Convert to { "type": "string", "nullable": true }
+   */
+  if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+    // If we have nullable:true and anyOf with type:null, fix it
+    if (obj.nullable === true && 'anyOf' in obj) {
+      const anyOf = obj.anyOf;
+      // Filter out the {type: null} entry
+      const nonNullTypes = anyOf.filter((t: AnyValue) => t.type !== 'null');
+      if (nonNullTypes.length === 1) {
+        // Single type with nullable - simplify
+        const actualType = nonNullTypes[0];
+        delete obj.anyOf;
+        Object.assign(obj, actualType);
+      } else if (nonNullTypes.length > 1) {
+        // Multiple types - keep anyOf but without type:null
+        obj.anyOf = nonNullTypes;
+      }
+    }
+
+    // Recurse into all values
+    for (const key of Object.keys(obj)) {
+      obj[key] = fixNullableTypes(obj[key]);
+    }
+  } else if (Array.isArray(obj)) {
+    return obj.map(item => fixNullableTypes(item));
+  }
+
+  return obj;
+}
+
+// =============================================================================
+// WEBSOCKET PATH REMOVAL
+// =============================================================================
+
+function removeWebsocketPaths(spec: OpenAPISpec): string[] {
+  /**
+   * Remove WebSocket paths from OpenAPI spec.
+   *
+   * Problem: OpenAPI doesn't support WebSocket specs. Elysia generates "ws": {...}
+   * which is invalid and causes Speakeasy to fail.
+   *
+   * Solution: Remove all paths that only have "ws" method, or remove "ws" from
+   * paths that have other methods.
+   */
+  const wsPathsRemoved: string[] = [];
+
+  if (!spec.paths) return wsPathsRemoved;
+
+  for (const path of Object.keys(spec.paths)) {
+    const methods = spec.paths[path];
+    if ('ws' in methods) {
+      // If ws is the only method, remove the whole path
+      if (Object.keys(methods).length === 1) {
+        wsPathsRemoved.push(path);
+        delete spec.paths[path];
+      } else {
+        // Just remove the ws method
+        delete methods.ws;
+      }
+    }
+  }
+
+  return wsPathsRemoved;
+}
+
+// =============================================================================
+// MISSING RESPONSE HANDLING
+// =============================================================================
+
+function addMissingResponses(spec: OpenAPISpec): number {
+  /**
+   * Add default responses to operations missing them.
+   *
+   * Problem: Some Elysia routes don't have response schemas defined,
+   * which is required by OpenAPI spec.
+   *
+   * Solution: Add a generic 200 response with object schema.
+   */
+  const defaultResponse = {
+    "200": {
+      "description": "Successful response",
+      "content": {
+        "application/json": {
+          "schema": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  };
+
+  let fixedCount = 0;
+  if (!spec.paths) return fixedCount;
+
+  for (const [path, methods] of Object.entries(spec.paths)) {
+    for (const [method, operation] of Object.entries(methods)) {
+      if (['get', 'post', 'put', 'patch', 'delete'].includes(method)) {
+        if (!operation.responses || Object.keys(operation.responses).length === 0) {
+          operation.responses = JSON.parse(JSON.stringify(defaultResponse));
+          fixedCount++;
+        }
+      }
+    }
+  }
+
+  return fixedCount;
+}
+
+// =============================================================================
+// PATTERN PROPERTIES REMOVAL
+// =============================================================================
+
+function removePatternProperties(obj: AnyValue): AnyValue {
+  /**
+   * Remove patternProperties from schemas.
+   *
+   * Problem: OpenAPI 3.0 doesn't support JSON Schema's patternProperties.
+   *
+   * Solution: Remove them.
+   */
+  if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+    if ('patternProperties' in obj) {
+      delete obj.patternProperties;
+    }
+    for (const k of Object.keys(obj)) {
+      obj[k] = removePatternProperties(obj[k]);
+    }
+  } else if (Array.isArray(obj)) {
+    return obj.map(item => removePatternProperties(item));
+  }
+  return obj;
+}
+
+// =============================================================================
+// DESCRIPTION FIXES
+// =============================================================================
+
+function fixDescriptions(obj: AnyValue): AnyValue {
+  /**
+   * Fix problematic text in descriptions.
+   *
+   * Problem: Speakeasy flags descriptions containing 'eval(' as security risk.
+   *
+   * Solution: Replace with safe alternative.
+   */
+  if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+    if ('description' in obj && typeof obj.description === 'string') {
+      if (obj.description.includes('eval(')) {
+        obj.description = obj.description.replace(/eval\(/g, 'evaluate(');
+      }
+    }
+    for (const k of Object.keys(obj)) {
+      obj[k] = fixDescriptions(obj[k]);
+    }
+  } else if (Array.isArray(obj)) {
+    return obj.map(item => fixDescriptions(item));
+  }
+  return obj;
+}
+
+// =============================================================================
+// $id FIELD REMOVAL
+// =============================================================================
+
+function removeIdFields(obj: AnyValue): { result: AnyValue; count: number } {
+  /**
+   * Recursively remove all $id fields from the spec.
+   *
+   * Problem: Elysia's OpenAPI plugin adds $id fields like
+   *   "$id": "#/components/schemas/PromptDatasetItem"
+   * throughout the spec. Speakeasy rejects these with:
+   *   schema.items.$id does not match pattern '[#]*#?$'
+   *
+   * Solution: Walk the entire spec and delete any key named "$id".
+   */
+  let count = 0;
+
+  function walk(node: AnyValue): AnyValue {
+    if (node && typeof node === 'object' && !Array.isArray(node)) {
+      if ('$id' in node) {
+        delete node.$id;
+        count++;
+      }
+      for (const key of Object.keys(node)) {
+        node[key] = walk(node[key]);
+      }
+    } else if (Array.isArray(node)) {
+      return node.map(item => walk(item));
+    }
+    return node;
+  }
+
+  const result = walk(obj);
+  return { result, count };
+}
+
+// =============================================================================
+// AUTHENTICATION SETUP
+// =============================================================================
+
+function setupDualAuthSchemes(spec: OpenAPISpec): { apiKey: boolean; bearerAuth: boolean } {
+  /**
+   * Configure BOTH authentication methods in OpenAPI spec.
+   *
+   * SDK Authentication Methods:
+   * 1. apiKey - Platform API Keys (mg_live_...) via MUTAGENT_API_KEY env var
+   * 2. bearerAuth - JWT session tokens via MUTAGENT_BEARER_AUTH env var
+   *
+   * Users can authenticate with EITHER method. The SDK will try apiKey first
+   * (if MUTAGENT_API_KEY is set), then fall back to bearerAuth.
+   *
+   * Backend supports both via x-api-key header OR Authorization: Bearer header.
+   */
+  if (!spec.components) {
+    spec.components = {};
+  }
+  if (!spec.components.securitySchemes) {
+    spec.components.securitySchemes = {};
+  }
+
+  const schemes = spec.components.securitySchemes;
+
+  // Primary: Platform API Key (MUTAGENT_API_KEY)
+  // Uses x-api-key header for clear distinction from JWT tokens
+  schemes.apiKey = {
+    "type": "apiKey",
+    "in": "header",
+    "name": "x-api-key",
+    "description": "Platform API Key (mg_live_...). Get one from Settings > API Keys."
+  };
+
+  // Secondary: Bearer Auth for JWT session tokens (MUTAGENT_BEARER_AUTH)
+  // Keep existing bearerAuth for backward compatibility with session tokens
+  if (!('bearerAuth' in schemes)) {
+    schemes.bearerAuth = {
+      "type": "http",
+      "scheme": "bearer",
+      "bearerFormat": "JWT",
+      "description": "JWT session token from login. Use for browser/UI authentication."
+    };
+  }
+
+  return {
+    apiKey: true,
+    bearerAuth: 'bearerAuth' in schemes
+  };
+}
+
+function configureSecurityOptions(spec: OpenAPISpec): number {
+  /**
+   * Configure security to allow EITHER apiKey OR bearerAuth.
+   *
+   * OpenAPI security arrays use OR logic between items, AND logic within items.
+   * We want: [{ apiKey: [] }, { bearerAuth: [] }] = apiKey OR bearerAuth
+   *
+   * This ensures SDK users can use either:
+   * - MUTAGENT_API_KEY for programmatic/service access
+   * - MUTAGENT_BEARER_AUTH for session-based access
+   */
+  let count = 0;
+
+  // Define security options (either apiKey OR bearerAuth)
+  const dualSecurity = [
+    { apiKey: [] },
+    { bearerAuth: [] }
+  ];
+
+  // Update global security
+  spec.security = dualSecurity;
+  count++;
+
+  // Update path-level security to support both methods
+  if (spec.paths) {
+    for (const [path, methods] of Object.entries(spec.paths)) {
+      for (const [method, operation] of Object.entries(methods)) {
+        if (operation && typeof operation === 'object' && 'security' in operation) {
+          // Replace any existing security with dual auth
+          operation.security = dualSecurity;
+          count++;
+        }
+      }
+    }
+  }
+
+  return count;
+}
+
+// =============================================================================
+// MODULE FILTERING - Configure which API modules to include in SDK
+// =============================================================================
+
+// Modules to INCLUDE in SDK (paths starting with these prefixes)
+const INCLUDED_MODULES = [
+  // Core APIs
+  '/api/prompt',           // Prompts (includes /api/prompt/ and /api/prompts/)
+  '/api/prompts',          // Prompts datasets, evaluations, etc.
+  '/api/agents',           // Agents
+  '/api/optimization',     // Optimization jobs
+  '/api/agent-datasets',   // Agent datasets
+  '/api/agent-dataset-items',  // Agent dataset items
+
+  // Infrastructure
+  '/api/conversations',    // Conversations
+  '/api/stream',           // Streaming/SSE
+  '/api/traces',           // Traces (ADDED - was missing)
+
+  // Tenancy/Org
+  '/api/organizations',    // Organizations
+  '/api/workspaces',       // Workspaces
+
+  // Auth/User
+  '/api/users',            // User profile
+  '/api/providers',        // OAuth providers
+];
+
+// Modules to EXCLUDE from SDK (explicitly removed even if matched above)
+const EXCLUDED_MODULES = [
+  '/health',               // Health checks
+  '/hello',                // Test/debug endpoints
+  '/api/stats',            // Internal stats
+  '/api/auth',             // Auth validation (internal)
+  '/api/sessions',         // Session management (use users instead)
+  '/api/api-keys',         // API key management
+  '/api/invitations',      // Invitations
+  '/api/mcp-servers',      // MCP servers
+];
+
+function filterModules(spec: OpenAPISpec): { included: string[]; excluded: string[] } {
+  /**
+   * Filter API paths to only include selected modules.
+   *
+   * Returns object with included_paths and excluded_paths for logging.
+   */
+  const included: string[] = [];
+  const excluded: string[] = [];
+
+  if (!spec.paths) return { included, excluded };
+
+  for (const path of Object.keys(spec.paths)) {
+    // Check if path should be excluded
+    const shouldExclude = EXCLUDED_MODULES.some(excl => path.startsWith(excl));
+
+    // Check if path should be included
+    const shouldInclude = INCLUDED_MODULES.some(incl => path.startsWith(incl));
+
+    if (shouldExclude || !shouldInclude) {
+      excluded.push(path);
+      delete spec.paths[path];
+    } else {
+      included.push(path);
+    }
+  }
+
+  return { included, excluded };
+}
+
+// =============================================================================
+// COLLAPSE t.Numeric() anyOf PATTERNS IN QUERY PARAMETERS
+// =============================================================================
+
+function collapseNumericAnyOfInQueryParams(spec: OpenAPISpec): number {
+  /**
+   * Collapse Elysia t.Numeric() / t.BooleanString() anyOf patterns in query parameters.
+   *
+   * Problem: Elysia's t.Numeric() generates:
+   *   { "anyOf": [{ "type": "string", "format": "numeric", "default": 0 }, { "type": "number", ... }] }
+   * The default:0 is a number but the branch says type:"string", causing Speakeasy warnings.
+   *
+   * Similarly t.BooleanString() generates:
+   *   { "anyOf": [{ "type": "string", "default": false }, { ... boolean-like ... }] }
+   *
+   * Solution: For query parameters only, when anyOf has exactly 2 items where one is
+   * type:"string" and the other is type:"number", collapse to the number branch.
+   * Same for string+boolean pairs: collapse to the boolean branch.
+   */
+  let collapsedCount = 0;
+
+  if (!spec.paths) return collapsedCount;
+
+  for (const [_path, methods] of Object.entries(spec.paths)) {
+    for (const [method, operation] of Object.entries(methods)) {
+      if (!['get', 'post', 'put', 'patch', 'delete'].includes(method)) continue;
+      if (!operation.parameters || !Array.isArray(operation.parameters)) continue;
+
+      for (const param of operation.parameters) {
+        if (param.in !== 'query') continue;
+        if (!param.schema || !Array.isArray(param.schema.anyOf)) continue;
+
+        const anyOf = param.schema.anyOf;
+        if (anyOf.length !== 2) continue;
+
+        const stringBranch = anyOf.find((b: AnyValue) => b.type === 'string');
+        const numberBranch = anyOf.find((b: AnyValue) => b.type === 'number');
+        const booleanBranch = anyOf.find((b: AnyValue) => b.type === 'boolean');
+
+        if (stringBranch && numberBranch) {
+          // Collapse to number branch, merging default from string branch if needed
+          const merged = { ...numberBranch };
+          if (!('default' in merged) && 'default' in stringBranch) {
+            merged.default = stringBranch.default;
+          }
+          // Replace the schema entirely
+          delete param.schema.anyOf;
+          Object.assign(param.schema, merged);
+          collapsedCount++;
+        } else if (stringBranch && booleanBranch) {
+          // Collapse to boolean branch, merging default from string branch if needed
+          const merged = { ...booleanBranch };
+          if (!('default' in merged) && 'default' in stringBranch) {
+            merged.default = stringBranch.default;
+          }
+          delete param.schema.anyOf;
+          Object.assign(param.schema, merged);
+          collapsedCount++;
+        }
+      }
+    }
+  }
+
+  return collapsedCount;
+}
+
+// =============================================================================
+// INJECT x-speakeasy-pagination FOR OFFSET/LIMIT ENDPOINTS
+// =============================================================================
+
+function injectSpeakeasyPagination(spec: OpenAPISpec): number {
+  /**
+   * Add x-speakeasy-pagination extension to operations with limit+offset query params.
+   *
+   * Problem: 10+ list endpoints use limit/offset but Speakeasy doesn't know how to paginate.
+   *
+   * Solution: For each operation that has both "limit" AND "offset" query parameters,
+   * inject the x-speakeasy-pagination extension for offsetLimit pagination.
+   */
+  let paginatedCount = 0;
+
+  if (!spec.paths) return paginatedCount;
+
+  for (const [_path, methods] of Object.entries(spec.paths)) {
+    for (const [method, operation] of Object.entries(methods)) {
+      if (!['get', 'post', 'put', 'patch', 'delete'].includes(method)) continue;
+      if (!operation.parameters || !Array.isArray(operation.parameters)) continue;
+
+      const queryParams = operation.parameters.filter((p: AnyValue) => p.in === 'query');
+      const hasOffset = queryParams.some((p: AnyValue) => p.name === 'offset');
+      const hasLimit = queryParams.some((p: AnyValue) => p.name === 'limit');
+
+      if (hasOffset && hasLimit) {
+        operation['x-speakeasy-pagination'] = {
+          type: 'offsetLimit',
+          inputs: [
+            { name: 'offset', in: 'parameters', type: 'offset' },
+            { name: 'limit', in: 'parameters', type: 'limit' }
+          ],
+          outputs: {
+            results: '$.data'
+          }
+        };
+        paginatedCount++;
+      }
+    }
+  }
+
+  return paginatedCount;
+}
+
+// =============================================================================
+// CONVERT const TO enum
+// =============================================================================
+
+function convertConstToEnum(obj: AnyValue): { result: AnyValue; count: number } {
+  /**
+   * Convert JSON Schema `const` keyword to `enum` for Speakeasy compatibility.
+   *
+   * Problem: Some schemas use { "const": "value" } which Speakeasy may not handle well.
+   *
+   * Solution: Replace { "const": "value" } with { "enum": ["value"] }.
+   * Also handles { "type": "string", "const": "foo" } -> { "type": "string", "enum": ["foo"] }.
+   */
+  let count = 0;
+
+  function walk(node: AnyValue): AnyValue {
+    if (node && typeof node === 'object' && !Array.isArray(node)) {
+      if ('const' in node) {
+        const constValue = node.const;
+        delete node.const;
+        node.enum = [constValue];
+        count++;
+      }
+      for (const key of Object.keys(node)) {
+        node[key] = walk(node[key]);
+      }
+    } else if (Array.isArray(node)) {
+      return node.map(item => walk(item));
+    }
+    return node;
+  }
+
+  const result = walk(obj);
+  return { result, count };
+}
+
+// =============================================================================
+// SCHEMA DEDUPLICATION
+// =============================================================================
+
+/**
+ * Create a canonical hash key for a schema by deep-stringifying it,
+ * excluding `description` and `title` so structurally identical schemas
+ * with different descriptions are still considered duplicates.
+ */
+function canonicalizeSchema(schema: AnyValue): string {
+  if (schema === null || schema === undefined) return String(schema);
+  if (typeof schema !== 'object') return JSON.stringify(schema);
+
+  if (Array.isArray(schema)) {
+    return '[' + schema.map(item => canonicalizeSchema(item)).join(',') + ']';
+  }
+
+  // Sort keys, exclude description and title for dedup purposes
+  const keys = Object.keys(schema)
+    .filter(k => k !== 'description' && k !== 'title')
+    .sort();
+
+  const parts = keys.map(k => JSON.stringify(k) + ':' + canonicalizeSchema(schema[k]));
+  return '{' + parts.join(',') + '}';
+}
+
+/**
+ * Generate a PascalCase component name from a schema's structure.
+ */
+function generateComponentName(schema: AnyValue): string {
+  // If the schema has a title, use it
+  if (schema.title && typeof schema.title === 'string') {
+    return toPascalCase(schema.title);
+  }
+
+  // For objects with properties, use property names
+  if (schema.type === 'object' && schema.properties) {
+    const propNames = Object.keys(schema.properties);
+    // Use first 3 property names to form a name
+    const nameParts = propNames.slice(0, 3).map(toPascalCase);
+    return nameParts.join('');
+  }
+
+  // For arrays of objects, prefix with ArrayOf
+  if (schema.type === 'array' && schema.items) {
+    const itemName = generateComponentName(schema.items);
+    if (itemName) return `ArrayOf${itemName}`;
+  }
+
+  // For anyOf/oneOf/allOf, try to derive from first item
+  for (const combiner of ['anyOf', 'oneOf', 'allOf']) {
+    if (Array.isArray(schema[combiner]) && schema[combiner].length > 0) {
+      const firstName = generateComponentName(schema[combiner][0]);
+      if (firstName) return `${firstName}${toPascalCase(combiner)}`;
+    }
+  }
+
+  return '';
+}
+
+/**
+ * Convert a string to PascalCase.
+ */
+function toPascalCase(str: string): string {
+  return str
+    .replace(/[^a-zA-Z0-9]+/g, ' ')
+    .split(' ')
+    .filter(Boolean)
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join('');
+}
+
+/**
+ * Check if a schema is "trivial" — too simple to be worth deduplicating.
+ * We skip schemas that are just a type with no properties, or objects with < 2 properties.
+ */
+function isTrivialSchema(schema: AnyValue): boolean {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return true;
+
+  // If it's a $ref, it's already deduplicated
+  if ('$ref' in schema) return true;
+
+  // Simple type-only schemas (e.g., { type: "string" })
+  const keys = Object.keys(schema).filter(k => k !== 'description' && k !== 'title');
+  if (keys.length <= 1) return true;
+
+  // Objects with fewer than 2 properties
+  if (schema.type === 'object' && schema.properties) {
+    if (Object.keys(schema.properties).length < 2) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Walk the entire spec and collect all inline schemas with their locations.
+ * Each location is represented as a path of keys to reach the schema,
+ * plus a reference to the parent object and the key to replace.
+ */
+interface SchemaLocation {
+  parent: AnyValue;
+  key: string | number;
+  schema: AnyValue;
+}
+
+function collectInlineSchemas(
+  obj: AnyValue,
+  locations: SchemaLocation[],
+  parent: AnyValue | null,
+  key: string | number | null,
+  depth: number = 0,
+  visited: Set<AnyValue> = new Set()
+): void {
+  // Guard against circular references and excessive depth
+  if (depth > 50) return;
+  if (obj === null || obj === undefined || typeof obj !== 'object') return;
+
+  if (visited.has(obj)) return;
+  visited.add(obj);
+
+  if (Array.isArray(obj)) {
+    for (let i = 0; i < obj.length; i++) {
+      collectInlineSchemas(obj[i], locations, obj, i, depth + 1, visited);
+    }
+    return;
+  }
+
+  // If this looks like a schema object (has 'type' as a string value, or 'properties', or combiners, or 'items')
+  // IMPORTANT: 'type' in obj is not enough — properties dicts can have a key named "type"
+  // (e.g., { path: {...}, type: { type: "string", enum: [...] } }). We must verify obj.type
+  // is a valid OpenAPI type string, not a nested schema object.
+  const VALID_TYPES = new Set(['array', 'boolean', 'integer', 'null', 'number', 'object', 'string']);
+  const hasValidType = 'type' in obj && typeof obj.type === 'string' && VALID_TYPES.has(obj.type);
+  const isSchema = hasValidType || 'properties' in obj ||
+    'anyOf' in obj || 'oneOf' in obj || 'allOf' in obj || 'items' in obj;
+
+  if (isSchema && parent !== null && key !== null && !isTrivialSchema(obj)) {
+    // Don't collect schemas that are already $refs
+    if (!('$ref' in obj)) {
+      locations.push({ parent, key, schema: obj });
+    }
+  }
+
+  // Recurse into child properties
+  for (const k of Object.keys(obj)) {
+    collectInlineSchemas(obj[k], locations, obj, k, depth + 1, visited);
+  }
+}
+
+/**
+ * Deduplicate schemas: find structurally identical schemas that appear 3+ times,
+ * extract them into components/schemas, and replace inline occurrences with $ref.
+ */
+function deduplicateSchemas(spec: OpenAPISpec): { extractedCount: number; replacedCount: number } {
+  // Ensure components.schemas exists
+  if (!spec.components) spec.components = {};
+  if (!spec.components.schemas) spec.components.schemas = {};
+
+  const existingComponentNames = new Set(Object.keys(spec.components.schemas));
+
+  // Step 1: Collect all inline schemas from paths
+  const locations: SchemaLocation[] = [];
+  if (spec.paths) {
+    collectInlineSchemas(spec.paths, locations, null, null);
+  }
+
+  // Step 2: Group by canonical hash
+  const hashToLocations = new Map<string, SchemaLocation[]>();
+  for (const loc of locations) {
+    const hash = canonicalizeSchema(loc.schema);
+    if (!hashToLocations.has(hash)) {
+      hashToLocations.set(hash, []);
+    }
+    hashToLocations.get(hash)!.push(loc);
+  }
+
+  // Step 3: Filter to schemas appearing 3+ times
+  let extractedCount = 0;
+  let replacedCount = 0;
+  const usedNames = new Set(existingComponentNames);
+
+  for (const [hash, locs] of hashToLocations.entries()) {
+    if (locs.length < 3) continue;
+
+    // Use the first occurrence as the canonical schema
+    const canonicalSchema = JSON.parse(JSON.stringify(locs[0].schema));
+
+    // Generate a name for this component
+    let baseName = generateComponentName(canonicalSchema);
+    if (!baseName) {
+      // Fallback: use hash-based name
+      baseName = 'Schema' + hash.slice(1, 8).replace(/[^a-zA-Z0-9]/g, '');
+    }
+
+    // Ensure uniqueness
+    let componentName = baseName;
+    let suffix = 2;
+    while (usedNames.has(componentName)) {
+      componentName = `${baseName}${suffix}`;
+      suffix++;
+    }
+    usedNames.add(componentName);
+
+    // Extract the canonical schema (strip description for the shared component)
+    const componentSchema = JSON.parse(JSON.stringify(canonicalSchema));
+    delete componentSchema.description;
+
+    // Safety net: if the extracted schema looks like a bare properties dict
+    // (has nested objects as values but no valid "type" string), wrap it properly.
+    // This catches cases where a properties dict was mistakenly collected as a schema
+    // (e.g., it had a key named "properties" or slipped through detection).
+    const validTypes = ['array', 'boolean', 'integer', 'null', 'number', 'object', 'string'];
+    const hasValidType = typeof componentSchema.type === 'string' && validTypes.includes(componentSchema.type);
+    const hasCombiner = 'anyOf' in componentSchema || 'oneOf' in componentSchema || 'allOf' in componentSchema;
+    const hasRef = '$ref' in componentSchema;
+
+    if (!hasValidType && !hasCombiner && !hasRef) {
+      // This is likely a bare properties dict — wrap it as an object schema
+      const wrappedSchema: AnyValue = {
+        type: 'object',
+        properties: { ...componentSchema },
+      };
+      // Remove non-property keys that shouldn't be inside properties
+      for (const k of Object.keys(componentSchema)) {
+        delete componentSchema[k];
+      }
+      Object.assign(componentSchema, wrappedSchema);
+    }
+
+    // Add to components/schemas
+    spec.components!.schemas![componentName] = componentSchema;
+    extractedCount++;
+
+    // Replace all inline occurrences with $ref
+    const refPath = `#/components/schemas/${componentName}`;
+    for (const loc of locs) {
+      const originalDescription = loc.schema.description;
+      const needsDescription = originalDescription && typeof originalDescription === 'string';
+
+      if (needsDescription) {
+        // Wrap in allOf to preserve the inline description
+        loc.parent[loc.key] = {
+          allOf: [{ $ref: refPath }],
+          description: originalDescription,
+        };
+      } else {
+        loc.parent[loc.key] = { $ref: refPath };
+      }
+      replacedCount++;
+    }
+  }
+
+  return { extractedCount, replacedCount };
+}
+
+// =============================================================================
+// MAIN EXECUTION
+// =============================================================================
+
+async function main() {
+  // Parse arguments
+  const inputFile = process.argv[2] || 'openapi.json';
+  const outputFile = process.argv[3] || inputFile;
+
+  console.log(`Processing: ${inputFile}`);
+
+  // Load spec
+  const file = Bun.file(inputFile);
+  let spec: OpenAPISpec;
+
+  try {
+    spec = await file.json();
+  } catch (error) {
+    console.error(`Error: Could not read or parse ${inputFile}`);
+    console.error(error);
+    process.exit(1);
+  }
+
+  // Apply fixes
+  console.log("1. Fixing nullable types...");
+  spec = fixNullableTypes(spec);
+
+  console.log("2. Removing WebSocket paths...");
+  const wsPaths = removeWebsocketPaths(spec);
+  console.log(`   Removed ${wsPaths.length} WebSocket paths: ${JSON.stringify(wsPaths)}`);
+
+  console.log("3. Adding missing responses...");
+  const responseCount = addMissingResponses(spec);
+  console.log(`   Added responses to ${responseCount} operations`);
+
+  console.log("4. Removing patternProperties...");
+  spec = removePatternProperties(spec);
+
+  console.log("5. Fixing descriptions...");
+  spec = fixDescriptions(spec);
+
+  console.log("6. Removing $id fields...");
+  const idResult = removeIdFields(spec);
+  spec = idResult.result;
+  console.log(`   Removed ${idResult.count} $id fields`);
+
+  console.log("7. Setting up dual authentication schemes...");
+  const authSchemes = setupDualAuthSchemes(spec);
+  console.log(`   Configured schemes: apiKey=${authSchemes.apiKey}, bearerAuth=${authSchemes.bearerAuth}`);
+
+  console.log("8. Configuring security options (apiKey OR bearerAuth)...");
+  const securityCount = configureSecurityOptions(spec);
+  console.log(`   Updated ${securityCount} security configurations`);
+
+  console.log("9. Filtering modules...");
+  const { included, excluded } = filterModules(spec);
+  console.log(`   Included ${included.length} paths, excluded ${excluded.length} paths`);
+  if (excluded.length > 0) {
+    const excludedModules = Array.from(new Set(
+      excluded.map(p => {
+        const parts = p.split('/');
+        return parts.length > 2 ? parts[2] : p;
+      })
+    )).sort();
+    console.log(`   Excluded modules: ${JSON.stringify(excludedModules)}`);
+  }
+
+  console.log("10. Collapsing t.Numeric() anyOf patterns in query parameters...");
+  const collapsedCount = collapseNumericAnyOfInQueryParams(spec);
+  console.log(`   Collapsed ${collapsedCount} anyOf query parameters`);
+
+  console.log("11. Injecting x-speakeasy-pagination for offset/limit endpoints...");
+  const paginatedCount = injectSpeakeasyPagination(spec);
+  console.log(`   Added pagination to ${paginatedCount} operations`);
+
+  console.log("12. Converting const to enum...");
+  const constResult = convertConstToEnum(spec);
+  spec = constResult.result;
+  console.log(`   Converted ${constResult.count} const to enum`);
+
+  console.log("13. Deduplicating inline schemas...");
+  const dedupResult = deduplicateSchemas(spec);
+  console.log(`   Deduplicated ${dedupResult.replacedCount} schemas into ${dedupResult.extractedCount} components`);
+
+  // Save
+  await Bun.write(outputFile, JSON.stringify(spec, null, 2));
+
+  console.log(`\nSaved to: ${outputFile}`);
+  console.log(`Total endpoints in SDK: ${included.length}`);
+  console.log("Ready for SDK generation: speakeasy run");
+}
+
+// Run main
+main().catch(error => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});