@workos/oagen 0.22.6 → 0.23.0

package/README.md

@@ -165,7 +165,7 @@ export default {
     retry: { backoff: { initialDelay: 0.5, maxDelay: 8.0 } },
     timeout: {
       defaultTimeoutSeconds: 30,
-      timeoutEnvVar: "WORKOS_REQUEST_TIMEOUT",
+      timeoutEnvVar: "SDK_REQUEST_TIMEOUT",
     },
     pagination: { autoPageDelayMs: 0 },
   },

package/dist/cli/index.mjs

@@ -14,9 +14,8 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, rea
 import { createHash } from "node:crypto";
 //#region src/ir/sdk-behavior.ts
 /**
-* Canonical SDK behavior defaults. These match the PHP emitter's current
-* implementation (the most complete). Per-language overrides can be applied
-* via `mergeSdkBehavior()` in each SDK's `oagen.config.ts`.
+* Canonical SDK behavior defaults. Per-language or per-project overrides can
+* be applied via `mergeSdkBehavior()` in each SDK's `oagen.config.ts`.
 *
 * - Retry: exponential backoff with jitter, retries on 429/5xx
 * - Errors: standard HTTP status → exception kind mapping
@@ -59,12 +58,11 @@ function defaultSdkBehavior() {
 				429: "RateLimitExceeded"
 			},
 			serverErrorKind: "Server",
-			clientErrorKind: "Api",
-			errorDocUrlTemplate: "https://workos.com/docs/errors/{code}"
+			clientErrorKind: "Api"
 		},
 		telemetry: {
 			enabledByDefault: true,
-			headerName: "X-WorkOS-Client-Telemetry",
+			headerName: "X-Client-Telemetry",
 			requestIdHeader: "X-Request-ID"
 		},
 		pagination: { autoPageDelayMs: 0 },
@@ -2044,11 +2042,11 @@ function inferVerb(method, path) {
 * Uses the last non-param segment (the resource being operated on).
 *
 * Examples:
-*   /user_management/users → "Users"
-*   /user_management/users/{id} → "User" (singular for item operations)
-*   /user_management/users/{id}/auth_factors → "AuthFactors"
+*   /accounts/users → "Users"
+*   /accounts/users/{id} → "User" (singular for item operations)
+*   /accounts/users/{id}/auth_factors → "AuthFactors"
 *   /organizations/{id}/api_keys → "ApiKeys"
-*   /sso/authorize → "Authorize" (action endpoint)
+*   /auth/authorize → "Authorize" (action endpoint)
 */
 function inferResourceFromPath(path) {
 	const segments = path.split("/").filter(Boolean);
@@ -2694,6 +2692,7 @@ async function parseSpec(specPath, options) {
 	const fieldInlineModels = extractInlineModelsFromSchemas(spec.components?.schemas);
 	clearSchemaNameTransform();
 	const finalModels = collapseJsonSuffixModels(mergeFieldInlineModels(responseNormalizedModels, fieldInlineModels), services);
+	applyFieldHints(finalModels, options?.fieldHints);
 	collectInlineEnumsFromModels(finalModels, enums);
 	collectInlineEnumsFromOperations(services, enums);
 	const auth = extractAuthSchemes(spec.components?.securitySchemes);
@@ -2716,6 +2715,22 @@ async function parseSpec(specPath, options) {
 	validateModelRefs(result);
 	return result;
 }
+/**
+* Apply `fieldHints` onto the built models, setting `Field.domainName` for each
+* matching (model name, wire field name) pair. Serialization still uses
+* `Field.name`; only the domain-facing identifier changes.
+*/
+function applyFieldHints(models, fieldHints) {
+	if (!fieldHints) return;
+	for (const model of models) {
+		const hints = fieldHints[model.name];
+		if (!hints) continue;
+		for (const field of model.fields) {
+			const domainName = hints[field.name];
+			if (domainName) field.domainName = domainName;
+		}
+	}
+}
 /** Extract authentication schemes from OpenAPI securitySchemes. */
 function extractAuthSchemes(securitySchemes) {
 	if (!securitySchemes) return void 0;
@@ -3313,12 +3328,12 @@ function extractKotlinClassMembers(classBody, source) {
 }
 /**
 * KDoc signature that identifies a generator-emitted service accessor inside
-* the WorkOS class. The Kotlin client emitter writes every accessor with this
+* a Kotlin client class. The Kotlin client emitter writes every accessor with this
 * exact doc preamble — when the existing file carries a member with this doc
 * but the regenerated content omits it, the member is stale (its mount target
 * was remapped or removed) and gets pruned.
 */
-const KOTLIN_MANAGED_ACCESSOR_DOC = /\/\*\*[\s\S]*?Lazily-constructed \[[^\]]+\] accessor for this \[WorkOS\] client\.[\s\S]*?\*\//;
+const KOTLIN_MANAGED_ACCESSOR_DOC = /\/\*\*[\s\S]*?Lazily-constructed \[[^\]]+\] accessor for this \[[^\]]+\] client\.[\s\S]*?\*\//;
 const kotlinMergeAdapter = {
 	language: "kotlin",
 	grammarModule: "tree-sitter-kotlin",
@@ -3571,7 +3586,6 @@ const nodeMergeAdapter = {
 		const newText = newMembers.map((m) => m.text).join("\n");
 		for (const match of newText.matchAll(/this\.(\w+)/g)) {
 			const propName = match[1];
-			if (propName === "workos") continue;
 			if (propName && !existingMemberKeys.has(propName)) return true;
 		}
 		return false;
@@ -5272,6 +5286,60 @@ function collectTsImports(lines) {
 	return out;
 }
 /**
+* Remove the given symbols from generated `import type` bindings, in place.
+*
+* Called when an existing *value* import for the same symbol is being spliced
+* back into the file. A value import satisfies both runtime and type uses, so
+* leaving the generated `import type { X }` would re-declare `X` (TS2300
+* duplicate identifier). Callers guarantee every symbol here is absent from
+* generated *value* imports, so each occurrence is type-only and safe to drop.
+*
+* Handles whole-line `import type { … }` and inline `import { …, type X }`,
+* single- or multi-line. A statement whose bindings all get stripped is
+* removed entirely.
+*/
+function dropGeneratedTypeOnlyBindings(resultLines, symbols) {
+	if (symbols.size === 0) return;
+	const out = [];
+	for (let i = 0; i < resultLines.length; i++) {
+		const line = resultLines[i];
+		const trimmed = line.trim();
+		if (!/^import\b/.test(trimmed) || !trimmed.includes("{")) {
+			out.push(line);
+			continue;
+		}
+		const span = [line];
+		while (!span.join(" ").includes("}") && i + 1 < resultLines.length) {
+			i++;
+			span.push(resultLines[i]);
+		}
+		const m = span.join(" ").replace(/\s+/g, " ").trim().replace(/;\s*$/, "").match(/^import\s+(type\s+)?(?:(\w+)\s*,\s*)?\{\s*([^}]*)\s*\}\s+from\s+(['"][^'"]+['"])$/);
+		if (!m) {
+			for (const s of span) out.push(s);
+			continue;
+		}
+		const isTypeOnly = !!m[1];
+		const defaultName = m[2];
+		const items = m[3].split(",").map((s) => s.trim()).filter(Boolean);
+		const modQuoted = m[4];
+		const kept = items.filter((raw) => {
+			const isTypeBinding = isTypeOnly || raw.startsWith("type ");
+			const bare = raw.replace(/^type\s+/, "");
+			return !(isTypeBinding && symbols.has(bare));
+		});
+		if (kept.length === items.length) {
+			for (const s of span) out.push(s);
+			continue;
+		}
+		if (kept.length === 0 && !defaultName) continue;
+		const lead = line.match(/^(\s*)/)?.[1] ?? "";
+		const prefix = isTypeOnly ? "import type " : "import ";
+		const defaultPart = defaultName ? `${defaultName}, ` : "";
+		out.push(`${lead}${prefix}${defaultPart}{ ${kept.join(", ")} } from ${modQuoted};`);
+	}
+	resultLines.splice(0, resultLines.length, ...out);
+}
+/**
 * Add imports from the existing file that are absent from the generated
 * result. Handles:
 *
@@ -5393,28 +5461,49 @@ function spliceExtraImports(existingLines, resultLines) {
 	const existingTs = collectTsImports(existingOutsideIgnore);
 	const generatedTs = collectTsImports(resultLines);
 	const extraTsLines = [];
+	const allGeneratedTsIds = /* @__PURE__ */ new Set();
+	const generatedValueIds = /* @__PURE__ */ new Set();
+	for (const ids of generatedTs.named.values()) for (const id of ids) {
+		allGeneratedTsIds.add(id);
+		generatedValueIds.add(id);
+	}
+	for (const ids of generatedTs.typeOnly.values()) for (const id of ids) allGeneratedTsIds.add(id);
+	for (const name of generatedTs.defaults.values()) {
+		allGeneratedTsIds.add(name);
+		generatedValueIds.add(name);
+	}
+	for (const name of generatedTs.namespaces.values()) {
+		allGeneratedTsIds.add(name);
+		generatedValueIds.add(name);
+	}
+	const reclaimedValueIds = /* @__PURE__ */ new Set();
+	const generatedHasValue = (id) => generatedValueIds.has(id);
+	const generatedHasTypeOnly = (id) => allGeneratedTsIds.has(id) && !generatedValueIds.has(id);
 	for (const mod of existingTs.sideEffects) if (!generatedTs.sideEffects.has(mod)) extraTsLines.push(`import '${mod}';`);
 	for (const [mod, name] of existingTs.defaults) {
 		if (generatedTs.defaults.has(mod)) continue;
 		if (!identifierUsed(ignoreRegionText, name)) continue;
+		if (generatedHasValue(name)) continue;
+		if (generatedHasTypeOnly(name)) reclaimedValueIds.add(name);
 		extraTsLines.push(`import ${name} from '${mod}';`);
 	}
 	for (const [mod, name] of existingTs.namespaces) {
 		if (!identifierUsed(ignoreRegionText, name)) continue;
-		if (!generatedTs.namespaces.has(mod)) extraTsLines.push(`import * as ${name} from '${mod}';`);
+		if (generatedHasValue(name)) continue;
+		if (generatedTs.namespaces.has(mod)) continue;
+		if (generatedHasTypeOnly(name)) reclaimedValueIds.add(name);
+		extraTsLines.push(`import * as ${name} from '${mod}';`);
 	}
 	for (const [mod, existIds] of existingTs.named) {
-		const genIds = generatedTs.named.get(mod) ?? /* @__PURE__ */ new Set();
-		const genTypeIds = generatedTs.typeOnly.get(mod) ?? /* @__PURE__ */ new Set();
-		const extra = [...existIds].filter((id) => !genIds.has(id) && !genTypeIds.has(id) && identifierUsed(ignoreRegionText, id));
+		const extra = [...existIds].filter((id) => !generatedHasValue(id) && identifierUsed(ignoreRegionText, id));
+		for (const id of extra) if (generatedHasTypeOnly(id)) reclaimedValueIds.add(id);
 		if (extra.length > 0) extraTsLines.push(`import { ${extra.join(", ")} } from '${mod}';`);
 	}
 	for (const [mod, existIds] of existingTs.typeOnly) {
-		const genIds = generatedTs.typeOnly.get(mod) ?? /* @__PURE__ */ new Set();
-		const genNamedIds = generatedTs.named.get(mod) ?? /* @__PURE__ */ new Set();
-		const extra = [...existIds].filter((id) => !genIds.has(id) && !genNamedIds.has(id) && identifierUsed(ignoreRegionText, id));
+		const extra = [...existIds].filter((id) => !allGeneratedTsIds.has(id) && identifierUsed(ignoreRegionText, id));
 		if (extra.length > 0) extraTsLines.push(`import type { ${extra.join(", ")} } from '${mod}';`);
 	}
+	dropGeneratedTypeOnlyBindings(resultLines, reclaimedValueIds);
 	const isPhpUseImport = (l) => /^use\s+[\w\\]+\\[\w\\]*(\s+as\s+\w+)?\s*;?$/.test(l);
 	const existingPhpUse = new Set(existingOutsideIgnore.filter(isPhpUseImport).map((l) => l.trim()));
 	const generatedPhpUse = new Set(resultLines.filter(isPhpUseImport).map((l) => l.trim()));
@@ -5458,7 +5547,31 @@ function spliceExtraImports(existingLines, resultLines) {
 			if ((resultLines[i].match(/[)}]/g) ?? []).length > 0) break;
 		}
 	}
