@workos/oagen 0.0.1

package/skills/generate-emitter/references/generator-guide.md

@@ -0,0 +1,201 @@
+# Generator Implementation Guide
+
+Detailed instructions for implementing each generator file in a language emitter. Read this when implementing Steps 2–4 of the main skill.
+
+## Table of Contents
+
+- [Type Mapping (type-map.ts)](#type-mapping)
+- [Naming Conventions (naming.ts)](#naming-conventions)
+- [Models (models.ts)](#models)
+- [Enums (enums.ts)](#enums)
+- [Resources (resources.ts)](#resources)
+- [Serializers (serializers.ts)](#serializers)
+- [Client (client.ts)](#client)
+- [Errors (errors.ts)](#errors)
+- [Config (config.ts)](#config)
+- [Common/Utilities (common.ts)](#common-utilities)
+- [Type Signatures (types-\*.ts)](#type-signatures)
+- [Tests (tests.ts) and Fixtures (fixtures.ts)](#tests-and-fixtures)
+
+---
+
+## Type Mapping
+
+Foundation file. Map every IR `TypeRef` kind to the target language's type representation.
+
+### Required Mappings
+
+| IR TypeRef                                                   | What to Map                          |
+| ------------------------------------------------------------ | ------------------------------------ |
+| `{ kind: "primitive", type: "string" }`                      | String type                          |
+| `{ kind: "primitive", type: "string", format: "date" }`      | Date type                            |
+| `{ kind: "primitive", type: "string", format: "date-time" }` | DateTime type                        |
+| `{ kind: "primitive", type: "string", format: "uuid" }`      | String or UUID type                  |
+| `{ kind: "primitive", type: "integer" }`                     | Integer type                         |
+| `{ kind: "primitive", type: "number" }`                      | Float/double type                    |
+| `{ kind: "primitive", type: "boolean" }`                     | Boolean type                         |
+| `{ kind: "array", items: ... }`                              | Array/list of mapped item type       |
+| `{ kind: "model", name: "Foo" }`                             | Reference to model class             |
+| `{ kind: "enum", name: "Foo" }`                              | Reference to enum type               |
+| `{ kind: "nullable", inner: ... }`                           | Optional/nullable wrapper            |
+| `{ kind: "union", variants: [...] }`                         | Union/sum type                       |
+| `{ kind: "map", valueType: ... }`                            | Map/dict/Record of mapped value type |
+
+Export a `mapTypeRef(typeRef: TypeRef, namespacePascal: string): string` function.
+
+**For Scenario A:** The type mapping must produce types that match the existing SDK's conventions. If the SDK uses `Date` objects instead of ISO strings for date-time, map accordingly. If the SDK wraps nullable types in `Optional<T>`, do that. Check the design doc's type mapping table.
+
+If the language has a separate type annotation system, also export mapping functions for those (e.g., `mapTypeRefForRbs`, `mapTypeRefForSorbet`).
+
+---
+
+## Naming Conventions
+
+Map oagen's PascalCase IR names to the target language's conventions.
+
+### Required Functions
+
+```typescript
+export function className(name: string): string;
+export function fileName(name: string): string;
+export function methodName(name: string): string;
+export function modulePath(
+  namespace: string,
+  category: string,
+  name: string,
+): string;
+```
+
+### Examples by Language
+
+| IR Name               | Ruby              | Python            | Go                | Kotlin           |
+| --------------------- | ----------------- | ----------------- | ----------------- | ---------------- |
+| `UserProfile` (class) | `UserProfile`     | `UserProfile`     | `UserProfile`     | `UserProfile`    |
+| `UserProfile` (file)  | `user_profile.rb` | `user_profile.py` | `user_profile.go` | `UserProfile.kt` |
+| `listUsers` (method)  | `list_users`      | `list_users`      | `ListUsers`       | `listUsers`      |
+| `user_id` (field)     | `user_id`         | `user_id`         | `UserID`          | `userId`         |
+
+**For Scenario A:** Verify naming conventions against the existing SDK. If the SDK uses non-standard naming (e.g., preserves acronyms like `SSO` instead of converting to `Sso`, or uses `ID` instead of `Id`), the naming functions must reproduce that behavior. Check 5–10 actual names from the SDK and verify the naming functions produce identical output.
+
+Use the shared utilities from `@workos/oagen` (`toPascalCase`, `toSnakeCase`, `toCamelCase`, `toKebabCase`, `toUpperSnakeCase`) as building blocks.
+
+---
+
+## Models
+
+- Input: `Model[]` (each has `name`, `description?`, `fields[]`)
+- Each `Field` has `name`, `type: TypeRef`, `required: boolean`, `description?`
+- Output: One file per model, using the exact model pattern from the design doc
+- Use `type-map.ts` to convert field types
+
+**For Scenario A:** If the existing SDK uses a dual type system (e.g., separate `Organization` and `OrganizationResponse` types), this generator must produce BOTH types. If the SDK has specific decorators, base classes, or factory methods on models, replicate them.
+
+---
+
+## Enums
+
+- Input: `Enum[]` (each has `name`, `values[]`)
+- Each `EnumValue` has `name`, `value` (string), `description?`
+- Output: One file per enum, using the exact enum pattern from the design doc
+
+---
+
+## Resources
+
+- Input: `Service[]` (each has `name`, `operations[]`)
+- Each `Operation` has: `name`, `httpMethod`, `path`, `pathParams`, `queryParams`, `requestBody?`, `response`, `paginated`, `injectIdempotencyKey`
+- Output: One file per service/resource
+- Handle:
+  - Path parameter interpolation (e.g., `/orgs/{id}` to target language's format string mechanism)
+  - Strip leading `/` from paths (use `"organizations"` not `"/organizations"`)
+  - Paginated responses — use the exact pagination pattern from the design doc (NOT a generic page type)
+  - Idempotent POST methods (include an idempotency key as a standalone parameter, not embedded in params)
+  - Query parameters for list methods
+  - A per-request options parameter on every method (last parameter, using the language's idiomatic calling convention)
+  - Documentation for parameters and return types using the target language's standard docstring format
+  - Delete methods signal "no response body" using the language's null/void type and return nil/null/unit
+
+**For Scenario A:** The method signatures, parameter ordering, and return types must match the existing SDK's patterns exactly. If the SDK takes an options object as the first parameter and an ID separately, replicate that. If it uses keyword arguments, replicate that. Read the resource pattern section of the design doc carefully.
+
+---
+
+## Serializers
+
+**Only create this file if the design doc documents a serialization pattern.**
+
+- Input: `Model[]` — generates serialize/deserialize functions for each model
+- Maps between wire format (API responses) and domain types (what the SDK exposes)
+- Common in SDKs that have separate Response and Domain type layers
+
+---
+
+## Client
+
+Mostly static code with namespace interpolation. Must include:
+
+- HTTP request method accepting: HTTP method, path, optional query params, optional body, a model type for deserialization, a page type for paginated responses, an optional idempotency key, and per-request options. Use the target language's idiomatic parameter passing convention.
+- Model and page parameters for response deserialization
+- Response handling: null/void model type returns nil/null, page type creates paginated response, model type creates model instance
+- HTTP request method dispatching (GET/POST/PUT/PATCH/DELETE)
+- Exponential backoff retry with jitter, capped at a reasonable maximum (see the language's SDK design doc for the specific formula)
+- Retryable statuses: 429, 500, 502, 503, 504
+- Respect `Retry-After` headers
+- Auto-generated UUID idempotency keys for POST, reused across retries
+- Resource accessor methods (one per service) with return type documentation
+- Per-request options support for extra headers and timeout overrides
+
+### SDK Scaffolding Files
+
+`generateClient` must also emit the project scaffolding that makes the generated SDK self-contained and analyzable:
+
+- **Barrel entry point** (e.g., `src/index.ts`) — re-exports all public types, models, enums, exceptions, and the main client. This is what `oagen verify` (via the extractor) uses to discover the SDK's public surface.
+- **Project config** (e.g., `tsconfig.json`) — so the SDK can be type-checked and built.
+- **Package manifest** (e.g., `package.json`) — with correct `main`, `types`, and `exports` fields so tooling resolves the entry point.
+
+Without these, `oagen verify` will fail with "No entry point found" because the extractor cannot discover the SDK's public surface.
+
+**For Scenario A:** The client architecture must match the existing SDK. If the client uses constructor overloads, has a specific initialization pattern, or delegates to a separate HTTP transport layer, replicate that. The design doc's client architecture section is authoritative.
+
+---
+
+## Errors
+
+Mostly static code with namespace interpolation. Required error types:
+
+- `APIError` (base), `AuthenticationError` (401), `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitExceededError` (429), `ServerError` (500+), `NetworkError` (connection failures), `ConfigurationError` (missing API key)
+
+**For Scenario A:** Match the existing SDK's error class names and hierarchy exactly. If the SDK names it `BadRequestException` instead of `UnprocessableEntityError`, use the SDK's name.
+
+---
+
+## Config
+
+Configuration class/module with: `api_key`, `base_url`, `max_retries`, `timeout`. Environment variable default for API key.
+
+---
+
+## Common/Utilities
+
+**Create this file if the design doc documents shared utilities.** Generates shared types, pagination base classes, barrel exports, or helper functions. Common in SDKs that have a `common/` directory with shared infrastructure.
+
+---
+
+## Type Signatures
+
+Language-specific. May be 0, 1, or 2 files depending on the language's type system. Examples: `.pyi` stubs for Python, `.d.ts` for JavaScript, nothing for Go/Rust (types are inline). Must include request options and idempotency key parameters on resource method signatures, enum type signatures using the target language's idiomatic enum representation, and delete operations returning the language's void/null type.
+
+---
+
+## Tests and Fixtures
+
+- `generateTests` is the only Emitter interface method — it should internally call `generateFixtures` from `fixtures.ts` and combine both into a single `GeneratedFile[]` return
+- Generate one test file per resource/service
+- Test file paths are language-specific — use the target language's idiomatic convention (e.g., Ruby uses `test/{namespace}/resources/{name}_test.rb`, Node uses `src/{service}/tests/{name}.test.ts`)
+- Test classes/modules nested in namespace modules
+- Each test: stub HTTP request, call method, assert response type using the language's idiomatic assertion style
+- Include error tests (404, 401), retry tests (429 with Retry-After), and idempotency tests (explicit + auto-generated keys)
+- Fixture JSON file paths are also language-specific — organize them near the test files using the target language's convention
+- Use a `load_fixture` helper for reading fixtures
+- Generate fixture JSON files from IR model schemas
+
+**For Scenario A:** Use the exact testing framework and mocking library from the existing SDK. If the SDK uses Jest + jest-fetch-mock, generate Jest tests with jest-fetch-mock, not Vitest + msw. If the SDK uses a specific test structure (describe/it vs test functions, specific setup/teardown patterns), replicate it. Read the test pattern section of the design doc.

package/skills/generate-emitter/references/project-scaffold.md

@@ -0,0 +1,138 @@
+# Emitter Project Scaffold
+
+When `{project}/package.json` does **NOT** exist, create the following boilerplate files to initialize the project. If `package.json` already exists, skip this entirely.
+
+## `package.json`
+
+```json
+{
+  "name": "@workos/oagen-emitters-{language}",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "sdk:generate": "oagen generate --lang {language} --output ./sdk",
+    "sdk:verify": "oagen verify --lang {language} --output ./sdk",
+    "sdk:extract": "oagen extract --lang {language} --output ./sdk-{language}-surface.json"
+  },
+  "dependencies": {
+    "@workos/oagen": "^0.0.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.0",
+    "vitest": "^3.0.0",
+    "@types/node": "^25.3.3"
+  }
+}
+```
+
+## `tsconfig.json`
+
+Mirror oagen core's config: ES2022, ESNext modules, bundler resolution, strict mode, declaration output.
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src", "test"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+## `vitest.config.ts`
+
+```ts
+import { defineConfig } from "vitest/config";
+export default defineConfig({
+  test: { globals: true, include: ["test/**/*.test.ts"] },
+});
+```
+
+## `tsup.config.ts`
+
+```ts
+import { defineConfig } from "tsup";
+export default defineConfig({
+  entry: { index: "src/index.ts" },
+  format: ["esm"],
+  dts: true,
+  clean: true,
+  target: "node20",
+});
+```
+
+## `oagen.config.ts`
+
+```ts
+import type { OagenConfig } from "@workos/oagen";
+const config: OagenConfig = { emitters: [] };
+export default config;
+```
+
+(Step 6 of the main skill adds the emitter to this config.)
+
+## `src/index.ts`
+
+```ts
+// Barrel export — re-exports all emitters
+```
+
+(Step 6 adds the re-export.)
+
+## `.gitignore`
+
+```
+node_modules/
+dist/
+```
+
+After creating these files, run `npm install` in the emitter project directory.
+
+## SDK generation scripts
+
+The `sdk:*` scripts bake in `--lang` and `--output` so you only need to pass the remaining flags via `--`:
+
+```bash
+# Fresh generation
+npm run sdk:generate -- --spec ../openapi.yaml --namespace workos
+
+# Verify generated output
+npm run sdk:verify -- --spec ../openapi.yaml
+
+# Extract API surface from an existing SDK (Scenario A)
+npm run sdk:extract -- --sdk-path ../path-to-live-sdk
+
+# Generate with compat overlay (Scenario A)
+npm run sdk:generate -- --spec ../openapi.yaml --namespace workos --api-surface ./sdk-{language}-surface.json
+
+# Verify with compat check (Scenario A)
+npm run sdk:verify -- --spec ../openapi.yaml --api-surface ./sdk-{language}-surface.json
+
+# Integrate into live SDK (Scenario A)
+npm run sdk:generate -- --spec ../openapi.yaml --namespace workos --api-surface ./sdk-{language}-surface.json --target ../path-to-live-sdk
+```
+
+The `--spec` flag can be replaced by setting `OPENAPI_SPEC_PATH` in the environment.

package/skills/generate-extractor/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: generate-extractor
+description: Scaffold a new language extractor for oagen's compat system, implementing the Extractor interface to extract a live SDK's public API surface. Use when the user wants to add backwards-compatibility support, build an extractor, check for breaking changes or regressions, or asks about extracting an API surface for any language — even if they don't use the word "extractor" explicitly. Also triggers for "compat support", "API surface analysis", or "public surface extraction".
+---
+
+# /generate-extractor
+
+Scaffold a language extractor for oagen's compat verification system. An extractor analyzes a live SDK and returns its public API surface as a canonical `ApiSurface` JSON, which the differ then compares against generated output to detect breaking changes.
+
+## Overview
+
+```
+Live SDK → Extractor → ApiSurface JSON → Differ ← Generated SDK → Violations
+```
+
+Each language needs its own extractor because public surface detection is language-specific (e.g., TypeScript exports vs. Ruby public methods vs. Python `__all__` vs. Go capitalized identifiers). An extractor implements the `Extractor` interface and is registered via `oagen.config.ts` in the emitter project.
+
+## Reference Docs
+
+- [Extractor Contract](../../docs/architecture/extractor-contract.md) — `Extractor` interface, `ApiSurface` type, language-specific strategies
+- [Dependency Layers](../../docs/architecture/dependency-layers.md) — where compat fits in the import hierarchy
+
+## Resolve Paths
+
+**Emitter project:** Use the `project` argument if provided, otherwise use `AskUserQuestion`.
+
+**oagen core:** Check for `node_modules/@workos/oagen/`, or `src/engine/types.ts` in the current directory, otherwise ask.
+
+## Prerequisites
+
+Read and understand these files before starting:
+
+1. **oagen core types** (from `@workos/oagen`): `Extractor`, `ApiSurface`, `ApiClass`, `ApiMethod`, `ApiParam`, `ApiProperty`, `ApiInterface`, `ApiField`, `ApiTypeAlias`, `ApiEnum`
+2. **Reference extractor:** `{oagen}/src/compat/extractors/node.ts` — study the structure, not the TypeScript-specific analysis
+3. **Reference tests:** `{oagen}/test/compat/extractors/node.test.ts`
+4. **Fixture SDK:** `{oagen}/test/fixtures/sample-sdk/`
+5. **Contract spec:** `{oagen}/docs/architecture/extractor-contract.md` — includes language-specific strategies
+
+If an `sdk_path` argument is provided, **delegate SDK exploration to a subagent** to keep file-reading noise out of the main context:
+
+Use the `Agent` tool with `subagent_type: Explore` and a prompt like:
+
+> Explore the SDK at `{sdk_path}`. Focus on: entry point discovery (main module/package), public surface detection (how public vs private symbols are distinguished), type information sources (compiler API, stubs, annotations), class/method extraction patterns, and file/directory layout. Return structured findings with real code snippets and file paths. Only report what you actually find.
+
+The real SDK is the ground truth.
+
+## Step 1: Determine Analysis Strategy
+
+Before writing any code, determine how to analyze the target language's SDK:
+
+| Decision                     | What it controls                                         |
+| ---------------------------- | -------------------------------------------------------- |
+| **Entry point discovery**    | How to find the SDK's main module/package                |
+| **Public surface detection** | How to distinguish public from private symbols           |
+| **Type information source**  | Where types come from (compiler API, stubs, annotations) |
+| **Class/method extraction**  | How to extract classes, methods, params, return types    |
+| **Analysis tooling**         | What npm packages or subprocess calls are needed         |
+
+### Implementation Strategy
+
+Extractors run as TypeScript code. For non-TS/JS SDKs, choose one:
+
+1. **Native analysis (preferred):** Use a TS/JS parser or AST library that can analyze the target language
+2. **Subprocess delegation:** Shell out to a target-language script that performs analysis and returns JSON
+3. **Static file parsing:** Parse type annotation files (`.rbi`, `.rbs`, `.pyi`) or source files directly
+
+Present your proposed strategy to the user for confirmation, including any runtime dependencies.
+
+## Step 2: Create the Extractor
+
+Create `src/compat/extractors/{language}.ts` **in the emitter project**.
+
+```typescript
+import type { ApiSurface, Extractor } from '@workos/oagen';
+import { resolveHints } from '@workos/oagen';
+
+export const {language}Extractor: Extractor = {
+  language: '{language}',
+  hints: resolveHints({
+    // Override only the hints that differ from Node/TypeScript defaults.
+    // See docs/architecture/extractor-contract.md for the full reference.
+    // stripNullable: (type) => ...,
+    // isExtractionArtifact: (type) => ...,
+    // tolerateCategoryMismatch: false,
+    // derivedModelNames: (name) => [...],
+  }),
+  async extract(sdkPath: string): Promise<ApiSurface> {
+    // 1. Discover entry point
+    // 2. Load and analyze public surface
+    // 3. Extract classes, interfaces, type aliases, enums
+    // 4. Build export map
+    // 5. Return sorted, deterministic ApiSurface
+    return {
+      language: '{language}',
+      extractedFrom: sdkPath,
+      extractedAt: new Date().toISOString(),
+      classes: sortRecord(classes),
+      interfaces: sortRecord(interfaces),
+      typeAliases: sortRecord(typeAliases),
+      enums: sortRecord(enums),
+      exports: sortRecord(exports),
+    };
+  },
+};
+```
+
+### Implementation Rules
+
+1. **Deterministic output** — Running twice on the same SDK must produce identical JSON. Sort all record keys and array members.
+2. **Public surface only** — Extract only public/exported symbols. Each language defines "public" differently.
+3. **Preserve fidelity** — Capture method signatures as they appear in the live SDK, not as the IR would generate them.
+4. **Handle missing infrastructure gracefully** — Throw a descriptive error if required files are missing.
+5. **Populate all ApiSurface fields** — `classes`, `interfaces`, `typeAliases`, `enums`, `exports`. Map as closely as possible even if the language doesn't have a direct equivalent for every category.
+6. **Provide `hints`** — Every extractor must include a `hints: LanguageHints` field. Use `resolveHints({...})` to start from Node defaults and override only the language-specific methods. Test that your hints produce correct results for the target language's type strings.
+
+## Step 3: Register the Extractor
+
+Add to `oagen.config.ts`:
+
+```typescript
+import { {language}Extractor } from './src/compat/extractors/{language}.js';
+const config: OagenConfig = {
+  emitters: [/* ... */],
+  extractors: [{language}Extractor],
+};
+```
+
+## Step 4: Create a Fixture SDK
+
+Create a minimal but representative fixture at `test/fixtures/sample-sdk-{language}/` **in the emitter project**. It must include:
+
+1. A client class with at least 3 methods (list, get, delete) — required/optional params, different return types
+2. At least one model/data class (e.g., `Organization` with `id`, `name`)
+3. At least one enum with 2+ members
+4. At least one interface/protocol/type alias (if the language supports them)
+5. A clear entry point that re-exports all public symbols
+6. At least one readonly property on the client class
+
+Mirror the Node fixture at `{oagen}/test/fixtures/sample-sdk/` in terms of what it tests, using the target language's idioms.
+
+## Step 5: Create Tests
+
+Create `test/compat/extractors/{language}.test.ts` **in the emitter project** covering:
+
+1. Extracts classes with methods and properties
+2. Extracts method params and return types
+3. Extracts optional params and readonly properties
+4. Extracts interfaces/protocols and enums
+5. Extracts type aliases and barrel exports
+6. Produces deterministic output (extract twice, compare)
+7. Sets metadata correctly
+
+Use `toMatchObject` for partial assertions and `toMatchInlineSnapshot()` for at least one representative snapshot per category.
+
+## Step 6: Validate
+
+```bash
+# All tests pass
+cd {project} && npx vitest run
+
+# Manual extraction against fixture
+npx tsx -e "
+  import { {language}Extractor } from './src/compat/extractors/{language}.js';
+  const surface = await {language}Extractor.extract('test/fixtures/sample-sdk-{language}');
+  console.log(JSON.stringify(surface, null, 2));
+" > /tmp/test-{language}-surface.json
+
+# Determinism check — extract twice, diff
+```
+
+If `sdk_path` was provided, also test against the real SDK and verify all public classes are captured, method signatures match, and no private symbols leak through.
+
+## Verification Report
+
+```
+=== Extractor: {language} ===
+Files created:   src/compat/extractors/{language}.ts, test suite, fixture SDK
+Modified:        oagen.config.ts
+Validation:      Tests / Fixture extract / Determinism / Real SDK extract
+ApiSurface:      {N} classes, {N} interfaces, {N} type aliases, {N} enums, {N} exports
+```
+
+## Output
+
+This skill produces, in the emitter project:
+
+- `src/compat/extractors/{language}.ts` — extractor implementing the `Extractor` interface with `LanguageHints`
+- `test/compat/extractors/{language}.test.ts` — extraction tests against fixture SDK
+- `test/fixtures/sample-sdk-{language}/` — minimal fixture SDK for testing
+- Updated `oagen.config.ts` with the new extractor registered
+
+## Common Pitfalls
+
+1. **Non-deterministic output** — Always sort record keys and array members
+2. **Missing error on bad input** — Throw descriptive errors for missing entry points or type infrastructure
+3. **Extracting private symbols** — Only extract what consumers can actually use
+4. **Subprocess encoding** — Ensure UTF-8 and handle stderr/stdout correctly
+5. **Hardcoded paths** — Use the `sdkPath` parameter, never hardcode fixture paths
+6. **Ignoring generics** — Capture generic type parameters (e.g., `ListResponse<Organization>`)
+7. **Forgetting the export map** — Map the entry point to its public symbols even if the language doesn't have explicit barrel exports