@styx-api/core 0.6.0 → 0.7.0

package/dist/index.cjs

@@ -733,6 +733,972 @@ var ArgdumpParser = class {
 	}
 };
 
+//#endregion
+//#region src/frontend/argtype/lexer.ts
+const PUNCT = {
+	":": "colon",
+	"=": "eq",
+	"|": "pipe",
+	".": "dot",
+	",": "comma",
+	"(": "lparen",
+	")": "rparen"
+};
+function isIdentStart(ch) {
+	return /[A-Za-z_]/.test(ch);
+}
+function isIdentPart(ch) {
+	return /[A-Za-z0-9_]/.test(ch);
+}
+function isDigit(ch) {
+	return ch >= "0" && ch <= "9";
+}
+function lex(source) {
+	const tokens = [];
+	const errors = [];
+	let i = 0;
+	let line = 1;
+	let col = 1;
+	const peek = (o = 0) => source[i + o] ?? "";
+	const advance = () => {
+		const ch = source[i++];
+		if (ch === "\n") {
+			line++;
+			col = 1;
+		} else col++;
+		return ch;
+	};
+	const push = (kind, value, l, c) => {
+		tokens.push({
+			kind,
+			value,
+			line: l,
+			column: c
+		});
+	};
+	while (i < source.length) {
+		const ch = peek();
+		const startLine = line;
+		const startCol = col;
+		if (ch === " " || ch === "	" || ch === "\r" || ch === "\n") {
+			advance();
+			continue;
+		}
+		if (ch === "/" && peek(1) === "/") {
+			const isDoc = peek(2) === "/";
+			advance();
+			advance();
+			if (isDoc) advance();
+			let text = "";
+			while (i < source.length && peek() !== "\n") text += advance();
+			if (isDoc) push("doc", text.trim(), startLine, startCol);
+			continue;
+		}
+		if (ch === "\"") {
+			advance();
+			let str = "";
+			let closed = false;
+			while (i < source.length) {
+				const c = advance();
+				if (c === "\\") {
+					const esc = i < source.length ? advance() : "";
+					str += unescape(esc);
+				} else if (c === "\"") {
+					closed = true;
+					break;
+				} else if (c === "\n") break;
+				else str += c;
+			}
+			if (!closed) errors.push({
+				message: "Unterminated string literal",
+				line: startLine,
+				column: startCol
+			});
+			push("string", str, startLine, startCol);
+			continue;
+		}
+		if (ch === "`") {
+			advance();
+			let body = "";
+			let closed = false;
+			while (i < source.length) {
+				const c = advance();
+				if (c === "\\") {
+					body += c;
+					if (i < source.length) body += advance();
+					continue;
+				}
+				if (c === "`") {
+					closed = true;
+					break;
+				}
+				body += c;
+			}
+			if (!closed) errors.push({
+				message: "Unterminated template literal",
+				line: startLine,
+				column: startCol
+			});
+			push("template", body, startLine, startCol);
+			continue;
+		}
+		if (isDigit(ch) || ch === "-" && isDigit(peek(1))) {
+			let num = advance();
+			while (i < source.length && isDigit(peek())) num += advance();
+			if (peek() === "." && isDigit(peek(1))) {
+				num += advance();
+				while (i < source.length && isDigit(peek())) num += advance();
+			}
+			if (peek() === "e" || peek() === "E") {
+				const signed = peek(1) === "+" || peek(1) === "-";
+				if (isDigit(peek(1)) || signed && isDigit(peek(2))) {
+					num += advance();
+					if (peek() === "+" || peek() === "-") num += advance();
+					while (i < source.length && isDigit(peek())) num += advance();
+				} else {
+					num += advance();
+					errors.push({
+						message: `Malformed number '${num}': exponent has no digits`,
+						line: startLine,
+						column: startCol
+					});
+				}
+			}
+			push("number", num, startLine, startCol);
+			continue;
+		}
+		if (isIdentStart(ch)) {
+			let id = advance();
+			while (i < source.length && isIdentPart(peek())) id += advance();
+			push("ident", id, startLine, startCol);
+			continue;
+		}
+		const punct = PUNCT[ch];
+		if (punct) {
+			advance();
+			push(punct, ch, startLine, startCol);
+			continue;
+		}
+		errors.push({
+			message: `Unexpected character '${ch}'`,
+			line: startLine,
+			column: startCol
+		});
+		advance();
+	}
+	push("eof", "", line, col);
+	return {
+		tokens,
+		errors
+	};
+}
+/** Minimal escape handling inside double-quoted strings. */
+function unescape(esc) {
+	switch (esc) {
+		case "n": return "\n";
+		case "t": return "	";
+		case "r": return "\r";
+		case "\"": return "\"";
+		case "\\": return "\\";
+		case "": return "";
+		default: return esc;
+	}
+}
+
+//#endregion
+//#region src/frontend/argtype/frontmatter.ts
+function splitFrontmatter(source) {
+	const lines = source.split("\n");
+	let start = 0;
+	while (start < lines.length && lines[start].trim() === "") start++;
+	if (lines[start]?.trim() !== "---") return {
+		body: source,
+		errors: []
+	};
+	let end = -1;
+	for (let i = start + 1; i < lines.length; i++) if (lines[i].trim() === "---") {
+		end = i;
+		break;
+	}
+	if (end === -1) return {
+		body: source,
+		errors: ["Unterminated frontmatter block (missing closing '---')"]
+	};
+	const { value, errors } = parseYamlish(lines.slice(start + 1, end));
+	return {
+		frontmatter: value,
+		body: lines.map((line, i) => i >= start && i <= end ? "" : line).join("\n"),
+		errors
+	};
+}
+function tokenizeLines(raw) {
+	const out = [];
+	for (const line of raw) {
+		const noComment = stripComment(line);
+		if (noComment.trim() === "") continue;
+		const indent = noComment.length - noComment.trimStart().length;
+		out.push({
+			indent,
+			content: noComment.trim()
+		});
+	}
+	return out;
+}
+/** Strip a trailing `#` comment that is not inside quotes. Following YAML, a
+* `#` only starts a comment at the start of the line or after whitespace, so an
+* unquoted value containing `#` (e.g. a URL fragment `https://x/#frag`) is kept
+* intact. */
+function stripComment(line) {
+	let inQuote = null;
+	for (let i = 0; i < line.length; i++) {
+		const ch = line[i];
+		if (inQuote === "\"" && ch === "\\") {
+			i++;
+			continue;
+		}
+		if (inQuote) {
+			if (ch === inQuote) inQuote = null;
+		} else if (ch === "\"" || ch === "'") inQuote = ch;
+		else if (ch === "#" && (i === 0 || line[i - 1] === " " || line[i - 1] === "	")) return line.slice(0, i);
+	}
+	return line;
+}
+function parseYamlish(raw) {
+	const lines = tokenizeLines(raw);
+	const errors = [];
+	let pos = 0;
+	function parseBlock(minIndent) {
+		if (pos < lines.length && lines[pos].indent >= minIndent && lines[pos].content.startsWith("- ")) {
+			const seq = [];
+			const indent = lines[pos].indent;
+			while (pos < lines.length && lines[pos].indent === indent && lines[pos].content.startsWith("- ")) {
+				seq.push(parseScalar(lines[pos].content.slice(2).trim()));
+				pos++;
+			}
+			return seq;
+		}
+		const map = {};
+		if (pos >= lines.length) return map;
+		const indent = lines[pos].indent;
+		while (pos < lines.length && lines[pos].indent === indent && !lines[pos].content.startsWith("- ")) {
+			const { content } = lines[pos];
+			const colon = findColon(content);
+			if (colon === -1) {
+				errors.push(`Malformed frontmatter line: '${content}'`);
+				pos++;
+				continue;
+			}
+			const key = content.slice(0, colon).trim();
+			const valueText = content.slice(colon + 1).trim();
+			pos++;
+			if (valueText !== "") map[key] = parseScalar(valueText);
+			else if (pos < lines.length && lines[pos].indent > indent) map[key] = parseBlock(lines[pos].indent);
+			else map[key] = null;
+		}
+		return map;
+	}
+	const value = parseBlock(0);
+	return {
+		value: isRecord$2(value) ? value : { _root: value },
+		errors
+	};
+}
+function findColon(s) {
+	let inQuote = null;
+	for (let i = 0; i < s.length; i++) {
+		const ch = s[i];
+		if (inQuote === "\"" && ch === "\\") {
+			i++;
+			continue;
+		}
+		if (inQuote) {
+			if (ch === inQuote) inQuote = null;
+		} else if (ch === "\"" || ch === "'") inQuote = ch;
+		else if (ch === ":") return i;
+	}
+	return -1;
+}
+/** Reverse the backslash escapes an emitter applies to a quoted scalar
+* (`\n`, `\t`, `\r`, `\"`, `\\`), so values with newlines/quotes round-trip. */
+function unescapeScalar(s) {
+	return s.replace(/\\(.)/g, (_, c) => c === "n" ? "\n" : c === "t" ? "	" : c === "r" ? "\r" : c);
+}
+function parseScalar(text) {
+	if (text.startsWith("\"") && text.endsWith("\"") && text.length >= 2) return unescapeScalar(text.slice(1, -1));
+	if (text.startsWith("'") && text.endsWith("'") && text.length >= 2) return text.slice(1, -1);
+	if (text === "true") return true;
+	if (text === "false") return false;
+	if (text === "null" || text === "~") return null;
+	if (/^-?\d+(\.\d+)?$/.test(text)) return Number(text);
+	return text;
+}
+function isRecord$2(x) {
+	return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+
+//#endregion
+//#region src/frontend/argtype/template.ts
+/**
+* Index of the `}` that closes an interpolation opened at `open` (the position
+* just past the `{`), or -1 if unterminated. A naive `indexOf("}")` would stop
+* at the first `}` even when it sits inside a quoted ref name (`{"a}b"}`) or a
+* quoted operation argument (`{a.or("{b}")}`); this scan skips double-quoted
+* spans (honoring `\"`) and balances nested `{}` so those round-trip.
+*/
+function interpolationEnd(body, open) {
+	let depth = 1;
+	let inQuote = false;
+	for (let j = open; j < body.length; j++) {
+		const c = body[j];
+		if (inQuote) {
+			if (c === "\\") j++;
+			else if (c === "\"") inQuote = false;
+			continue;
+		}
+		if (c === "\"") inQuote = true;
+		else if (c === "{") depth++;
+		else if (c === "}" && --depth === 0) return j;
+	}
+	return -1;
+}
+function parseTemplate(body) {
+	const tokens = [];
+	const errors = [];
+	let lit = "";
+	let i = 0;
+	const flushLit = () => {
+		if (lit.length > 0) {
+			tokens.push({
+				kind: "literal",
+				value: lit
+			});
+			lit = "";
+		}
+	};
+	while (i < body.length) {
+		const ch = body[i];
+		if (ch === "\\" && i + 1 < body.length) {
+			const next = body[i + 1];
+			lit += next === "{" || next === "}" || next === "`" || next === "\\" ? next : "\\" + next;
+			i += 2;
+			continue;
+		}
+		if (ch === "{") {
+			const close = interpolationEnd(body, i + 1);
+			if (close === -1) {
+				errors.push("Unterminated '{' in output template");
+				lit += body.slice(i);
+				break;
+			}
+			flushLit();
+			const { token, error } = parseRef(body.slice(i + 1, close).trim());
+			if (error) errors.push(error);
+			tokens.push(token);
+			i = close + 1;
+		} else {
+			lit += ch;
+			i++;
+		}
+	}
+	flushLit();
+	return {
+		tokens,
+		errors
+	};
+}
+/** Parse the inside of `{...}`: an optional name followed by `.op(arg)` calls.
+* The name is a bare identifier, a double-quoted string (for a non-identifier
+* target name, e.g. `{"4d_output"}`), or absent for a self-reference (`{}`). */
+function parseRef(inner) {
+	const token = { kind: "ref" };
+	let rest = inner;
+	const quoted = /^"((?:[^"\\]|\\.)*)"/.exec(inner);
+	if (quoted) {
+		token.name = unescapeArg(quoted[1]);
+		rest = inner.slice(quoted[0].length);
+	} else {
+		const nameMatch = /^[A-Za-z_][A-Za-z0-9_]*/.exec(inner);
+		if (nameMatch) {
+			token.name = nameMatch[0];
+			rest = inner.slice(nameMatch[0].length);
+		}
+	}
+	const opRe = /^\.\s*([A-Za-z_]+)\s*\(\s*(?:"((?:[^"\\]|\\.)*)")?\s*\)/;
+	let error;
+	while (rest.length > 0) {
+		const m = opRe.exec(rest);
+		if (!m) {
+			error = `Unrecognized output-reference operation near '${rest}'`;
+			break;
+		}
+		const op = m[1];
+		const arg = m[2];
+		switch (op) {
+			case "strip_suffix":
+				if (arg !== void 0) (token.stripSuffix ??= []).push(unescapeArg(arg));
+				break;
+			case "strip_prefix":
+				if (arg !== void 0) (token.stripPrefix ??= []).push(unescapeArg(arg));
+				break;
+			case "basename":
+				token.basename = true;
+				break;
+			case "or":
+				if (arg !== void 0) token.or = unescapeArg(arg);
+				break;
+			default: error = `Unknown output-reference operation '${op}'`;
+		}
+		rest = rest.slice(m[0].length).trimStart();
+	}
+	return {
+		token,
+		...error && { error }
+	};
+}
+function unescapeArg(s) {
+	return s.replace(/\\(.)/g, "$1");
+}
+
+//#endregion
+//#region src/frontend/argtype/doc.ts
+/**
+* Reflow a `///` description as Markdown-style prose: a single line break is a
+* soft wrap (the lines join with a space) and a blank line starts a new
+* paragraph (kept as `\n\n`). This lets an author wrap a long description across
+* several `///` lines for readability without forcing hard breaks, while real
+* paragraph structure survives. (It does not preserve Markdown lists or indented
+* code blocks - their single line breaks are joined like ordinary prose.)
+*/
+function reflowProse(text) {
+	return text.split(/\n{2,}/).map((para) => para.split("\n").map((line) => line.trim()).filter((line) => line.length > 0).join(" ")).filter((para) => para.length > 0).join("\n\n");
+}
+/**
+* Split a `///` doc block into title + description. A leading Markdown H1
+* (`# Title` on the first line) is the title; everything after it is the
+* description. Without a leading `# `, the whole block is the description (no
+* title). The description is reflowed as prose (see `reflowProse`): single line
+* breaks soft-wrap, blank lines separate paragraphs.
+*/
+function splitDocText(raw) {
+	const newline = raw.indexOf("\n");
+	const firstLine = (newline === -1 ? raw : raw.slice(0, newline)).trim();
+	if (firstLine.startsWith("# ")) {
+		const title = firstLine.slice(2).trim();
+		const description = reflowProse(newline === -1 ? "" : raw.slice(newline + 1));
+		return {
+			...title && { title },
+			...description && { description }
+		};
+	}
+	const description = reflowProse(raw);
+	return description ? { description } : {};
+}
+
+//#endregion
+//#region src/frontend/argtype/parser.ts
+/** Split a `///` block and attach its title/description to a node. Per the spec,
+* the block "is applied first and wins": for each field the block provides it
+* overrides a value a chained `.title()`/`.description()` already set, while a
+* field the block leaves unset keeps whatever the chain supplied. */
+function attachDocText(target, raw) {
+	const { title, description } = splitDocText(raw);
+	if (title !== void 0) target.title = title;
+	if (description !== void 0) target.description = description;
+}
+const COMBINATORS = new Set([
+	"seq",
+	"set",
+	"opt",
+	"rep",
+	"alt",
+	"any"
+]);
+const TERMINALS = new Set([
+	"int",
+	"float",
+	"str",
+	"path"
+]);
+/** Core + supported-extension chaining methods. Anything else is an extension
+* we don't implement and is parsed-and-ignored (the spec's "ignorable" rule). */
+const KNOWN_METHODS = new Set([
+	"name",
+	"title",
+	"description",
+	"default",
+	"min",
+	"max",
+	"join",
+	"count",
+	"countMin",
+	"countMax",
+	"mediaType",
+	"mutable",
+	"resolveParent"
+]);
+var Parser = class {
+	tokens;
+	pos = 0;
+	errors = [];
+	warnings = [];
+	constructor(tokens) {
+		this.tokens = tokens;
+	}
+	peek(o = 0) {
+		return this.tokens[Math.min(this.pos + o, this.tokens.length - 1)];
+	}
+	at(kind) {
+		return this.peek().kind === kind;
+	}
+	next() {
+		return this.tokens[this.pos++] ?? this.tokens[this.tokens.length - 1];
+	}
+	expect(kind, what) {
+		if (this.at(kind)) return this.next();
+		const tok = this.peek();
+		this.error(`Expected ${what} but found '${tok.value || tok.kind}'`, tok);
+		return tok;
+	}
+	error(message, tok = this.peek()) {
+		this.errors.push({
+			message,
+			line: tok.line,
+			column: tok.column
+		});
+	}
+	warn(message, tok = this.peek()) {
+		this.warnings.push({
+			message,
+			line: tok.line,
+			column: tok.column
+		});
+	}
+	parseDocument(frontmatter) {
+		const aliases = [];
+		let rootName;
+		let root;
+		while (!this.at("eof")) {
+			const docs = this.collectDocs();
+			if (this.at("eof")) break;
+			const labelLike = this.at("ident") || this.at("string");
+			const following = this.peek(1).kind;
+			if (labelLike && following === "eq") {
+				const nameTok = this.next();
+				if (nameTok.kind === "string") this.error("Alias names must be identifiers, not quoted strings", nameTok);
+				this.next();
+				const expr = this.parseElement();
+				if (docs) attachDocText(expr, docs);
+				aliases.push({
+					name: nameTok.value,
+					expr
+				});
+				continue;
+			}
+			if (labelLike && following === "colon") {
+				const nameTok = this.next();
+				this.next();
+				const expr = this.parseElement();
+				if (docs) attachDocText(expr, docs);
+				if (root) this.error(`Multiple root definitions; '${nameTok.value}' ignored (already have '${rootName ?? "<anonymous>"}')`, nameTok);
+				else {
+					rootName = nameTok.value;
+					root = expr;
+					if (!root.name) root.name = nameTok.value;
+				}
+				continue;
+			}
+			if (!this.at("ident") && !this.at("string") && !this.at("lparen")) {
+				this.error("Expected a definition (name: expr), an alias (Name = expr), or a root expression");
+				break;
+			}
+			const expr = this.parseElement();
+			if (docs) attachDocText(expr, docs);
+			if (root) {
+				this.error("Multiple root definitions; a second top-level expression is not allowed");
+				break;
+			}
+			root = expr;
+		}
+		if (!root) {
+			this.error("No root definition (expected `name: expr` or a bare root expression)");
+			return;
+		}
+		return {
+			...frontmatter && { frontmatter },
+			aliases,
+			...rootName !== void 0 && { rootName },
+			root
+		};
+	}
+	/** Collect consecutive `///` doc lines, joined with newlines. */
+	collectDocs() {
+		const lines = [];
+		while (this.at("doc")) lines.push(this.next().value);
+		return lines.length > 0 ? lines.join("\n") : void 0;
+	}
+	/**
+	* An element is the unit inside a comma list: an optionally-named expression.
+	* `label:` is looser than `|`, so a name binds the whole alternative that
+	* follows it.
+	*/
+	parseElement() {
+		if ((this.at("ident") || this.at("string")) && this.peek(1).kind === "colon") {
+			const nameTok = this.next();
+			this.next();
+			const inner = this.parseElement();
+			inner.name = nameTok.value;
+			return inner;
+		}
+		return this.parseAlt();
+	}
+	parseAlt() {
+		const first = this.parseChain();
+		if (!this.at("pipe")) return first;
+		const alts = [first];
+		while (this.at("pipe")) {
+			this.next();
+			alts.push(this.parseChain());
+		}
+		return {
+			kind: "comb",
+			op: "alt",
+			children: alts
+		};
+	}
+	parseChain() {
+		const node = this.parsePrimary();
+		let chained = false;
+		while (this.at("dot")) {
+			this.next();
+			this.applyMethod(node);
+			chained = true;
+		}
+		if (this.at("eq")) {
+			const eqTok = this.next();
+			const value = this.parseValue();
+			if (node.kind === "terminal" && !chained) node.default = value;
+			else this.error("`= value` default is only allowed on a bare terminal; use `.default(...)` after a method chain", eqTok);
+		}
+		return node;
+	}
+	parsePrimary() {
+		const tok = this.peek();
+		if (tok.kind === "string") {
+			this.next();
+			return {
+				kind: "literal",
+				value: tok.value
+			};
+		}
+		if (tok.kind === "lparen") return {
+			kind: "comb",
+			op: "seq",
+			children: this.parseParenList()
+		};
+		if (tok.kind === "ident") {
+			if (COMBINATORS.has(tok.value) && this.peek(1).kind === "lparen") {
+				this.next();
+				const children = this.parseParenList();
+				return {
+					kind: "comb",
+					op: tok.value,
+					children
+				};
+			}
+			if (TERMINALS.has(tok.value)) {
+				this.next();
+				return {
+					kind: "terminal",
+					terminal: tok.value
+				};
+			}
+			this.next();
+			return {
+				kind: "ref",
+				refName: tok.value
+			};
+		}
+		this.error(`Unexpected token '${tok.value || tok.kind}' in expression`, tok);
+		this.next();
+		return {
+			kind: "literal",
+			value: ""
+		};
+	}
+	/** Parse `( elem, elem, ... )` with optional leading docs and trailing comma. */
+	parseParenList() {
+		this.expect("lparen", "'('");
+		const items = [];
+		while (!this.at("rparen") && !this.at("eof")) {
+			const docs = this.collectDocs();
+			if (this.at("rparen")) break;
+			const elem = this.parseElement();
+			if (docs) attachDocText(elem, docs);
+			items.push(elem);
+			if (this.at("comma")) this.next();
+			else break;
+		}
+		this.expect("rparen", "')'");
+		return items;
+	}
+	applyMethod(node) {
+		const nameTok = this.expect("ident", "a method name");
+		const method = nameTok.value;
+		if (method === "output") {
+			node.outputs = [...node.outputs ?? [], ...this.parseOutputArgs()];
+			return;
+		}
+		if (!KNOWN_METHODS.has(method)) {
+			this.skipBalancedArgs();
+			this.warn(`Ignoring unsupported method '.${method}()'`, nameTok);
+			return;
+		}
+		const args = this.parseScalarArgs();
+		switch (method) {
+			case "name":
+				if (typeof args[0] === "string") node.name = args[0];
+				break;
+			case "title":
+				if (typeof args[0] === "string") node.title = args[0];
+				break;
+			case "description":
+				if (typeof args[0] === "string") node.description = args[0];
+				break;
+			case "default":
+				if (args[0] !== void 0) node.default = args[0];
+				break;
+			case "min":
+				if (typeof args[0] === "number") node.min = args[0];
+				break;
+			case "max":
+				if (typeof args[0] === "number") node.max = args[0];
+				break;
+			case "join":
+				node.join = typeof args[0] === "string" ? args[0] : "";
+				break;
+			case "count":
+				if (typeof args[0] === "number") {
+					node.countMin = args[0];
+					node.countMax = args[0];
+				}
+				break;
+			case "countMin":
+				if (typeof args[0] === "number") node.countMin = args[0];
+				break;
+			case "countMax":
+				if (typeof args[0] === "number") node.countMax = args[0];
+				break;
+			case "mediaType":
+				if (typeof args[0] === "string") (node.mediaTypes ??= []).push(args[0]);
+				break;
+			case "mutable":
+				node.mutable = true;
+				break;
+			case "resolveParent":
+				node.resolveParent = true;
+				break;
+		}
+	}
+	/** Parse a parenthesized list of plain scalar arguments (numbers / strings). */
+	parseScalarArgs() {
+		this.expect("lparen", "'('");
+		const args = [];
+		while (!this.at("rparen") && !this.at("eof")) {
+			args.push(this.parseValue());
+			if (this.at("comma")) this.next();
+			else break;
+		}
+		this.expect("rparen", "')'");
+		return args;
+	}
+	/** Consume a balanced `( ... )` group without interpreting its contents.
+	* Used to skip the arguments of an unsupported extension method. */
+	skipBalancedArgs() {
+		if (!this.at("lparen")) return;
+		let depth = 0;
+		do {
+			const tok = this.next();
+			if (tok.kind === "lparen") depth++;
+			else if (tok.kind === "rparen") depth--;
+			else if (tok.kind === "eof") break;
+		} while (depth > 0);
+	}
+	/** Parse the argument list of `.output(...)`: one or more template expressions. */
+	parseOutputArgs() {
+		this.expect("lparen", "'('");
+		const outputs = [];
+		while (!this.at("rparen") && !this.at("eof")) {
+			const docs = this.collectDocs();
+			if (this.at("rparen")) break;
+			const out = this.parseOutputTemplate();
+			if (docs) attachDocText(out, docs);
+			outputs.push(out);
+			if (this.at("comma")) this.next();
+			else break;
+		}
+		this.expect("rparen", "')'");
+		return outputs;
+	}
+	/** `label: \`tpl\`` or `\`tpl\`` followed by optional `.name(...)` / `.or(...)`. */
+	parseOutputTemplate() {
+		let name;
+		if ((this.at("ident") || this.at("string")) && this.peek(1).kind === "colon") {
+			name = this.next().value;
+			this.next();
+		}
+		const out = { tokens: [] };
+		if (this.at("template")) {
+			const tmplTok = this.next();
+			const { tokens, errors } = parseTemplate(tmplTok.value);
+			out.tokens = tokens;
+			for (const e of errors) this.error(e, tmplTok);
+		} else this.error(`Expected an output template literal`);
+		const CHAIN = new Set([
+			"name",
+			"or",
+			"title",
+			"description"
+		]);
+		while (this.at("dot")) {
+			this.next();
+			const m = this.expect("ident", "a template method");
+			if (CHAIN.has(m.value)) {
+				const arg = this.parseScalarArgs()[0];
+				if (typeof arg === "string") if (m.value === "name") name = arg;
+				else if (m.value === "or") out.fallback = arg;
+				else if (m.value === "title") out.title = arg;
+				else out.description = arg;
+			} else {
+				this.skipBalancedArgs();
+				this.warn(`Ignoring unsupported output-template method '.${m.value}()'`, m);
+			}
+		}
+		if (name !== void 0) out.name = name;
+		return out;
+	}
+	parseValue() {
+		const tok = this.peek();
+		if (tok.kind === "string") {
+			this.next();
+			return tok.value;
+		}
+		if (tok.kind === "number") {
+			this.next();
+			return Number(tok.value);
+		}
+		this.error(`Expected a value (string or number) but found '${tok.value || tok.kind}'`, tok);
+		this.next();
+		return "";
+	}
+};
+function parseArgtype(source) {
+	const { frontmatter, body, errors: fmErrors } = splitFrontmatter(source);
+	const { tokens, errors: lexErrors } = lex(body);
+	const parser = new Parser(tokens);
+	const doc = parser.parseDocument(frontmatter);
+	const errors = [
+		...fmErrors.map((m) => ({ message: m })),
+		...lexErrors.map((e) => ({
+			message: e.message,
+			line: e.line,
+			column: e.column
+		})),
+		...parser.errors
+	];
+	return {
+		...doc && { doc },
+		errors,
+		warnings: parser.warnings
+	};
+}
+
+//#endregion
+//#region src/ir/builders.ts
+function lit(str) {
+	return {
+		kind: "literal",
+		attrs: { str }
+	};
+}
+function str(meta) {
+	return {
+		kind: "str",
+		attrs: {},
+		meta: normalizeMeta(meta)
+	};
+}
+function int(meta) {
+	return {
+		kind: "int",
+		attrs: {},
+		meta: normalizeMeta(meta)
+	};
+}
+function float(meta) {
+	return {
+		kind: "float",
+		attrs: {},
+		meta: normalizeMeta(meta)
+	};
+}
+function path(meta) {
+	return {
+		kind: "path",
+		attrs: {},
+		meta: normalizeMeta(meta)
+	};
+}
+function seq(...nodes) {
+	return {
+		kind: "sequence",
+		attrs: { nodes }
+	};
+}
+function seqJoin(join, ...nodes) {
+	return {
+		kind: "sequence",
+		attrs: {
+			nodes,
+			join
+		}
+	};
+}
+function opt(node, meta) {
+	return {
+		kind: "optional",
+		attrs: { node },
+		meta: normalizeMeta(meta)
+	};
+}
+function rep(node, meta) {
+	return {
+		kind: "repeat",
+		attrs: { node },
+		meta: normalizeMeta(meta)
+	};
+}
+function repJoin(join, node, meta) {
+	return {
+		kind: "repeat",
+		attrs: {
+			node,
+			join
+		},
+		meta: normalizeMeta(meta)
+	};
+}
+function alt(...alts) {
+	return {
+		kind: "alternative",
+		attrs: { alts }
+	};
+}
+function normalizeMeta(meta) {
+	if (meta === void 0) return void 0;
+	if (typeof meta === "string") return { name: meta };
+	return meta;
+}
+
 //#endregion
 //#region src/ir/meta.ts
 /** Construct a NodeRef from a node name. */
