@workos/oagen 0.6.0 → 0.8.0

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

@@ -12,7 +12,8 @@ When `{project}/package.json` does **NOT** exist, create the following boilerpla
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./plugin": { "types": "./dist/plugin.d.ts", "import": "./dist/plugin.js" }
   },
   "scripts": {
     "build": "tsup",
@@ -76,7 +77,7 @@ export default defineConfig({
 ```ts
 import { defineConfig } from "tsup";
 export default defineConfig({
-  entry: { index: "src/index.ts" },
+  entry: { index: "src/index.ts", plugin: "src/plugin.ts" },
   format: ["esm"],
   dts: true,
   clean: true,
@@ -86,21 +87,41 @@ export default defineConfig({
 
 ## `oagen.config.ts`
 
+Minimal config for local emitter development. The canonical consumer config lives in the consumer project.
+
 ```ts
 import type { OagenConfig } from "@workos/oagen";
-const config: OagenConfig = { emitters: [] };
+import { plugin } from "./src/plugin.js";
+const config: OagenConfig = { ...plugin };
 export default config;
 ```
 
-(Step 6 of the main skill adds the emitter to this config.)
+## `src/plugin.ts`
+
+Plugin bundle export. The consumer project imports this to get all emitters, extractors, and smoke runners.
+
+```ts
+import type { OagenConfig } from "@workos/oagen";
+export const plugin: Pick<
+  OagenConfig,
+  "emitters" | "extractors" | "smokeRunners"
+> = {
+  emitters: [],
+  extractors: [],
+  smokeRunners: {},
+};
+```
+
+(Step 7 of the main skill adds the emitter to this plugin bundle.)
 
 ## `src/index.ts`
 
 ```ts
-// Barrel export — re-exports all emitters
+// Barrel export — re-exports all emitters and the plugin bundle
+export { plugin } from "./plugin.js";
 ```
 
-(Step 6 adds the re-export.)
+(Step 7 adds the emitter re-export.)
 
 ## `.gitignore`
 

package/skills/generate-extractor/SKILL.md

@@ -13,7 +13,7 @@ Scaffold a language extractor for oagen's compat verification system. An extract
 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.
+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 exported through the emitter project's plugin bundle (e.g., `workosEmittersPlugin`), which the consumer project's `oagen.config.ts` imports.
 
 ## Reference Docs
 
@@ -115,16 +115,22 @@ export const {language}Extractor: Extractor = {
 
 ## Step 3: Register the Extractor
 
-Add to `oagen.config.ts`:
+Add the extractor to the plugin bundle export (e.g., `src/plugin.ts`) and re-export from `src/index.ts`:
 
 ```typescript
-import { {language}Extractor } from './src/compat/extractors/{language}.js';
-const config: OagenConfig = {
-  emitters: [/* ... */],
-  extractors: [{language}Extractor],
+// src/plugin.ts
+import { {language}Extractor } from './compat/extractors/{language}.js';
+export const workosEmittersPlugin = {
+  extractors: [/* existing, */ {language}Extractor],
+  // ...
 };
+
+// src/index.ts
+export { {language}Extractor } from './compat/extractors/{language}.js';
 ```
 
+The consumer project's `oagen.config.ts` imports the plugin bundle, so the new extractor is automatically available.
+
 ## 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:
@@ -175,7 +181,7 @@ If `sdk_path` was provided, also test against the real SDK and verify all public
 ```
 === Extractor: {language} ===
 Files created:   src/compat/extractors/{language}.ts, test suite, fixture SDK
-Modified:        oagen.config.ts
+Modified:        src/plugin.ts, src/index.ts
 Validation:      Tests / Fixture extract / Determinism / Real SDK extract
 ApiSurface:      {N} classes, {N} interfaces, {N} type aliases, {N} enums, {N} exports
 ```
@@ -187,7 +193,7 @@ 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
+- Updated plugin bundle (`src/plugin.ts`) and `src/index.ts` with the new extractor registered
 
 ## Common Pitfalls
 

package/skills/generate-sdk/SKILL.md

@@ -91,7 +91,7 @@ ls {project}/src/{language}/index.ts
 cd {project} && npx vitest run test/{language}/ 2>&1 | tail -5
 
 # After /generate-extractor — extractor registered with hints
-grep -l "{language}Extractor\|{language}_extractor" {project}/oagen.config.ts
+grep -l "{language}Extractor\|{language}_extractor" {project}/src/plugin.ts {project}/src/index.ts
 grep -l "hints" {project}/src/compat/extractors/{language}.ts
 
 # After /verify-compat — handled by the skill itself
@@ -148,7 +148,7 @@ Only include this next section in the output if this is Scenario A:
 
 This skill produces, via its sub-skills:
 
-- A complete language emitter registered in `oagen.config.ts`
+- A complete language emitter registered in the plugin bundle (`src/plugin.ts`)
 - An API surface extractor (Scenario A only)
 - A smoke test script at `smoke/sdk-{language}.ts`
 - Generated SDK code at `{project}/sdk/`

package/skills/generate-smoke-test/SKILL.md

@@ -136,17 +136,21 @@ Create the script **in the emitter project**:
 
 ## Step 6: Register the Smoke Runner
 
-Add to `oagen.config.ts`:
+Add the smoke runner path to the plugin bundle export (e.g., `src/plugin.ts`):
 
 ```typescript
-const config: OagenConfig = {
-  emitters: [/* ... */],
+// src/plugin.ts
+export const workosEmittersPlugin = {
   smokeRunners: {
-    {language}: './smoke/sdk-{language}.ts',
+    // existing runners...
+    {language}: path.join(smokeDir, 'sdk-{language}.ts'),
   },
+  // ...
 };
 ```
 
+The consumer project's `oagen.config.ts` imports the plugin bundle, so the new smoke runner is automatically available.
+
 ## Step 7: Validate
 
 ```bash
@@ -182,4 +186,4 @@ See `scripts/smoke/README.md` (in oagen core) for the full remediation guide. Se
 This skill produces, in the emitter project:
 
 - `smoke/sdk-{language}.ts` — self-contained smoke test script
-- Updated `oagen.config.ts` with the smoke runner path registered
+- Updated plugin bundle (`src/plugin.ts`) with the smoke runner path registered

package/skills/review-operations/SKILL.md

@@ -19,7 +19,7 @@ Accept `--spec <path>` as an optional argument. If not provided, fall back to th
 ## Step 1: Resolve Paths
 
 1. **Spec path**: from argument, `OPENAPI_SPEC_PATH` env, or `../openapi-spec/spec/open-api-spec.yaml`
-2. **oagen-emitters project**: check if `oagen.config.ts` exists in the current directory. If not, use `AskUserQuestion`: "Where is your oagen-emitters project?"
+2. **Consumer config project**: check if `oagen.config.ts` exists in the current directory. If not, try `../openapi-spec/oagen.config.ts`. If neither exists, use `AskUserQuestion`: "Where is your consumer config project (the project with `oagen.config.ts`)?"
 3. Validate the spec file exists before proceeding.
 
 ## Step 2: Run Resolution
@@ -80,4 +80,4 @@ Print a summary:
 - Algorithm-derived (no action needed)
 - Needs review (may need hints)
 
-If there are operations needing review, ask the user: "Would you like me to add hints for any of these operations to `oagen.config.ts`?"
+If there are operations needing review, ask the user: "Would you like me to add hints for any of these operations to the consumer project's `oagen.config.ts`?"

package/skills/verify-compat/SKILL.md

@@ -44,7 +44,7 @@ All artifacts (surface files, generated output) live **inside the emitter projec
 
 Determine required paths:
 
-1. **Emitter project** (`project`): from argument, or detect from CWD (look for `oagen.config.ts`), or use `AskUserQuestion`
+1. **Emitter project** (`project`): from argument, or detect from CWD (look for `src/plugin.ts` or `oagen.config.ts`), or use `AskUserQuestion`
 2. **Spec** (`spec`): from argument, or use `AskUserQuestion`
 3. **Live SDK** (`sdk_path`): from argument, or use `AskUserQuestion`
 4. **API surface file**: `{project}/sdk-{language}-surface.json` — always in the emitter project root