@workos/oagen 0.4.0 → 0.6.0

package/dist/cli/index.mjs

@@ -679,6 +679,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,
@@ -902,6 +982,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 +1000,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",
@@ -1662,7 +1751,9 @@ function extractParams(params, location, operationContext) {
 		description: p.description,
 		deprecated: p.deprecated || p.schema?.deprecated || void 0,
 		default: p.schema?.default,
-		example: p.example ?? p.schema?.example
+		example: p.example ?? p.schema?.example,
+		style: p.style,
+		explode: p.explode
 	}));
 }
 function extractRequestBody(body, op, inlineModels) {
@@ -2596,6 +2687,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",
@@ -2636,6 +2762,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;
@@ -3426,6 +3579,30 @@ function safeParse(parser, source) {
 * Supports any language with a tree-sitter grammar package.
 */
 const parserCache = /* @__PURE__ */ new Map();
+/**
+* When replacing an existing docstring with a generated one, carry over any
+* `@deprecated` lines from the existing doc that aren't present in the
+* generated doc.  This prevents hand-written deprecation notices from being
+* silently dropped during docstring refresh.
+*/
+function preserveDeprecatedTags(existingDoc, generatedDoc) {
+	if (!existingDoc.includes("@deprecated")) return generatedDoc;
+	if (generatedDoc.includes("@deprecated")) return generatedDoc;
+	const deprecatedParts = [];
+	for (const line of existingDoc.split("\n")) if (/@deprecated\b/.test(line)) {
+		const match = line.match(/@deprecated\b.*/);
+		if (match) {
+			const cleaned = match[0].replace(/\s*\*\/\s*$/, "");
+			deprecatedParts.push(`   * ${cleaned}`);
+		}
+	}
+	if (deprecatedParts.length === 0) return generatedDoc;
+	const closingIdx = generatedDoc.lastIndexOf("*/");
+	if (closingIdx === -1) return generatedDoc;
+	const before = generatedDoc.slice(0, closingIdx);
+	const after = generatedDoc.slice(closingIdx);
+	return before + deprecatedParts.join("\n") + "\n " + after;
+}
 function findIgnoredRegions(source) {
 	const regions = [];
 	const startTag = "@oagen-ignore-start";
@@ -3539,10 +3716,21 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 	}
 	for (const anchor of existingStatements.importAnchors) lastImportEndIndex = existingContent.slice(0, existingContent.indexOf(anchor)).split("\n").length - 1 + anchor.split("\n").length - 1;
 	if (lastImportEndIndex === -1 && existingStatements.importInsertionAnchor) lastImportEndIndex = existingContent.slice(0, existingContent.indexOf(existingStatements.importInsertionAnchor)).split("\n").length - 1 + existingStatements.importInsertionAnchor.split("\n").length - 1;
+	const existingExportedNames = /* @__PURE__ */ new Set();
 	for (const stmt of existingStatements.statements) {
-		if (stmt.kind === "reexport") existingReexports.add(adapter.normalizeReexport ? adapter.normalizeReexport(stmt.text.trim()) : stmt.text.trim());
-		if (stmt.key) existingKeys.add(stmt.key);
-		else existingUnnamedTexts.add(stmt.text.trim());
+		if (stmt.kind === "reexport") {
+			existingReexports.add(adapter.normalizeReexport ? adapter.normalizeReexport(stmt.text.trim()) : stmt.text.trim());
+			const braceMatch = stmt.text.match(/\{([^}]+)\}/);
+			if (braceMatch) for (const part of braceMatch[1].split(",")) {
+				const segments = part.trim().split(/\s+as\s+/);
+				const exportedName = (segments[1] ?? segments[0]).trim();
+				if (exportedName) existingExportedNames.add(exportedName);
+			}
+		}
+		if (stmt.key) {
+			existingKeys.add(stmt.key);
+			existingExportedNames.add(stmt.key);
+		} else existingUnnamedTexts.add(stmt.text.trim());
 	}
 	const headerLine = header.trim();
 	const newImports = [];
@@ -3602,6 +3790,17 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 				preserved++;
 				continue;
 			}