@@ -752,6 +1718,473 @@ function effectiveOutputName(output, index) {
 	return output.name ?? `output_${index}`;
 }
 
+//#endregion
+//#region src/frontend/argtype/lower.ts
+/**
+* Lower an `AstDocument` to Styx IR (`Expr` + `AppMeta`).
+*
+* Mapping highlights:
+* - Combinators map 1:1 except `set` -> `sequence` (order-not-meaningful is not
+*   modeled in the IR) and `any` -> its first branch (the spec's "emit branch 0"
+*   rule; the interchangeable alternatives are dropped with a warning).
+* - Aliases are resolved by substitution with cycle detection.
+* - `.output(...)` declarations attach to the nearest enclosing sequence scope,
+*   so an output nested in a repeat / subcommand keeps its list / struct shape
+*   (per-output gating is recovered downstream from each ref binding's gate).
+*/
+/** Build IR `Documentation` from an AST node's already-split title/description. */
+function docFrom(node) {
+	const doc = {
+		...node.title && { title: node.title },
+		...node.description && { description: node.description }
+	};
+	return Object.keys(doc).length > 0 ? doc : void 0;
+}
+var Lowerer = class {
+	errors = [];
+	warnings = [];
+	/** Extensions whose annotations the document actually uses, collected during
+	* lowering so `lowerDocument` can flag any used-but-undeclared in frontmatter. */
+	usedExtensions = /* @__PURE__ */ new Set();
+	aliases = /* @__PURE__ */ new Map();
+	constructor(aliases) {
+		for (const a of aliases) {
+			if (this.aliases.has(a.name)) this.warnings.push(`Duplicate alias '${a.name}'; last definition wins`);
+			this.aliases.set(a.name, a.expr);
+		}
+	}
+	lower(doc) {
+		const rootSink = [];
+		const expr = this.lowerNode(doc.root, /* @__PURE__ */ new Set(), void 0, rootSink);
+		const root = expr.kind === "sequence" ? expr : seq(expr);
+		if (root !== expr) root.meta = { ...doc.root.name && { name: doc.root.name } };
+		if (rootSink.length > 0) root.meta = {
+			...root.meta,
+			outputs: [...root.meta?.outputs ?? [], ...rootSink]
+		};
+		return {
+			expr: root,
+			errors: this.errors,
+			warnings: this.warnings
+		};
+	}
+	/**
+	* @param expanding - alias names currently being expanded (cycle guard).
+	* @param selfName - nearest enclosing named node, for `{}` self-references.
+	* @param sink - outputs array of the nearest enclosing sequence; a `.output()`
+	*   on this node attaches here (seq/set nodes instead own their outputs).
+	*/
+	lowerNode(node, expanding, selfName, sink) {
+		if (node.kind === "ref") return this.lowerRef(node, expanding, selfName, sink);
+		const name = node.name ?? selfName;
+		const joinable = node.kind === "comb" && (node.op === "seq" || node.op === "set" || node.op === "rep" || node.op === "opt");
+		if (node.join !== void 0 && !joinable) this.warnings.push("`.join()` is only supported on seq/set/rep/opt; ignored here");
+		const isNumericTerminal = node.kind === "terminal" && (node.terminal === "int" || node.terminal === "float");
+		const isRep = node.kind === "comb" && node.op === "rep";
+		const isPath = node.kind === "terminal" && node.terminal === "path";
+		if ((node.min !== void 0 || node.max !== void 0) && !isNumericTerminal) this.warnings.push("`.min()`/`.max()` is only supported on int/float terminals; ignored here");
+		if ((node.countMin !== void 0 || node.countMax !== void 0) && !isRep) this.warnings.push("`.count()`/`.countMin()`/`.countMax()` is only supported on rep; ignored here");
+		if ((node.mutable || node.resolveParent) && !isPath) this.warnings.push("`.mutable()`/`.resolveParent()` is only supported on path; ignored here");
+		if (node.mediaTypes?.length && !isPath) this.warnings.push("`.mediaType()` is only supported on path; ignored here");
+		if (node.outputs?.length) this.usedExtensions.add("outputs");
+		if (node.mediaTypes?.length && isPath) this.usedExtensions.add("mediatypes");
+		if ((node.mutable || node.resolveParent) && isPath) this.usedExtensions.add("paths");
+		const isSeqSet = node.kind === "comb" && (node.op === "seq" || node.op === "set");
+		if (node.outputs?.length && !isSeqSet) for (const o of node.outputs) sink.push(this.toOutput(o, name));
+		switch (node.kind) {
+			case "literal": {
+				const e = lit(node.value ?? "");
+				this.applyMeta(e, node);
+				return e;
+			}
+			case "terminal": return this.lowerTerminal(node);
+			case "comb": return this.lowerComb(node, expanding, name, sink);
+			default:
+				this.errors.push(`Unknown AST node kind '${node.kind}'`);
+				return seq();
+		}
+	}
+	lowerRef(node, expanding, selfName, sink) {
+		const target = node.refName;
+		const aliasExpr = this.aliases.get(target);
+		if (!aliasExpr) {
+			this.errors.push(`Unknown alias '${target}'`);
+			return seq();
+		}
+		if (expanding.has(target)) {
+			this.errors.push(`Recursive alias '${target}' is not allowed`);
+			return seq();
+		}
+		const clone = structuredClone(aliasExpr);
+		clone.name = node.name ?? clone.name;
+		clone.title = node.title ?? clone.title;
+		clone.description = node.description ?? clone.description;
+		if (node.default !== void 0) clone.default = node.default;
+		if (node.min !== void 0) clone.min = node.min;
+		if (node.max !== void 0) clone.max = node.max;
+		if (node.join !== void 0) clone.join = node.join;
+		if (node.countMin !== void 0) clone.countMin = node.countMin;
+		if (node.countMax !== void 0) clone.countMax = node.countMax;
+		if (node.mediaTypes?.length) clone.mediaTypes = [...clone.mediaTypes ?? [], ...node.mediaTypes];
+		if (node.mutable) clone.mutable = true;
+		if (node.resolveParent) clone.resolveParent = true;
+		if (node.outputs?.length) clone.outputs = [...clone.outputs ?? [], ...node.outputs];
+		const next = new Set(expanding);
+		next.add(target);
+		return this.lowerNode(clone, next, selfName, sink);
+	}
+	lowerTerminal(node) {
+		switch (node.terminal) {
+			case "int": {
+				const e = int();
+				this.checkBounds(node.min, node.max, "value", "min", "max");
+				if (node.min !== void 0) e.attrs.minValue = node.min;
+				if (node.max !== void 0) e.attrs.maxValue = node.max;
+				this.applyMeta(e, node);
+				return e;
+			}
+			case "float": {
+				const e = float();
+				this.checkBounds(node.min, node.max, "value", "min", "max");
+				if (node.min !== void 0) e.attrs.minValue = node.min;
+				if (node.max !== void 0) e.attrs.maxValue = node.max;
+				this.applyMeta(e, node);
+				return e;
+			}
+			case "str": {
+				const e = str();
+				this.applyMeta(e, node);
+				return e;
+			}
+			case "path": {
+				const e = path();
+				if (node.mediaTypes?.length) e.attrs.mediaTypes = node.mediaTypes;
+				if (node.mutable) e.attrs.mutable = true;
+				if (node.resolveParent) e.attrs.resolveParent = true;
+				this.applyMeta(e, node);
+				return e;
+			}
+			default:
+				this.errors.push(`Unknown terminal '${String(node.terminal)}'`);
+				return str();
+		}
+	}
+	lowerComb(node, expanding, name, sink) {
+		const children = node.children ?? [];
+		const lowerChildren = (s) => children.map((c) => this.lowerNode(c, expanding, name, s));
+		switch (node.op) {
+			case "seq":
+			case "set": {
+				const selfOutputs = [];
+				for (const o of node.outputs ?? []) selfOutputs.push(this.toOutput(o, name));
+				const lowered = lowerChildren(selfOutputs);
+				this.dedupeSiblingNames(lowered);
+				const e = seq(...lowered);
+				if (node.join !== void 0) e.attrs.join = node.join;
+				this.applyMeta(e, node);
+				if (selfOutputs.length > 0) e.meta = {
+					...e.meta,
+					outputs: [...e.meta?.outputs ?? [], ...selfOutputs]
+				};
+				return e;
+			}
+			case "alt": {
+				const arms = lowerChildren(sink);
+				this.dedupeSiblingNames(arms);
+				const e = alt(...arms);
+				this.applyMeta(e, node);
+				return e;
+			}
+			case "any": {
+				if (children.length === 0) {
+					this.errors.push("`any(...)` requires at least one branch");
+					return seq();
+				}
+				const e = this.lowerNode(children[0], expanding, name, sink);
+				if (node.name) e.meta = {
+					...e.meta,
+					name: node.name
+				};
+				{
+					const d = docFrom(node);
+					if (d) e.meta = {
+						...e.meta,
+						doc: d
+					};
+				}
+				return e;
+			}
+			case "opt": {
+				const inner = this.wrapChildren(children, expanding, name, sink);
+				if (node.join !== void 0 && (inner.kind === "sequence" || inner.kind === "repeat")) inner.attrs.join = node.join;
+				const e = opt(inner);
+				this.applyMeta(e, node);
+				if (inner.kind === "literal") e.meta = {
+					...e.meta,
+					defaultValue: false
+				};
+				return e;
+			}
+			case "rep": {
+				const e = rep(this.wrapChildren(children, expanding, name, sink));
+				if (node.join !== void 0) e.attrs.join = node.join;
+				this.checkBounds(node.countMin, node.countMax, "repetition count", "countMin", "countMax");
+				if (node.countMin !== void 0) e.attrs.countMin = node.countMin;
+				if (node.countMax !== void 0) e.attrs.countMax = node.countMax;
+				this.applyMeta(e, node);
+				return e;
+			}
+			default:
+				this.errors.push(`Unknown combinator '${String(node.op)}'`);
+				return seq();
+		}
+	}
+	/** Warn on an inverted `[min, max]` pair (a lower bound above its upper
+	* bound), which yields an unsatisfiable constraint downstream. */
+	checkBounds(min, max, what, minLabel, maxLabel) {
+		if (min !== void 0 && max !== void 0 && min > max) this.warnings.push(`Inverted ${what} bounds: ${minLabel} (${min}) > ${maxLabel} (${max})`);
+	}
+	/**
+	* Disambiguate duplicate explicit names among the direct children of a
+	* sequence/set (struct fields) or the arms of an alternative (union
+	* discriminants). The solver turns each named child into a struct field / union
+	* variant keyed by its name; two siblings with the same name would silently
+	* collapse (the second overwrites the first, dropping a parameter). argtype is
+	* hand-authored
+	* and gives no uniqueness guarantee, so - like the mrtrix frontend - we rename
+	* collisions (`name_2`, `name_3`, ...) and warn. (This catches duplicate
+	* explicit labels; it does not detect collisions between solver-derived names
+	* of otherwise-unnamed children, which the solver also does not guard.)
+	*/
+	dedupeSiblingNames(children) {
+		const used = /* @__PURE__ */ new Set();
+		for (const child of children) {
+			const nm = child.meta?.name;
+			if (nm === void 0) continue;
+			if (!used.has(nm)) {
+				used.add(nm);
+				continue;
+			}
+			let n = 2;
+			while (used.has(`${nm}_${n}`)) n++;
+			const renamed = `${nm}_${n}`;
+			used.add(renamed);
+			child.meta = {
+				...child.meta,
+				name: renamed
+			};
+			this.warnings.push(`Duplicate sibling name '${nm}'; renamed one occurrence to '${renamed}'`);
+		}
+	}
+	/** `opt`/`rep` with multiple children implicitly wrap them in a sequence,
+	* which - like any sequence - is the output scope for those children. */
+	wrapChildren(children, expanding, name, sink) {
+		if (children.length === 1) return this.lowerNode(children[0], expanding, name, sink);
+		const selfOutputs = [];
+		const e = seq(...children.map((c) => this.lowerNode(c, expanding, name, selfOutputs)));
+		if (selfOutputs.length > 0) e.meta = {
+			...e.meta,
+			outputs: selfOutputs
+		};
+		return e;
+	}
+	/** Fold an AST node's name/doc/default decorations onto an IR node's meta. */
+	applyMeta(e, node) {
+		const meta = {};
+		if (node.name) meta.name = node.name;
+		const doc = docFrom(node);
+		if (doc) meta.doc = doc;
+		if (node.default !== void 0) meta.defaultValue = node.default;
+		if (Object.keys(meta).length > 0) e.meta = {
+			...e.meta,
+			...meta
+		};
+	}
+	toOutput(o, selfName) {
+		const tokens = [];
+		for (const t of o.tokens) {
+			if (t.kind === "literal") {
+				tokens.push({
+					kind: "literal",
+					value: t.value
+				});
+				continue;
+			}
+			const targetName = t.name ?? selfName;
+			if (!targetName) {
+				this.warnings.push("Output self-reference '{}' has no named node to resolve to; emitting empty");
+				tokens.push({
+					kind: "literal",
+					value: ""
+				});
+				continue;
+			}
+			if (t.stripPrefix?.length) this.warnings.push("Output ref op 'strip_prefix' is not supported by the IR; ignored");
+			if (t.basename) this.warnings.push("Output ref op 'basename' is not supported by the IR; ignored");
+			tokens.push({
+				kind: "ref",
+				target: nodeRef(targetName),
+				...t.stripSuffix?.length && { stripExtensions: t.stripSuffix },
+				...t.or !== void 0 && { fallback: t.or }
+			});
+		}
+		if (o.fallback !== void 0) this.warnings.push("Output-level '.or(...)' fallback is not supported by the IR; ignored");
+		const doc = docFrom(o);
+		return {
+			...o.name && { name: o.name },
+			...doc && { doc },
+			tokens
+		};
+	}
+};
+function buildAppMeta(fm, rootDoc, rootName) {
+	const warnings = [];
+	const rootTitleDesc = docFrom(rootDoc);
+	if (!fm) {
+		const meta = {
+			...rootName && { id: rootName },
+			...rootTitleDesc && { doc: rootTitleDesc }
+		};
+		return Object.keys(meta).length > 0 ? {
+			meta,
+			warnings
+		} : { warnings };
+	}
+	const asStr = (x) => typeof x === "string" && x.length > 0 ? x : void 0;
+	const id = asStr(rootName) ?? asStr(fm.exe) ?? asStr(fm.id);
+	const version = asStr(fm.version) ?? (typeof fm.version === "number" ? String(fm.version) : void 0);
+	const strList = (x) => Array.isArray(x) ? x.filter((a) => typeof a === "string") : [];
+	const authors = strList(fm.authors);
+	const urls = strList(fm.urls);
+	const references = strList(fm.references);
+	const doc = {
+		...rootTitleDesc,
+		...authors.length > 0 && { authors },
+		...urls.length > 0 && { urls },
+		...references.length > 0 && { literature: references }
+	};
+	const meta = {
+		...id && { id },
+		...version && { version },
+		...Object.keys(doc).length > 0 && { doc }
+	};
+	if (isRecord$1(fm.container)) {
+		const image = asStr(fm.container.image);
+		const type = asStr(fm.container.type);
+		if (image) meta.container = {
+			image,
+			...type === "docker" || type === "singularity" ? { type } : {}
+		};
+	}
+	meta.stdout = streamFrom(fm.stdout, warnings, "stdout");
+	meta.stderr = streamFrom(fm.stderr, warnings, "stderr");
+	if (!meta.stdout) delete meta.stdout;
+	if (!meta.stderr) delete meta.stderr;
+	return {
+		meta,
+		warnings
+	};
+}
+function streamFrom(x, warnings, key) {
+	if (x === void 0 || x === null) return void 0;
+	if (isRecord$1(x)) {
+		const name = typeof x.name === "string" ? x.name : void 0;
+		if (!name) {
+			warnings.push(`Frontmatter '${key}' is missing a 'name'; ignored`);
+			return;
+		}
+		const description = typeof x.description === "string" ? x.description : void 0;
+		return {
+			name,
+			...description && { doc: { description } }
+		};
+	}
+	if (typeof x === "string") return { name: x };
+	warnings.push(`Frontmatter '${key}' has an unexpected shape; ignored`);
+}
+function isRecord$1(x) {
+	return typeof x === "object" && x !== null && !Array.isArray(x);
+}
+function lowerDocument(doc) {
+	const lowerer = new Lowerer(doc.aliases);
+	const result = lowerer.lower(doc);
+	const exe = typeof doc.frontmatter?.exe === "string" ? doc.frontmatter.exe : void 0;
+	if (exe) result.expr.attrs.nodes.unshift(lit(exe));
+	const { meta, warnings } = buildAppMeta(doc.frontmatter, {
+		title: doc.root.title,
+		description: doc.root.description
+	}, doc.rootName);
+	const extWarnings = [];
+	if (doc.frontmatter) {
+		const declared = new Set(Array.isArray(doc.frontmatter.extensions) ? doc.frontmatter.extensions.filter((e) => typeof e === "string") : []);
+		for (const used of lowerer.usedExtensions) if (!declared.has(used)) extWarnings.push(`Uses the '${used}' extension but does not declare it in frontmatter (add it to 'extensions:')`);
+	}
+	return {
+		...meta && { meta },
+		expr: result.expr,
+		errors: result.errors,
+		warnings: [
+			...result.warnings,
+			...warnings,
+			...extWarnings
+		]
+	};
+}
+
+//#endregion
+//#region src/frontend/argtype/parser-frontend.ts
+/** A fresh empty root sequence for error returns (IR passes mutate in place). */
+function emptyExpr$2() {
+	return {
+		kind: "sequence",
+		attrs: { nodes: [] }
+	};
+}
+/**
+* Frontend for the argtype sugar DSL - the hand-authored, TypeScript-types-like
+* language for describing CLI argument grammars (see the argtype spec). Parses
+* the text into an AST, then lowers it to Styx IR + AppMeta.
+*
+* Supported today: the argtype core (combinators, terminals, literals, naming,
+* aliases, value constraints, `.join`/`.count`/`.default`, doc comments,
+* frontmatter) plus the `outputs`, `mediatypes`, and `paths` extensions. `set`
+* lowers to a sequence and `any` to its first branch; the `constraints`
+* extension is parsed-and-ignored.
+*/
+var ArgtypeParser = class {
+	name = "argtype";
+	extensions = ["argtype"];
+	parse(source, _filename) {
+		const { doc, errors: parseErrors, warnings: parseWarnings } = parseArgtype(source);
+		const toLocation = (e) => e.line !== void 0 ? { location: {
+			line: e.line,
+			column: e.column
+		} } : {};
+		const errors = parseErrors.map((e) => ({
+			message: e.message,
+			...toLocation(e)
+		}));
+		const warnings = parseWarnings.map((e) => ({
+			message: e.message,
+			...toLocation(e)
+		}));
+		if (!doc) return {
+			expr: emptyExpr$2(),
+			errors,
+			warnings
+		};
+		const lowered = lowerDocument(doc);
+		warnings.push(...lowered.warnings.map((message) => ({ message })));
+		errors.push(...lowered.errors.map((message) => ({ message })));
+		return {
+			...lowered.meta && { meta: lowered.meta },
+			expr: lowered.expr,
+			errors,
+			warnings
+		};
+	}
+};
+
 //#endregion
 //#region src/frontend/boutiques/destruct-template.ts
 /**
@@ -1243,12 +2676,17 @@ var BoutiquesParser = class {
 	wrapWithFlag(node, btInput) {
 		const flag = btInput["command-line-flag"];
 		if (!isString$2(flag)) return node;
+		const flagSep = btInput["command-line-flag-separator"];
+		const fused = isString$2(flagSep) && flagSep !== " ";
 		return {
 			kind: "sequence",
-			attrs: { nodes: [{
-				kind: "literal",
-				attrs: { str: flag + (btInput["command-line-flag-separator"] ?? "") }
-			}, node] }
+			attrs: {
+				nodes: [{
+					kind: "literal",
+					attrs: { str: fused ? flag + flagSep : flag }
+				}, node],
+				...fused && { join: "" }
+			}
 		};
 	}
 	wrapWithOptional(node) {
@@ -1363,100 +2801,13 @@ var BoutiquesParser = class {
 			name: baseMeta.id
 		};
 		return {
-			meta: baseMeta,
-			expr,
-			errors: this.errors,
-			warnings: this.warnings
-		};
-	}
-};
-
-//#endregion
-//#region src/ir/builders.ts
-function lit(str) {
-	return {
-		kind: "literal",
-		attrs: { str }
-	};
-}
-function str(meta) {
-	return {
-		kind: "str",
-		attrs: {},
-		meta: normalizeMeta(meta)
-	};
-}
-function int(meta) {
-	return {
-		kind: "int",
-		attrs: {},
-		meta: normalizeMeta(meta)
-	};
-}
-function float(meta) {
-	return {
-		kind: "float",
-		attrs: {},
-		meta: normalizeMeta(meta)
-	};
-}
-function path(meta) {
-	return {
-		kind: "path",
-		attrs: {},
-		meta: normalizeMeta(meta)
-	};
-}
-function seq(...nodes) {
-	return {
-		kind: "sequence",
-		attrs: { nodes }
-	};
-}
-function seqJoin(join, ...nodes) {
-	return {
-		kind: "sequence",
-		attrs: {
-			nodes,
-			join
-		}
-	};
-}
-function opt(node, meta) {
-	return {
-		kind: "optional",
-		attrs: { node },
-		meta: normalizeMeta(meta)
-	};
-}
-function rep(node, meta) {
-	return {
-		kind: "repeat",
-		attrs: { node },
-		meta: normalizeMeta(meta)
-	};
-}
-function repJoin(join, node, meta) {
-	return {
-		kind: "repeat",
-		attrs: {
-			node,
-			join
-		},
-		meta: normalizeMeta(meta)
-	};
-}
-function alt(...alts) {
-	return {
-		kind: "alternative",
-		attrs: { alts }
-	};
-}
-function normalizeMeta(meta) {
-	if (meta === void 0) return void 0;
-	if (typeof meta === "string") return { name: meta };
-	return meta;
-}
+			meta: baseMeta,
+			expr,
+			errors: this.errors,
+			warnings: this.warnings
+		};
+	}
+};
 
 //#endregion
 //#region src/backend/string-case.ts
@@ -2207,11 +3558,33 @@ function extractVersion(versionInfo) {
 
 //#endregion
 //#region src/frontend/detect-format.ts
+/** The first non-whitespace character of a source ("" if it is all blank). */
+function firstNonBlankChar(source) {
+	const match = source.match(/\S/);
+	return match ? match[0] : "";
+}
 /**
-* Auto-detect the format of a JSON descriptor source string.
-* Returns null if the format cannot be determined.
+* Auto-detect the format of a descriptor source string.
+*
+* Every JSON frontend (boutiques, argdump, workbench, mrtrix) is a top-level
+* object, so the first non-blank character being `{` is the signal for "some
+* JSON format"; we then inspect its keys to pick which one. Anything else
+* non-blank is treated as the argtype DSL, whose sources open with a terminal
+* (`int`), a literal (`"hello"`), a combinator (`seq(...)`), a `name: expr`
+* definition, or a `---` frontmatter fence - never with `{`.
+*
+* Deciding on the leading character (rather than trying `JSON.parse` first) is
+* what lets standalone argtype snippets like `"hello"` or `42` be recognized:
+* those are *also* valid JSON scalars, so a parse-first approach would swallow
+* them and then reject them as "not an object".
+*
+* Returns null only when the source is blank, or opens with `{` but matches no
+* known JSON format (ambiguous, or still being typed).
 */
 function detectFormat(source) {
+	const first = firstNonBlankChar(source);
+	if (first === "") return null;
+	if (first !== "{") return "argtype";
 	let parsed;
 	try {
 		parsed = JSON.parse(source);
@@ -2228,6 +3601,605 @@ function detectFormat(source) {
 	return null;
 }
 
+//#endregion
+//#region src/backend/scope.ts
+/** Symbol collision avoidance for code generation. */
+var Scope = class Scope {
+	reserved;
+	used;
+	parent;
+	constructor(reserved = [], parent) {
+		this.reserved = new Set(reserved);
+		this.used = /* @__PURE__ */ new Set();
+		this.parent = parent;
+	}
+	/** Check if a symbol is already taken (in this scope or any parent). */
+	has(symbol) {
+		return this.reserved.has(symbol) || this.used.has(symbol) || (this.parent?.has(symbol) ?? false);
+	}
+	/**
+	* Add a symbol, appending a numeric suffix to avoid collisions. Returns the
+	* safe name.
+	*
+	* When a `recase` transform is given, a disambiguated candidate is routed back
+	* through it so the suffix is absorbed into the identifier's casing - e.g.
+	* `pascalCase` folds `Config_2` into `Config2` - rather than leaving a
+	* mixed-case `Config_2`. Uniqueness is always checked on the final emitted
+	* form, so two hints that case-collide still get distinct names. Defaults to
+	* identity (the bare `<name>_<n>` suffix) for callers that don't case-normalize.
+	*/
+	add(candidate, recase = (s) => s) {
+		if (!this.has(candidate)) {
+			this.used.add(candidate);
+			return candidate;
+		}
+		let suffix = 2;
+		let safe = recase(`${candidate}_${suffix}`);
+		while (this.has(safe)) {
+			suffix++;
+			safe = recase(`${candidate}_${suffix}`);
+		}
+		this.used.add(safe);
+		return safe;
+	}
+	/** Create a child scope that inherits this scope's restrictions. */
+	child(reserved = []) {
+		return new Scope(reserved, this);
+	}
+};
+
+//#endregion
+//#region src/backend/argtype/emit.ts
+const INDENT = "  ";
+/** Target content width (excluding the `/// ` prefix and indentation) for a
+* wrapped `///` description line. */
+const DOC_WIDTH = 80;
+function pad(level) {
+	return INDENT.repeat(level);
+}
+/**
+* Wrap a description into `///`-ready content lines. Paragraphs (separated by a
+* blank line) are word-wrapped to `width`; an empty string marks a paragraph
+* break (the caller emits it as a bare `///`).
+*
+* The argtype frontend reflows a `///` block as prose - a single line break
+* rejoins with a space, a blank line separates paragraphs - so wrapping here is
+* the inverse: it round-trips paragraph text exactly (whitespace within a
+* paragraph is normalized to single spaces, matching the frontend's reflow), and
+* keeps a long description from emitting as one giant physical line.
+*/
+function wrapDoc(text, width) {
+	const lines = [];
+	for (const paragraph of text.split(/\n{2,}/)) {
+		const words = paragraph.split(/\s+/).filter((w) => w.length > 0);
+		if (words.length === 0) continue;
+		if (lines.length > 0) lines.push("");
+		let cur = "";
+		for (const word of words) if (cur === "") cur = word;
+		else if (cur.length + 1 + word.length <= width) cur += ` ${word}`;
+		else {
+			lines.push(cur);
+			cur = word;
+		}
+		if (cur !== "") lines.push(cur);
+	}
+	return lines;
+}
+function num(n) {
+	return String(n);
+}
+/** Escape a string for a double-quoted argtype literal (matches the lexer). */
+function escapeString(s) {
+	return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n").replace(/\t/g, "\\t").replace(/\r/g, "\\r");
+}
+function quote(s) {
+	return `"${escapeString(s)}"`;
+}
+/** A value terminal kind whose `meta.defaultValue` argtype can express. */
+function isValueTerminal(node) {
+	return node.kind === "int" || node.kind === "float" || node.kind === "str" || node.kind === "path";
+}
+/**
+* Find the single value terminal a wrapper's default should attach to. Descends
+* through optional/repeat and a sequence with exactly one non-literal child
+* (the flag-value pattern `seq(lit, value)`). Returns undefined when the value
+* slot is ambiguous (multiple non-literal children) or absent (a bare literal
+* flag), in which case the wrapper default has no terminal to sink onto.
+*/
+function findValueTerminal(node) {
+	switch (node.kind) {
+		case "int":
+		case "float":
+		case "str":
+		case "path": return node;
+		case "optional": return findValueTerminal(node.attrs.node);
+		case "repeat": return findValueTerminal(node.attrs.node);
+		case "sequence": {
+			const nonLiteral = node.attrs.nodes.filter((n) => n.kind !== "literal");
+			return nonLiteral.length === 1 ? findValueTerminal(nonLiteral[0]) : void 0;
+		}
+		default: return;
+	}
+}
+/**
+* Push a wrapper's `meta.defaultValue` down onto its inner value terminal so it
+* can be emitted as `int = 5` / `.default(...)`. Boutiques (and argparse) hoist
+* an input's default onto the outermost wrapper (`optional` / `sequence`); the
+* argtype surface only carries `.default()` on a terminal, so we relocate it.
+* Boolean defaults are left in place: those are the `opt(literal)` flag-false
+* convention, which the frontend regenerates for free and which has no terminal.
+*/
+function sinkDefaults(expr) {
+	const clone = structuredClone(expr);
+	const visit = (node) => {
+		switch (node.kind) {
+			case "optional":
+				visit(node.attrs.node);
+				sinkInto(node);
+				break;
+			case "repeat":
+				visit(node.attrs.node);
+				sinkInto(node);
+				break;
+			case "sequence":
+				for (const c of node.attrs.nodes) visit(c);
+				sinkInto(node);
+				break;
+			case "alternative":
+				for (const c of node.attrs.alts) visit(c);
+				break;
+			default: break;
+		}
+	};
+	visit(clone);
+	return clone;
+}
+function sinkInto(wrapper) {
+	const dv = wrapper.meta?.defaultValue;
+	if (dv === void 0 || typeof dv === "boolean") return;
+	const terminal = findValueTerminal(wrapper);
+	if (!terminal || !isValueTerminal(terminal) || terminal.meta?.defaultValue !== void 0) return;
+	terminal.meta = {
+		...terminal.meta,
+		defaultValue: dv
+	};
+	const meta = { ...wrapper.meta };
+	delete meta.defaultValue;
+	wrapper.meta = Object.keys(meta).length > 0 ? meta : void 0;
+}
+/**
+* Detect the synthetic single-child sequence the frontend wraps a non-sequence
+* root in. Such a wrapper carries only `name` (matching the child's name) plus
+* any collected `outputs`; the doc/default live on the inner node. Returns the
+* inner node and the wrapper's outputs so the caller can emit the inner node as
+* the definition body (the frontend re-wraps it identically on re-parse).
+*/
+function syntheticWrap(root) {
+	if (root.kind !== "sequence" || root.attrs.nodes.length !== 1 || root.attrs.join !== void 0) return;
+	const meta = root.meta;
+	if (meta?.doc || meta?.defaultValue !== void 0 || meta?.variantTag !== void 0) return;
+	const child = root.attrs.nodes[0];
+	if (child.kind === "sequence") return void 0;
+	if ((child.meta?.name ?? void 0) !== (meta?.name ?? void 0)) return void 0;
+	return {
+		child,
+		...meta?.outputs && { outputs: meta.outputs }
+	};
+}
+function hasOutputs(expr) {
+	return walkSome(expr, (n) => (n.meta?.outputs?.length ?? 0) > 0);
+}
+function hasMediaTypes(expr) {
+	return walkSome(expr, (n) => n.kind === "path" && (n.attrs.mediaTypes?.length ?? 0) > 0);
+}
+function hasPaths(expr) {
+	return walkSome(expr, (n) => n.kind === "path" && (!!n.attrs.mutable || !!n.attrs.resolveParent));
+}
+function walkSome(node, pred) {
+	if (pred(node)) return true;
+	switch (node.kind) {
+		case "sequence": return node.attrs.nodes.some((n) => walkSome(n, pred));
+		case "alternative": return node.attrs.alts.some((n) => walkSome(n, pred));
+		case "optional": return walkSome(node.attrs.node, pred);
+		case "repeat": return walkSome(node.attrs.node, pred);
+		default: return false;
+	}
+}
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** A name rendered where an identifier is expected: bare when it is a valid
+* identifier, otherwise a double-quoted form preserving it exactly. Used for
+* both `label:` prefixes and output-template `{ref}` targets (templates accept a
+* quoted name, `{"4d_output"}`), so the two always agree and no lossy
+* sanitization is needed. */
+function identOrQuoted(name) {
+	return IDENT_RE.test(name) ? name : quote(name);
+}
+var ArgtypeEmitter = class {
+	warnings = [];
+	warn(message) {
+		this.warnings.push({ message });
+	}
+	/** Render a name as it appears before a `:` label (bare identifier or quoted
+	* label, e.g. `"1deval":`, `"1D":`). */
+	labelFor(name) {
+		return identOrQuoted(name);
+	}
+	/**
+	* `///` doc lines for a `Documentation`. A title is written as a leading
+	* Markdown H1 (`# Title`); the description follows after a blank `///` line.
+	* Either alone emits just that part.
+	*/
+	docLines(doc) {
+		if (!doc) return [];
+		const out = [];
+		if (doc.title) out.push(`/// # ${doc.title}`);
+		if (doc.title && doc.description) out.push("///");
+		if (doc.description) for (const line of wrapDoc(doc.description, DOC_WIDTH)) out.push(line === "" ? "///" : `/// ${line}`);
+		return out;
+	}
+	/**
+	* Whether a `///` block would not round-trip, so the doc must instead be
+	* emitted as `.title()` / `.description()` chaining (which sets the fields
+	* verbatim). Three cases:
+	* - a multi-line title (only its first line would survive `splitDocText`);
+	* - a description with a lone line break (a single `\n`, not a blank-line
+	*   paragraph break), which a `///` block reflows to a space - chaining keeps
+	*   the hard break intact;
+	* - a title-less description whose first line looks like an H1 heading
+	*   (`# ...`), which would be promoted to a spurious title.
+	* A blank-line paragraph break is safe: the frontend reflows a `///` block back
+	* into the same paragraphs, and a description under a title is safe too
+	* (`splitDocText` consumes only the very first line as the title).
+	*/
+	docNeedsChain(doc) {
+		if (!doc) return false;
+		if (doc.title?.includes("\n")) return true;
+		const desc = doc.description;
+		if (desc) {
+			if (desc.split(/\n{2,}/).some((para) => para.includes("\n"))) return true;
+			if (!doc.title && (desc.split("\n")[0] ?? "").trim().startsWith("# ")) return true;
+		}
+		return false;
+	}
+	/** `.title(...)` / `.description(...)` chaining for a doc that cannot round-trip
+	* as a `///` block (see `docNeedsChain`). */
+	docChain(doc) {
+		if (!doc) return "";
+		let chain = "";
+		if (doc.title) chain += `.title(${quote(doc.title)})`;
+		if (doc.description) chain += `.description(${quote(doc.description)})`;
+		return chain;
+	}
+	/**
+	* Warn for `Documentation` fields a node's `///` comment cannot carry. `title`
+	* and `description` are emitted (see `docLines`); literature / comment /
+	* authors / urls attached to an inner node have no surface, so surface them
+	* rather than dropping silently.
+	*/
+	warnUnrepresentableDoc(doc, where) {
+		if (!doc) return;
+		const lost = [];
+		if (doc.literature?.length) lost.push("literature");
+		if (doc.comment) lost.push("comment");
+		if (doc.authors?.length) lost.push("authors");
+		if (doc.urls?.length) lost.push("urls");
+		if (lost.length > 0) this.warn(`Documentation ${lost.join("/")} on ${where} has no argtype node surface; ignored`);
+	}
+	emit(expr, app) {
+		const raw = sinkDefaults(expr);
+		const lines = [];
+		let exe;
+		let root = raw;
+		if (raw.kind === "sequence" && raw.attrs.nodes[0]?.kind === "literal") {
+			exe = raw.attrs.nodes[0].attrs.str;
+			root = {
+				kind: "sequence",
+				attrs: {
+					...raw.attrs,
+					nodes: raw.attrs.nodes.slice(1)
+				}
+			};
+			if (raw.meta) root.meta = raw.meta;
+		}
+		const frontmatter = this.emitFrontmatter(app, exe, hasOutputs(root), hasMediaTypes(root), hasPaths(root));
+		if (frontmatter) lines.push(frontmatter, "");
+		const synthetic = syntheticWrap(root);
+		const defNode = synthetic ? synthetic.child : root;
+		const wrapperOutputs = synthetic ? synthetic.outputs : void 0;
+		const rootDoc = defNode.meta?.doc ?? app?.doc;
+		const rootChain = this.docNeedsChain(rootDoc);
+		if (!rootChain) lines.push(...this.docLines(rootDoc));
+		this.warnUnrepresentableDoc(defNode.meta?.doc, "the root node");
+		const rootName = this.labelFor(defNode.meta?.name || app?.id || "tool");
+		let body = this.emitNode(defNode, 0);
+		if (rootChain) body += this.docChain(rootDoc);
+		if (wrapperOutputs?.length) body += this.emitOutputs(wrapperOutputs, 0);
+		lines.push(`${rootName}: ${body}`);
+		return lines.join("\n") + "\n";
+	}
+	/**
+	* Emit a node's core expression plus its node-local chains (value
+	* constraints, default, join, count, media types) and any `.output(...)`.
+	* The first line is not indented (the caller places it after a label or pad);
+	* continuation lines are indented relative to `level`.
+	*/
+	emitNode(expr, level) {
+		let core;
+		switch (expr.kind) {
+			case "literal":
+				core = quote(expr.attrs.str);
+				break;
+			case "str":
+				core = "str" + this.defaultSuffix(expr, false);
+				break;
+			case "int":
+			case "float": {
+				core = expr.kind;
+				let chained = false;
+				const min = this.finiteNum(expr.attrs.minValue, "min");
+				if (min !== void 0) {
+					core += `.min(${min})`;
+					chained = true;
+				}
+				const max = this.finiteNum(expr.attrs.maxValue, "max");
+				if (max !== void 0) {
+					core += `.max(${max})`;
+					chained = true;
+				}
+				core += this.defaultSuffix(expr, chained);
+				break;
+			}
+			case "path": {
+				core = "path";
+				const media = expr.attrs.mediaTypes ?? [];
+				for (const m of media) core += `.mediaType(${quote(m)})`;
+				if (expr.attrs.mutable) core += ".mutable()";
+				if (expr.attrs.resolveParent) core += ".resolveParent()";
+				const chained = media.length > 0 || !!expr.attrs.mutable || !!expr.attrs.resolveParent;
+				core += this.defaultSuffix(expr, chained);
+				break;
+			}
+			case "sequence":
+				core = this.emitCombinator("seq", expr.attrs.nodes, level, expr.attrs.join);
+				core += this.structuralDefaultSuffix(expr);
+				break;
+			case "optional":
+				core = this.emitOptional(expr, level) + this.structuralDefaultSuffix(expr);
+				break;
+			case "repeat":
+				core = this.emitRepeat(expr, level) + this.structuralDefaultSuffix(expr);
+				break;
+			case "alternative":
+				for (const arm of expr.attrs.alts) {
+					const tag = arm.meta?.variantTag;
+					if (tag !== void 0 && tag !== arm.meta?.name) this.warn(`Union arm discriminator '${tag}' has no argtype surface and will be re-derived from the arm name '${arm.meta?.name ?? "<unnamed>"}' on re-parse`);
+				}
+				core = this.emitCombinator("alt", expr.attrs.alts, level) + this.structuralDefaultSuffix(expr);
+				break;
+			default: core = "";
+		}
+		if (expr.meta?.outputs?.length) core += this.emitOutputs(expr.meta.outputs, level);
+		return core;
+	}
+	/** `String(n)` when `n` is finite; otherwise undefined with a warning, since
+	* `Infinity`/`NaN` have no argtype number literal (emitting them would produce
+	* an identifier that fails to re-parse). */
+	finiteNum(n, where) {
+		if (n === void 0) return void 0;
+		if (!Number.isFinite(n)) {
+			this.warn(`Non-finite number (${String(n)}) on ${where} has no argtype literal; ignored`);
+			return;
+		}
+		return num(n);
+	}
+	/** `= value` on a bare terminal, else `.default(value)` once a chain started. */
+	defaultSuffix(expr, chained) {
+		const dv = expr.meta?.defaultValue;
+		if (dv === void 0 || typeof dv === "boolean") return "";
+		let value;
+		if (typeof dv === "number") {
+			const n = this.finiteNum(dv, "default");
+			if (n === void 0) return "";
+			value = n;
+		} else value = quote(dv);
+		return chained ? `.default(${value})` : ` = ${value}`;
+	}
+	/**
+	* A `.default(value)` chained onto a structural node (e.g. an enum
+	* `alternative`, or a wrapper whose default could not sink onto an inner
+	* terminal). Booleans have no argtype value literal: the only legitimate one
+	* is the `opt(literal)` flag-false convention, which the frontend regenerates,
+	* so it is silently dropped; any other boolean default is warned and dropped.
+	*/
+	structuralDefaultSuffix(expr) {
+		const dv = expr.meta?.defaultValue;
+		if (dv === void 0) return "";
+		if (typeof dv === "boolean") {
+			if (!(expr.kind === "optional" && expr.attrs.node.kind === "literal" && dv === false)) this.warn(`Boolean default on a ${expr.kind} cannot be expressed in argtype; ignored`);
+			return "";
+		}
+		if (typeof dv === "number") {
+			const n = this.finiteNum(dv, "default");
+			return n === void 0 ? "" : `.default(${n})`;
+		}
+		return `.default(${quote(dv)})`;
+	}
+	emitOptional(expr, level) {
+		const inner = expr.attrs.node;
+		if (inner.kind === "sequence" && !inner.meta && inner.attrs.join === void 0) return this.emitCombinator("opt", inner.attrs.nodes, level);
+		return this.emitCombinator("opt", [inner], level);
+	}
+	emitRepeat(expr, level) {
+		const node = expr.attrs.node;
+		let core;
+		if (node.kind === "sequence" && !node.meta && node.attrs.join === void 0) core = this.emitCombinator("rep", node.attrs.nodes, level);
+		else core = this.emitCombinator("rep", [node], level);
+		if (expr.attrs.join !== void 0) core += `.join(${expr.attrs.join === "" ? "" : quote(expr.attrs.join)})`;
+		const { countMin, countMax } = expr.attrs;
+		if (countMin !== void 0 && countMin === countMax) core += `.count(${countMin})`;
+		else {
+			if (countMin !== void 0) core += `.countMin(${countMin})`;
+			if (countMax !== void 0) core += `.countMax(${countMax})`;
+		}
+		return core;
+	}
+	emitCombinator(keyword, children, level, join) {
+		let core;
+		if (children.length === 0) core = `${keyword}()`;
+		else {
+			const items = children.map((c) => this.emitDecorated(c, level + 1));
+			const inline = `${keyword}(${items.join(", ")})`;
+			if (!items.some((i) => i.includes("\n")) && inline.length + level * 2 <= 80) core = inline;
+			else core = `${keyword}(\n${items.map((i) => pad(level + 1) + i).join(",\n")},\n${pad(level)})`;
+		}
+		if (join !== void 0) core += `.join(${join === "" ? "" : quote(join)})`;
+		return core;
+	}
+	/**
+	* A list item: leading `///` doc lines, an optional `label:` prefix, then the
+	* node. The first line is unindented (the caller pads it); continuation lines
+	* are indented to `level`.
+	*/
+	emitDecorated(expr, level) {
+		const doc = expr.meta?.doc;
+		const useChain = this.docNeedsChain(doc);
+		const parts = useChain ? [] : [...this.docLines(doc)];
+		this.warnUnrepresentableDoc(doc, `node '${expr.meta?.name ?? expr.kind}'`);
+		const label = expr.meta?.name ? `${this.labelFor(expr.meta.name)}: ` : "";
+		let node = this.emitNode(expr, level);
+		if (useChain) node += this.docChain(doc);
+		parts.push(label + node);
+		return parts.join("\n" + pad(level));
+	}
+	emitOutputs(outputs, level) {
+		return `.output(\n${outputs.map((o) => {
+			const useChain = this.docNeedsChain(o.doc);
+			const docs = useChain ? [] : this.docLines(o.doc).map((l) => pad(level + 1) + l);
+			let template = pad(level + 1) + this.emitOutputTemplate(o);
+			if (useChain) template += this.docChain(o.doc);
+			return [...docs, template].join("\n");
+		}).join(",\n")},\n${pad(level)})`;
+	}
+	emitOutputTemplate(output) {
+		if (output.mediaTypes?.length) this.warn(`Output '${output.name ?? "<anon>"}' has media types, which have no argtype surface; ignored`);
+		const label = output.name ? `${this.labelFor(output.name)}: ` : "";
+		let body = "";
+		for (const token of output.tokens) {
+			if (token.kind === "literal") {
+				body += token.value.replace(/[\\{}`]/g, (c) => `\\${c}`);
+				continue;
+			}
+			let ref = identOrQuoted(token.target.name);
+			for (const ext of token.stripExtensions ?? []) ref += `.strip_suffix(${quote(ext)})`;
+			if (token.fallback !== void 0) ref += `.or(${quote(token.fallback)})`;
+			body += `{${ref}}`;
+		}
+		return `${label}\`${body}\``;
+	}
+	/** Quote a frontmatter scalar (double-quoted, backslash-escaped). The
+	* frontmatter parser unescapes symmetrically, so quotes/newlines round-trip. */
+	fmScalar(value) {
+		return quote(value);
+	}
+	emitFrontmatter(app, exe, outputs, mediaTypes, paths) {
+		const lines = [];
+		if (exe !== void 0) lines.push(`exe: ${this.fmScalar(exe)}`);
+		if (app) {
+			if (app.version) lines.push(`version: ${this.fmScalar(app.version)}`);
+			const authors = app.doc?.authors ?? [];
+			if (authors.length > 0) {
+				lines.push("authors:");
+				for (const a of authors) lines.push(`  - ${this.fmScalar(a)}`);
+			}
+			const urls = app.doc?.urls ?? [];
+			if (urls.length > 0) {
+				lines.push("urls:");
+				for (const u of urls) lines.push(`  - ${this.fmScalar(u)}`);
+			}
+			const references = app.doc?.literature ?? [];
+			if (references.length > 0) {
+				lines.push("references:");
+				for (const rf of references) lines.push(`  - ${this.fmScalar(rf)}`);
+			}
+			if (app.container) {
+				lines.push("container:");
+				lines.push(`  image: ${this.fmScalar(app.container.image)}`);
+				if (app.container.type) lines.push(`  type: ${this.fmScalar(app.container.type)}`);
+			}
+			if (app.stdout) this.emitStream(lines, "stdout", app.stdout);
+			if (app.stderr) this.emitStream(lines, "stderr", app.stderr);
+			if (app.doc?.comment) this.warn("AppMeta.doc.comment has no argtype surface; ignored");
+		}
+		const extensions = [];
+		if (outputs) extensions.push("outputs");
+		if (mediaTypes) extensions.push("mediatypes");
+		if (paths) extensions.push("paths");
+		if (extensions.length > 0) {
+			lines.push("extensions:");
+			for (const e of extensions) lines.push(`  - ${e}`);
+		}
+		if (lines.length === 0) return void 0;
+		return [
+			"---",
+			...lines,
+			"---"
+		].join("\n");
+	}
+	emitStream(lines, key, stream) {
+		lines.push(`${key}:`);
+		lines.push(`  name: ${this.fmScalar(stream.name)}`);
+		if (stream.doc?.description) lines.push(`  description: ${this.fmScalar(stream.doc.description)}`);
+		if (stream.doc?.title) this.warn(`${key} stream title has no argtype surface; ignored`);
+	}
+};
+/** Emit argtype sugar-DSL source from an IR expression tree and optional `AppMeta`. */
+function generateArgtype(expr, app) {
+	const emitter = new ArgtypeEmitter();
+	return {
+		source: emitter.emit(expr, app),
+		warnings: emitter.warnings
+	};
+}
+
+//#endregion
+//#region src/backend/argtype/argtype.ts
+/**
+* A per-tool file stem, so co-located tools in a catalog build don't clobber one
+* another's `descriptor.argtype`. Standalone single-tool builds (no scope) keep
+* the bare name. Mirrors the JSON Schema backend's `schemaStem`.
+*/
+function argtypeStem(ctx, scope) {
+	const id = ctx.app?.id;
+	if (!id || !scope) return void 0;
+	return scope.add(snakeCase(id) || "descriptor");
+}
+/**
+* Serialization backend: emit argtype sugar-DSL source from the IR + `AppMeta`.
+*
+* The dogfooding / round-trip counterpart to the argtype frontend. Like the
+* Boutiques backend it only needs the IR (`ctx.expr`) and app metadata
+* (`ctx.app`), never the solved bindings, so it ignores the rest of the context.
+*/
+var ArgtypeBackend = class {
+	name = "argtype";
+	target = "argtype";
+	/** One scope per package so per-tool file stems stay unique in the suite dir. */
+	newPackageScope() {
+		return new Scope();
+	}
+	emitApp(ctx, scope) {
+		const { source, warnings } = generateArgtype(ctx.expr, ctx.app);
+		const stem = argtypeStem(ctx, scope);
+		const filename = stem ? `${stem}.argtype` : "descriptor.argtype";
+		return {
+			meta: ctx.app,
+			files: new Map([[filename, source]]),
+			errors: [],
+			warnings
+		};
+	}
+};
+
 //#endregion
 //#region src/backend/find-doc.ts
 /**
@@ -2559,53 +4531,6 @@ function planScope(scope, scopeGate, bindings) {
 	return scope.outputs.map((output) => planOutput(scopeGate, output, bindings));
 }
 
-//#endregion
-//#region src/backend/scope.ts
-/** Symbol collision avoidance for code generation. */
-var Scope = class Scope {
-	reserved;
-	used;
-	parent;
-	constructor(reserved = [], parent) {
-		this.reserved = new Set(reserved);
-		this.used = /* @__PURE__ */ new Set();
-		this.parent = parent;
-	}
-	/** Check if a symbol is already taken (in this scope or any parent). */
-	has(symbol) {
-		return this.reserved.has(symbol) || this.used.has(symbol) || (this.parent?.has(symbol) ?? false);
-	}
-	/**
-	* Add a symbol, appending a numeric suffix to avoid collisions. Returns the
-	* safe name.
-	*
-	* When a `recase` transform is given, a disambiguated candidate is routed back
-	* through it so the suffix is absorbed into the identifier's casing - e.g.
-	* `pascalCase` folds `Config_2` into `Config2` - rather than leaving a
-	* mixed-case `Config_2`. Uniqueness is always checked on the final emitted
-	* form, so two hints that case-collide still get distinct names. Defaults to
-	* identity (the bare `<name>_<n>` suffix) for callers that don't case-normalize.
-	*/
-	add(candidate, recase = (s) => s) {
-		if (!this.has(candidate)) {
-			this.used.add(candidate);
-			return candidate;
-		}
-		let suffix = 2;
-		let safe = recase(`${candidate}_${suffix}`);
-		while (this.has(safe)) {
-			suffix++;
-			safe = recase(`${candidate}_${suffix}`);
-		}
-		this.used.add(safe);
-		return safe;
-	}
-	/** Create a child scope that inherits this scope's restrictions. */
-	child(reserved = []) {
-		return new Scope(reserved, this);
-	}
-};
-
 //#endregion
 //#region src/backend/boutiques/boutiques.ts
 var BoutiquesEmitter = class {
@@ -2763,7 +4688,7 @@ var BoutiquesEmitter = class {
 		}
 		if (peeled.flag) {
 			input["command-line-flag"] = peeled.flag;
-			if (peeled.flagSeparator) input["command-line-flag-separator"] = peeled.flagSeparator;
+			if (peeled.flagSeparator !== void 0) input["command-line-flag-separator"] = peeled.flagSeparator;
 		}
 		if (mapped.integer) input.integer = true;
 		if (mapped.minimum !== void 0) input.minimum = mapped.minimum;
@@ -2904,7 +4829,7 @@ var BoutiquesEmitter = class {
 		}
 		if (peeled.flag) {
 			input["command-line-flag"] = peeled.flag;
-			if (peeled.flagSeparator) input["command-line-flag-separator"] = peeled.flagSeparator;
+			if (peeled.flagSeparator !== void 0) input["command-line-flag-separator"] = peeled.flagSeparator;
 		}
 		if (mapped.integer) input.integer = true;
 		if (mapped.minimum !== void 0) input.minimum = mapped.minimum;
@@ -2973,9 +4898,11 @@ var BoutiquesEmitter = class {
 				const nodes = node.attrs.nodes;
 				if (nodes.length === 2 && nodes[0].kind === "literal") {
 					const flagLit = nodes[0].attrs.str;
-					const { flag, separator } = this.splitFlagLiteral(flagLit);
-					result.flag = flag;
-					if (separator) result.flagSeparator = separator;
+					if (node.attrs.join !== void 0) {
+						const { flag, separator } = this.splitFlagLiteral(flagLit);
+						result.flag = flag;
+						result.flagSeparator = separator;
+					} else result.flag = flagLit;
 					this.peelNodeInner(nodes[1], type, result);
 				}
 				break;
@@ -3496,6 +5423,10 @@ function resultToStmt$1(r) {
 	return isExpr$1(r) ? `cargs.append(${r.expr})` : r.stmt;
 }
 function appendLines$1(cb, code) {
+	if (code.trim() === "") {
+		cb.line("pass");
+		return;
+	}
 	for (const line of code.split("\n")) cb.line(line);
 }
 function toStringExpr$1(node, type, expr) {
@@ -9079,7 +11010,8 @@ function solve(expr, options) {
 //#region src/index.ts
 function compile(source, filenameOrOptions) {
 	const options = typeof filenameOrOptions === "string" ? { filename: filenameOrOptions } : filenameOrOptions ?? {};
-	const format = options.format ?? detectFormat(source);
+	const byExtension = options.filename?.endsWith(".argtype") ? "argtype" : void 0;
+	const format = options.format ?? byExtension ?? detectFormat(source);
 	if (!format) return {
 		expr: {
 			kind: "sequence",
@@ -9088,10 +11020,20 @@ function compile(source, filenameOrOptions) {
 		errors: [{ message: "Could not detect input format. Specify format explicitly." }],
 		warnings: []
 	};
-	return (format === "argdump" ? new ArgdumpParser() : format === "workbench" ? new WorkbenchParser() : format === "mrtrix" ? new MrtrixParser() : new BoutiquesParser()).parse(source, options.filename);
+	return (() => {
+		switch (format) {
+			case "argdump": return new ArgdumpParser();
+			case "argtype": return new ArgtypeParser();
+			case "workbench": return new WorkbenchParser();
+			case "mrtrix": return new MrtrixParser();
+			case "boutiques": return new BoutiquesParser();
+			default: return new BoutiquesParser();
+		}
+	})().parse(source, options.filename);
 }
 
 //#endregion
+exports.ArgtypeBackend = ArgtypeBackend;
 exports.BoutiquesBackend = BoutiquesBackend;
 exports.CodeBuilder = CodeBuilder;
 exports.JsonSchemaBackend = JsonSchemaBackend;
@@ -9130,6 +11072,7 @@ exports.flatten = flatten;
 exports.float = float;
 exports.format = format;
 exports.formatSolveResult = formatSolveResult;
+exports.generateArgtype = generateArgtype;
 exports.generateBoutiques = generateBoutiques;
 exports.generateNipype = generateNipype;
 exports.generateOutputsSchema = generateOutputsSchema;