@workos/oagen 0.0.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "oagen",
+  "version": "0.0.1",
+  "description": "Skills for building language emitters, extractors, and smoke tests for the oagen OpenAPI SDK generator",
+  "author": {
+    "name": "WorkOS",
+    "url": "https://github.com/workos"
+  },
+  "repository": "https://github.com/workos/oagen",
+  "license": "MIT",
+  "keywords": ["openapi", "sdk", "codegen", "emitter"]
+}

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WorkOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# oagen
+
+oagen is a framework for building custom SDK generators from OpenAPI 3.x specifications.
+
+Its core job is narrow:
+
+- parse an OpenAPI spec into a typed intermediate representation (IR)
+- let language emitters turn that IR into files
+- regenerate the SDK when the spec changes
+
+More advanced workflows, such as preserving the public API of an existing SDK during a migration to generation, is also supported.
+
+## Who This Is For
+
+oagen is a fit if you:
+
+- need more control than off-the-shelf generators give you
+- want to build or maintain a custom emitter for one or more languages
+- care about generated output being idiomatic for a specific SDK style
+
+oagen is probably not a fit if you:
+
+- just want a turnkey SDK generator with batteries included
+- do not want to maintain emitter code
+- do not need a reusable IR or generation framework
+
+## Core Concept
+
+oagen has a small core:
+
+- **Parser**: OpenAPI 3.x -> `ApiSpec` IR
+- **Emitter runtime**: `ApiSpec` -> `GeneratedFile[]`
+- **Diffing**: compare spec versions and map changes to generated output
+
+Advanced features such as API-surface extraction, compatibility overlays, smoke verification, and live-SDK integration are available, but they are optional. You can ignore them until you need them.
+
+## Quickstart
+
+Install the package:
+
+```bash
+npm install @workos/oagen
+```
+
+Inspect a spec:
+
+```bash
+oagen parse --spec openapi.yml
+```
+
+Create an emitter project:
+
+```bash
+oagen init --lang ruby --project ./my-emitter
+cd ./my-emitter
+```
+
+Generate files with your emitter:
+
+```bash
+npm run sdk:generate -- --spec ../openapi.yml --namespace MyService
+```
+
+For the shortest end-to-end setup, see [Minimal Quickstart](docs/core/quickstart.md).
+
+## The Core API
+
+The default `@workos/oagen` entrypoint is intentionally focused on the framework core:
+
+```ts
+import {
+  diffSpecs,
+  generate,
+  generateFiles,
+  generateIncremental,
+  getEmitter,
+  mapChangesToFiles,
+  parseSpec,
+  planOperation,
+  registerEmitter,
+  toCamelCase,
+  toPascalCase,
+  toSnakeCase,
+} from "@workos/oagen";
+import type {
+  ApiSpec,
+  Emitter,
+  EmitterContext,
+  GeneratedFile,
+  Model,
+  Enum,
+  Service,
+  OperationPlan,
+} from "@workos/oagen";
+```
+
+Advanced compat and verification APIs are available through explicit subpaths:
+
+```ts
+import {
+  buildOverlayLookup,
+  patchOverlay,
+  registerExtractor,
+} from "@workos/oagen/compat";
+import { runCompatCheck, runOverlayRetryLoop } from "@workos/oagen/verify";
+```
+
+## Building an Emitter
+
+Emitters are pure functions over the IR. They receive typed IR nodes and return `GeneratedFile[]`.
+
+```ts
+import type { Emitter } from "@workos/oagen";
+
+const myEmitter: Emitter = {
+  language: "go",
+  generateModels: (models, ctx) => [
+    /* ... */
+  ],
+  generateEnums: (enums, ctx) => [
+    /* ... */
+  ],
+  generateResources: (services, ctx) => [
+    /* ... */
+  ],
+  generateClient: (spec, ctx) => [
+    /* ... */
+  ],
+  generateErrors: () => [],
+  generateConfig: () => [],
+  generateTests: () => [],
+  fileHeader: () => "// Auto-generated by oagen. Do not edit.",
+};
+```
+
+Start with:
+
+- [Reference Emitter](examples/reference-emitter/) — a working TypeScript emitter with tests against a GitHub-flavored fixture spec
+- [Minimal Quickstart](docs/core/quickstart.md)
+- [Emitter Contract](docs/architecture/emitter-contract.md)
+- [IR Type System Reference](docs/architecture/ir-types.md)
+
+## Commands
+
+| Command          | Purpose                                             |
+| ---------------- | --------------------------------------------------- |
+| `oagen parse`    | Parse a spec and print IR JSON                      |
+| `oagen init`     | Scaffold an emitter project                         |
+| `oagen generate` | Run a registered emitter                            |
+| `oagen diff`     | Review spec changes or incrementally regenerate     |
+| `oagen extract`  | Advanced: extract an SDK API surface for compat use |
+| `oagen verify`   | Advanced: smoke-test output and run compat checks   |
+
+See [CLI Reference](docs/cli.md).
+
+## Documentation
+
+- [Docs Overview](docs/index.md)
+- [Core Docs](docs/core/index.md)
+- [Advanced Docs](docs/advanced/index.md)
+- [Contributor Docs](docs/contributor/index.md)
+- [Public API Policy](docs/contributor/public-api.md)
+- [Versioning and Migration](docs/contributor/versioning.md)
+
+## Advanced Workflows
+
+oagen also includes tooling for a more opinionated migration workflow:
+
+- extract the public API of an existing SDK
+- generate a replacement while preserving names and exports
+- verify the generated SDK against smoke tests and compatibility checks
+- integrate generated files into a live SDK tree
+
+Those workflows are documented separately because they are not required to use the core framework:
+
+- [Workflows](docs/architecture/workflows.md)
+- [Extractor Contract](docs/architecture/extractor-contract.md)
+- [CLI Reference](docs/cli.md)
+
+## AI / Plugin Tooling
+
+This repo ships with Claude Code plugin assets and skills for scaffold-and-verify workflows. The framework is usable without any agent tooling.
+
+If you need them, start here:
+
+- [Agent Docs](docs/agents/architecture.md)
+- [Emitter Agent Docs](docs/agents/emitters.md)
+- [Testing Agent Docs](docs/agents/testing.md)
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run typecheck
+```

package/dist/chunk-CIX5NOBF.js

@@ -0,0 +1,263 @@
+// src/ir/types.ts
+function assertNever(x) {
+  const kind = x.kind;
+  const err = new Error(
+    `Unexpected TypeRef kind: ${kind}
+Hint: If you added a new TypeRef variant, handle it in every switch/case that calls assertNever.`
+  );
+  err.name = "InternalError";
+  throw err;
+}
+function walkTypeRef(ref, visitor) {
+  switch (ref.kind) {
+    case "model":
+      visitor.model?.(ref);
+      break;
+    case "enum":
+      visitor.enum?.(ref);
+      break;
+    case "array":
+      walkTypeRef(ref.items, visitor);
+      break;
+    case "nullable":
+      walkTypeRef(ref.inner, visitor);
+      break;
+    case "union":
+      for (const v of ref.variants) walkTypeRef(v, visitor);
+      break;
+    case "map":
+      if (ref.keyType) walkTypeRef(ref.keyType, visitor);
+      walkTypeRef(ref.valueType, visitor);
+      break;
+    case "literal":
+      visitor.literal?.(ref);
+      break;
+    case "primitive":
+      visitor.primitive?.(ref);
+      break;
+    default:
+      assertNever(ref);
+  }
+}
+function mapTypeRef(ref, mapper) {
+  switch (ref.kind) {
+    case "primitive":
+      return mapper.primitive(ref);
+    case "array":
+      return mapper.array(ref, mapTypeRef(ref.items, mapper));
+    case "model":
+      return mapper.model(ref);
+    case "enum":
+      return mapper.enum(ref);
+    case "union":
+      return mapper.union(
+        ref,
+        ref.variants.map((v) => mapTypeRef(v, mapper))
+      );
+    case "nullable":
+      return mapper.nullable(ref, mapTypeRef(ref.inner, mapper));
+    case "literal":
+      return mapper.literal(ref);
+    case "map":
+      return mapper.map(
+        ref,
+        mapTypeRef(ref.valueType, mapper),
+        ref.keyType ? mapTypeRef(ref.keyType, mapper) : void 0
+      );
+    default:
+      return assertNever(ref);
+  }
+}
+
+// src/errors.ts
+var OagenError = class extends Error {
+  hint;
+  constructor(message, hint) {
+    const fullMessage = hint ? `${message}
+Hint: ${hint}` : message;
+    super(fullMessage);
+    this.name = "OagenError";
+    this.hint = hint;
+  }
+};
+var CommandError = class extends OagenError {
+  exitCode;
+  constructor(message, hint, exitCode) {
+    super(message, hint);
+    this.name = "CommandError";
+    this.exitCode = exitCode;
+  }
+};
+var SpecParseError = class extends OagenError {
+  constructor(message, hint) {
+    super(message, hint);
+    this.name = "SpecParseError";
+  }
+};
+var ConfigError = class extends OagenError {
+  constructor(message, hint) {
+    super(message, hint);
+    this.name = "ConfigError";
+  }
+};
+var ConfigLoadError = class extends ConfigError {
+  constructor(message, hint) {
+    super(message, hint);
+    this.name = "ConfigLoadError";
+  }
+};
+var ConfigVersionMismatchError = class extends ConfigError {
+  constructor(message, hint) {
+    super(message, hint);
+    this.name = "ConfigVersionMismatchError";
+  }
+};
+var ExtractorError = class extends OagenError {
+  constructor(message, hint) {
+    super(message, hint);
+    this.name = "ExtractorError";
+  }
+};
+var RegistryError = class extends OagenError {
+  constructor(message, hint) {
+    super(message, hint);
+    this.name = "RegistryError";
+  }
+};
+var InternalError = class extends OagenError {
+  constructor(message, hint) {
+    super(message, hint);
+    this.name = "InternalError";
+  }
+};
+
+// src/utils/naming.ts
+function splitWords(s) {
+  if (!s) return [];
+  return s.replace(/[^a-zA-Z0-9_\-\s.]/g, "_").replace(/([a-z])([A-Z])/g, "$1\0$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1\0$2").replace(/([a-zA-Z])(\d)/g, "$1\0$2").replace(/(\d)([a-zA-Z])/g, "$1\0$2").split(/[\0_\-\s.]+/).filter((w) => w.length > 0);
+}
+var ACRONYM_SET = /* @__PURE__ */ new Set(["SSO", "FGA", "SAML", "SCIM", "JWT", "HMAC"]);
+function toPascalCase(s, acronyms) {
+  const merged = acronyms ? /* @__PURE__ */ new Set([...ACRONYM_SET, ...acronyms]) : ACRONYM_SET;
+  return splitWords(s).map((w) => {
+    const upper = w.toUpperCase();
+    if (merged.has(upper)) return upper;
+    if (upper === "OAUTH") return "OAuth";
+    return w.charAt(0).toUpperCase() + w.slice(1).toLowerCase();
+  }).join("");
+}
+function toCamelCase(s, acronyms) {
+  const merged = acronyms ? /* @__PURE__ */ new Set([...ACRONYM_SET, ...acronyms]) : ACRONYM_SET;
+  const words = splitWords(s);
+  if (words.length === 0) return "";
+  return words.map((w, i) => {
+    if (i === 0) return w.toLowerCase();
+    const upper = w.toUpperCase();
+    if (merged.has(upper)) return upper;
+    if (upper === "OAUTH") return "OAuth";
+    return w.charAt(0).toUpperCase() + w.slice(1).toLowerCase();
+  }).join("");
+}
+function toSnakeCase(s) {
+  return splitWords(s).map((w) => w.toLowerCase()).join("_");
+}
+function toKebabCase(s) {
+  return splitWords(s).map((w) => w.toLowerCase()).join("-");
+}
+function toUpperSnakeCase(s) {
+  return splitWords(s).map((w) => w.toUpperCase()).join("_");
+}
+var BACKEND_SUFFIXES = ["Dto", "DTO", "Controller"];
+function stripBackendSuffixes(name) {
+  for (const suffix of BACKEND_SUFFIXES) {
+    if (name.endsWith(suffix) && name.length > suffix.length) {
+      return name.slice(0, -suffix.length);
+    }
+  }
+  return name;
+}
+function stripBackendPrefixes(name) {
+  return name.replace(/Userland/g, "").replace(/Controller/g, "");
+}
+function stripListItemMarkers(name) {
+  return name.replace(/ListItem/g, "").replace(/ByExternalId/g, "").replace(/ByResourceId/g, "").replace(/ForResource/g, "");
+}
+var SINGULAR_SAFE_LIST = /* @__PURE__ */ new Set([
+  "Status",
+  "Address",
+  "Access",
+  "Process",
+  "Progress",
+  "Success",
+  "Radius",
+  "Canvas",
+  "Alias",
+  "Basis",
+  "Bus"
+]);
+function singularize(word) {
+  if (SINGULAR_SAFE_LIST.has(word)) return word;
+  if (word.endsWith("ies") && word.length > 4) {
+    return word.slice(0, -3) + "y";
+  }
+  if (word.endsWith("ses") && word.length > 4) {
+    return word.slice(0, -2);
+  }
+  if (word.endsWith("s") && !word.endsWith("ss") && word.length > 4) {
+    return word.slice(0, -1);
+  }
+  return word;
+}
+function normalizeJsExtension(text) {
+  return text.replace(/\.js(['"])/g, "$1");
+}
+function cleanSchemaName(name) {
+  let result = stripBackendPrefixes(stripBackendSuffixes(name));
+  result = stripListItemMarkers(result);
+  const match = result.match(/^([A-Z][a-z]*)/);
+  if (match) {
+    const leadWord = match[1];
+    const singular = singularize(leadWord);
+    if (singular !== leadWord) {
+      result = singular + result.slice(leadWord.length);
+    }
+  }
+  return result;
+}
+
+// src/utils/tree-sitter.ts
+var TS_SAFE_CHUNK = 32767;
+function safeParse(parser, source) {
+  if (source.length < TS_SAFE_CHUNK) {
+    return parser.parse(source);
+  }
+  return parser.parse((offset) => source.slice(offset, offset + TS_SAFE_CHUNK));
+}
+
+export {
+  assertNever,
+  walkTypeRef,
+  mapTypeRef,
+  OagenError,
+  CommandError,
+  SpecParseError,
+  ConfigError,
+  ConfigLoadError,
+  ConfigVersionMismatchError,
+  ExtractorError,
+  RegistryError,
+  InternalError,
+  splitWords,
+  ACRONYM_SET,
+  toPascalCase,
+  toCamelCase,
+  toSnakeCase,
+  toKebabCase,
+  toUpperSnakeCase,
+  stripBackendPrefixes,
+  stripListItemMarkers,
+  singularize,
+  normalizeJsExtension,
+  cleanSchemaName,
+  safeParse
+};