+			const braceMatch = stmt.text.match(/\{([^}]+)\}/);
+			if (braceMatch) {
+				const exportedNames = braceMatch[1].split(",").map((n) => {
+					const parts = n.trim().split(/\s+as\s+/);
+					return (parts[1] ?? parts[0]).trim();
+				}).filter(Boolean);
+				if (exportedNames.length > 0 && exportedNames.every((n) => existingExportedNames.has(n))) {
+					preserved++;
+					continue;
+				}
+			}
 		}
 		if (stmt.key && (existingKeys.has(stmt.key) || existingImportedNames.has(stmt.key))) {
 			preserved++;
@@ -3639,10 +3838,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;
 			}
@@ -3703,10 +3902,11 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 			const genDoc = genInfo.docstring && genInfo.docstring.text.trim() !== headerLine ? genInfo.docstring : null;
 			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);
 					edits.push({
 						start: existInfo.docstring.startIndex,
 						end: existInfo.docstring.endIndex,
-						newText: genDoc.text
+						newText
 					});
 					docstringUpdates++;
 				}
@@ -3723,14 +3923,16 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 			const matchedExistMembers = /* @__PURE__ */ new Set();
 			for (const [memberName, genMember] of genInfo.members) {
 				const existMember = existInfo.members.get(memberName);
-				if (!existMember || !genMember.docstring) continue;
+				if (!existMember) continue;
 				matchedExistMembers.add(memberName);
+				if (!genMember.docstring) continue;
 				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);
 						edits.push({
 							start: existMember.docstring.startIndex,
 							end: existMember.docstring.endIndex,
-							newText: genMember.docstring.text
+							newText
 						});
 						docstringUpdates++;
 					}
@@ -3745,34 +3947,59 @@ async function mergeIntoExisting(existingContent, generatedContent, language, he
 					docstringUpdates++;
 				}
 			}
