@styx-api/core 0.4.0 → 0.5.1

package/dist/index.mjs

@@ -3387,196 +3387,6 @@ function resolveTypeName(namedTypes) {
 	};
 }
 
-//#endregion
-//#region src/backend/styxdefs-compat.ts
-/**
-* Runtime version floors baked into generated dependency metadata.
-*
-* styx2-generated code calls `mutable_copy` / `mutableCopy` (introduced in the
-* styxdefs 0.7.0 / styxdefs-js 0.2.0 release), so emitted packages genuinely
-* require that runtime floor. This is the single source of truth: bump here and
-* both the Python and TypeScript backends pick it up.
-*/
-const STYXDEFS_COMPAT = {
-	python: ">=0.7.0,<0.8.0",
-	npm: "^0.2.0"
-};
-/**
-* Extra Python runtime packages the root distribution pulls in (container +
-* graph runners). Left unpinned - styxdefs's floor constrains them transitively
-* via their own inter-package pins.
-*/
-const PYTHON_RUNNER_DEPS = [
-	"styxdocker",
-	"styxsingularity",
-	"styxgraph"
-];
-
-//#endregion
-//#region src/backend/python/packaging.ts
-const REQUIRES_PYTHON = ">=3.10";
-const BUILD_SYSTEM = `[build-system]
-requires = ["setuptools>=61"]
-build-backend = "setuptools.build_meta"`;
-/** Escape a value for embedding in a TOML basic string. */
-function tomlStr(s) {
-	return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/[\r\n]+/g, " ").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "").trim();
-}
-/** Suite directory / importable package name; matches the CLI's `pkgDir` fallback. */
-function pkgDir(pkg) {
-	return pkg.name ?? "package";
-}
-/** Distribution (PyPI) name for a package: `<project>_<package>`, or just `<package>`. */
-function pyDistName(proj, pkg) {
-	const name = pkgDir(pkg);
-	return proj.name ? `${proj.name}_${name}` : name;
-}
-const SUMMARY_MAX_LEN = 512;
-/**
-* Clamp a description to a <=512-char one-line summary. Prefer cutting at the
-* last complete sentence that fits (clean, no dangling fragment); if there is no
-* sentence boundary early enough, cut at a word boundary and mark the elision.
-*/
-function clampSummary(s) {
-	if (s.length <= SUMMARY_MAX_LEN) return s;
-	const window = s.slice(0, SUMMARY_MAX_LEN);
-	const lastSentence = window.lastIndexOf(". ");
-	if (lastSentence >= 0) return s.slice(0, lastSentence + 1);
-	const ellipsis = "...";
-	const body = window.slice(0, SUMMARY_MAX_LEN - 3);
-	const lastSpace = body.lastIndexOf(" ");
-	return (lastSpace > 0 ? body.slice(0, lastSpace) : body).replace(/[.,;:\s]+$/, "") + ellipsis;
-}
-function description$1(doc, fallbackName) {
-	return clampSummary(doc?.description ?? `Styx generated wrappers for ${doc?.title ?? fallbackName ?? "tools"}.`);
-}
-function authorsField(doc) {
-	return `[${(doc?.authors?.length ? doc.authors : ["unknown"]).map((a) => `{ name = "${tomlStr(a)}" }`).join(", ")}]`;
-}
-function licenseField(proj) {
-	return `{ text = "${tomlStr(proj.license?.description ?? "unknown")}" }`;
-}
-/**
-* Per-suite `pyproject.toml`. The flat layout (`python/<pkg>/bet.py`) makes the
-* directory itself the importable package, so setuptools' `package-dir` maps the
-* import name (`<pkg>`) onto the distribution's root directory. The styxdefs
-* floor is the only runtime dependency.
-*
-* Precondition: `pkg.name` must be a valid Python identifier - the flat layout's
-* relative imports (`from .bet import *`) already require this, and the CLI uses
-* it verbatim as the directory name, so this stays consistent with that.
-*/
-function generateSubPyproject(proj, pkg) {
-	const importName = pkgDir(pkg);
-	const cb = new CodeBuilder("  ");
-	cb.line("[project]");
-	cb.line(`name = "${tomlStr(pyDistName(proj, pkg))}"`);
-	cb.line(`version = "${tomlStr(proj.version ?? "0.0.0")}"`);
-	cb.line(`description = "${tomlStr(description$1(pkg.doc, pkg.name))}"`);
-	cb.line(`readme = "README.md"`);
-	cb.line(`license = ${licenseField(proj)}`);
-	cb.line(`authors = ${authorsField(pkg.doc ?? proj.doc)}`);
-	cb.line(`requires-python = "${REQUIRES_PYTHON}"`);
-	cb.line("dependencies = [");
-	cb.line(`  "styxdefs${STYXDEFS_COMPAT.python}",`);
-	cb.line("]");
-	cb.blank();
-	cb.line("[tool.setuptools]");
-	cb.line(`packages = ["${importName}"]`);
-	cb.line(`package-dir = { "${importName}" = "." }`);
-	cb.blank();
-	cb.line("[tool.setuptools.package-data]");
-	cb.line(`"${importName}" = ["py.typed"]`);
-	cb.blank();
-	cb.line(BUILD_SYSTEM);
-	return cb.toString() + "\n";
-}
-/**
-* Root `pyproject.toml`: a metapackage depending on each per-suite distribution
-* plus the container/graph runner packages. `packages = []` keeps setuptools
-* from sweeping the sibling suite directories into this distribution.
-*/
-function generateRootPyproject(proj, distNames) {
-	const cb = new CodeBuilder("  ");
-	cb.line("[project]");
-	cb.line(`name = "${tomlStr(proj.name ?? "project")}"`);
-	cb.line(`version = "${tomlStr(proj.version ?? "0.0.0")}"`);
-	cb.line(`description = "${tomlStr(description$1(proj.doc, proj.name))}"`);
-	cb.line(`readme = "README.md"`);
-	cb.line(`license = ${licenseField(proj)}`);
-	cb.line(`authors = ${authorsField(proj.doc)}`);
-	cb.line(`requires-python = "${REQUIRES_PYTHON}"`);
-	cb.line("dependencies = [");
-	for (const dep of PYTHON_RUNNER_DEPS) cb.line(`  "${dep}",`);
-	for (const dist of distNames) cb.line(`  "${tomlStr(dist)}",`);
-	cb.line("]");
-	cb.blank();
-	cb.line("[tool.setuptools]");
-	cb.line("packages = []");
-	cb.blank();
-	cb.line(BUILD_SYSTEM);
-	return cb.toString() + "\n";
-}
-/** Per-suite README crediting the upstream tool authors. */
-function generateSubReadme(proj, pkg) {
-	const projectTitle = proj.doc?.title ?? proj.name ?? "Styx";
-	const packageTitle = pkg.doc?.title ?? pkg.name ?? "package";
-	const url = pkg.doc?.urls?.[0];
-	const titleMd = url ? `[${packageTitle}](${url})` : packageTitle;
-	const credits = pkg.doc?.authors?.length ? pkg.doc.authors.join(", ") : pkg.doc?.urls?.join(", ") ?? "unknown";
-	return `# ${projectTitle} wrappers for ${titleMd}${pkg.doc?.description ? `\n\n${pkg.doc.description}` : ""}\n\n${packageTitle} is made by ${credits}.\n\nThis package contains wrappers only and has no affiliation with the original authors.\n`;
-}
-/** Root README listing the bundled per-suite distributions. */
-function generateRootReadme(proj, distNames) {
-	return `# ${proj.doc?.title ?? proj.name ?? "Styx"}\n${proj.doc?.description ? `\n${proj.doc.description}\n` : ""}\nAuto-generated Styx wrappers. This project bundles the following packages:\n\n${distNames.map((d) => `- ${d}`).join("\n")}\n`;
-}
-/** Local-install manifest: each suite directory first, then the root metapackage. */
-function generateRequirementsTxt(pkgDirs) {
-	return [...pkgDirs.map((d) => `./${d}`), "./"].join("\n") + "\n";
-}
-
-//#endregion
-//#region src/backend/sig-entries.ts
-/**
-* Build per-field signature entries for the kwarg wrapper and params factory.
-* Skips `@type` (the factory injects it as a constant). Required-no-default
-* entries are placed before defaulted ones so the resulting signature is
-* syntactically valid in both Python and TS.
-*
-* `registerLocal` is called once per field with the wire key; it must return
-* a scrubbed, unique host identifier (typically by combining a language-aware
-* scrub function with `Scope.add()`). The caller's scope should already have
-* the function's other locals (`params`, `runner`, ...) reserved so this
-* registration cannot collide with them.
-*/
-function buildSigEntries(rootType, fieldInfo, registerLocal, opts) {
-	const entries = [];
-	for (const [fieldName, fieldType] of Object.entries(rootType.fields)) {
-		if (fieldType.kind === "literal") continue;
-		const fi = fieldInfo.get(fieldName);
-		const isOptional = fieldType.kind === "optional";
-		const inner = isOptional ? fieldType.inner : fieldType;
-		let sigType = opts.renderType(inner);
-		if (isOptional) sigType += opts.nullableSuffix;
-		let sigDefault;
-		const hasExplicitDefault = fi?.defaultValue !== void 0;
-		if (hasExplicitDefault) sigDefault = opts.renderDefault(fi.defaultValue);
-		else if (isOptional) sigDefault = opts.nullableDefault;
-		entries.push({
-			name: registerLocal(fieldName),
-			wireKey: fieldName,
-			sigType,
-			sigDefault,
-			isOptional,
-			hasExplicitDefault,
-			doc: fi?.doc
-		});
-	}
-	const required = entries.filter((e) => e.sigDefault === void 0);
-	const defaulted = entries.filter((e) => e.sigDefault !== void 0);
-	return [...required, ...defaulted];
-}
-
 //#endregion
 //#region src/backend/union-variants.ts
 /**
@@ -4345,54 +4155,452 @@ function emitParamsFactory$1(entries, funcName, paramsType, typeTag, cb) {
 	});
 }
 /**
-* Emit the user-facing kwarg wrapper: takes the same kwargs as `_params()`
-* plus `runner`, builds the params dict, and delegates to the dict-style
-* execute function.
+* Emit the user-facing kwarg wrapper: takes the same kwargs as `_params()`
+* plus `runner`, builds the params dict, and delegates to the dict-style
+* execute function.
+*/
+function emitKwargWrapper$1(ctx, entries, funcName, paramsFnName, executeFnName, outputsType, cb) {
+	cb.line(`def ${funcName}(`);
+	cb.indent(() => {
+		emitSigParams$1(entries, cb);
+		cb.line("runner: Runner | None = None,");
+	});
+	const returnType = outputsType ?? "None";
+	cb.line(`) -> ${returnType}:`);
+	cb.indent(() => {
+		const appDoc = ctx.app?.doc;
+		cb.line("\"\"\"");
+		if (appDoc?.title) cb.line(appDoc.title);
+		if (appDoc?.description) {
+			if (appDoc?.title) cb.blank();
+			cb.line(appDoc.description);
+		}
+		if (appDoc?.authors?.length) {
+			cb.blank();
+			cb.line(`Author: ${appDoc.authors.join(", ")}`);
+		}
+		if (appDoc?.urls?.length) {
+			cb.blank();
+			cb.line(`URL: ${appDoc.urls[0]}`);
+		}
+		cb.blank();
+		emitArgsBlock([...entries, {
+			name: "runner",
+			doc: "Command runner (defaults to global runner)."
+		}], cb);
+		cb.blank();
+		cb.line("Returns:");
+		cb.line(outputsType ? "    Tool outputs (paths to files produced by the tool)." : "    None.");
+		cb.line("\"\"\"");
+		if (entries.length === 0) cb.line(`params = ${paramsFnName}()`);
+		else {
+			cb.line(`params = ${paramsFnName}(`);
+			cb.indent(() => {
+				for (const e of entries) cb.line(`${e.name}=${e.name},`);
+			});
+			cb.line(")");
+		}
+		if (outputsType) cb.line(`return ${executeFnName}(params, runner)`);
+		else cb.line(`${executeFnName}(params, runner)`);
+	});
+}
+
+//#endregion
+//#region src/backend/nipype/emit.ts
+function call(ctor, args) {
+	return `${ctor}(${args.join(", ")})`;
+}
+/**
+* Render a numeric literal, forcing a float form (e.g. `0.0`) for a float field.
+* `traits.Range` infers its numeric type from the bound literals, so integer
+* bounds on a float field (e.g. `low=0, high=1`) would build an *integer* range
+* that rejects `0.5`. Emitting `0.0`/`1.0` keeps it a float range.
+*/
+function renderNum(value, asFloat) {
+	if (asFloat && typeof value === "number" && Number.isInteger(value)) return `${value}.0`;
+	return renderPyLiteral(value);
+}
+/** Human-readable `desc=` text: doc + degrade/media-type notes. */
+function descText(p) {
+	const parts = [];
+	if (p.doc) parts.push(p.doc);
+	if (p.kind === "struct" || p.kind === "union") parts.push("(nested configuration; pass a dict)");
+	if (p.mediaTypes && p.mediaTypes.length > 0) parts.push(`(media types: ${p.mediaTypes.join(", ")})`);
+	return parts.length > 0 ? parts.join(" ") : void 0;
+}
+/** Map a list element descriptor to a (bare) nipype inner trait. */
+function renderItemTrait(item) {
+	if (!item) return "traits.Any()";
+	switch (item.kind) {
+		case "path": return "File(exists=True)";
+		case "int":
+		case "count": return "traits.Int()";
+		case "float": return "traits.Float()";
+		case "str": return "traits.Str()";
+		case "bool": return "traits.Bool()";
+		case "enum": return call("traits.Enum", (item.choices ?? []).map((c) => renderPyLiteral(c)));
+		default: return "traits.Any()";
+	}
+}
+/** Map a parameter to its nipype input trait expression, carrying rich constraints. */
+function renderInputTrait(p) {
+	const tail = [];
+	if (p.mandatory) tail.push("mandatory=True");
+	const desc = descText(p);
+	if (desc) tail.push(`desc=${pyStr(desc)}`);
+	const hasDef = p.hasDefault && p.default !== void 0;
+	const def = p.default;
+	switch (p.kind) {
+		case "path": return call("File", ["exists=True", ...tail]);
+		case "bool": return call("traits.Bool", [...hasDef ? [renderPyLiteral(def), "usedefault=True"] : [], ...tail]);
+		case "count": return call("traits.Int", [...hasDef ? [renderPyLiteral(def), "usedefault=True"] : [], ...tail]);
+		case "int":
+		case "float": {
+			const asFloat = p.kind === "float";
+			if (p.range) {
+				const a = [];
+				if (hasDef) a.push(`value=${renderNum(def, asFloat)}`);
+				if (p.range.min !== void 0) a.push(`low=${renderNum(p.range.min, asFloat)}`);
+				if (p.range.max !== void 0) a.push(`high=${renderNum(p.range.max, asFloat)}`);
+				if (hasDef) a.push("usedefault=True");
+				return call("traits.Range", [...a, ...tail]);
+			}
+			return call(p.kind === "int" ? "traits.Int" : "traits.Float", [...hasDef ? [renderNum(def, asFloat), "usedefault=True"] : [], ...tail]);
+		}
+		case "str": return call("traits.Str", [...hasDef ? [renderPyLiteral(def), "usedefault=True"] : [], ...tail]);
+		case "enum": {
+			const choices = p.choices ?? [];
+			return call("traits.Enum", [
+				...(hasDef ? [def, ...choices.filter((c) => c !== def)] : choices).map((c) => renderPyLiteral(c)),
+				...hasDef ? ["usedefault=True"] : [],
+				...tail
+			]);
+		}
+		case "list": {
+			const inner = renderItemTrait(p.itemType);
+			const bounds = [];
+			if (p.listBounds?.min !== void 0) bounds.push(`minlen=${p.listBounds.min}`);
+			if (p.listBounds?.max !== void 0) bounds.push(`maxlen=${p.listBounds.max}`);
+			return call("traits.List", [
+				inner,
+				...bounds,
+				...tail
+			]);
+		}
+		case "struct":
+		case "union": return call("traits.Any", tail);
+	}
+}
+/**
+* Map an output field to its nipype output trait expression. `isRoot` is the
+* synthetic output directory, typed as a `Directory` rather than a `File`.
+*/
+function renderOutputTrait(f, isRoot) {
+	const tail = f.doc ? [`desc=${pyStr(f.doc)}`] : [];
+	if (f.shape.kind === "list") return call("traits.List", ["File()", ...tail]);
+	if (isRoot) return call("Directory", tail);
+	return call("File", tail);
+}
+/**
+* Emit the nipype interface module for one tool: a typed InputSpec/OutputSpec and
+* a BaseInterface that delegates execution to the co-emitted styx Python wrapper.
+*/
+function emitNipypeInterface(ctx, spec, names) {
+	const cb = new CodeBuilder("    ");
+	cb.comment("This file was auto generated by Styx.", "# ");
+	cb.comment("Do not edit this file directly.", "# ");
+	cb.blank();
+	cb.line("from nipype.interfaces.base import (");
+	cb.indent(() => {
+		cb.line("BaseInterface,");
+		cb.line("BaseInterfaceInputSpec,");
+		cb.line("Directory,");
+		cb.line("File,");
+		cb.line("TraitedSpec,");
+		cb.line("isdefined,");
+		cb.line("traits,");
+	});
+	cb.line(")");
+	cb.blank();
+	cb.line(`from .${names.styxStem} import ${spec.delegation.wrapperFn}, ${spec.delegation.outputsClass}`);
+	cb.blank();
+	cb.blank();
+	cb.line(`class ${names.inputSpec}(BaseInterfaceInputSpec):`);
+	cb.indent(() => {
+		if (!spec.rootIsStruct || spec.params.length === 0) {
+			cb.line("pass");
+			return;
+		}
+		for (const p of spec.params) cb.line(`${p.hostName} = ${renderInputTrait(p)}`);
+	});
+	cb.blank();
+	cb.blank();
+	cb.line(`class ${names.outputSpec}(TraitedSpec):`);
+	cb.indent(() => {
+		if (spec.outputs.length === 0 && spec.streams.length === 0) {
+			cb.line("pass");
+			return;
+		}
+		spec.outputs.forEach((f, i) => cb.line(`${f.id} = ${renderOutputTrait(f, i === 0)}`));
+		for (const s of spec.streams) {
+			const tail = s.doc ? `, desc=${pyStr(s.doc)}` : "";
+			cb.line(`${s.id} = traits.List(traits.Str()${tail})`);
+		}
+	});
+	cb.blank();
+	cb.blank();
+	cb.line(`class ${names.cls}(BaseInterface):`);
+	cb.indent(() => {
+		emitDocstring(cb, [ctx.app?.doc?.title, ctx.app?.doc?.description].filter(Boolean).join("\n\n") || void 0);
+		cb.line(`input_spec = ${names.inputSpec}`);
+		cb.line(`output_spec = ${names.outputSpec}`);
+		cb.blank();
+		cb.line("def _run_interface(self, runtime):");
+		cb.indent(() => {
+			if (!spec.rootIsStruct) {
+				cb.line("raise NotImplementedError(");
+				cb.indent(() => cb.line(pyStr("styx nipype backend: tools with a non-struct root are not supported.")));
+				cb.line(")");
+				return;
+			}
+			cb.line("kwargs = {}");
+			for (const p of spec.params) if (p.mandatory) cb.line(`kwargs[${pyStr(p.hostName)}] = self.inputs.${p.hostName}`);
+			else {
+				cb.line(`if isdefined(self.inputs.${p.hostName}):`);
+				cb.indent(() => cb.line(`kwargs[${pyStr(p.hostName)}] = self.inputs.${p.hostName}`));
+			}
+			cb.line(`self._result: ${spec.delegation.outputsClass} = ${spec.delegation.wrapperFn}(**kwargs)`);
+			cb.line("return runtime");
+		});
+		cb.blank();
+		cb.line("def _list_outputs(self):");
+		cb.indent(() => {
+			if (!spec.rootIsStruct) {
+				cb.line("return self._outputs().get()");
+				return;
+			}
+			cb.line("result = self._result");
+			cb.line("outputs = self._outputs().get()");
+			for (const f of spec.outputs) if (f.shape.kind === "single" && f.shape.optional) {
+				cb.line(`if result.${f.id} is not None:`);
+				cb.indent(() => cb.line(`outputs[${pyStr(f.id)}] = result.${f.id}`));
+			} else cb.line(`outputs[${pyStr(f.id)}] = result.${f.id}`);
+			for (const s of spec.streams) cb.line(`outputs[${pyStr(s.id)}] = result.${s.id}`);
+			cb.line("return outputs");
+		});
+	});
+	return cb.toString();
+}
+
+//#endregion
+//#region src/backend/styxdefs-compat.ts
+/**
+* Runtime version floors baked into generated dependency metadata.
+*
+* styx2-generated code calls `mutable_copy` / `mutableCopy` (introduced in the
+* styxdefs 0.7.0 / styxdefs-js 0.2.0 release), so emitted packages genuinely
+* require that runtime floor. This is the single source of truth: bump here and
+* both the Python and TypeScript backends pick it up.
+*/
+const STYXDEFS_COMPAT = {
+	python: ">=0.7.0,<0.8.0",
+	npm: "^0.2.0"
+};
+/**
+* Extra Python runtime packages the root metapackage pulls in. `styxkit[all]`
+* provides the cross-backend runner-selection helpers (`use_docker`, `use_auto`,
+* ...) that the metapackage's `__init__` re-exports, and transitively installs
+* every container/graph runner backend. Left unpinned - styxkit's own styxdefs
+* floor constrains the stack.
+*/
+const PYTHON_RUNNER_DEPS = ["styxkit[all]"];
+
+//#endregion
+//#region src/backend/python/packaging.ts
+const REQUIRES_PYTHON = ">=3.10";
+const BUILD_SYSTEM = `[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"`;
+/** Escape a value for embedding in a TOML basic string. */
+function tomlStr(s) {
+	return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/[\r\n]+/g, " ").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "").trim();
+}
+/** Suite directory / importable package name; matches the CLI's `pkgDir` fallback. */
+function pkgDir(pkg) {
+	return pkg.name ?? "package";
+}
+/** Distribution (PyPI) name for a package: `<project>_<package>`, or just `<package>`. */
+function pyDistName(proj, pkg) {
+	const name = pkgDir(pkg);
+	return proj.name ? `${proj.name}_${name}` : name;
+}
+const SUMMARY_MAX_LEN = 512;
+/**
+* Clamp a description to a <=512-char one-line summary. Prefer cutting at the
+* last complete sentence that fits (clean, no dangling fragment); if there is no
+* sentence boundary early enough, cut at a word boundary and mark the elision.
+*/
+function clampSummary(s) {
+	if (s.length <= SUMMARY_MAX_LEN) return s;
+	const window = s.slice(0, SUMMARY_MAX_LEN);
+	const lastSentence = window.lastIndexOf(". ");
+	if (lastSentence >= 0) return s.slice(0, lastSentence + 1);
+	const ellipsis = "...";
+	const body = window.slice(0, SUMMARY_MAX_LEN - 3);
+	const lastSpace = body.lastIndexOf(" ");
+	return (lastSpace > 0 ? body.slice(0, lastSpace) : body).replace(/[.,;:\s]+$/, "") + ellipsis;
+}
+function description$1(doc, fallbackName) {
+	return clampSummary(doc?.description ?? `Styx generated wrappers for ${doc?.title ?? fallbackName ?? "tools"}.`);
+}
+function authorsField(doc) {
+	return `[${(doc?.authors?.length ? doc.authors : ["unknown"]).map((a) => `{ name = "${tomlStr(a)}" }`).join(", ")}]`;
+}
+function licenseField(proj) {
+	return `{ text = "${tomlStr(proj.license?.description ?? "unknown")}" }`;
+}
+/**
+* Per-suite `pyproject.toml`. The suite source stays in a flat directory
+* (`python/<pkg>/bet.py`), but setuptools' `package-dir` maps that directory onto
+* the dotted import package `<project>.<pkg>`, so every suite nests under the
+* metapackage's `<project>/` namespace. That restores `from <project> import
+* <pkg>` while keeping each suite a separately-installable distribution (and
+* leaves no top-level `<pkg>` polluting the global namespace). With no project
+* name the import name is the bare `<pkg>` (top-level fallback). The styxdefs
+* floor is the only runtime dependency.
+*
+* Precondition: `importName` is a valid (possibly dotted) Python package path -
+* the caller scrubs the project + package names into identifiers accordingly.
+*/
+function generateSubPyproject(proj, pkg, importName) {
+	const cb = new CodeBuilder("  ");
+	cb.line("[project]");
+	cb.line(`name = "${tomlStr(pyDistName(proj, pkg))}"`);
+	cb.line(`version = "${tomlStr(proj.version ?? "0.0.0")}"`);
+	cb.line(`description = "${tomlStr(description$1(pkg.doc, pkg.name))}"`);
+	cb.line(`readme = "README.md"`);
+	cb.line(`license = ${licenseField(proj)}`);
+	cb.line(`authors = ${authorsField(pkg.doc ?? proj.doc)}`);
+	cb.line(`requires-python = "${REQUIRES_PYTHON}"`);
+	cb.line("dependencies = [");
+	cb.line(`  "styxdefs${STYXDEFS_COMPAT.python}",`);
+	cb.line("]");
+	cb.blank();
+	cb.line("[tool.setuptools]");
+	cb.line(`packages = ["${importName}"]`);
+	cb.line(`package-dir = { "${importName}" = "." }`);
+	cb.blank();
+	cb.line("[tool.setuptools.package-data]");
+	cb.line(`"${importName}" = ["py.typed"]`);
+	cb.blank();
+	cb.line(BUILD_SYSTEM);
+	return cb.toString() + "\n";
+}
+/**
+* The metapackage's `__init__.py`. A thin re-export of styxkit so the runner
+* configuration helpers (`use_docker`, `use_local`, `set_global_runner`, ...)
+* are reachable as `<project>.<name>` - the v1 ergonomic that the v2 split into
+* per-suite distributions otherwise dropped. The logic lives in styxkit (pulled
+* in via `styxkit[all]`), so this stays a wildcard re-export and never re-emits
+* the runner-config code itself.
+*/
+function generateRootInitPy() {
+	return "# This file was auto generated by Styx.\n# Do not edit this file directly.\n\n# Re-export styxkit's runner-configuration helpers (use_docker, use_local,\n# use_auto, set_global_runner, get_global_runner, ...) so they are available\n# directly on this package, e.g. `import niwrap; niwrap.use_docker()`.\nfrom styxkit import *  # noqa: F401,F403\n";
+}
+/**
+* Root `pyproject.toml`: a metapackage depending on `styxkit[all]` (the runner
+* stack it re-exports) plus each per-suite distribution. `packages` lists only
+* the metapackage's own module so setuptools ships the styxkit re-export without
+* sweeping the sibling suite directories into this distribution. The module is
+* the `<project>/` namespace package the suites nest into, so installing the
+* metapackage makes `<project>.use_docker()` reachable alongside the suites'
+* `from <project> import <pkg>`. `moduleDir` is the on-disk source directory; it
+* differs from the import `moduleName` only when a suite is named after the
+* project, in which case a `package-dir` remap keeps the import name intact.
+*/
+function generateRootPyproject(proj, distNames, moduleName, moduleDir) {
+	const cb = new CodeBuilder("  ");
+	cb.line("[project]");
+	cb.line(`name = "${tomlStr(proj.name ?? "project")}"`);
+	cb.line(`version = "${tomlStr(proj.version ?? "0.0.0")}"`);
+	cb.line(`description = "${tomlStr(description$1(proj.doc, proj.name))}"`);
+	cb.line(`readme = "README.md"`);
+	cb.line(`license = ${licenseField(proj)}`);
+	cb.line(`authors = ${authorsField(proj.doc)}`);
+	cb.line(`requires-python = "${REQUIRES_PYTHON}"`);
+	cb.line("dependencies = [");
+	for (const dep of PYTHON_RUNNER_DEPS) cb.line(`  "${dep}",`);
+	for (const dist of distNames) cb.line(`  "${tomlStr(dist)}",`);
+	cb.line("]");
+	cb.blank();
+	cb.line("[tool.setuptools]");
+	cb.line(`packages = ["${moduleName}"]`);
+	if (moduleDir !== moduleName) cb.line(`package-dir = { "${moduleName}" = "${moduleDir}" }`);
+	cb.blank();
+	cb.line("[tool.setuptools.package-data]");
+	cb.line(`"${moduleName}" = ["py.typed"]`);
+	cb.blank();
+	cb.line(BUILD_SYSTEM);
+	return cb.toString() + "\n";
+}
+/** Per-suite README crediting the upstream tool authors. */
+function generateSubReadme(proj, pkg) {
+	const projectTitle = proj.doc?.title ?? proj.name ?? "Styx";
+	const packageTitle = pkg.doc?.title ?? pkg.name ?? "package";
+	const url = pkg.doc?.urls?.[0];
+	const titleMd = url ? `[${packageTitle}](${url})` : packageTitle;
+	const credits = pkg.doc?.authors?.length ? pkg.doc.authors.join(", ") : pkg.doc?.urls?.join(", ") ?? "unknown";
+	return `# ${projectTitle} wrappers for ${titleMd}${pkg.doc?.description ? `\n\n${pkg.doc.description}` : ""}\n\n${packageTitle} is made by ${credits}.\n\nThis package contains wrappers only and has no affiliation with the original authors.\n`;
+}
+/** Root README listing the bundled per-suite distributions. */
+function generateRootReadme(proj, distNames) {
+	return `# ${proj.doc?.title ?? proj.name ?? "Styx"}\n${proj.doc?.description ? `\n${proj.doc.description}\n` : ""}\nAuto-generated Styx wrappers. This project bundles the following packages:\n\n${distNames.map((d) => `- ${d}`).join("\n")}\n`;
+}
+/** Local-install manifest: each suite directory first, then the root metapackage. */
+function generateRequirementsTxt(pkgDirs) {
+	return [...pkgDirs.map((d) => `./${d}`), "./"].join("\n") + "\n";
+}
+
+//#endregion
+//#region src/backend/sig-entries.ts
+/**
+* Build per-field signature entries for the kwarg wrapper and params factory.
+* Skips `@type` (the factory injects it as a constant). Required-no-default
+* entries are placed before defaulted ones so the resulting signature is
+* syntactically valid in both Python and TS.
+*
+* `registerLocal` is called once per field with the wire key; it must return
+* a scrubbed, unique host identifier (typically by combining a language-aware
+* scrub function with `Scope.add()`). The caller's scope should already have
+* the function's other locals (`params`, `runner`, ...) reserved so this
+* registration cannot collide with them.
 */