-	if (lastImportIdx >= 0) resultLines.splice(lastImportIdx + 1, 0, ...allExtra);
+	if (lastImportIdx >= 0) {
+		resultLines.splice(lastImportIdx + 1, 0, ...allExtra);
+		return;
+	}
+	let insertAt = 0;
+	let inBlockComment = false;
+	for (let i = 0; i < resultLines.length; i++) {
+		const t = resultLines[i].trim();
+		if (inBlockComment) {
+			insertAt = i + 1;
+			if (t.includes("*/")) inBlockComment = false;
+			continue;
+		}
+		if (t.startsWith("//")) {
+			insertAt = i + 1;
+			continue;
+		}
+		if (t.startsWith("/*")) {
+			insertAt = i + 1;
+			inBlockComment = !t.includes("*/");
+			continue;
+		}
+		break;
+	}
+	resultLines.splice(insertAt, 0, ...allExtra);
 }
 //#endregion
 //#region src/ir/operation-hints.ts
@@ -5603,6 +5716,15 @@ function resolveResponseModelName(op) {
 //#endregion
 //#region src/engine/generate-files.ts
 function buildEmitterContext(spec, options) {
+	const resolvedOperations = resolveOperations(spec, options.operationHints, options.mountRules);
+	let scopedModelNames;
+	let scopedEnumNames;
+	if (options.scopedServices && options.scopedServices.size > 0) {
+		const selected = options.scopedServices;
+		const reachable = collectReferencedNames(spec.services.filter((s) => resolvedOperations.some((r) => r.service.name === s.name && selected.has(r.mountOn))), spec.models, { preserveAllDiscriminated: false });
+		scopedModelNames = reachable.models;
+		scopedEnumNames = reachable.enums;
+	}
 	return {
 		namespace: toSnakeCase(options.namespace),
 		namespacePascal: options.namespace,
@@ -5610,11 +5732,14 @@ function buildEmitterContext(spec, options) {
 		outputDir: options.outputDir,
 		apiSurface: options.apiSurface,
 		overlayLookup: options.overlayLookup,
-		resolvedOperations: resolveOperations(spec, options.operationHints, options.mountRules),
+		resolvedOperations,
 		modelHints: options.modelHints,
 		emitterOptions: options.emitterOptions,
 		targetDir: options.target,
-		priorTargetManifestPaths: options.priorTargetManifestPaths
+		priorTargetManifestPaths: options.priorTargetManifestPaths,
+		scopedServices: options.scopedServices,
+		scopedModelNames,
+		scopedEnumNames
 	};
 }
 /**
@@ -5622,7 +5747,8 @@ function buildEmitterContext(spec, options) {
 * Walks operation parameters, request bodies, responses, and pagination item
 * types, then chases model field references until the set stabilizes.
 */
-function collectReferencedNames(services, models) {
+function collectReferencedNames(services, models, opts = {}) {
+	const preserveAllDiscriminated = opts.preserveAllDiscriminated !== false;
 	const referencedModels = /* @__PURE__ */ new Set();
 	const referencedEnums = /* @__PURE__ */ new Set();
 	const collectFromTypeRef = (ref) => {
@@ -5644,7 +5770,7 @@ function collectReferencedNames(services, models) {
 		for (const err of op.errors) if (err.type) collectFromTypeRef(err.type);
 		if (op.successResponses) for (const sr of op.successResponses) collectFromTypeRef(sr.type);
 	}
-	for (const model of models) {
+	if (preserveAllDiscriminated) for (const model of models) {
 		if (isDiscriminatedModel(model)) referencedModels.add(model.name);
 		const disc = model.discriminator;
 		if (disc?.mapping) for (const variantName of Object.values(disc.mapping)) referencedModels.add(variantName);
@@ -5658,6 +5784,13 @@ function collectReferencedNames(services, models) {
 		visited.add(name);
 		const model = modelsByName.get(name);
 		if (!model) continue;
+		const disc = model.discriminator;
+		if (disc?.mapping) {
+			for (const variantName of Object.values(disc.mapping)) if (!referencedModels.has(variantName)) {
+				referencedModels.add(variantName);
+				queue.push(variantName);
+			}
+		}
 		for (const field of model.fields) {
 			collectFromTypeRef(field.type);
 			for (const m of referencedModels) if (!visited.has(m)) queue.push(m);
@@ -5671,7 +5804,16 @@ function collectReferencedNames(services, models) {
 function isDiscriminatedModel(model) {
 	return model.fields.some((field) => (field.name === "event" || field.name === "type" || field.name === "object") && field.type.kind === "literal");
 }
-/** Collect all generated files from an emitter (no headers, no path prefixes). */
+/**
+* Collect all generated files from an emitter (no headers, no path prefixes).
+*
+* In a scoped (`--services`) run the spec is NOT filtered: every generator runs
+* over the full spec so model placement, dedup, the root client, and all
+* aggregate/barrel files are byte-identical to a full run (and a brand-new
+* selected service is wired into the client automatically). The emitters
+* themselves consult `ctx.scopedServices` to emit only the selected services'
+* per-service resource/test files.
+*/
 function generateAllFiles(spec, emitter, ctx) {
 	const referenced = collectReferencedNames(spec.services, spec.models);
 	const reachableModels = spec.models.filter((m) => referenced.models.has(m.name));
@@ -5712,6 +5854,47 @@ function generateFiles(spec, emitter, options) {
 	};
 }
 //#endregion
+//#region src/engine/scoped-services.ts
+/**
+* Validate a `--services` selection and return it as a set of POST-MOUNT service
+* names for emitters to scope on.
+*
+* Scoped generation does NOT filter the IR: model placement, dedup/aliasing, and
+* shared-schema decisions are global computations over the full service/model set
+* (filtering them churns shared `common/` files). Instead the full spec flows to
+* the emitters unchanged and this set is passed as `ctx.scopedServices`; each
+* emitter gates only its per-service resource/test emission on it.
+*
+* Matching is on the POST-MOUNT name. Mount resolution never mutates
+* `spec.services` — the post-mount target lives on `ResolvedOperation.mountOn`
+* (`mountOn = hint?.mountOn ?? mountRules[service.name] ?? service.name`) — so the
+* post-mount name of a source service is derived here as
+* `mountRules[service.name] ?? service.name`. Selecting a target (e.g.
+* `DirectorySync`) is valid because every source tag that mounts into it
+* (`DirectoryUsers`, `DirectoryGroups`, …) shares that post-mount name, and the
+* emitters group resources by mount, so all siblings emit together.
+*
+* @param spec - The parsed API spec (never mutated; never filtered).
+* @param selected - Post-mount service names from `--services` (normalized/trimmed).
+* @param mountRules - Source-service-name → post-mount-target mappings.
+* @returns The validated selection as a `Set` of post-mount names.
+* @throws A `ConfigError` listing valid post-mount names when a selection is
+*   unknown — scoped generation never silently emits the wrong set.
+*/
+function resolveScopedServices(spec, selected, mountRules) {
+	const mounts = mountRules ?? {};
+	const postMountName = (name) => mounts[name] ?? name;
+	const validPostMount = new Set(spec.services.map((s) => postMountName(s.name)));
+	const selectedSet = new Set(selected);
+	const unknown = [...selectedSet].filter((s) => !validPostMount.has(s));
+	if (unknown.length > 0) {
+		const err = /* @__PURE__ */ new Error(`Unknown --services: ${unknown.sort().join(", ")}. Valid post-mount services: ${[...validPostMount].sort().join(", ")}`);
+		err.name = "ConfigError";
+		throw err;
+	}
+	return selectedSet;
+}
+//#endregion
 //#region src/engine/integrate.ts
 /**
 * Resolve a relative import path against a source file path to get the
@@ -5828,7 +6011,7 @@ function mapFilesForTargetIntegration(files, language) {
 * that would shadow an existing module file (e.g., `api_keys.py`), move the
 * module file's content into `_compat.py` inside the package and add a
 * re-export from `__init__.py`.  This preserves backward-compatible imports
-* (e.g., `from workos.api_keys import ApiKeysModule`) while the package directory
+* (e.g., `from acme.api_keys import ApiKeysModule`) while the package directory
 * provides the generated models and resource classes.
 */
 async function resolveFileToDirectoryConflicts(files, targetDir) {
@@ -5994,6 +6177,35 @@ function computeStalePaths(prev, currentPaths) {
 	return prev.files.filter((p) => !current.has(p)).sort();
 }
 /**
+* Merge a scoped run's emitted records into the prior manifest's records.
+*
+* A scoped (`--services`) run only emits files for the selected services, but it
+* must NOT discard the prior manifest's record of unselected services' files
+* records. The result unions prior + scoped file paths and shallow-merges the
+* operations maps, with scoped operations overriding prior entries for the same
+* "METHOD /path" key (a re-emission updates that operation's record).
+*
+* When `prev` is null (the first-ever run is scoped) there is nothing to
+* preserve, so the scoped subset is returned unchanged — matching the
+* first-adoption behavior of a full run.
+*/
+function mergeScopedManifestRecords(prev, scopedFiles, scopedOperations) {
+	const scopedFileList = [...scopedFiles];
+	if (!prev) return {
+		files: scopedFileList,
+		operations: scopedOperations
+	};
+	const files = [...new Set([...prev.files, ...scopedFileList])].sort();
+	const priorOps = prev.operations;
+	return {
+		files,
+		operations: priorOps || scopedOperations ? {
+			...priorOps,
+			...scopedOperations
+		} : void 0
+	};
+}
+/**
 * Delete stale files from `dir`.
 *
 * When `header` is provided, a file is only deleted if its contents start with
@@ -6062,12 +6274,17 @@ async function removeEmptyParents(startDir, stopDir) {
 //#endregion
 //#region src/engine/orchestrator.ts
 async function generate(spec, emitter, options) {
-	const outputPrevManifestForCtx = options.noPrune ? null : await readManifest(options.outputDir);
-	const targetManifestForCtx = options.target && !options.noPrune ? await readManifest(options.target) : null;
+	const scopedServices = options.services && options.services.length > 0 ? resolveScopedServices(spec, options.services, options.mountRules) : void 0;
+	const scoped = scopedServices !== void 0;
+	const noPrune = options.noPrune === true || scoped;
+	const skipManifestRead = options.noPrune === true && !scoped;
+	const outputPrevManifestForCtx = skipManifestRead ? null : await readManifest(options.outputDir);
+	const targetManifestForCtx = options.target && !skipManifestRead ? await readManifest(options.target) : null;
 	const priorTargetManifestPaths = targetManifestForCtx ? new Set(targetManifestForCtx.files) : outputPrevManifestForCtx ? new Set(outputPrevManifestForCtx.files) : void 0;
 	const { files: withHeaders, header, operations } = generateFiles(spec, emitter, {
 		...options,
-		priorTargetManifestPaths
+		priorTargetManifestPaths,
+		scopedServices
 	});
 	if (options.dryRun) {
 		if (options.target) {
@@ -6091,8 +6308,9 @@ async function generate(spec, emitter, options) {
 		currentPaths: outputEmittedPaths,
 		language: emitter.language,
 		header,
-		noPrune: options.noPrune,
-		operations
+		noPrune,
+		operations,
+		scoped
 	});
 	const allOutputFiles = [...writeResult.written, ...writeResult.merged];
 	if (allOutputFiles.length > 0) await formatTargetFiles(emitter, options.outputDir, allOutputFiles);
@@ -6114,8 +6332,9 @@ async function generate(spec, emitter, options) {
 			currentPaths: targetResult.emittedPaths,
 			language: emitter.language,
 			header,
-			noPrune: options.noPrune,
-			operations
+			noPrune,
+			operations,
+			scoped
 		});
 		const allTargetFiles = [
 			...targetResult.written,
@@ -6131,11 +6350,15 @@ async function generate(spec, emitter, options) {
 * then write the fresh manifest.  Safe on first adoption (no previous manifest).
 */
 async function applyManifestPrune(opts) {
-	const manifestOpts = {
-		language: opts.language,
+	const records = opts.scoped ? mergeScopedManifestRecords(opts.prevManifest, opts.currentPaths, opts.operations) : {
 		files: opts.currentPaths,
 		operations: opts.operations
 	};
+	const manifestOpts = {
+		language: opts.language,
+		files: records.files,
+		operations: records.operations
+	};
 	if (opts.noPrune) {
 		await writeManifest(opts.dir, manifestOpts);
 		return;
@@ -6775,7 +6998,7 @@ function loadOverlayContext(opts) {
 //#region src/utils/expand-doc-urls.ts
 /**
 * Walk all description fields in the IR and expand relative URL paths
-* (e.g. `/reference/authkit/user`) into full URLs using the given base.
+* (e.g. `/reference/users/user`) into full URLs using the given base.
 *
 * Matches markdown-style links: `[text](/path)` → `[text](https://example.com/path)`
 * and bare parenthetical refs: `(/path)` → `(https://example.com/path)`
@@ -6832,11 +7055,13 @@ async function generateCommand(opts) {
 	let ir = await parseSpec(opts.spec, {
 		operationIdTransform: opts.operationIdTransform,
 		schemaNameTransform: opts.schemaNameTransform,
-		transformSpec: opts.transformSpec
+		transformSpec: opts.transformSpec,
+		fieldHints: opts.fieldHints
 	});
 	if (opts.docUrl) ir = expandDocUrls(ir, opts.docUrl);
 	const emitter = getEmitter(opts.lang);
 	const namespace = opts.namespace ?? ir.name;
+	const services = (Array.isArray(opts.services) ? opts.services : opts.services?.split(","))?.map((s) => s.trim()).filter(Boolean);
 	let apiSurface;
 	let overlayLookup;
 	if (opts.apiSurface && opts.compatCheck !== false) {
@@ -6860,7 +7085,8 @@ async function generateCommand(opts) {
 		mountRules: opts.mountRules,
 		modelHints: opts.modelHints,
 		emitterOptions: opts.emitterOptions,
-		noPrune: opts.prune === false
+		noPrune: opts.prune === false,
+		services: services && services.length > 0 ? services : void 0
 	});
 	if (opts.dryRun) for (const f of files) console.log(f.path);
 	else {
@@ -8123,7 +8349,7 @@ function specDerivedFieldPaths(spec, hints) {
 	return paths;
 }
 /**
-* Compute the set of method paths (e.g., "SSO.authorize") that are defined
+* Compute the set of method paths (e.g., "Auth.authorize") that are defined
 * as operations in the OpenAPI spec's services. Used by filterSurface to
 * exclude hand-written SDK methods that don't correspond to spec operations.
 */
@@ -8159,7 +8385,7 @@ function filterRecord(record, allowed) {
 *
 * For classes: when methodPaths is provided, only keeps methods whose names
 * appear in the spec-derived method paths. This prevents false positives from
-* hand-written SDK methods (e.g., SSO.authorization_url, Webhooks.construct_event)
+* hand-written SDK methods (e.g., Auth.authorization_url, Webhooks.construct_event)
 * that don't correspond to spec operations. Properties on service classes are
 * also filtered: only UPPER_CASE constants that are spec-derivable are kept.
 */
@@ -9802,6 +10028,7 @@ let configDocUrl;
 let configOperationHints;
 let configMountRules;
 let configModelHints;
+let configFieldHints;
 let configEmitterOptions;
 let configCompat;
 try {
@@ -9816,6 +10043,7 @@ try {
 		configOperationHints = config.operationHints;
 		configMountRules = config.mountRules;
 		configModelHints = config.modelHints;
+		configFieldHints = config.fieldHints;
 		configEmitterOptions = config.emitterOptions;
 		configCompat = config.compat;
 	}
@@ -9836,7 +10064,7 @@ program.command("parse").description("Parse an OpenAPI spec and output IR as JSO
 		transformSpec: configTransformSpec
 	});
 });
-program.command("generate").description("Run a registered emitter against an OpenAPI spec").option("--spec <path>", "Path to OpenAPI spec file (or set OPENAPI_SPEC_PATH)").requiredOption("--lang <language>", "Target language").requiredOption("--output <dir>", "Output directory").option("--target <dir>", "Target directory for live SDK integration (merged output)").option("--namespace <name>", "SDK namespace/package name").option("--dry-run", "Preview files without writing").option("--api-surface <path>", "Path to baseline API surface JSON for compat overlay").option("--no-compat-check", "Skip compat overlay even if --api-surface is provided").option("--no-prune", "Skip deletion of stale files recorded in the previous .oagen-manifest.json").action((opts) => {
+program.command("generate").description("Run a registered emitter against an OpenAPI spec").option("--spec <path>", "Path to OpenAPI spec file (or set OPENAPI_SPEC_PATH)").requiredOption("--lang <language>", "Target language").requiredOption("--output <dir>", "Output directory").option("--target <dir>", "Target directory for live SDK integration (merged output)").option("--namespace <name>", "SDK namespace/package name").option("--dry-run", "Preview files without writing").option("--api-surface <path>", "Path to baseline API surface JSON for compat overlay").option("--no-compat-check", "Skip compat overlay even if --api-surface is provided").option("--no-prune", "Skip deletion of stale files recorded in the previous .oagen-manifest.json").option("--services <list>", "Comma-separated post-mount service names to generate (default: all)").action((opts) => {
 	opts.spec ??= process.env.OPENAPI_SPEC_PATH;
 	if (!opts.spec) {
 		console.error("error: --spec <path> or OPENAPI_SPEC_PATH env var is required");
@@ -9851,6 +10079,7 @@ program.command("generate").description("Run a registered emitter against an Ope
 		operationHints: configOperationHints,
 		mountRules: configMountRules,
 		modelHints: configModelHints,
+		fieldHints: configFieldHints,
 		emitterOptions: configEmitterOptions?.[opts.lang]
 	}).catch(handleError);
 });