@workos/oagen 0.5.0 → 0.7.0

package/dist/cli/index.mjs

@@ -600,7 +600,7 @@ function findSchemaByName(pascalName, schemas) {
 	for (const [k, v] of Object.entries(schemas)) if (resolveSchemaName(k) === pascalName) return v;
 	return null;
 }
-/** Walk into a schema to find a field's sub-schema, resolving allOf. */
+/** Walk into a schema to find a field's sub-schema, resolving allOf and oneOf/anyOf. */
 function findNestedFieldSchema(fieldName, parentSchema, schemas) {
 	if (parentSchema.properties?.[fieldName]) return parentSchema.properties[fieldName];
 	if (parentSchema.allOf) for (const sub of parentSchema.allOf) {
@@ -612,6 +612,15 @@ function findNestedFieldSchema(fieldName, parentSchema, schemas) {
 		}
 		if (resolved.properties?.[fieldName]) return resolved.properties[fieldName];
 	}
+	for (const variant of [...parentSchema.oneOf ?? [], ...parentSchema.anyOf ?? []]) {
+		let resolved = variant;
+		if (variant.$ref) {
+			const segments = variant.$ref.split("/");
+			const refName = segments[segments.length - 1];
+			if (refName && schemas[refName]) resolved = schemas[refName];
+		}
+		if (resolved.properties?.[fieldName]) return resolved.properties[fieldName];
+	}
 	return null;
 }
 /** Extract a model (and nested models) from an inline field schema. */
@@ -679,6 +688,86 @@ function buildFieldFromSchema(fieldName, fieldSchema, contextName, requiredSet)
 		example: fieldSchema.example
 	};
 }
+/**
+* If every non-null oneOf/anyOf variant is a string-valued const, return the
+* list of those const values so the union can collapse into a single enum.
+* Returns null when any variant isn't a pure string-const (model ref,
+* number const, nullable, etc.).
+*/
+function collectLiteralStringConsts(variants) {
+	if (variants.length === 0) return null;
+	const values = [];
+	for (const v of variants) {
+		if (typeof v.const === "string") {
+			values.push(v.const);
+			continue;
+		}
+		if (Array.isArray(v.enum) && v.enum.length === 1 && typeof v.enum[0] === "string") {
+			values.push(v.enum[0]);
+			continue;
+		}
+		return null;
+	}
+	return values;
+}
+/** Build an EnumRef the same way the regular enum path does for naming. */
+function buildSyntheticEnumRef(values, contextName, parentModelName) {
+	const baseName = toPascalCase(contextName ?? "UnknownEnum");
+	const cleanParent = parentModelName ? stripListItemMarkers(parentModelName) : void 0;
+	return {
+		kind: "enum",
+		name: cleanParent && !baseName.startsWith(cleanParent) ? `${cleanParent}${baseName}` : baseName,
+		values
+	};
+}
+/**
+* Detect an implicit discriminator on an oneOf where every variant is an
+* object schema that pins the same property to a const value. Returns
+* { property, mapping } so the IR can represent the union as discriminated
+* without needing an explicit `discriminator:` key in the spec.
+*
+* Both shapes are supported:
+*   { properties: { event: { const: "x" } }, required: ["event"] }
+*   { properties: { event: { type: "string", enum: ["x"] } } }
+*
+* Returns null when any variant doesn't fit the pattern or when variants
+* disagree on which property carries the discriminator.
+*/
+function detectConstPropertyDiscriminator(variants) {
+	if (variants.length < 2) return null;
+	let candidateProperty = null;
+	const candidates = Object.keys(variants[0]?.properties ?? {});
+	for (const propName of candidates) if (variants.every((v) => getConstPropertyValue(v, propName) !== null)) {
+		candidateProperty = propName;
+		break;
+	}
+	if (!candidateProperty) return null;
+	const mapping = {};
+	for (const v of variants) {
+		const value = getConstPropertyValue(v, candidateProperty);
+		if (value === null) return null;
+		const variantName = resolveVariantModelName(v);
+		if (!variantName) return null;
+		mapping[value] = variantName;
+	}
+	return {
+		property: candidateProperty,
+		mapping
+	};
+}
+function getConstPropertyValue(schema, property) {
+	const prop = schema.properties?.[property];
+	if (!prop) return null;
+	if (typeof prop.const === "string") return prop.const;
+	if (Array.isArray(prop.enum) && prop.enum.length === 1 && typeof prop.enum[0] === "string") return prop.enum[0];
+	return null;
+}
+function resolveVariantModelName(schema) {
+	if (schema.$ref) return resolveSchemaName(schema.$ref.replace(/^#\/components\/schemas\//, ""));
+	const title = typeof schema["title"] === "string" ? schema["title"] : null;
+	if (title) return resolveSchemaName(title);
+	return null;
+}
 function extractEnum(name, schema) {
 	return {
 		name,
@@ -697,6 +786,19 @@ function extractModel(name, schema, schemas) {
 		if (!fieldSchema) continue;
 		fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, requiredSet));
 	}
+	if (fields.length === 0 && (schema.oneOf || schema.anyOf)) {
+		const variants = schema.oneOf ?? schema.anyOf ?? [];
+		const emptyRequired = /* @__PURE__ */ new Set();
+		const seenFieldNames = /* @__PURE__ */ new Set();
+		for (const variant of variants) {
+			if (!variant.properties) continue;
+			for (const [fieldName, fieldSchema] of Object.entries(variant.properties)) {
+				if (!fieldSchema || seenFieldNames.has(fieldName)) continue;
+				seenFieldNames.add(fieldName);
+				fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, emptyRequired));
+			}
+		}
+	}
 	if (schema.additionalProperties && typeof schema.additionalProperties === "object" && schema.properties) {
 		if (Object.keys(schema.additionalProperties).length > 0) {
 			const valueType = schemaToTypeRef(schema.additionalProperties, "additionalProperties", name);
@@ -736,6 +838,18 @@ function extractAllOfModel(name, schema, schemas) {
 				});
 				if (f.required) requiredSet.add(f.name);
 			}