-function emitKwargWrapper$1(ctx, entries, funcName, paramsFnName, executeFnName, outputsType, cb) {
-	cb.line(`def ${funcName}(`);
-	cb.indent(() => {
-		emitSigParams$1(entries, cb);
-		cb.line("runner: Runner | None = None,");
-	});
-	const returnType = outputsType ?? "None";
-	cb.line(`) -> ${returnType}:`);
-	cb.indent(() => {
-		const appDoc = ctx.app?.doc;
-		cb.line("\"\"\"");
-		if (appDoc?.title) cb.line(appDoc.title);
-		if (appDoc?.description) {
-			if (appDoc?.title) cb.blank();
-			cb.line(appDoc.description);
-		}
-		if (appDoc?.authors?.length) {
-			cb.blank();
-			cb.line(`Author: ${appDoc.authors.join(", ")}`);
-		}
-		if (appDoc?.urls?.length) {
-			cb.blank();
-			cb.line(`URL: ${appDoc.urls[0]}`);
-		}
-		cb.blank();
-		emitArgsBlock([...entries, {
-			name: "runner",
-			doc: "Command runner (defaults to global runner)."
-		}], cb);
-		cb.blank();
-		cb.line("Returns:");
-		cb.line(outputsType ? "    Tool outputs (paths to files produced by the tool)." : "    None.");
-		cb.line("\"\"\"");
-		if (entries.length === 0) cb.line(`params = ${paramsFnName}()`);
-		else {
-			cb.line(`params = ${paramsFnName}(`);
-			cb.indent(() => {
-				for (const e of entries) cb.line(`${e.name}=${e.name},`);
-			});
-			cb.line(")");
-		}
-		if (outputsType) cb.line(`return ${executeFnName}(params, runner)`);
-		else cb.line(`${executeFnName}(params, runner)`);
-	});
+function buildSigEntries(rootType, fieldInfo, registerLocal, opts) {
+	const entries = [];
+	for (const [fieldName, fieldType] of Object.entries(rootType.fields)) {
+		if (fieldType.kind === "literal") continue;
+		const fi = fieldInfo.get(fieldName);
+		const isOptional = fieldType.kind === "optional";
+		const inner = isOptional ? fieldType.inner : fieldType;
+		let sigType = opts.renderType(inner);
+		if (isOptional) sigType += opts.nullableSuffix;
+		let sigDefault;
+		const hasExplicitDefault = fi?.defaultValue !== void 0;
+		if (hasExplicitDefault) sigDefault = opts.renderDefault(fi.defaultValue);
+		else if (isOptional) sigDefault = opts.nullableDefault;
+		entries.push({
+			name: registerLocal(fieldName),
+			wireKey: fieldName,
+			sigType,
+			sigDefault,
+			isOptional,
+			hasExplicitDefault,
+			doc: fi?.doc
+		});
+	}
+	const required = entries.filter((e) => e.sigDefault === void 0);
+	const defaulted = entries.filter((e) => e.sigDefault !== void 0);
+	return [...required, ...defaulted];
 }
 
 //#endregion
@@ -5156,7 +5364,7 @@ function computePublicNames$1(appId) {
 * (the `reg` registrations and the `sigScope` child), so passing the same scope
 * the emitter continues with keeps later local registrations consistent.
 */
-function buildEmitModel$1(ctx, scope = new Scope(PY_RESERVED)) {
+function buildEmitModel(ctx, scope = new Scope(PY_RESERVED)) {
 	const appId = ctx.app?.id;
 	const pkg = ctx.package?.name;
 	const publicNames = computePublicNames$1(appId);
@@ -5199,7 +5407,7 @@ function buildEmitModel$1(ctx, scope = new Scope(PY_RESERVED)) {
 function generatePython(ctx, packageScope) {
 	const cb = new CodeBuilder("    ");
 	const scope = packageScope ?? new Scope(PY_RESERVED);
-	const { names, rootType, rootIsStruct, namedTypes, typeDecls, rootTypeTag, paramsType, sigEntries } = buildEmitModel$1(ctx, scope);
+	const { names, rootType, rootIsStruct, namedTypes, typeDecls, rootTypeTag, paramsType, sigEntries } = buildEmitModel(ctx, scope);
 	cb.comment("This file was auto generated by Styx.", "# ");
 	cb.comment("Do not edit this file directly.", "# ");
 	cb.blank();
@@ -5346,21 +5554,33 @@ var PythonBackend = class {
 		const files = /* @__PURE__ */ new Map();
 		const distNames = [];
 		const pkgDirs = [];
+		const warnings = [];
+		const nsName = proj.name && proj.name.trim() ? pyScrubIdent(proj.name, PY_RESERVED) : void 0;
 		for (const p of packages) {
 			const pkg = p.meta ?? {};
 			const dir = pkg.name ?? "package";
 			pkgDirs.push(dir);
 			distNames.push(pyDistName(proj, pkg));
-			files.set(`${dir}/pyproject.toml`, generateSubPyproject(proj, pkg));
+			const importPkg = nsName ? `${nsName}.${dir}` : dir;
+			files.set(`${dir}/pyproject.toml`, generateSubPyproject(proj, pkg, importPkg));
 			files.set(`${dir}/README.md`, generateSubReadme(proj, pkg));
 		}
-		files.set("pyproject.toml", generateRootPyproject(proj, distNames));
+		const metaImport = nsName ?? "project";
+		let metaDir = metaImport;
+		if (pkgDirs.includes(metaDir)) {
+			const collided = metaDir;
+			while (pkgDirs.includes(metaDir)) metaDir += "_";
+			warnings.push({ message: `metapackage directory "${collided}" collides with a suite directory; emitting its sources in "${metaDir}" instead (import name stays "${metaImport}")` });
+		}
+		files.set(`${metaDir}/__init__.py`, generateRootInitPy());
+		files.set(`${metaDir}/py.typed`, "");
+		files.set("pyproject.toml", generateRootPyproject(proj, distNames, metaImport, metaDir));
 		files.set("README.md", generateRootReadme(proj, distNames));
 		files.set("requirements.txt", generateRequirementsTxt(pkgDirs));
 		return {
 			files,
 			errors: [],
-			warnings: []
+			warnings
 		};
 	}
 };
@@ -5506,7 +5726,7 @@ const pyDialect = {
 * @param opts - Import and package-root options.
 */
 function renderPythonCall(ctx, config, opts = {}) {
-	const model = buildEmitModel$1(ctx);
+	const model = buildEmitModel(ctx);
 	const pkg = ctx.package?.name;
 	const callee = pkg ? `${pkg}.${model.names.wrapper}` : model.names.wrapper;
 	const call = model.rootIsStruct && model.rootType.kind === "struct" ? renderKwargCall(callee, model.sigEntries, model.rootType, config) : `${callee}(${renderValue(config, model.rootType, "", pyDialect)})`;
@@ -5529,6 +5749,495 @@ function renderKwargCall(callee, sigEntries, rootType, config) {
 	return `${callee}(\n${lines.join("\n")}\n)`;
 }
 
+//#endregion
+//#region src/backend/typed-spec.ts
+/** Project a tool's solved tree into the flat typed spec for delegation backends. */
+function buildTypedSpec(ctx) {
+	const model = buildEmitModel(ctx);
+	const delegation = {
+		moduleName: appModuleName$1(ctx.app),
+		wrapperFn: model.names.wrapper,
+		outputsClass: model.names.outputs
+	};
+	const outputs = collectOutputFields(ctx, pyId);
+	const streams = streamFields(ctx, pyId);
+	if (!model.rootIsStruct || model.rootType.kind !== "struct") return {
+		rootIsStruct: false,
+		params: [],
+		outputs,
+		streams,
+		delegation
+	};
+	const rootType = model.rootType;
+	const fieldByName = new Map(structFields(ctx, rootType, ctx.expr).map((f) => [f.name, f]));
+	const fieldInfo = collectFieldInfo(ctx, rootType);
+	return {
+		rootIsStruct: true,
+		params: model.sigEntries.map((e) => {
+			const fe = fieldByName.get(e.wireKey);
+			const fi = fieldInfo.get(e.wireKey);
+			return describeParam(e, fe?.type, fe?.node, fi?.defaultValue, fi?.doc);
+		}),
+		outputs,
+		streams,
+		delegation
+	};
+}
+function describeParam(e, type, node, defaultValue, fallbackDoc) {
+	const optional = e.isOptional;
+	const hasDefault = e.hasExplicitDefault;
+	const base = {
+		hostName: e.name,
+		wireKey: e.wireKey,
+		optional,
+		hasDefault,
+		mandatory: !optional && !hasDefault,
+		default: defaultValue,
+		doc: e.doc ?? fallbackDoc
+	};
+	const inner = type && type.kind === "optional" ? type.inner : type;
+	const choices = inner ? literalChoices(inner, node) : void 0;
+	if (choices) return {
+		...base,
+		kind: "enum",
+		choices
+	};
+	switch (inner?.kind) {
+		case "scalar":
+			if (inner.scalar === "path") return {
+				...base,
+				kind: "path",
+				scalarKind: "path",
+				mediaTypes: pathMediaTypes(node)
+			};
+			if (inner.scalar === "int" || inner.scalar === "float") return {
+				...base,
+				kind: inner.scalar,
+				scalarKind: inner.scalar,
+				range: numericRange(node)
+			};
+			return {
+				...base,
+				kind: "str",
+				scalarKind: "str"
+			};
+		case "bool": return {
+			...base,
+			kind: "bool"
+		};
+		case "count": return {
+			...base,
+			kind: "count"
+		};
+		case "list": return {
+			...base,
+			kind: "list",
+			listBounds: listBounds(node),
+			itemType: describeItem(inner.item, node)
+		};
+		case "struct": return {
+			...base,
+			kind: "struct"
+		};
+		case "union": return {
+			...base,
+			kind: "union"
+		};
+		default: return {
+			...base,
+			kind: "str"
+		};
+	}
+}
+function describeItem(item, node) {
+	const inner = item.kind === "optional" ? item.inner : item;
+	const choices = literalChoices(inner, node);
+	if (choices) return {
+		kind: "enum",
+		choices
+	};
+	switch (inner.kind) {
+		case "scalar":
+			if (inner.scalar === "path") return {
+				kind: "path",
+				scalarKind: "path",
+				mediaTypes: pathMediaTypes(node)
+			};
+			return {
+				kind: inner.scalar,
+				scalarKind: inner.scalar
+			};
+		case "bool": return { kind: "bool" };
+		case "count": return { kind: "count" };
+		case "struct": return { kind: "struct" };
+		case "union": return { kind: "union" };
+		default: return { kind: "str" };
+	}
+}
+/** Allowed values when `inner` is a literal or a union of literals (else undefined). */
+function literalChoices(inner, node) {
+	if (inner.kind === "literal") return [inner.value];
+	if (inner.kind === "union" && inner.variants.length > 0 && inner.variants.every((v) => v.type.kind === "literal")) return inner.variants.map((v) => v.type.value);
+	const altNode = node ? findNode(node, (n) => n.kind === "alternative") : void 0;
+	if (altNode && altNode.kind === "alternative") {
+		const alts = altNode.attrs.alts;
+		if (alts.length > 0 && alts.every((a) => a.kind === "literal")) return alts.map((a) => a.attrs.str);
+	}
+}
+function numericRange(node) {
+	const r = findRangeNode(node);
+	if (!r) return void 0;
+	const { minValue, maxValue } = r.attrs;
+	if (minValue === void 0 && maxValue === void 0) return void 0;
+	return {
+		min: minValue,
+		max: maxValue
+	};
+}
+function listBounds(node) {
+	const r = findRepeatNode(node);
+	if (!r) return void 0;
+	const { countMin, countMax } = r.attrs;
+	if (countMin === void 0 && countMax === void 0) return void 0;
+	return {
+		min: countMin,
+		max: countMax
+	};
+}
+function pathMediaTypes(node) {
+	const p = node ? findNode(node, (n) => n.kind === "path") : void 0;
+	if (p && p.kind === "path") {
+		const mt = p.attrs.mediaTypes;
+		if (mt && mt.length > 0) return mt;
+	}
+}
+
+//#endregion
+//#region src/backend/nipype/nipype.ts
+/** Derive the per-tool nipype module/class names. */
+function nipypeNames(ctx) {
+	const mod = appModuleName$1(ctx.app);
+	const rawId = ctx.app?.id ?? "tool";
+	const cls = pascalCase(/^[0-9]/.test(rawId) ? "v_" + rawId : rawId);
+	return {
+		styxStem: `_${mod}`,
+		ifaceStem: mod,
+		cls,
+		inputSpec: `${cls}InputSpec`,
+		outputSpec: `${cls}OutputSpec`
+	};
+}
+/** Generate the nipype interface module source for one tool. */
+function generateNipype(ctx) {
+	return emitNipypeInterface(ctx, buildTypedSpec(ctx), nipypeNames(ctx));
+}
+/**
+* Emits nipype `Interface` definitions whose typed InputSpec/OutputSpec carry
+* rich constraints (numeric ranges, list bounds, enum choices, file types) and
+* which delegate execution to the styx Python wrapper (Option B): no command-line
+* arg-building or output-path resolution is re-implemented here.
+*
+* Per tool, two co-located files are emitted so the output is a self-contained,
+* importable Python package: `_<tool>.py` (the styx Python module) and
+* `<tool>.py` (the interface, importing the wrapper via a relative import).
+*/
+var NipypeBackend = class {
+	name = "nipype";
+	target = "nipype";
+	emitApp(ctx, _scope) {
+		const names = nipypeNames(ctx);
+		const spec = buildTypedSpec(ctx);
+		const warnings = [];
+		if (!spec.rootIsStruct) warnings.push({ message: `nipype: '${ctx.app?.id ?? "?"}' has a non-struct root; emitted interface has no typed inputs and raises on run.` });
+		const styxCode = generatePython(ctx);
+		const ifaceCode = emitNipypeInterface(ctx, spec, names);
+		return {
+			meta: ctx.app,
+			files: new Map([[`${names.styxStem}.py`, styxCode], [`${names.ifaceStem}.py`, ifaceCode]]),
+			errors: [],
+			warnings
+		};
+	}
+};
+
+//#endregion
+//#region src/backend/pydra/emit.ts
+/** A scalar enum's Python type: int when every choice is numeric, else str. */
+function enumScalar(choices) {
+	return (choices ?? []).every((c) => typeof c === "number") ? "int" : "str";
+}
+/** True when a parameter is a file path (a path scalar or a list of paths). */
+function isPathParam(p) {
+	return p.kind === "path" || p.kind === "list" && p.itemType?.kind === "path";
+}
+function itemTypeStr(item, imp) {
+	if (!item) {
+		imp.typing = true;
+		return "ty.Any";
+	}
+	switch (item.kind) {
+		case "path":
+			imp.file = true;
+			return "File";
+		case "int":
+		case "count": return "int";
+		case "float": return "float";
+		case "str": return "str";
+		case "bool": return "bool";
+		case "enum": return enumScalar(item.choices);
+		default:
+			imp.typing = true;
+			return "ty.Any";
+	}
+}
+/** Base (non-optional) Python type expression for a parameter. */
+function baseType(p, imp) {
+	switch (p.kind) {
+		case "path":
+			imp.file = true;
+			return "File";
+		case "int":
+		case "count": return "int";
+		case "float": return "float";
+		case "str": return "str";
+		case "bool": return "bool";
+		case "enum": return enumScalar(p.choices);
+		case "list": return `list[${itemTypeStr(p.itemType, imp)}]`;
+		case "struct":
+		case "union":
+			imp.typing = true;
+			return "ty.Any";
+	}
+}
+/** Full input type, wrapping in `ty.Optional[...]` for an omittable-no-default field. */
+function inputType(p, imp) {
+	const base = baseType(p, imp);
+	if (p.optional && !p.hasDefault) {
+		imp.typing = true;
+		return `ty.Optional[${base}]`;
+	}
+	return base;
+}
+/** An attrs validator enforcing numeric range / list-length bounds, or undefined. */
+function validatorExpr(p, imp) {
+	const checks = [];
+	if (p.range) {
+		if (p.range.min !== void 0) checks.push(`attrs.validators.ge(${renderPyLiteral(p.range.min)})`);
+		if (p.range.max !== void 0) checks.push(`attrs.validators.le(${renderPyLiteral(p.range.max)})`);
+	}
+	if (p.listBounds) {
+		if (p.listBounds.min !== void 0) checks.push(`attrs.validators.min_len(${p.listBounds.min})`);
+		if (p.listBounds.max !== void 0) checks.push(`attrs.validators.max_len(${p.listBounds.max})`);
+	}
+	if (checks.length === 0) return void 0;
+	imp.attrs = true;
+	return `_styx_optional(${checks.length === 1 ? checks[0] : `attrs.validators.and_(${checks.join(", ")})`})`;
+}
+/** Help text: doc + degrade / media-type notes. */
+function helpText(p) {
+	const parts = [];
+	if (p.doc) parts.push(p.doc);
+	if (p.kind === "struct" || p.kind === "union") parts.push("(nested configuration; pass a dict)");
+	if (p.mediaTypes && p.mediaTypes.length > 0) parts.push(`(media types: ${p.mediaTypes.join(", ")})`);
+	return parts.length > 0 ? parts.join(" ") : void 0;
+}
+/** Render a `python.arg(...)` field for one parameter. */
+function renderInputArg(p, imp) {
+	const args = [`type=${inputType(p, imp)}`];
+	if (p.mandatory) {} else if (p.optional && !p.hasDefault) args.push("default=None");
+	else args.push(`default=${renderPyLiteral(p.default)}`);
+	if (p.kind === "enum") args.push(`allowed_values=[${(p.choices ?? []).map((c) => renderPyLiteral(c)).join(", ")}]`);
+	const v = validatorExpr(p, imp);
+	if (v) args.push(`validator=${v}`);
+	const h = helpText(p);
+	if (h) args.push(`help=${pyStr(h)}`);
+	return `python.arg(${args.join(", ")})`;
+}
+/** Python type for an output field. `isRoot` is the synthetic output directory. */
+function outputType(f, isRoot, imp) {
+	if (f.shape.kind === "list") {
+		imp.file = true;
+		return "list[File]";
+	}
+	if (isRoot) {
+		imp.directory = true;
+		return "Directory";
+	}
+	imp.file = true;
+	if (f.shape.optional) {
+		imp.typing = true;
+		return "ty.Optional[File]";
+	}
+	return "File";
+}
+function renderOutputArg(f, isRoot, imp) {
+	const args = [`type=${outputType(f, isRoot, imp)}`];
+	if (f.doc) args.push(`help=${pyStr(f.doc)}`);
+	return `python.out(${args.join(", ")})`;
+}
+/**
+* Emit the pydra task module for one tool: a `@python.define` task whose typed
+* inputs/outputs carry rich constraints and whose body delegates execution to the
+* co-emitted styx Python wrapper (Option B). Targets the post-rewrite
+* `pydra.compose` API (pydra >= 1.0a, Python >= 3.11).
+*/
+function emitPydraTask(ctx, spec, names) {
+	const imp = {
+		typing: false,
+		attrs: false,
+		file: false,
+		directory: false
+	};
+	const inputEntries = spec.params.map((p) => ({
+		key: p.hostName,
+		expr: renderInputArg(p, imp)
+	}));
+	const outputEntries = spec.outputs.map((f, i) => ({
+		key: f.id,
+		expr: renderOutputArg(f, i === 0, imp)
+	}));
+	for (const s of spec.streams) outputEntries.push({
+		key: s.id,
+		expr: `python.out(type=list[str]${s.doc ? `, help=${pyStr(s.doc)}` : ""})`
+	});
+	const needsPath = spec.params.some(isPathParam);
+	const cb = new CodeBuilder("    ");
+	cb.comment("This file was auto generated by Styx.", "# ");
+	cb.comment("Do not edit this file directly.", "# ");
+	cb.comment("Targets the pydra.compose API (pydra >= 1.0a, Python >= 3.11).", "# ");
+	cb.blank();
+	if (needsPath) cb.line("import os");
+	if (imp.typing) cb.line("import typing as ty");
+	if (imp.attrs) cb.line("import attrs.validators");
+	cb.line("from pydra.compose import python");
+	const ff = [];
+	if (imp.directory) ff.push("Directory");
+	if (imp.file) ff.push("File");
+	if (ff.length > 0) cb.line(`from fileformats.generic import ${ff.join(", ")}`);
+	cb.blank();
+	cb.line(`from .${names.styxStem} import ${spec.delegation.wrapperFn}`);
+	cb.blank();
+	cb.blank();
+	if (imp.attrs) {
+		cb.line("def _styx_optional(validator):");
+		cb.indent(() => {
+			cb.line("\"\"\"Apply an attrs validator only to a set (non-NOTHING), non-None value.\"\"\"");
+			cb.line("def _check(instance, attribute, value):");
+			cb.indent(() => {
+				cb.line("if value is attrs.NOTHING or value is None:");
+				cb.indent(() => cb.line("return"));
+				cb.line("validator(instance, attribute, value)");
+			});
+			cb.line("return _check");
+		});
+		cb.blank();
+		cb.blank();
+	}
+	if (needsPath) {
+		cb.line("def _styx_path(value):");
+		cb.indent(() => {
+			cb.line("\"\"\"Convert fileformats / Path inputs into a styxdefs-accepted path.\"\"\"");
+			cb.line("if value is None:");
+			cb.indent(() => cb.line("return None"));
+			cb.line("if isinstance(value, (list, tuple)):");
+			cb.indent(() => cb.line("return [os.fspath(v) for v in value]"));
+			cb.line("return os.fspath(value)");
+		});
+		cb.blank();
+		cb.blank();
+	}
+	cb.line("@python.define(");
+	cb.indent(() => {
+		if (inputEntries.length === 0) cb.line("inputs={},");
+		else {
+			cb.line("inputs={");
+			cb.indent(() => {
+				for (const e of inputEntries) cb.line(`${pyStr(e.key)}: ${e.expr},`);
+			});
+			cb.line("},");
+		}
+		cb.line("outputs={");
+		cb.indent(() => {
+			for (const e of outputEntries) cb.line(`${pyStr(e.key)}: ${e.expr},`);
+		});
+		cb.line("},");
+	});
+	cb.line(")");
+	const paramList = spec.params.map((p) => p.hostName);
+	cb.line(`def ${names.cls}(${paramList.join(", ")}):`);
+	cb.indent(() => {
+		emitDocstring(cb, [ctx.app?.doc?.title, ctx.app?.doc?.description].filter(Boolean).join("\n\n") || void 0);
+		if (!spec.rootIsStruct) {
+			cb.line("raise NotImplementedError(");
+			cb.indent(() => cb.line(pyStr("styx pydra backend: tools with a non-struct root are not supported.")));
+			cb.line(")");
+			return;
+		}
+		if (spec.params.length === 0) cb.line(`result = ${spec.delegation.wrapperFn}()`);
+		else {
+			cb.line(`result = ${spec.delegation.wrapperFn}(`);
+			cb.indent(() => {
+				for (const p of spec.params) {
+					const expr = isPathParam(p) ? `_styx_path(${p.hostName})` : p.hostName;
+					cb.line(`${p.hostName}=${expr},`);
+				}
+			});
+			cb.line(")");
+		}
+		const returns = [...spec.outputs.map((f) => `result.${f.id}`), ...spec.streams.map((s) => `result.${s.id}`)];
+		if (returns.length === 1) cb.line(`return ${returns[0]}`);
+		else cb.line(`return ${returns.join(", ")}`);
+	});
+	return cb.toString();
+}
+
+//#endregion
+//#region src/backend/pydra/pydra.ts
+/** Derive the per-tool pydra module/class names. */
+function pydraNames(ctx) {
+	const mod = appModuleName$1(ctx.app);
+	const rawId = ctx.app?.id ?? "tool";
+	const safeId = /^[0-9]/.test(rawId) ? "v_" + rawId : rawId;
+	return {
+		styxStem: `_${mod}`,
+		ifaceStem: mod,
+		cls: pascalCase(safeId)
+	};
+}
+/** Generate the pydra task module source for one tool. */
+function generatePydra(ctx) {
+	return emitPydraTask(ctx, buildTypedSpec(ctx), pydraNames(ctx));
+}
+/**
+* Emits pydra tasks (`@python.define`, the post-rewrite pydra.compose API) whose
+* typed inputs/outputs carry rich constraints (numeric ranges and list bounds via
+* attrs validators, enum choices, file types, defaults) and which delegate
+* execution to the styx Python wrapper (Option B): no command-line arg-building
+* or output-path resolution is re-implemented here.
+*
+* Per tool, two co-located files are emitted so the output is a self-contained,
+* importable Python package: `_<tool>.py` (the styx Python module) and
+* `<tool>.py` (the task, importing the wrapper via a relative import).
+*/
+var PydraBackend = class {
+	name = "pydra";
+	target = "pydra";
+	emitApp(ctx, _scope) {
+		const names = pydraNames(ctx);
+		const spec = buildTypedSpec(ctx);
+		const warnings = [];
+		if (!spec.rootIsStruct) warnings.push({ message: `pydra: '${ctx.app?.id ?? "?"}' has a non-struct root; emitted task has no typed inputs and raises on run.` });
+		const styxCode = generatePython(ctx);
+		const taskCode = emitPydraTask(ctx, spec, names);
+		return {
+			meta: ctx.app,
+			files: new Map([[`${names.styxStem}.py`, styxCode], [`${names.ifaceStem}.py`, taskCode]]),
+			errors: [],
+			warnings
+		};
+	}
+};
+
 //#endregion
 //#region src/backend/schema/jsonschema.ts
 var SchemaBuilder = class {
@@ -5574,7 +6283,7 @@ var SchemaBuilder = class {
 			case "literal": return { const: type.value };
 			case "optional": return this.fromType(type.inner, node?.kind === "optional" ? node.attrs.node : void 0);
 			case "list": {
-				const repeat = node?.kind === "repeat" ? node : void 0;
+				const repeat = findRepeatNode(node);
 				const schema = {
 					type: "array",
 					items: this.fromType(type.item, repeat?.attrs.node)
@@ -5584,7 +6293,7 @@ var SchemaBuilder = class {
 				return schema;
 			}
 			case "struct": return this.structSchema(type, node);
-			case "union": return this.unionSchema(type);
+			case "union": return this.unionSchema(type, node);
 		}
 	}
 	findTerminal(node) {
@@ -5645,9 +6354,20 @@ var SchemaBuilder = class {
 		if (required.length > 0) schema.required = required;
 		return schema;
 	}
-	unionSchema(type) {
+	unionSchema(type, node) {
 		if (type.variants.every((v) => v.type.kind === "literal")) return { enum: type.variants.map((v) => v.type.kind === "literal" ? v.type.value : "") };
-		return { oneOf: type.variants.map((v) => this.fromType(v.type)) };
+		const altNode = findAlternativeNode(node);
+		return { oneOf: type.variants.map((v, i) => {
+			const schema = this.fromType(v.type, altNode?.attrs.alts[i]);
+			if (v.type.kind === "struct" && "@type" in v.type.fields && schema.properties && !("@type" in schema.properties)) {
+				schema.properties = {
+					"@type": this.fromType(v.type.fields["@type"]),
+					...schema.properties
+				};
+				schema.required = ["@type", ...schema.required ?? []];
+			}
+			return schema;
+		}) };
 	}
 };
 function generateSchema(ctx) {
@@ -6899,7 +7619,7 @@ function computePublicNames(appId) {
 * (the `reg` registrations and the `sigScope` child), so passing the same scope
 * the emitter continues with keeps later local registrations consistent.
 */
-function buildEmitModel(ctx, scope = new Scope(TS_RESERVED)) {
+function buildEmitModel$1(ctx, scope = new Scope(TS_RESERVED)) {
 	const appId = ctx.app?.id;
 	const pkg = ctx.package?.name ?? "unknown";
 	const publicNames = computePublicNames(appId);
@@ -6942,7 +7662,7 @@ function buildEmitModel(ctx, scope = new Scope(TS_RESERVED)) {
 function generateTypeScript(ctx, packageScope) {
 	const cb = new CodeBuilder("  ");
 	const scope = packageScope ?? new Scope(TS_RESERVED);
-	const { appId, pkg, names, rootType, rootIsStruct, namedTypes, typeDecls, rootTypeTag, paramsType, sigEntries } = buildEmitModel(ctx, scope);
+	const { appId, pkg, names, rootType, rootIsStruct, namedTypes, typeDecls, rootTypeTag, paramsType, sigEntries } = buildEmitModel$1(ctx, scope);
 	cb.comment("This file was auto generated by Styx.");
 	cb.comment("Do not edit this file directly.");
 	cb.blank();
@@ -7125,7 +7845,7 @@ const tsDialect = {
 * @param opts - Import and package-root options.
 */
 function renderTypeScriptCall(ctx, config, opts = {}) {
-	const model = buildEmitModel(ctx);
+	const model = buildEmitModel$1(ctx);
 	const pkg = ctx.package?.name;
 	const fnName = model.rootIsStruct ? model.names.execute : model.names.wrapper;
 	const call = `${pkg ? `${pkg}.${fnName}` : fnName}(${model.rootIsStruct && model.rootType.kind === "struct" ? renderStructLiteral(config, model.rootType, "", tsDialect, model.rootTypeTag) : renderValue(config, model.rootType, "", tsDialect)})`;
@@ -8287,5 +9007,5 @@ function compile(source, filenameOrOptions) {
 }
 
 //#endregion
-export { BoutiquesBackend, CodeBuilder, JsonSchemaBackend, PYTHON_RUNNER_DEPS, PassStatus, PythonBackend, STYXDEFS_COMPAT, Scope, TypeScriptBackend, alt, appEntrypoint, atomKey, buildSigEntries, camelCase, canonicalize, collectFieldInfo, collectNamedTypes, compactTokens, compile, compose, createContext, createPipeline, createRegistry, defaultNamingStrategy, defaultPipeline, detectFormat, effectiveOutputName, findDoc, findStructNode, fixpoint, flatten, float, format, formatSolveResult, generateBoutiques, generateOutputsSchema, generatePython, generateSchema, generateTypeScript, int, isGated, isIterated, isStructural, isTerminal, lit, nodeRef, opt, outputGate, pascalCase, path, planOutput, planScope, removeEmpty, renderPythonCall, renderStructLiteral, renderTypeScriptCall, renderValue, rep, repJoin, resolveFieldBinding, resolveOutputs, resolveTypeName, screamingSnakeCase, seq, seqJoin, simplify, snakeCase, solve, str, structKey, typeKey, unionKey };
+export { BoutiquesBackend, CodeBuilder, JsonSchemaBackend, NipypeBackend, PYTHON_RUNNER_DEPS, PassStatus, PydraBackend, PythonBackend, STYXDEFS_COMPAT, Scope, TypeScriptBackend, alt, appEntrypoint, atomKey, buildEmitModel, buildSigEntries, buildTypedSpec, camelCase, canonicalize, collectFieldInfo, collectNamedTypes, compactTokens, compile, compose, createContext, createPipeline, createRegistry, defaultNamingStrategy, defaultPipeline, detectFormat, effectiveOutputName, findDoc, findStructNode, fixpoint, flatten, float, format, formatSolveResult, generateBoutiques, generateNipype, generateOutputsSchema, generatePydra, generatePython, generateSchema, generateTypeScript, int, isGated, isIterated, isStructural, isTerminal, lit, nipypeNames, nodeRef, opt, outputGate, pascalCase, path, planOutput, planScope, pydraNames, removeEmpty, renderPythonCall, renderStructLiteral, renderTypeScriptCall, renderValue, rep, repJoin, resolveFieldBinding, resolveOutputs, resolveTypeName, screamingSnakeCase, seq, seqJoin, simplify, snakeCase, solve, str, structKey, typeKey, unionKey };
 //# sourceMappingURL=index.mjs.map