-			for (const [_genName, genMember] of genInfo.members) {
+			const unmatchedGenByFp = /* @__PURE__ */ new Map();
+			for (const [genName, genMember] of genInfo.members) {
+				if (matchedExistMembers.has(genName)) continue;
 				if (!genMember.docstring || !genMember.urlFingerprint) continue;
-				for (const [existName, existMember] of existInfo.members) {
-					if (matchedExistMembers.has(existName)) continue;
-					if (!existMember.urlFingerprint || existMember.urlFingerprint !== genMember.urlFingerprint) continue;
-					if (existMember.docstring) {
-						if (existMember.docstring.text.includes("@oagen-ignore")) continue;
-						if (existMember.docstring.text !== genMember.docstring.text) {
-							edits.push({
-								start: existMember.docstring.startIndex,
-								end: existMember.docstring.endIndex,
-								newText: genMember.docstring.text
-							});
-							docstringUpdates++;
-						}
-					} else {
-						const lineStart = existMember.declStartIndex - existMember.declColumn;
-						const indent = " ".repeat(existMember.declColumn);
+				if (existInfo.members.has(genName)) continue;
+				const bucket = unmatchedGenByFp.get(genMember.urlFingerprint) ?? [];
+				bucket.push({
+					name: genName,
+					member: genMember
+				});
+				unmatchedGenByFp.set(genMember.urlFingerprint, bucket);
+			}
+			const unmatchedExistByFp = /* @__PURE__ */ new Map();
+			for (const [existName, existMember] of existInfo.members) {
+				if (matchedExistMembers.has(existName)) continue;
+				if (!existMember.urlFingerprint) continue;
+				const bucket = unmatchedExistByFp.get(existMember.urlFingerprint) ?? [];
+				bucket.push({
+					name: existName,
+					member: existMember
+				});
+				unmatchedExistByFp.set(existMember.urlFingerprint, bucket);
+			}
+			for (const [fp, genBucket] of unmatchedGenByFp) {
+				if (genBucket.length !== 1) continue;
+				const existBucket = unmatchedExistByFp.get(fp);
+				if (!existBucket || existBucket.length !== 1) continue;
+				const genMember = genBucket[0].member;
+				const existEntry = existBucket[0];
+				const existMember = existEntry.member;
+				if (!genMember.docstring) continue;
+				if (existMember.docstring) {
+					if (existMember.docstring.text.includes("@oagen-ignore")) continue;
+					if (existMember.docstring.text !== genMember.docstring.text) {
+						const newText = preserveDeprecatedTags(existMember.docstring.text, genMember.docstring.text);
 						edits.push({
-							start: lineStart,
-							end: lineStart,
-							newText: indent + genMember.docstring.text + "\n"
+							start: existMember.docstring.startIndex,
+							end: existMember.docstring.endIndex,
+							newText
 						});
 						docstringUpdates++;
 					}
-					matchedExistMembers.add(existName);
-					break;
+				} else {
+					const lineStart = existMember.declStartIndex - existMember.declColumn;
+					const indent = " ".repeat(existMember.declColumn);
+					edits.push({
+						start: lineStart,
+						end: lineStart,
+						newText: indent + genMember.docstring.text + "\n"
+					});
+					docstringUpdates++;
 				}
+				matchedExistMembers.add(existEntry.name);
 			}
 		}
 		if (edits.length > 0) {
@@ -4059,12 +4286,16 @@ function spliceExtraImports(existingLines, resultLines) {
 	const extraSimple = [...existingSimple].filter((l) => !generatedSimple.has(l));
 	const existingFrom = collectFromImports(existingLines);
 	const generatedFrom = collectFromImports(resultLines);
+	const allGeneratedIds = /* @__PURE__ */ new Set();
+	for (const ids of generatedFrom.values()) for (const id of ids) allGeneratedIds.add(id);
 	const extraFromLines = [];
 	for (const [mod, existIds] of existingFrom) {
 		const genIds = generatedFrom.get(mod);
-		if (!genIds) extraFromLines.push(`from ${mod} import ${[...existIds].join(", ")}`);
-		else {
-			const extra = [...existIds].filter((id) => !genIds.has(id));
+		if (!genIds) {
+			const extra = [...existIds].filter((id) => !allGeneratedIds.has(id));
+			if (extra.length > 0) extraFromLines.push(`from ${mod} import ${extra.join(", ")}`);
+		} else {
+			const extra = [...existIds].filter((id) => !genIds.has(id) && !allGeneratedIds.has(id));
 			if (extra.length > 0) extraFromLines.push(`from ${mod} import ${extra.join(", ")}`);
 		}
 	}
@@ -4171,7 +4402,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}`;
 }
 /**
@@ -4197,7 +4428,7 @@ function resolveOperations(spec, hints, mountRules) {
 			defaults: sh.defaults ?? {},
 			inferFromClient: sh.inferFromClient ?? [],
 			exposedParams: sh.exposedParams ?? [],
-			optionalParams: [],
+			optionalParams: sh.optionalParams ?? [],
 			responseModelName: resolveResponseModelName(op)
 		}));
 		resolved.push({
@@ -4205,7 +4436,10 @@ function resolveOperations(spec, hints, mountRules) {
 			service,
 			methodName,
 			mountOn,
-			wrappers
+			wrappers,
+			defaults: hint?.defaults ?? {},
+			inferFromClient: hint?.inferFromClient ?? [],
+			urlBuilder: hint?.urlBuilder ?? false
 		});
 	}
 	return resolved;
@@ -4228,7 +4462,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
 	};
 }
 /**
@@ -4297,7 +4533,6 @@ function generateAllFiles(spec, emitter, ctx) {
 		...emitter.generateResources(spec.services, ctx),
 		...emitter.generateClient(spec, ctx),
 		...emitter.generateErrors(ctx),
-		...emitter.generateConfig(ctx),
 		...emitter.generateTypeSignatures?.(reachableSpec, ctx) ?? [],
 		...emitter.generateTests(reachableSpec, ctx),
 		...emitter.generateManifest?.(spec, ctx) ?? []
@@ -4348,7 +4583,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;
@@ -4485,7 +4720,10 @@ async function integrateGeneratedFiles(opts) {
 	for (const filePath of removals) try {
 		await fs.unlink(filePath);
 	} catch {}
-	return result;
+	return {
+		...result,
+		emittedPaths: resolved.map((f) => f.path)
+	};
 }
 //#endregion
 //#region src/engine/formatter.ts
@@ -4520,9 +4758,141 @@ async function formatTargetFiles(emitter, targetDir, filePaths) {
 	}
 }
 //#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}):`);
@@ -4530,13 +4900,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,
@@ -4546,6 +4928,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,
@@ -4555,6 +4946,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();
@@ -5239,7 +5664,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 {
@@ -6755,10 +7181,6 @@ export const ${`${toCamelCase(lang)}Emitter`}: Emitter = {
     return [];
   },
 
-  generateConfig(_ctx: EmitterContext): GeneratedFile[] {
-    return [];
-  },
-
   generateTypeSignatures(_spec: ApiSpec, _ctx: EmitterContext): GeneratedFile[] {
     return [];
   },
@@ -6959,7 +7381,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");