@workos/oagen 0.0.1

package/docs/cli.md

@@ -0,0 +1,156 @@
+# CLI Reference
+
+All commands support `--help` for full usage details.
+
+## `oagen generate`
+
+Generate SDK code from an OpenAPI spec.
+
+```bash
+oagen generate --spec openapi.yml --lang node --output ./sdk --namespace WorkOS
+```
+
+| Argument               | Required | Default                        | Description                                                                                                                                                                                                                                  |
+| ---------------------- | -------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--spec <path>`        | No       | `OPENAPI_SPEC_PATH` env        | Path to an OpenAPI 3.x spec file.                                                                                                                                                                                                            |
+| `--lang <language>`    | Yes      |                                | Target language — must have a registered emitter (via `oagen.config.ts`)                                                                                                                                                                     |
+| `--output <dir>`       | Yes      |                                | Directory to write generated files into                                                                                                                                                                                                      |
+| `--namespace <name>`   | No       | Spec's `info.title`            | SDK namespace in PascalCase — used directly for code identifiers (e.g., `WorkOS::Client`) and converted to `snake_case` for file paths (e.g., `lib/work_os/`). Use PascalCase with the exact casing you want (e.g., `WorkOS` not `work_os`). |
+| `--dry-run`            | No       | `false`                        | Print the list of file paths that would be generated, without writing anything to disk                                                                                                                                                       |
+| `--api-surface <path>` | No       |                                | Path to baseline API surface JSON for compat overlay                                                                                                                                                                                         |
+| `--manifest <path>`    | No       | `<output>/smoke-manifest.json` | Path to smoke-manifest.json for method overlay (auto-discovered in output dir if present)                                                                                                                                                    |
+| `--no-compat-check`    | No       | `false`                        | Skip compat overlay even if `--api-surface` is provided                                                                                                                                                                                      |
+
+## `oagen diff`
+
+Review or apply spec changes. Use `--report` to see what changed, or pass `--lang` and `--output` to incrementally regenerate affected files.
+
+```bash
+oagen diff --old v1.yml --new v2.yml --report           # review changes
+oagen diff --old v1.yml --new v2.yml --lang node --output ./sdk  # regenerate
+```
+
+| Argument               | Required | Description                                             |
+| ---------------------- | -------- | ------------------------------------------------------- |
+| `--old <path>`         | Yes      | Path to the old/previous spec                           |
+| `--new <path>`         | Yes      | Path to the new/current spec                            |
+| `--lang <language>`    | No       | Target language (required unless `--report`)            |
+| `--output <dir>`       | No       | Output directory for regenerated files                  |
+| `--report`             | No       | Output a diff report as JSON instead of generating code |
+| `--force`              | No       | Allow file deletions without confirmation               |
+| `--api-surface <path>` | No       | Path to baseline API surface JSON for compat overlay    |
+| `--manifest <path>`    | No       | Path to smoke-manifest.json for method overlay          |
+
+## `oagen extract`
+
+Extract the public API surface from an existing SDK. Produces a JSON file used as input for compat overlay and verification.
+
+```bash
+oagen extract --sdk-path ./existing-sdk --lang ruby --output ./sdk/sdk-ruby-surface.json
+oagen extract --sdk-path ./existing-sdk --lang ruby --output my-surface.json
+```
+
+| Argument            | Required | Default                   | Description                                                                                                     |
+| ------------------- | -------- | ------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `--sdk-path <path>` | Yes      |                           | Path to the live SDK                                                                                            |
+| `--lang <language>` | Yes      |                           | Target language                                                                                                 |
+| `--output <path>`   | No       | `sdk-{lang}-surface.json` | Output file path (recommend writing to your output dir, e.g. `./sdk/sdk-ruby-surface.json`, and gitignoring it) |
+
+## `oagen verify`
+
+Verify an already-generated SDK — run smoke tests and optional compat checks. Use after `oagen generate` or `oagen diff`.
+
+```bash
+oagen verify --lang node --output ./sdk --spec openapi.yml
+
+# With compat check
+oagen verify --lang node --output ./sdk --spec openapi.yml \
+  --api-surface ./sdk/sdk-node-surface.json
+```
+
+| Argument                | Required | Default                         | Description                                                                                                   |
+| ----------------------- | -------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `--lang <language>`     | Yes      |                                 | Target language                                                                                               |
+| `--output <dir>`        | Yes      |                                 | Path to the generated SDK                                                                                     |
+| `--spec <path>`         | No       | `OPENAPI_SPEC_PATH` env         | Path to an OpenAPI 3.x spec file                                                                              |
+| `--api-surface <path>`  | No       |                                 | Baseline API surface JSON — enables compat verification                                                       |
+| `--raw-results <path>`  | No       | auto-generated                  | Path to an existing smoke baseline file to diff against                                                       |
+| `--smoke-config <path>` | No       |                                 | Smoke config JSON for skip lists and service mappings                                                         |
+| `--smoke-runner <path>` | No       |                                 | Custom smoke runner script (overrides built-in `sdk-test.ts`)                                                 |
+| `--scope <mode>`        | No       | `spec-only` when `--spec` given | Compat scope: `full` compares all baseline symbols, `spec-only` only compares symbols derivable from the spec |
+| `--diagnostics`         | No       | `false`                         | Output `verify-diagnostics.json` with structured violation breakdown                                          |
+| `--max-retries <n>`     | No       | `3`                             | Max retry iterations for self-correcting overlay loop (set to 0 for single-pass)                              |
+
+**Exit codes:**
+
+| Code | Meaning                                                                 | Details                     |
+| ---- | ----------------------------------------------------------------------- | --------------------------- |
+| 0    | Clean — all checks passed                                               |                             |
+| 1    | Findings — CRITICAL smoke mismatches, compat violations, or missing ops | `smoke-diff-findings.json`  |
+| 2    | Compile error — SDK failed type check                                   | `smoke-compile-errors.json` |
+
+## `oagen init`
+
+Scaffold a new emitter project with all boilerplate files and a compilable stub emitter.
+
+```bash
+oagen init --lang ruby
+oagen init --lang go --project ./my-emitter
+```
+
+| Argument            | Required | Default | Description                          |
+| ------------------- | -------- | ------- | ------------------------------------ |
+| `--lang <language>` | Yes      |         | Target language (e.g., `ruby`, `go`) |
+| `--project <dir>`   | No       | `.`     | Directory to create the project in   |
+
+Creates:
+
+- `package.json` with `@workos/oagen` dependency and `sdk:generate`/`sdk:verify`/`sdk:extract` scripts
+- `tsconfig.json`, `vitest.config.ts`, `tsup.config.ts` — build/test tooling
+- `oagen.config.ts` — registers the stub emitter
+- `src/{language}/index.ts` — stub emitter implementing the full `Emitter` interface
+- `src/index.ts` — barrel export
+- Empty directories: `test/`, `smoke/`, `docs/sdk-architecture/`
+
+After initialization, `npm run typecheck` passes immediately. Implement your emitter methods in `src/{language}/` to start generating SDK code.
+
+## `oagen parse`
+
+Parse an OpenAPI spec and output the IR as JSON to stdout. Useful for inspecting what the parser extracts.
+
+```bash
+oagen parse --spec openapi.yml
+```
+
+| Argument        | Required | Default                 | Description                                      |
+| --------------- | -------- | ----------------------- | ------------------------------------------------ |
+| `--spec <path>` | No       | `OPENAPI_SPEC_PATH` env | Path to an OpenAPI 3.x spec file (YAML or JSON). |
+
+## Configuration (`oagen.config.ts`)
+
+Place an `oagen.config.ts` (or `.js`/`.mjs`) in your project root to register emitters, extractors, and customize pipeline behavior. The CLI loads this file at startup before any command runs.
+
+```ts
+import type { OagenConfig } from "@workos/oagen";
+import { nodeEmitter } from "./src/node/index.js";
+import { nodeExtractor } from "./src/node/extractor.js";
+
+const config: OagenConfig = {
+  emitters: [nodeEmitter],
+  extractors: [nodeExtractor],
+  docUrl: "https://workos.com/docs",
+};
+
+export default config;
+```
+
+### Options
+
+| Key                    | Type                     | Description                                                                                                                                                                                                                       |
+| ---------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `emitters`             | `Emitter[]`              | Language emitters to register. Each emitter implements the `Emitter` interface and generates SDK files for one target language.                                                                                                   |
+| `extractors`           | `Extractor[]`            | API surface extractors to register. Each extractor parses a live SDK and produces an `ApiSurface` JSON used for compat verification.                                                                                              |
+| `emitterProject`       | `string`                 | Path to the emitter project directory. Used by skills to scaffold new emitters, tests, and smoke runners in the correct location.                                                                                                 |
+| `smokeRunners`         | `Record<string, string>` | Map from language key to custom smoke runner script path. Overrides the built-in `sdk-test.ts` for `oagen verify`. Can also be set per-invocation with `--smoke-runner`.                                                          |
+| `operationIdTransform` | `(id: string) => string` | Custom transform for operation IDs. Receives the raw `operationId` from the spec; return the desired operation name. No additional casing conversion is applied. When omitted, `operationId` values are converted to `camelCase`. |
+| `docUrl`               | `string`                 | Base URL for documentation links. When set, relative markdown paths in descriptions (e.g. `[User](/reference/authkit/user)`) are expanded to full URLs (e.g. `[User](https://workos.com/docs/reference/authkit/user)`).           |

package/docs/contributor/index.md

@@ -0,0 +1,10 @@
+# Contributor Docs
+
+These documents describe the maintenance rules for oagen itself and the guarantees made to consumers of the public API. If you are modifying oagen core (the parser, engine, IR types, compat system, or CLI), start here to understand what contracts you must preserve.
+
+## Key Documents
+
+- [Public API Policy](public-api.md) — three-tier public surface (core default export, advanced subpaths, internal) and what constitutes a breaking change
+- [Versioning and Migration](versioning.md) — IR version bumping rules, package versioning, and advanced workflow compatibility
+- [Dependency Layers](../architecture/dependency-layers.md) — one-way import matrix (`ir → utils → parser → engine/differ/compat → cli`) enforced by structural linter
+- [Pipeline Architecture](../architecture/pipeline.md) — three-stage parse/emit/write flow with orchestrator details

package/docs/contributor/public-api.md

@@ -0,0 +1,59 @@
+# Public API Policy
+
+This document defines what oagen treats as public API for OSS consumers.
+
+## Core Public API
+
+The default `@workos/oagen` entrypoint is the core public API.
+
+It includes:
+
+- IR types
+- parser entrypoints such as `parseSpec`
+- emitter-facing types such as `Emitter`, `EmitterContext`, and `GeneratedFile`
+- generation runtime entrypoints such as `generate`, `generateFiles`, and `generateIncremental`
+- spec diffing APIs such as `diffSpecs` and `mapChangesToFiles`
+- naming utilities used by emitters
+- `planOperation`
+- config typing needed by emitter projects
+
+Changes to this surface require a deliberate compatibility review.
+
+## Advanced Public API
+
+The following APIs are public, but not part of the default entrypoint:
+
+- `@workos/oagen/compat`
+- `@workos/oagen/verify`
+
+These modules cover compatibility overlays, extractor registration, built-in extractors, and verification helpers. They are supported, but they are more opinionated and may evolve faster than the core framework surface.
+
+## Internal API
+
+Anything not exported from a package entrypoint should be treated as internal implementation detail, including:
+
+- deep imports into `src/*`
+- CLI implementation modules
+- parser internals below `parseSpec`
+- compat internals below the documented compat entrypoint
+- verify internals below the documented verify entrypoint
+
+Internal APIs may change without notice.
+
+## Documentation Rule
+
+If an API is intended for external use, it must satisfy all of the following:
+
+1. It is exported from a package entrypoint.
+2. It is documented in user-facing docs.
+3. It has tests that reflect the intended behavior.
+
+If one of those is missing, the API should be considered provisional at best.
+
+## Stability Rule
+
+When in doubt:
+
+- keep the default entrypoint small
+- prefer adding advanced capabilities behind explicit subpaths
+- avoid promoting internal helpers into the public surface unless they are needed by emitter authors

package/docs/contributor/versioning.md

@@ -0,0 +1,48 @@
+# Versioning and Migration
+
+oagen has two different compatibility concerns. They should not be treated as interchangeable.
+
+## 1. Package Version
+
+The npm package version communicates overall release maturity and changelog history.
+
+## 2. Advanced Workflow Compatibility
+
+Compat extraction, overlays, smoke verification, and target integration are higher-level workflows built on top of the core framework. They may require narrower migration guidance than the core parser/emitter contract.
+
+Treat changes here as public if they affect:
+
+- documented CLI flags
+- documented subpath exports
+- persisted file formats such as extracted API surfaces or diagnostics files
+
+## Compile-Time Safety
+
+The primary compatibility mechanism is `assertNever`, which enforces exhaustive `switch` statements over `TypeRef.kind` at compile time. Adding a new IR variant causes build failures in any emitter that doesn't handle it.
+
+## Migration Guidance
+
+Every release that changes public behavior should describe:
+
+1. what changed
+2. who is affected
+3. whether the change is core or advanced
+4. what users need to update
+
+At minimum, migration notes should call out:
+
+- IR shape changes
+- emitter contract changes
+- config shape changes
+- CLI flag changes
+- compat JSON format changes
+
+## Release Discipline
+
+Before broadening the public surface:
+
+1. decide whether the API belongs in the core entrypoint or an advanced subpath
+2. document it
+3. add tests that exercise its intended use by external consumers
+
+If that discipline is too expensive, the API is not ready to be public.

package/docs/core/index.md

@@ -0,0 +1,12 @@
+# Core Docs
+
+These documents define the stable center of oagen as an OSS framework.
+
+- [Minimal Quickstart](quickstart.md)
+- [Minimal Emitter](minimal-emitter.md)
+- [CLI Reference](../cli.md)
+- [Pipeline Architecture](../architecture/pipeline.md)
+- [IR Type System Reference](../architecture/ir-types.md)
+- [Emitter Contract](../architecture/emitter-contract.md)
+
+Read the quickstart first. The goal is to get from a spec to generated files without learning compatibility overlays, extractors, or smoke workflows.

package/docs/core/minimal-emitter.md

@@ -0,0 +1,134 @@
+# Minimal Emitter
+
+This guide shows the smallest useful emitter shape in oagen.
+
+Use it when you want to understand the minimum contract quickly. If you need the full interface details, overlay behavior, and versioning rules, read the [Emitter Contract](../architecture/emitter-contract.md).
+
+## Goal
+
+A minimal emitter should:
+
+- declare a `language`
+- return files from at least one generator method
+- return `[]` from methods the language does not use yet
+
+That is enough to prove the parser, runtime, and file-writing loop are working.
+
+## Smallest Practical Skeleton
+
+```ts
+import type {
+  ApiSpec,
+  Emitter,
+  Enum,
+  GeneratedFile,
+  Model,
+  Service,
+} from "@workos/oagen";
+
+function namesFile(path: string, values: string[]): GeneratedFile[] {
+  if (values.length === 0) return [];
+  return [{ path, content: values.join("\n") }];
+}
+
+export const demoEmitter: Emitter = {
+  language: "demo",
+
+  generateModels(models: Model[]): GeneratedFile[] {
+    return namesFile(
+      "models.txt",
+      models.map((model) => model.name),
+    );
+  },
+
+  generateEnums(enums: Enum[]): GeneratedFile[] {
+    return namesFile(
+      "enums.txt",
+      enums.map((entry) => entry.name),
+    );
+  },
+
+  generateResources(services: Service[]): GeneratedFile[] {
+    return namesFile(
+      "services.txt",
+      services.map((service) => service.name),
+    );
+  },
+
+  generateClient(spec: ApiSpec): GeneratedFile[] {
+    return [
+      {
+        path: "summary.txt",
+        content: [
+          `name: ${spec.name}`,
+          `services: ${spec.services.length}`,
+        ].join("\n"),
+      },
+    ];
+  },
+
+  generateErrors(): GeneratedFile[] {
+    return [];
+  },
+
+  generateConfig(): GeneratedFile[] {
+    return [];
+  },
+
+  generateTypeSignatures(): GeneratedFile[] {
+    return [];
+  },
+
+  generateTests(): GeneratedFile[] {
+    return [];
+  },
+
+  fileHeader(): string {
+    return "# Generated by oagen";
+  },
+};
+```
+
+## What This Proves
+
+With just this emitter, you can verify:
+
+- the spec parses into IR
+- the emitter is registered correctly
+- the generation runtime calls each method in the expected order
+- output files are written to disk
+
+## What It Does Not Cover Yet
+
+This is intentionally incomplete. It does not try to solve:
+
+- language-specific naming conventions
+- request/response rendering
+- operation planning
+- compatibility overlays
+- smoke verification
+- integration into an existing SDK
+
+## The First Real Upgrade
+
+After the minimal emitter works, the next step is usually to make `generateResources()` and `generateClient()` understand operations rather than only names.
+
+That is when `planOperation()` becomes useful:
+
+```ts
+import { planOperation } from "@workos/oagen";
+
+for (const service of services) {
+  for (const operation of service.operations) {
+    const plan = planOperation(operation);
+    // render using plan.hasBody, plan.isPaginated, plan.responseModelName, ...
+  }
+}
+```
+
+## Recommended Path
+
+1. Start with this minimal emitter.
+2. Make generation deterministic and add golden tests.
+3. Add real model and operation rendering.
+4. Only then add advanced features like compat overlays or smoke verification.

package/docs/core/quickstart.md

@@ -0,0 +1,142 @@
+# Minimal Quickstart
+
+This guide takes you from an OpenAPI spec to a tiny working emitter with the fewest moving parts possible.
+
+## What You Will Build
+
+- parse an OpenAPI spec into oagen's IR
+- scaffold an emitter project
+- replace the stub emitter with a minimal implementation
+- generate a few files
+
+This quickstart intentionally ignores advanced features like API-surface extraction, compatibility overlays, smoke verification, and live-SDK integration.
+
+## 1. Install oagen
+
+```bash
+npm install @workos/oagen
+```
+
+## 2. Inspect Your Spec
+
+```bash
+oagen parse --spec openapi.yml
+```
+
+This prints the parsed IR as JSON. Before writing an emitter, confirm the parser is extracting the services, models, and enums you expect.
+
+## 3. Scaffold an Emitter Project
+
+```bash
+oagen init --lang demo --project ./demo-emitter
+cd ./demo-emitter
+npm install
+```
+
+The scaffold gives you:
+
+- `oagen.config.ts`
+- `src/demo/index.ts`
+- build/test tooling
+- `sdk:generate` and related package scripts
+
+## 4. Replace the Stub Emitter
+
+Edit `src/demo/index.ts` to return a few simple files:
+
+```ts
+import type {
+  ApiSpec,
+  Emitter,
+  Enum,
+  GeneratedFile,
+  Model,
+  Service,
+} from "@workos/oagen";
+
+function renderSummary(spec: ApiSpec): string {
+  return [
+    `name: ${spec.name}`,
+    `services: ${spec.services.length}`,
+    `models: ${spec.models.length}`,
+    `enums: ${spec.enums.length}`,
+  ].join("\n");
+}
+
+function renderModels(models: Model[]): GeneratedFile[] {
+  if (models.length === 0) return [];
+  return [
+    {
+      path: "models.txt",
+      content: models.map((model) => model.name).join("\n"),
+    },
+  ];
+}
+
+function renderEnums(enums: Enum[]): GeneratedFile[] {
+  if (enums.length === 0) return [];
+  return [
+    {
+      path: "enums.txt",
+      content: enums.map((entry) => entry.name).join("\n"),
+    },
+  ];
+}
+
+function renderServices(services: Service[]): GeneratedFile[] {
+  if (services.length === 0) return [];
+  return [
+    {
+      path: "services.txt",
+      content: services.map((service) => service.name).join("\n"),
+    },
+  ];
+}
+
+export const demoEmitter: Emitter = {
+  language: "demo",
+  generateModels: (models) => renderModels(models),
+  generateEnums: (enums) => renderEnums(enums),
+  generateResources: (services) => renderServices(services),
+  generateClient: (spec) => [
+    {
+      path: "summary.txt",
+      content: renderSummary(spec),
+    },
+  ],
+  generateErrors: () => [],
+  generateConfig: () => [],
+  generateTypeSignatures: () => [],
+  generateTests: () => [],
+  fileHeader: () => "# Generated by oagen",
+};
+```
+
+## 5. Generate Files
+
+```bash
+npm run sdk:generate -- --spec ../openapi.yml --namespace DemoSdk
+```
+
+Expected result:
+
+- `sdk/summary.txt`
+- `sdk/models.txt` when the spec has models
+- `sdk/enums.txt` when the spec has enums
+- `sdk/services.txt` when the spec has services
+
+## 6. Grow from Here
+
+Once the minimal loop works:
+
+1. Replace text files with real language output.
+2. Use [`planOperation`](../../src/engine/operation-plan.ts) via `@workos/oagen` to share operation decision logic.
+3. Add emitter tests with fixture specs and golden files.
+4. Only then consider advanced workflows like `oagen verify` or compatibility overlays.
+
+## Next Reads
+
+- [Reference Emitter](../../examples/reference-emitter/) — a working TypeScript emitter you can study and copy
+- [Emitter Contract](../architecture/emitter-contract.md)
+- [IR Type System Reference](../architecture/ir-types.md)
+- [CLI Reference](../cli.md)

package/docs/diagrams/generate-sdk-workflow.md

@@ -0,0 +1,50 @@
+# /generate-sdk Workflow
+
+```mermaid
+---
+config:
+    layout: elk
+---
+flowchart TD
+    start([/generate-sdk]) --> existingSDK{Existing SDK?}
+
+    existingSDK -- "Yes: Scenario A" --> a_emitter["/generate-emitter"]
+    existingSDK -- "No: Scenario B" --> b_emitter["/generate-emitter"]
+
+    a_emitter --> a_extractor["/generate-extractor
+    extract live SDK public API
+    into api-surface.json"]
+
+    a_extractor --> a_compat["/verify-compat
+    diff generated SDK
+    against api-surface.json"]
+
+    a_compat --> overlay_gen
+
+    subgraph overlay loop
+        overlay_gen["generate with overlay"]
+        overlay_gen --> overlay_diff["diff against baseline"]
+        overlay_diff --> violations{violations?}
+        violations -- yes --> patch["patchOverlay"]
+        patch --> overlay_gen
+    end
+
+    violations -- no --> smoke["/generate-smoke-test
+    scaffold HTTP interception
+    + wire-level parity tests"]
+
+    b_emitter --> smoke
+
+    smoke --> loop_start
+
+    subgraph emitter-fixing loop
+        loop_start["oagen generate"]
+        loop_start --> loop_verify["oagen verify"]
+        loop_verify --> exitcode{exit code?}
+        exitcode -- "1 or 2" --> fix["read findings, fix emitter"]
+        fix --> loop_start
+    end
+
+    exitcode -- 0 --> final(["final validation
+    tsc + vitest + tsup + lint"])
+```

package/docs/index.md

@@ -0,0 +1,40 @@
+# Docs Overview
+
+oagen documentation is organized by adoption stage.
+
+## Core
+
+Start here if you want to understand or use the framework itself:
+
+- [Core Index](core/index.md)
+- [Minimal Quickstart](core/quickstart.md)
+- [CLI Reference](cli.md)
+- [Emitter Contract](architecture/emitter-contract.md)
+- [IR Type System Reference](architecture/ir-types.md)
+- [Pipeline Architecture](architecture/pipeline.md)
+
+## Advanced
+
+Read these when you need migration or verification workflows beyond basic generation:
+
+- [Advanced Index](advanced/index.md)
+- [Workflows](architecture/workflows.md)
+- [Extractor Contract](architecture/extractor-contract.md)
+- [Non-Additive Changes](architecture/non-additive-changes.md)
+
+## Agent Task Guides
+
+Focused guides for AI agents working on specific areas of the codebase:
+
+- [Architecture & Core Contracts](agents/architecture.md)
+- [Emitter Implementation](agents/emitters.md)
+- [Testing & Smoke Validation](agents/testing.md)
+
+## Contributor
+
+Read these if you are maintaining oagen itself or depending on its public API surface:
+
+- [Contributor Index](contributor/index.md)
+- [Public API Policy](contributor/public-api.md)
+- [Versioning and Migration](contributor/versioning.md)
+- [Dependency Layers](architecture/dependency-layers.md)