+		} else if (resolved.oneOf || resolved.anyOf) {
+			const variants = resolved.oneOf ?? resolved.anyOf ?? [];
+			const emptyRequired = /* @__PURE__ */ new Set();
+			const seenFieldNames = new Set(fields.map((f) => f.name));
+			for (const variant of variants) {
+				if (!variant.properties) continue;
+				for (const [fieldName, fieldSchema] of Object.entries(variant.properties)) {
+					if (!fieldSchema || seenFieldNames.has(fieldName)) continue;
+					seenFieldNames.add(fieldName);
+					fields.push(buildFieldFromSchema(fieldName, fieldSchema, name, emptyRequired));
+				}
+			}
 		} else {
 			if (resolved.required) for (const r of resolved.required) requiredSet.add(r);
 			if (resolved.properties) {
@@ -902,6 +1016,15 @@ function schemaToTypeRef(schema, contextName, parentModelName) {
 			kind: "nullable",
 			inner: schemaToTypeRef(nonNullVariants[0], contextName, parentModelName)
 		};
+		const literalStrings = collectLiteralStringConsts(nonNullVariants);
+		if (literalStrings !== null && literalStrings.length >= 2) {
+			const enumRef = buildSyntheticEnumRef(literalStrings, contextName, parentModelName);
+			return nullVariant ? {
+				kind: "nullable",
+				inner: enumRef
+			} : enumRef;
+		}
+		const syntheticDiscriminator = !schema.discriminator && compositionKind === "oneOf" ? detectConstPropertyDiscriminator(nonNullVariants) : null;
 		const variants = rawVariants.filter((v) => v.type !== "null").map((v) => schemaToTypeRef(v, contextName, parentModelName));
 		const hasNull = !!nullVariant;
 		const union = {
@@ -911,7 +1034,7 @@ function schemaToTypeRef(schema, contextName, parentModelName) {
 			...schema.discriminator ? { discriminator: {
 				property: schema.discriminator.propertyName,
 				mapping: Object.fromEntries(Object.entries(schema.discriminator.mapping ?? {}).map(([k, v]) => [k, v.replace(/^#\/components\/schemas\//, "")]))
-			} } : {}
+			} } : syntheticDiscriminator ? { discriminator: syntheticDiscriminator } : {}
 		};
 		return hasNull ? {
 			kind: "nullable",
@@ -1583,6 +1706,94 @@ function inferDeeperContext(path) {
 	if (nonParams.length >= 3) return toPascalCase(nonParams.slice(1, -1).join("_"));
 	return null;
 }
+/**
+* Extract mutually-exclusive parameter groups from the `x-mutually-exclusive-parameter-groups`
+* operation extension. Cross-references grouped parameter names against the already-extracted
+* IR parameter arrays so emitters get object-identity references.
+*/
+function extractParameterGroups(op, allIRParams, operationContext) {
+	const raw = op["x-mutually-exclusive-parameter-groups"];
+	if (!raw || typeof raw !== "object") return void 0;
+	const paramByName = /* @__PURE__ */ new Map();
+	for (const p of allIRParams) paramByName.set(p.name, p);
+	const groups = [];
+	for (const [groupName, groupDef] of Object.entries(raw)) {
+		if (!groupDef || typeof groupDef !== "object") throw new Error(`Malformed x-mutually-exclusive-parameter-groups.${groupName} in ${operationContext}: expected an object with "optional" and "variants".`);
+		if (typeof groupDef.optional !== "boolean") throw new Error(`Malformed x-mutually-exclusive-parameter-groups.${groupName}.optional in ${operationContext}: expected a boolean.`);
+		if (!groupDef.variants || typeof groupDef.variants !== "object") throw new Error(`Malformed x-mutually-exclusive-parameter-groups.${groupName}.variants in ${operationContext}: expected an object mapping variant names to parameter name arrays.`);
+		if (Object.keys(groupDef.variants).length === 0) throw new Error(`Malformed x-mutually-exclusive-parameter-groups.${groupName} in ${operationContext}: group has zero variants.`);
+		const variants = Object.entries(groupDef.variants).map(([variantName, paramNames]) => {
+			if (!Array.isArray(paramNames) || paramNames.length === 0) throw new Error(`Malformed x-mutually-exclusive-parameter-groups.${groupName}.variants.${variantName} in ${operationContext}: expected a non-empty array of parameter names.`);
+			return {
+				name: variantName,
+				parameters: paramNames.map((pName) => {
+					const irParam = paramByName.get(pName);
+					if (!irParam) throw new Error(`x-mutually-exclusive-parameter-groups.${groupName}.variants.${variantName} references parameter "${pName}" which does not exist in the operation's parameters[] (${operationContext}).`);
+					return irParam;
+				})
+			};
+		});
+		groups.push({
+			name: groupName,
+			optional: groupDef.optional,
+			variants
+		});
+	}
+	return groups.length > 0 ? groups : void 0;
+}
+/**
+* Extract mutually-exclusive body parameter groups from the
+* `x-mutually-exclusive-body-groups` operation extension. Unlike query
+* parameter groups (whose parameters live in operation.queryParams), body
+* group parameters are synthetic — built from the oneOf variant schemas in
+* the request body. Emitters use the group's presence to generate sum-type
+* interfaces and custom JSON marshalling instead of flat optional fields.
+*/
+function extractBodyParameterGroups(op, operationContext) {
+	const raw = op["x-mutually-exclusive-body-groups"];
+	if (!raw || typeof raw !== "object") return void 0;
+	const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+	const variantFieldSchemas = /* @__PURE__ */ new Map();
+	if (bodySchema) {
+		for (const sub of bodySchema.allOf ?? []) for (const variant of sub.oneOf ?? []) if (variant.properties) {
+			for (const [name, fieldSchema] of Object.entries(variant.properties)) if (fieldSchema) variantFieldSchemas.set(name, fieldSchema);
+		}
+		for (const variant of bodySchema.oneOf ?? []) if (variant.properties) {
+			for (const [name, fieldSchema] of Object.entries(variant.properties)) if (fieldSchema) variantFieldSchemas.set(name, fieldSchema);
+		}
+	}
+	const groups = [];
+	for (const [groupName, groupDef] of Object.entries(raw)) {
+		if (!groupDef || typeof groupDef !== "object") continue;
+		if (typeof groupDef.optional !== "boolean") continue;
+		if (!groupDef.variants || typeof groupDef.variants !== "object") continue;
+		if (Object.keys(groupDef.variants).length === 0) continue;
+		const variants = Object.entries(groupDef.variants).map(([variantName, paramNames]) => {
+			if (!Array.isArray(paramNames) || paramNames.length === 0) throw new Error(`Malformed x-mutually-exclusive-body-groups.${groupName}.variants.${variantName} in ${operationContext}: expected a non-empty array of parameter names.`);
+			return {
+				name: variantName,
+				parameters: paramNames.map((pName) => {
+					const fieldSchema = variantFieldSchemas.get(pName);
+					return {
+						name: pName,
+						type: fieldSchema ? schemaToTypeRef(fieldSchema, toPascalCase(pName)) : {
+							kind: "primitive",
+							type: "string"
+						},
+						required: false,
+						description: fieldSchema?.description
+					};
+				})
+			};
+		});
+		groups.push({
+			name: groupName,
+			optional: groupDef.optional,
+			variants
+		});
+	}
+	return groups.length > 0 ? groups : void 0;
+}
 function buildOperation(method, path, op, pathLevelParams, operationIdTransform, serviceName) {
 	const allParams = [...pathLevelParams, ...op.parameters ?? []];
 	const hasIdempotencyHeader = allParams.some((p) => p.in === "header" && p.name.toLowerCase() === "idempotency-key");
@@ -1608,6 +1819,16 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform,
 		};
 	} else if (paginationFromParams) pagination = paginationFromParams;
 	const security = extractOperationSecurity(op.security);
+	const allIRParams = [
+		...pathParams,
+		...queryParams,
+		...headerParams,
+		...cookieParams
+	];
+	const opLabel = op.operationId ?? `${method.toUpperCase()} ${path}`;
+	const queryParamGroups = extractParameterGroups(op, allIRParams, opLabel);
+	const bodyParamGroups = extractBodyParameterGroups(op, opLabel);
+	const parameterGroups = queryParamGroups || bodyParamGroups ? [...queryParamGroups ?? [], ...bodyParamGroups ?? []] : void 0;
 	return {
 		operation: {
 			name: inferOperationName(method, path, op.operationId, operationIdTransform),
@@ -1627,7 +1848,8 @@ function buildOperation(method, path, op, pathLevelParams, operationIdTransform,
 			injectIdempotencyKey: hasIdempotencyHeader,
 			deprecated: op.deprecated || void 0,
 			async: op["x-oagen-async"],
-			security
+			security,
+			parameterGroups
 		},
 		inlineModels
 	};
@@ -2598,6 +2820,41 @@ function findPrecedingKdoc(children, index, source) {
 	}
 	return null;
 }
+function extractKotlinClassMembers(classBody, source) {
+	const members = [];
+	const children = classBody.namedChildren;
+	for (let i = 0; i < children.length; i++) {
+		const child = children[i];
+		let memberName = null;
+		if (child.type === "property_declaration") memberName = child.children.find((c) => c.type === "variable_declaration")?.children.find((c) => c.type === "simple_identifier")?.text ?? null;
+		else if (child.type === "function_declaration") memberName = child.children.find((c) => c.type === "simple_identifier")?.text ?? null;
+		else if (child.type === "companion_object") memberName = "companion";
+		if (!memberName) continue;
+		let endIdx = child.endIndex;
+		if (child.type === "property_declaration") while (i + 1 < children.length) {
+			const next = children[i + 1];
+			if (next.type === "getter" || next.type === "setter") {
+				endIdx = next.endIndex;
+				i++;
+			} else break;
+		}
+		let startIdx = child.startIndex;
+		for (let k = i - 1; k >= 0; k--) {
+			const prev = children[k];
+			if (prev.type === "multiline_comment") {
+				if (source.slice(prev.startIndex, prev.endIndex).startsWith("/**")) startIdx = prev.startIndex;
+				break;
+			}
+			if (prev.type === "line_comment") continue;
+			break;
+		}
+		members.push({
+			key: memberName,
+			text: source.slice(startIdx, endIdx)
+		});
+	}
+	return members;
+}
 const kotlinMergeAdapter = {
 	language: "kotlin",
 	grammarModule: "tree-sitter-kotlin",
@@ -2638,6 +2895,33 @@ const kotlinMergeAdapter = {
 	renderImports(imports) {
 		return imports.map((entry) => entry.text);
 	},
+	shouldSkipDeepMerge(_symbolName, existingMemberKeys, newMembers) {
+		const newText = newMembers.map((m) => m.text).join("\n");
+		for (const match of newText.matchAll(/this\.(\w+)/g)) {
+			const propName = match[1];
+			if (propName && !existingMemberKeys.has(propName)) return true;
+		}
+		return false;
+	},
+	extractMembers(tree, source) {
+		const result = /* @__PURE__ */ new Map();
+		for (const child of tree.rootNode.children) {
+			if (child.type !== "class_declaration") continue;
+			const nameNode = child.children.find((c) => c.type === "type_identifier");
+			if (!nameNode) continue;
+			const body = child.children.find((c) => c.type === "class_body");
+			if (!body) continue;
+			const members = extractKotlinClassMembers(body, source);
+			const firstMember = body.firstNamedChild;
+			const memberIndent = firstMember ? " ".repeat(firstMember.startPosition.column) : void 0;
+			result.set(nameNode.text, {
+				members,
+				bodyEndLine: body.endPosition.row,
+				memberIndent
+			});
+		}
+		return result;
+	},
 	extractDocstrings(tree, source) {
 		const result = /* @__PURE__ */ new Map();
 		const rootChildren = tree.rootNode.children;
@@ -2820,6 +3104,7 @@ 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;
@@ -3476,6 +3761,40 @@ function buildIgnoredSymbolNames(docstrings, regions) {
 	for (const [name, info] of docstrings) if (regions.some((r) => info.declStartIndex >= r.startIndex && info.declStartIndex <= r.endIndex)) ignored.add(name);
 	return ignored;
 }
+function clampIndex(value, contentLength) {
+	if (!Number.isFinite(value)) return 0;
+	if (value < 0) return 0;
+	if (value > contentLength) return contentLength;
+	return value;
+}
+/**
+* Resolve the declaration line start for insertion using the current content,
+* instead of relying on parser column arithmetic. This avoids misplaced inserts
+* when parser columns/offsets drift.
+*/
+function declarationLineStart(content, declStartIndex) {
+	const idx = clampIndex(declStartIndex, content.length);
+	const prevNewline = content.lastIndexOf("\n", Math.max(0, idx - 1));
+	return prevNewline === -1 ? 0 : prevNewline + 1;
+}
+/**
+* Resolve a docstring range by searching for the nearest matching text before
+* the declaration start. Falls back to parser-provided offsets when search fails.
+*/
+function resolveDocRange(content, docText, declStartIndex, fallbackStart, fallbackEnd) {
+	const safeDecl = clampIndex(declStartIndex, content.length);
+	const safeFallbackStart = clampIndex(fallbackStart, content.length);
+	const safeFallbackEnd = clampIndex(fallbackEnd, content.length);
+	const found = content.lastIndexOf(docText, safeDecl);
+	if (found !== -1) return {
+		start: found,
+		end: found + docText.length
+	};
+	return {
+		start: safeFallbackStart,
+		end: safeFallbackEnd
+	};
+}
 /**
 * Check if a tree-sitter grammar is configured for the given language.
 */
@@ -3524,15 +3843,17 @@ async function extractClassEndLines(source, language) {
 		if (source[body ? body.endIndex - 1 : node.endIndex - 1] === "}") map.set(name, { bodyEndLine: endRow });
 		else map.set(name, { bodyEndLine: endRow + 1 });
 	}
-	for (const child of tree.rootNode.children) {
-		if (child.type === "class_definition" || child.type === "class_declaration") processClassNode(child);
-		if (child.type === "decorated_definition") {
-			for (const inner of child.namedChildren) if (inner.type === "class_definition") processClassNode(inner);
+	function walk(node) {
+		if (node.type === "class" || node.type === "class_definition" || node.type === "class_declaration") processClassNode(node);
+		if (node.type === "decorated_definition") {
+			for (const inner of node.namedChildren) if (inner.type === "class_definition") processClassNode(inner);
 		}
-		if (child.type === "export_statement") {
-			for (const inner of child.namedChildren) if (inner.type === "class_declaration") processClassNode(inner);
+		if (node.type === "export_statement") {
+			for (const inner of node.namedChildren) if (inner.type === "class_declaration") processClassNode(inner);
 		}
+		for (const child of node.namedChildren) walk(child);
 	}
+	for (const child of tree.rootNode.children) walk(child);
 	return map;
 }
 /**
@@ -3687,10 +4008,10 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 			if (newMembers.length > 0) {
 				if (adapter.shouldSkipDeepMerge?.(symbolName, existingMemberKeys, newMembers)) continue;
 				const indent = existSymbol.memberIndent ?? "  ";
-				const insertText = newMembers.map((m) => indent + m.text).join("\n");
+				const insertText = newMembers.map((m) => indent + m.text).join("\n\n");
 				insertions.push({
 					line: existSymbol.bodyEndLine,
-					text: insertText
+					text: "\n" + insertText
 				});
 				deepAdded += newMembers.length;
 			}
@@ -3752,15 +4073,16 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 			if (genDoc) if (existInfo.docstring) {
 				if (!existInfo.docstring.text.includes("@oagen-ignore") && existInfo.docstring.text !== genDoc.text) {
 					const newText = preserveDeprecatedTags(existInfo.docstring.text, genDoc.text);
+					const range = resolveDocRange(result, existInfo.docstring.text, existInfo.declStartIndex, existInfo.docstring.startIndex, existInfo.docstring.endIndex);
 					edits.push({
-						start: existInfo.docstring.startIndex,
-						end: existInfo.docstring.endIndex,
+						start: range.start,
+						end: range.end,
 						newText
 					});
 					docstringUpdates++;
 				}
 			} else {
-				const lineStart = existInfo.declStartIndex - existInfo.declColumn;
+				const lineStart = declarationLineStart(result, existInfo.declStartIndex);
 				const indent = " ".repeat(existInfo.declColumn);
 				edits.push({
 					start: lineStart,
@@ -3778,15 +4100,16 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 				if (existMember.docstring) {
 					if (!existMember.docstring.text.includes("@oagen-ignore") && existMember.docstring.text !== genMember.docstring.text) {
 						const newText = preserveDeprecatedTags(existMember.docstring.text, genMember.docstring.text);
+						const range = resolveDocRange(result, existMember.docstring.text, existMember.declStartIndex, existMember.docstring.startIndex, existMember.docstring.endIndex);
 						edits.push({
-							start: existMember.docstring.startIndex,
-							end: existMember.docstring.endIndex,
+							start: range.start,
+							end: range.end,
 							newText
 						});
 						docstringUpdates++;
 					}
 				} else {
-					const lineStart = existMember.declStartIndex - existMember.declColumn;
+					const lineStart = declarationLineStart(result, existMember.declStartIndex);
 					const indent = " ".repeat(existMember.declColumn);
 					edits.push({
 						start: lineStart,
@@ -3831,15 +4154,16 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 					if (existMember.docstring.text.includes("@oagen-ignore")) continue;
 					if (existMember.docstring.text !== genMember.docstring.text) {
 						const newText = preserveDeprecatedTags(existMember.docstring.text, genMember.docstring.text);
+						const range = resolveDocRange(result, existMember.docstring.text, existMember.declStartIndex, existMember.docstring.startIndex, existMember.docstring.endIndex);
 						edits.push({
-							start: existMember.docstring.startIndex,
-							end: existMember.docstring.endIndex,
+							start: range.start,
+							end: range.end,
 							newText
 						});
 						docstringUpdates++;
 					}
 				} else {
-					const lineStart = existMember.declStartIndex - existMember.declColumn;
+					const lineStart = declarationLineStart(result, existMember.declStartIndex);
 					const indent = " ".repeat(existMember.declColumn);
 					edits.push({
 						start: lineStart,
@@ -4012,7 +4336,7 @@ async function overwriteWithPreservedRegions(existingContent, generatedContent,
 		});
 	}
 	if (blocks.length === 0) return generatedContent;
-	const result = [...generatedLines];
+	const result = stripIgnoreRegions(generatedLines);
 	spliceExtraImports(existingLines, result);
 	const classEndLines = await extractClassEndLines(result.join("\n"), language);
 	const blocksByClass = /* @__PURE__ */ new Map();
@@ -4079,10 +4403,33 @@ async function overwriteWithPreservedRegions(existingContent, generatedContent,
 	for (const ins of insertions) result.splice(ins.line, 0, ...ins.content);
 	return result.join("\n");
 }
+/**
+* Remove every `@oagen-ignore-start`..`@oagen-ignore-end` region from the
+* supplied lines, collapsing stretches of blank lines that get left behind.
+* Used to drop generator-emitted seed blocks before splicing the on-disk
+* versions back in — otherwise every regen doubles up.
+*/
+function stripIgnoreRegions(lines) {
+	const out = [];
+	let skipping = false;
+	for (const line of lines) {
+		if (!skipping && line.includes("@oagen-ignore-start")) {
+			skipping = true;
+			while (out.length > 0 && out[out.length - 1].trim() === "") out.pop();
+			continue;
+		}
+		if (skipping) {
+			if (line.includes("@oagen-ignore-end")) skipping = false;
+			continue;
+		}
+		out.push(line);
+	}
+	return out;
+}
 /** Scan backwards from `lineIdx` to find the nearest class declaration name. */
 function findContainingClass(lines, lineIdx) {
 	for (let j = lineIdx - 1; j >= 0; j--) {
-		const m = lines[j].match(/^(?:export\s+)?class\s+(\w+)/);
+		const m = lines[j].match(/^\s*(?:export\s+)?class\s+(\w+)/);
 		if (m) return m[1];
 	}
 	return "";
@@ -4092,7 +4439,7 @@ function findContainingClass(lines, lineIdx) {
 * by scanning backwards from `beforeLine`.
 */
 function findClassDeclarationStart(lines, className, beforeLine) {
-	const classPattern = new RegExp(`^(?:export\\s+)?class\\s+${className}\\b`);
+	const classPattern = new RegExp(`^\\s*(?:export\\s+)?class\\s+${className}\\b`);
 	for (let i = beforeLine - 1; i >= 0; i--) {
 		if (!classPattern.test(lines[i])) continue;
 		let start = i;
@@ -4251,7 +4598,7 @@ function deriveMethodName(op, _service) {
 		const termIdx = segments.lastIndexOf(staticSegments[staticSegments.length - 1]);
 		if (segments.slice(penIdx + 1, termIdx).some((s) => s.startsWith("{"))) resource = `${toSnake(singularize(penultimate))}_${resource}`;
 	}
-	const noun = trailingParam ? singularize(resource) : resource;
+	const noun = trailingParam || verb === "create" ? singularize(resource) : resource;
 	return `${verb}_${verb === "list" ? resource : noun}`;
 }
 /**
@@ -4277,7 +4624,7 @@ function resolveOperations(spec, hints, mountRules) {
 			defaults: sh.defaults ?? {},
 			inferFromClient: sh.inferFromClient ?? [],
 			exposedParams: sh.exposedParams ?? [],
-			optionalParams: [],
+			optionalParams: sh.optionalParams ?? [],
 			responseModelName: resolveResponseModelName(op)
 		}));
 		resolved.push({
@@ -4287,7 +4634,8 @@ function resolveOperations(spec, hints, mountRules) {
 			mountOn,
 			wrappers,
 			defaults: hint?.defaults ?? {},
-			inferFromClient: hint?.inferFromClient ?? []
+			inferFromClient: hint?.inferFromClient ?? [],
+			urlBuilder: hint?.urlBuilder ?? false
 		});
 	}
 	return resolved;
@@ -4310,7 +4658,9 @@ function buildEmitterContext(spec, options) {
 		outputDir: options.outputDir,
 		apiSurface: options.apiSurface,
 		overlayLookup: options.overlayLookup,
-		resolvedOperations: resolveOperations(spec, options.operationHints, options.mountRules)
+		resolvedOperations: resolveOperations(spec, options.operationHints, options.mountRules),
+		targetDir: options.target,
+		priorTargetManifestPaths: options.priorTargetManifestPaths
 	};
 }
 /**
@@ -4429,7 +4779,7 @@ function resolveImportPath(fromFilePath, importModulePath, knownPaths) {
 */
 function isRootFile(filePath) {
 	if (filePath.includes("/fixtures/")) return false;
-	if (filePath.endsWith(".spec.ts") || filePath.endsWith(".test.ts")) return false;
+	if (filePath.endsWith(".spec.ts") || filePath.endsWith(".test.ts")) return true;
 	if (filePath.includes("/serializers/")) return false;
 	if (filePath.includes("/interfaces/") && !filePath.endsWith("/index.ts")) return false;
 	return true;
@@ -4558,7 +4908,8 @@ async function resolveFileToDirectoryConflicts(files, targetDir) {
 	};
 }
 async function integrateGeneratedFiles(opts) {
-	const { files: resolved, removals } = await resolveFileToDirectoryConflicts(await treeShakeFiles(mapFilesForTargetIntegration(opts.files, opts.language), opts.language), opts.targetDir);
+	const mapped = mapFilesForTargetIntegration(opts.files, opts.language);
+	const { files: resolved, removals } = await resolveFileToDirectoryConflicts(await treeShakeFiles(mapped, opts.language), opts.targetDir);
 	const result = await writeFiles(resolved, opts.targetDir, {
 		language: opts.language,
 		header: opts.header
@@ -4566,7 +4917,10 @@ async function integrateGeneratedFiles(opts) {
 	for (const filePath of removals) try {
 		await fs.unlink(filePath);
 	} catch {}
-	return result;
+	return {
+		...result,
+		emittedPaths: mapped.map((f) => f.path)
+	};
 }
 //#endregion
 //#region src/engine/formatter.ts
@@ -4589,6 +4943,7 @@ async function formatTargetFiles(emitter, targetDir, filePaths) {
 	if (!formatCmd) return;
 	const absolutePaths = filePaths.map((f) => path$1.resolve(targetDir, f));
 	const batchSize = formatCmd.batchSize ?? 100;
+	process.stderr.write(`[oagen] formatting ${absolutePaths.length} file(s) with ${formatCmd.cmd} (batch ${batchSize})\n`);
 	for (let i = 0; i < absolutePaths.length; i += batchSize) {
 		const batch = absolutePaths.slice(i, i + batchSize);
 		try {
@@ -4597,13 +4952,148 @@ async function formatTargetFiles(emitter, targetDir, filePaths) {
 				maxBuffer: 10 * 1024 * 1024,
 				timeout: 12e4
 			});
-		} catch {}
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`[oagen] formatter batch failed: ${msg}\n`);
+		}
+	}
+}
+//#endregion
+//#region src/engine/manifest.ts
+/**
+* Prune-manifest support for `oagen generate`.
+*
+* The manifest records every auto-generated file emitted on the previous run,
+* relative to the directory it lives in (either the `--output` standalone dir
+* or the `--target` integration dir).  On the next run we diff the previous
+* list against the current emission set and delete anything that's no longer
+* produced — preventing stale-file accumulation across regens.
+*
+* Design notes:
+*  - The manifest is versioned so future format changes can be handled safely.
+*  - Paths are stored sorted for deterministic diffs in git.
+*  - Deletion is gated on a header guard when one is available: we only remove
+*    files whose contents start with the auto-generated header.  This protects
+*    a hand-maintained file that happens to share a name with a previously
+*    generated one (extremely rare, but worth catching).
+*  - On first adoption (no previous manifest), pruning is skipped and a
+*    one-line notice is printed — no surprise deletions.
+*/
+const MANIFEST_FILENAME = ".oagen-manifest.json";
+const MANIFEST_VERSION = 1;
+/** Read `.oagen-manifest.json` from a directory.  Returns null if absent or malformed. */
+async function readManifest(dir) {
+	const manifestPath = path$1.join(dir, MANIFEST_FILENAME);
+	let raw;
+	try {
+		raw = await fs.readFile(manifestPath, "utf-8");
+	} catch {
+		return null;
+	}
+	try {
+		const parsed = JSON.parse(raw);
+		if (typeof parsed.version !== "number" || typeof parsed.language !== "string" || typeof parsed.generatedAt !== "string" || !Array.isArray(parsed.files) || !parsed.files.every((p) => typeof p === "string")) return null;
+		if (parsed.version > MANIFEST_VERSION) {
+			console.warn(`[oagen] ${MANIFEST_FILENAME} schema version ${parsed.version} is newer than supported (${MANIFEST_VERSION}); ignoring for pruning.`);
+			return null;
+		}
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+/** Write `.oagen-manifest.json` to a directory with sorted paths. */
+async function writeManifest(dir, opts) {
+	const manifest = {
+		version: MANIFEST_VERSION,
+		language: opts.language,
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		files: [...new Set(opts.files)].sort()
+	};
+	const manifestPath = path$1.join(dir, MANIFEST_FILENAME);
+	await fs.mkdir(dir, { recursive: true });
+	await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n", "utf-8");
+}
+/** Return the set of previous paths no longer present in the current emission. */
+function computeStalePaths(prev, currentPaths) {
+	const current = new Set(currentPaths);
+	return prev.files.filter((p) => !current.has(p)).sort();
+}
+/**
+* Delete stale files from `dir`.
+*
+* When `header` is provided, a file is only deleted if its contents start with
+* that header — so hand-maintained files that somehow collide with a previously
+* generated path can't be clobbered.  When `header` is omitted, the guard is
+* skipped (useful for non-source artifacts like fixture JSON).
+*
+* Returns lists for reporting.  Empty parent directories are removed after
+* deletion, up to (but not including) `dir` itself.
+*/
+async function pruneStaleFiles(dir, paths, opts = {}) {
+	const pruned = [];
+	const preserved = [];
+	const missing = [];
+	for (const relPath of paths) {
+		const fullPath = path$1.join(dir, relPath);
+		let content;
+		try {
+			content = await fs.readFile(fullPath, "utf-8");
+		} catch {
+			missing.push(relPath);
+			continue;
+		}
+		if (opts.header && !content.startsWith(opts.header)) {
+			preserved.push(relPath);
+			continue;
+		}
+		try {
+			await fs.unlink(fullPath);
+			pruned.push(relPath);
+		} catch {
+			missing.push(relPath);
+			continue;
+		}
+		await removeEmptyParents(path$1.dirname(fullPath), dir);
+	}
+	return {
+		pruned,
+		preserved,
+		missing
+	};
+}
+/**
+* Walk up from `startDir` removing empty directories until we hit `stopDir`
+* (exclusive) or a non-empty directory.  Silently ignores errors.
+*/
+async function removeEmptyParents(startDir, stopDir) {
+	let current = path$1.resolve(startDir);
+	const stop = path$1.resolve(stopDir);
+	while (current.startsWith(stop + path$1.sep) && current !== stop) {
+		let entries;
+		try {
+			entries = await fs.readdir(current);
+		} catch {
+			return;
+		}
+		if (entries.length > 0) return;
+		try {
+			await fs.rmdir(current);
+		} catch {
+			return;
+		}
+		current = path$1.dirname(current);
 	}
 }
 //#endregion
 //#region src/engine/orchestrator.ts
 async function generate(spec, emitter, options) {
-	const { files: withHeaders, header } = generateFiles(spec, emitter, options);
+	const targetManifestForCtx = options.target && !options.noPrune ? await readManifest(options.target) : null;
+	const priorTargetManifestPaths = targetManifestForCtx ? new Set(targetManifestForCtx.files) : void 0;
+	const { files: withHeaders, header } = generateFiles(spec, emitter, {
+		...options,
+		priorTargetManifestPaths
+	});
 	if (options.dryRun) {
 		if (options.target) {
 			console.log(`\nTarget integration (${options.target}):`);
@@ -4611,13 +5101,25 @@ async function generate(spec, emitter, options) {
 		}
 		return withHeaders;
 	}
+	const outputPrevManifest = options.noPrune ? null : await readManifest(options.outputDir);
 	const writeResult = await writeFiles(withHeaders, options.outputDir, {
 		language: emitter.language,
 		header
 	});
 	if (writeResult.merged.length > 0) console.log(`Merged into ${writeResult.merged.length} existing files (additive only)`);
 	if (writeResult.ignored.length > 0) console.log(`Ignored ${writeResult.ignored.length} files (@oagen-ignore-file)`);
+	const outputEmittedPaths = withHeaders.map((f) => f.path);
+	await applyManifestPrune({
+		dir: options.outputDir,
+		label: "Output",
+		prevManifest: outputPrevManifest,
+		currentPaths: outputEmittedPaths,
+		language: emitter.language,
+		header,
+		noPrune: options.noPrune
+	});
 	if (options.target) {
+		const targetPrevManifest = targetManifestForCtx;
 		const targetResult = await integrateGeneratedFiles({
 			files: withHeaders,
 			language: emitter.language,
@@ -4627,6 +5129,15 @@ async function generate(spec, emitter, options) {
 		if (targetResult.written.length > 0) console.log(`Target: created ${targetResult.written.length} new files`);
 		if (targetResult.merged.length > 0) console.log(`Target: merged into ${targetResult.merged.length} existing files (additive only)`);
 		if (targetResult.skipped.length > 0) console.log(`Target: skipped ${targetResult.skipped.length} files (excluded or no grammar)`);
+		await applyManifestPrune({
+			dir: options.target,
+			label: "Target",
+			prevManifest: targetPrevManifest,
+			currentPaths: targetResult.emittedPaths,
+			language: emitter.language,
+			header,
+			noPrune: options.noPrune
+		});
 		const allTargetFiles = [
 			...targetResult.written,
 			...targetResult.merged,
@@ -4636,6 +5147,40 @@ async function generate(spec, emitter, options) {
 	}
 	return withHeaders;
 }
+/**
+* Prune files recorded in the previous manifest but absent from the current emission,
+* then write the fresh manifest.  Safe on first adoption (no previous manifest).
+*/
+async function applyManifestPrune(opts) {
+	if (opts.noPrune) {
+		await writeManifest(opts.dir, {
+			language: opts.language,
+			files: opts.currentPaths
+		});
+		return;
+	}
+	if (!opts.prevManifest) {
+		console.log(`${opts.label}: no ${MANIFEST_FILENAME} found — skipping prune (this baseline manifest will be written now).`);
+		await writeManifest(opts.dir, {
+			language: opts.language,
+			files: opts.currentPaths
+		});
+		return;
+	}
+	const stale = computeStalePaths(opts.prevManifest, opts.currentPaths);
+	if (stale.length > 0) {
+		const { pruned, preserved } = await pruneStaleFiles(opts.dir, stale, { header: opts.header });
+		if (pruned.length > 0) console.log(`${opts.label}: pruned ${pruned.length} stale file${pruned.length === 1 ? "" : "s"}`);
+		if (preserved.length > 0) {
+			console.log(`${opts.label}: preserved ${preserved.length} file${preserved.length === 1 ? "" : "s"} in previous manifest but lacking the auto-generated header (possibly hand-edited).`);
+			for (const p of preserved) console.log(`  ${p}`);
+		}
+	}
+	await writeManifest(opts.dir, {
+		language: opts.language,
+		files: opts.currentPaths
+	});
+}
 //#endregion
 //#region src/engine/registry.ts
 const emitters = /* @__PURE__ */ new Map();
@@ -5320,7 +5865,8 @@ async function generateCommand(opts) {
 		apiSurface,
 		overlayLookup,
 		operationHints: opts.operationHints,
-		mountRules: opts.mountRules
+		mountRules: opts.mountRules,
+		noPrune: opts.prune === false
 	});
 	if (opts.dryRun) for (const f of files) console.log(f.path);
 	else {
@@ -7036,7 +7582,7 @@ program.command("parse").description("Parse an OpenAPI spec and output IR as JSO
 	}
 	return parseCommand(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("--manifest <path>", "Path to smoke-manifest.json for method overlay").option("--no-compat-check", "Skip compat overlay even if --api-surface is provided").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("--manifest <path>", "Path to smoke-manifest.json for method 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) => {
 	opts.spec ??= process.env.OPENAPI_SPEC_PATH;
 	if (!opts.spec) {
 		console.error("error: --spec <path> or OPENAPI_SPEC_PATH env var is required");