@styx-api/core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1143 @@
+//#region src/frontend/detect-format.d.ts
+type FormatName = "boutiques" | "argdump" | "workbench";
+/**
+ * Auto-detect the format of a JSON descriptor source string.
+ * Returns null if the format cannot be determined.
+ */
+declare function detectFormat(source: string): FormatName | null;
+//#endregion
+//#region src/ir/types.d.ts
+/** Scalar type kinds for terminal nodes */
+type ScalarKind = "int" | "float" | "str" | "path";
+/** Media type identifier (MIME type) */
+type MediaTypeIdentifier = string;
+/** Human-facing documentation metadata */
+interface Documentation {
+  title?: string;
+  description?: string;
+  authors?: string[];
+  literature?: string[];
+  urls?: string[];
+  comment?: string;
+}
+//#endregion
+//#region src/ir/meta.d.ts
+/**
+ * Opaque, name-based reference to an IR node by its `NodeMeta.name`.
+ *
+ * Resolved post-solve against the binding registry, not within IR passes.
+ * Names survive optimization (pointers don't), so token refs stay valid even
+ * after passes rewrite the tree. See `memory/design_outputs.md`.
+ */
+interface NodeRef {
+  kind: "node-ref";
+  name: string;
+}
+/** Construct a NodeRef from a node name. */
+declare function nodeRef(name: string): NodeRef;
+/** Output token: literal text or a parameter reference. */
+type OutputToken = {
+  kind: "literal";
+  value: string;
+} | {
+  kind: "ref";
+  target: NodeRef;
+  stripExtensions?: string[];
+  fallback?: string;
+};
+/**
+ * Specification for a file the tool produces. Lives on `NodeMeta.outputs` of
+ * the struct node (root sequence or subcommand sequence) that declared it.
+ * Per-output gating is derived downstream from the scope's binding gate and
+ * each ref binding's gate, so no host node or `optional` flag is stored.
+ */
+interface Output {
+  name?: string;
+  doc?: Documentation;
+  tokens: OutputToken[];
+  mediaTypes?: MediaTypeIdentifier[];
+}
+/** Metadata attached to any IR node. */
+interface NodeMeta {
+  /** Name identifier for this node (used by solver for binding names). */
+  name?: string;
+  /**
+   * The discriminator (`@type`) tag for this node when it is a union arm (a
+   * Boutiques sub-command). Kept separate from `name`: a single-field
+   * sub-command collapses onto its inner field, whose `name` then wins, so the
+   * tag would otherwise become the inner field's id - e.g. two distinct
+   * sub-commands `VariousString`/`VariousFile` both wrapping an `obj` field
+   * would collide on `@type: "obj"` (and the second arm would be unreachable).
+   * `mergeMeta` preserves this through the collapse and the solver prefers it
+   * for the variant tag, so distinct sub-commands keep distinct, reachable
+   * `@type`s.
+   */
+  variantTag?: string;
+  doc?: Documentation;
+  defaultValue?: string | number | boolean;
+  /** Files produced when this node is active. See `Output`. */
+  outputs?: Output[];
+}
+/** Application-level metadata for the root node. */
+interface AppMeta {
+  id?: string;
+  version?: string;
+  doc?: Documentation;
+  container?: {
+    image: string;
+    type?: "docker" | "singularity";
+  };
+  stdout?: StreamOutput;
+  stderr?: StreamOutput;
+}
+interface StreamOutput {
+  name: string;
+  doc?: Documentation;
+}
+/**
+ * Produce a usable name for an Output. Frontends may leave `Output.name`
+ * unset; downstream code (resolver, validator, backends) needs a stable
+ * identifier for diagnostics and field naming. Falls back to `output_<index>`
+ * keyed by the output's position in tree-walk order.
+ */
+declare function effectiveOutputName(output: Output, index: number): string;
+//#endregion
+//#region src/ir/node.d.ts
+/** Base structure for all IR nodes */
+interface BaseNode<K extends string, Attrs> {
+  kind: K;
+  meta?: NodeMeta;
+  attrs: Attrs;
+}
+type Literal = BaseNode<"literal", {
+  str: string;
+}>;
+type Sequence = BaseNode<"sequence", {
+  nodes: Expr[];
+  join?: string;
+}>;
+type Optional = BaseNode<"optional", {
+  node: Expr;
+}>;
+type Alternative = BaseNode<"alternative", {
+  alts: Expr[];
+}>;
+type Repeat = BaseNode<"repeat", {
+  node: Expr;
+  join?: string;
+  countMin?: number;
+  countMax?: number;
+}>;
+type Int = BaseNode<"int", {
+  minValue?: number;
+  maxValue?: number;
+}>;
+type Float = BaseNode<"float", {
+  minValue?: number;
+  maxValue?: number;
+}>;
+type Str = BaseNode<"str", Record<string, never>>;
+type Path = BaseNode<"path", {
+  resolveParent?: boolean;
+  mutable?: boolean;
+  mediaTypes?: MediaTypeIdentifier[];
+}>;
+type StructuralNode = Sequence | Optional | Alternative | Repeat;
+type Terminal = Literal | Int | Float | Str | Path;
+type Expr = StructuralNode | Terminal;
+declare function isTerminal(expr: Expr): expr is Terminal;
+declare function isStructural(expr: Expr): expr is StructuralNode;
+//#endregion
+//#region src/ir/builders.d.ts
+declare function lit(str: string): Literal;
+declare function str(meta?: NodeMeta | string): Str;
+declare function int(meta?: NodeMeta | string): Int;
+declare function float(meta?: NodeMeta | string): Float;
+declare function path(meta?: NodeMeta | string): Path;
+declare function seq(...nodes: Expr[]): Sequence;
+declare function seqJoin(join: string, ...nodes: Expr[]): Sequence;
+declare function opt(node: Expr, meta?: NodeMeta | string): Optional;
+declare function rep(node: Expr, meta?: NodeMeta | string): Repeat;
+declare function repJoin(join: string, node: Expr, meta?: NodeMeta | string): Repeat;
+declare function alt(...alts: Expr[]): Alternative;
+//#endregion
+//#region src/ir/format.d.ts
+declare function format(expr: Expr, meta?: AppMeta): string;
+//#endregion
+//#region src/ir/passes/pass.d.ts
+declare enum PassStatus {
+  Unchanged = "unchanged",
+  Changed = "changed",
+  ChangedNeedsRerun = "changed-needs-rerun"
+}
+interface PassResult {
+  expr: Expr;
+  status: PassStatus;
+  warnings?: string[];
+}
+interface Pass {
+  readonly name: string;
+  apply(expr: Expr): PassResult;
+}
+declare function compose(...passes: Pass[]): Pass;
+declare function fixpoint(pass: Pass, maxIterations?: number): Pass;
+//#endregion
+//#region src/ir/passes/canonicalize.d.ts
+/**
+ * Canonicalize IR for consistent representation:
+ * - Sort alternatives by kind, then name, then structure
+ * - Deduplicate identical alternatives
+ */
+declare const canonicalize: Pass;
+//#endregion
+//#region src/ir/passes/flatten.d.ts
+/**
+ * Flatten passes
+ * - seq(a, seq(b, c)) -> seq(a, b, c)
+ * - alt(a, alt(b, c)) -> alt(a, b, c)
+ */
+declare const flatten: Pass;
+//#endregion
+//#region src/ir/passes/pipeline.d.ts
+declare const defaultPipeline: Pass;
+declare function createPipeline(passes: Pass[], options?: {
+  fixpoint?: boolean;
+  maxIterations?: number;
+}): Pass;
+//#endregion
+//#region src/ir/passes/simplify.d.ts
+/**
+ * Simplify passes:
+ * - optional(optional(T)) -> optional(T)
+ * - repeat(repeat(T)) -> repeat(T) with merged constraints
+ * - seq(T) -> T, alt(T) -> T (singleton unwrapping)
+ * - seq(lit("a"), lit("b")) -> seq(lit("ab")) (merge consecutive literals)
+ *
+ * Every collapse that drops a wrapper layer merges that layer's `NodeMeta`
+ * into the surviving node via `mergeMeta`, so names and attached outputs are
+ * never lost.
+ */
+declare const simplify: Pass;
+//#endregion
+//#region src/ir/passes/remove-empty.d.ts
+/**
+ * Remove empty nodes:
+ * - seq() → removed
+ * - alt() → removed
+ * - opt(seq()) → removed
+ * - rep(alt()) → removed
+ */
+declare const removeEmpty: Pass;
+//#endregion
+//#region src/frontend/frontend.d.ts
+interface ParseResult {
+  meta?: AppMeta;
+  expr: Expr;
+  errors: ParseError[];
+  warnings: ParseWarning[];
+}
+interface ParseError {
+  message: string;
+  location?: SourceLocation;
+}
+interface ParseWarning {
+  message: string;
+  location?: SourceLocation;
+}
+interface SourceLocation {
+  file?: string;
+  line?: number;
+  column?: number;
+}
+interface Frontend {
+  readonly name: string;
+  readonly extensions: string[];
+  parse(source: string, filename?: string): ParseResult;
+}
+//#endregion
+//#region src/bindings/resolved-output.d.ts
+/**
+ * Resolved token in an output path template. Refs point at solved bindings;
+ * literals are emitted verbatim.
+ */
+type ResolvedToken = {
+  kind: "literal";
+  value: string;
+} | {
+  kind: "ref";
+  binding: BindingId;
+  stripExtensions?: string[];
+  fallback?: string;
+};
+/**
+ * One wrapper layer on a binding's path from the root. Atoms are stored
+ * root-to-leaf in `Binding.gate`; backends nest wrappers in array order.
+ *
+ * - `present`: the binding is inside the active branch of `binding` (a non-null
+ *   `optional`, `true` for a `bool`, `> 0` for a `count`). Reads as a boolean
+ *   guard at codegen.
+ * - `variant`: the binding is inside the `variant` arm of the union bound by
+ *   `binding`. Reads as a discriminator check.
+ * - `iter`: the binding is inside a `repeat` whose value is a `list`. Reads as
+ *   a per-element loop variable bound to `binding`.
+ */
+type GateAtom = {
+  kind: "present";
+  binding: BindingId;
+} | {
+  kind: "variant";
+  binding: BindingId;
+  variant: string;
+} | {
+  kind: "iter";
+  binding: BindingId;
+};
+/**
+ * Output specification translated against the binding registry. Pure template
+ * data: a name and a token sequence. Per-output gating is derived at codegen
+ * time from the declaring scope's gate plus each ref binding's gate.
+ */
+interface ResolvedOutput {
+  name: string;
+  doc?: Documentation;
+  tokens: ResolvedToken[];
+  mediaTypes?: MediaTypeIdentifier[];
+}
+/**
+ * Outputs declared on one struct binding, grouped under that scope. The
+ * solver guarantees a binding on every output-carrying sequence (forcing a
+ * struct binding even when it would otherwise collapse), so the scope is
+ * always a real BindingId. Per-output gating derives from the scope binding's
+ * `gate` plus each ref binding's `gate`.
+ */
+interface OutputScope {
+  scope: BindingId;
+  outputs: ResolvedOutput[];
+}
+//#endregion
+//#region src/bindings/types.d.ts
+type BoundType = {
+  kind: "scalar";
+  scalar: ScalarKind;
+} | {
+  kind: "bool";
+} | {
+  kind: "count";
+} | {
+  kind: "literal";
+  value: string | number;
+} | {
+  kind: "optional";
+  inner: BoundType;
+} | {
+  kind: "list";
+  item: BoundType;
+} | {
+  kind: "struct";
+  fields: Record<string, BoundType>;
+} | {
+  kind: "union";
+  variants: BoundVariant[];
+};
+interface BoundVariant {
+  name?: string;
+  type: BoundType;
+}
+//#endregion
+//#region src/bindings/binding.d.ts
+type BindingId = string;
+/**
+ * One step in a binding's access path relative to top-level `params`.
+ *
+ * - `field`: descend into a named field of the enclosing struct scope. Renders
+ *   as `params.name` (TS) / `params["name"]` (Python).
+ * - `iter`: the access base resets to the per-element loop variable bound to
+ *   `binding` (a `repeat`-of-list). The renderer substitutes the active loop
+ *   variable at emit time (from the `iter` gate atom's loop, or the
+ *   arg-builder's local loop), so segments after an `iter` build off the
+ *   element rather than off `params`.
+ *
+ * There is deliberately no `variant` or `directValue` segment: complex-union
+ * variant fields are plain `field` segments off the union's own path (the
+ * `@type` discriminant lives in `GateAtom`, not the access path), and the
+ * solver's wrapper collapses (`optional<scalar>`, scalar lists) are expressed
+ * by a binding simply inheriting its parent wrapper's path.
+ */
+type AccessSegment = {
+  kind: "field";
+  name: string;
+} | {
+  kind: "iter";
+  binding: BindingId;
+};
+/**
+ * A binding's location relative to top-level `params`, as a structured segment
+ * sequence. Computed once by the solver (`assignAccessPaths`) and rendered by
+ * each backend's `renderAccess`, so the arg-builder and outputs emitter share
+ * one source of truth instead of each re-deriving paths.
+ */
+type AccessPath = AccessSegment[];
+interface Binding {
+  id: BindingId;
+  node: Expr;
+  name: string;
+  type: BoundType;
+  /**
+   * Wrapper layers on the path from the root to this binding, root-to-leaf.
+   * Captures the optional/repeat/alternative ancestors as `present`/`iter`/
+   * `variant` atoms. Backends nest wrappers in array order; "is this binding
+   * conditionally active?" reduces to `gate.length > 0`.
+   */
+  gate: GateAtom[];
+  /**
+   * Access path relative to top-level `params`, assigned by the solver's
+   * `assignAccessPaths` pass after types settle. Backends render it via
+   * `renderAccess` rather than re-walking the IR to recompute where this
+   * binding lives.
+   */
+  access: AccessPath;
+}
+type BindingRegistry = Map<BindingId, Binding>;
+type OutputDiagnosticLevel = "error" | "warning";
+interface OutputDiagnostic {
+  output: string;
+  message: string;
+  level: OutputDiagnosticLevel;
+}
+interface OutputValidationResult {
+  errors: OutputDiagnostic[];
+  warnings: OutputDiagnostic[];
+}
+interface SolveResult {
+  bindings: BindingRegistry;
+  resolve: (node: Expr) => Binding | undefined;
+}
+declare function createRegistry(): BindingRegistry;
+//#endregion
+//#region src/bindings/output-gate.d.ts
+/**
+ * The unified wrapper sequence for a single output: the scope's gate, then for
+ * each ref token both the ref binding's path-gate and (if its type is itself
+ * "thick" - nullable or iterable) a self-atom on the ref binding. Atoms are
+ * deduped while preserving first-occurrence order.
+ *
+ * The self-atom encodes facts derivable from `Binding.type` alone:
+ * - `optional`, `bool`, `count` -> `present(binding)` (value may be absent)
+ * - `list` -> `iter(binding)` (iterate per element)
+ *
+ * `scopeGate` is the gate of the scope's struct binding (often `[]` at the
+ * root). Backends nest wrappers in array order; the atom kind decides whether
+ * it renders as a guard (`present` / `variant`) or a loop (`iter`).
+ */
+declare function outputGate(scopeGate: GateAtom[], output: ResolvedOutput, bindings: BindingRegistry): GateAtom[];
+declare function atomKey(atom: GateAtom): string;
+//#endregion
+//#region src/bindings/format.d.ts
+interface FormatExtras {
+  scopes?: OutputScope[];
+  diagnostics?: OutputValidationResult;
+}
+declare function formatSolveResult(result: SolveResult, expr: Expr, extras?: FormatExtras): string;
+//#endregion
+//#region src/solver/resolve-outputs.d.ts
+interface OutputResolution {
+  scopes: OutputScope[];
+  diagnostics: OutputValidationResult;
+}
+/**
+ * Translate each `NodeMeta.outputs` entry against the binding registry,
+ * grouped by the declaring struct binding (the "scope"). The solver forces a
+ * binding on every output-carrying sequence, so an output without a scope
+ * binding indicates a frontend bug (outputs attached to a non-sequence
+ * node) - it is reported as a diagnostic and dropped.
+ */
+declare function resolveOutputs(root: Expr, solved: SolveResult): OutputResolution;
+//#endregion
+//#region src/solver/solver.d.ts
+interface SolveOptions {
+  namingStrategy?: NamingStrategy;
+}
+interface NamingStrategy {
+  getName: (node: Expr, path: string[]) => string;
+  generateId: () => BindingId;
+}
+declare function defaultNamingStrategy(): NamingStrategy;
+declare function solve(expr: Expr, options?: SolveOptions): SolveResult;
+//#endregion
+//#region src/manifest/types.d.ts
+interface ProjectMeta {
+  name?: string;
+  version?: string;
+  doc?: Documentation;
+  license?: Documentation;
+}
+interface PackageMeta {
+  name?: string;
+  version?: string;
+  docker?: string;
+  doc?: Documentation;
+}
+//#endregion
+//#region src/manifest/context.d.ts
+interface CodegenContext {
+  expr: Expr;
+  bindings: BindingRegistry;
+  resolve: SolveResult["resolve"];
+  outputScopes: OutputScope[];
+  outputDiagnostics: OutputValidationResult;
+  app?: AppMeta;
+  package?: PackageMeta;
+  project?: ProjectMeta;
+}
+declare function createContext(expr: Expr, solveResult: SolveResult, outputs: OutputResolution, meta?: {
+  app?: AppMeta;
+  package?: PackageMeta;
+  project?: ProjectMeta;
+}): CodegenContext;
+//#endregion
+//#region src/backend/scope.d.ts
+/** Symbol collision avoidance for code generation. */
+declare class Scope {
+  private readonly reserved;
+  private readonly used;
+  private readonly parent?;
+  constructor(reserved?: Iterable<string>, parent?: Scope);
+  /** Check if a symbol is already taken (in this scope or any parent). */
+  has(symbol: string): boolean;
+  /**
+   * 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: string, recase?: (s: string) => string): string;
+  /** Create a child scope that inherits this scope's restrictions. */
+  child(reserved?: Iterable<string>): Scope;
+}
+//#endregion
+//#region src/backend/backend.d.ts
+interface EmitResult {
+  files: Map<string, string>;
+  errors: EmitError[];
+  warnings: EmitWarning[];
+}
+interface EmitError {
+  message: string;
+}
+interface EmitWarning {
+  message: string;
+}
+/**
+ * What the suite-level dispatcher needs to route a config object to one app's
+ * dict-style executor, keyed by the root `@type` discriminator.
+ */
+interface AppEntrypoint {
+  /** Root `@type` discriminator value (`<package>/<app>`). */
+  type: string;
+  /**
+   * Dict-style execute function name - `<tool>Execute` / `<tool>_execute` for a
+   * struct root, `<tool>` for a non-struct root. Takes `(params, runner)`.
+   */
+  executeFn: string;
+}
+interface EmittedApp extends EmitResult {
+  meta?: AppMeta;
+  /**
+   * Dispatch entrypoint, present when the app has a stable `@type` (both an id
+   * and a package name are known). Consumed by `emitPackage` to build the
+   * suite-level `execute(params, runner)` dispatcher.
+   */
+  entrypoint?: AppEntrypoint;
+}
+interface EmittedPackage extends EmitResult {
+  meta?: PackageMeta;
+}
+/**
+ * A code generator for one target language. Implementations emit in up to
+ * three tiers; only `emitApp` is mandatory.
+ *
+ * The CLI's `--mode` flag selects which tiers run: `scripts` = `emitApp` only,
+ * `single` = `emitApp` + one `emitPackage`, `multi` = all three tiers.
+ *
+ * Paths in returned file maps are relative to the emit tier's natural root
+ * (package directory for app/package emit, project root for project emit).
+ * Orchestration is responsible for prefixing/merging the maps.
+ */
+interface Backend {
+  readonly name: string;
+  readonly target: string;
+  /**
+   * Emit the per-tool file(s) for one app. Mandatory.
+   *
+   * When emitting many tools into one suite barrel, pass a `scope` shared across
+   * the package (from `newPackageScope`) so emitted top-level names stay unique
+   * across tools - a flat `export *` / `from .x import *` re-export otherwise
+   * collides same-named types. Omit it for standalone single-tool emission.
+   */
+  emitApp(ctx: CodegenContext, scope?: Scope): EmittedApp;
+  /**
+   * Create a fresh symbol scope seeded with this backend's reserved words, to be
+   * shared across all `emitApp` calls for one package. Optional; callers fall
+   * back to per-tool scoping (still safe via name prefixing) when absent.
+   */
+  newPackageScope?(): Scope;
+  /**
+   * Emit suite-level files for a package containing many apps (e.g. the
+   * `__init__.py` re-exporting `from .bet import *` per tool, or an
+   * `index.ts` doing `export * from "./bet.js"`). Optional; defaulted to
+   * no-op by callers when absent.
+   */
+  emitPackage?(pkg: PackageMeta, apps: EmittedApp[]): EmittedPackage;
+  /**
+   * Emit project-level artifacts spanning many packages (e.g. root
+   * `pyproject.toml`, top-level `__init__.py`, runner helpers).
+   * Wired up by Plan 2's CLI catalog mode; backends opt in as needed.
+   */
+  emitProject?(proj: ProjectMeta, packages: EmittedPackage[]): EmitResult;
+}
+interface TypeMap {
+  map(type: BoundType): string;
+  imports(type: BoundType): string[];
+}
+//#endregion
+//#region src/backend/boutiques/boutiques.d.ts
+interface BtDescriptor {
+  name?: string;
+  id?: string;
+  description?: string;
+  "schema-version"?: string;
+  "tool-version"?: string;
+  author?: string;
+  url?: string;
+  "container-image"?: {
+    image: string;
+    type?: string;
+  };
+  "command-line"?: string;
+  inputs?: BtInput[];
+  "stdout-output"?: {
+    id: string;
+    name?: string;
+    description?: string;
+  };
+  "stderr-output"?: {
+    id: string;
+    name?: string;
+    description?: string;
+  };
+  "output-files"?: BtOutputFile[];
+}
+interface BtOutputFile {
+  id: string;
+  name?: string;
+  description?: string;
+  "path-template": string;
+  optional?: boolean;
+  list?: boolean;
+  "path-template-stripped-extensions"?: string[];
+}
+interface BtInput {
+  id: string;
+  name?: string;
+  description?: string;
+  type: string | BtDescriptor | BtDescriptor[];
+  "value-key": string;
+  optional?: boolean;
+  list?: boolean;
+  "list-separator"?: string;
+  "min-list-entries"?: number;
+  "max-list-entries"?: number;
+  "command-line-flag"?: string;
+  "command-line-flag-separator"?: string;
+  "value-choices"?: (string | number)[];
+  "default-value"?: string | number | boolean;
+  minimum?: number;
+  maximum?: number;
+  integer?: boolean;
+  "resolve-parent"?: boolean;
+  mutable?: boolean;
+}
+declare function generateBoutiques(ctx: CodegenContext): {
+  descriptor: BtDescriptor;
+  warnings: EmitWarning[];
+};
+declare class BoutiquesBackend implements Backend {
+  readonly name = "boutiques";
+  readonly target = "boutiques";
+  emitApp(ctx: CodegenContext): EmittedApp;
+}
+//#endregion
+//#region src/backend/code-builder.d.ts
+/** Line-buffer abstraction for code emission. */
+declare class CodeBuilder {
+  private readonly lines;
+  private depth;
+  private readonly indentStr;
+  constructor(indent?: string);
+  /** Append a line at the current indentation level. */
+  line(text: string): this;
+  /** Append a blank line. */
+  blank(): this;
+  /** Append a comment line. */
+  comment(text: string, prefix?: string): this;
+  /** Run a callback with increased indentation. */
+  indent(fn: () => void): this;
+  /** Append all lines from another CodeBuilder at the current indentation level. */
+  append(other: CodeBuilder): this;
+  /** Return the built code as a string. */
+  toString(): string;
+}
+//#endregion
+//#region src/backend/collect-field-info.d.ts
+/**
+ * Metadata extracted for each field of a struct type.
+ *
+ * `doc` is the field's description, recovered from wrapper nodes via `findDoc`.
+ * `defaultValue` is pulled from the wrapper or binding node's metadata.
+ */
+interface FieldInfo {
+  doc?: string;
+  defaultValue?: string | number | boolean;
+}
+/**
+ * Collect field metadata (doc, defaultValue) for each field of a struct type.
+ *
+ * Walks the IR tree to find the sequence node containing the struct's fields,
+ * then resolves each child to its field binding. Metadata is recovered from both
+ * the wrapper node (where the parser hoists doc) and the binding node (where the
+ * solver places the binding after sequence collapse).
+ */
+declare function collectFieldInfo(ctx: CodegenContext, structType: Extract<BoundType, {
+  kind: "struct";
+}>): Map<string, FieldInfo>;
+//#endregion
+//#region src/backend/collect-named-types.d.ts
+/** A named compound type (struct or union) discovered during type collection. */
+interface NamedType {
+  name: string;
+  type: BoundType;
+}
+/**
+ * Recursively collect all struct/union types and assign unique names.
+ *
+ * Walks the BoundType tree depth-first, using structural keys (`structKey`,
+ * `unionKey`) to deduplicate types that appear multiple times in the tree.
+ * Each unique struct/union gets a name generated by applying `nameTransform`
+ * to a hint string (derived from the root name or field/variant names).
+ *
+ * @param rootType - The root BoundType to walk.
+ * @param rootName - The hint for the root type's name (already tool-qualified).
+ * @param scope - Symbol scope for collision avoidance.
+ * @param nameTransform - Converts a hint string to a type name (e.g. pascalCase, snake_case).
+ * @param nestedPrefix - Prepended to every NON-root type name so a suite's flat
+ *   barrel (`export * from`/`from .x import *`) can't collide two tools' types
+ *   that share a local field/variant name (e.g. `Outputtype`). Pass the tool's
+ *   type prefix (its root name); defaults to "" for single-tool emission.
+ * @returns `namedTypes` maps structural keys to assigned names, `typeDecls` lists declarations in order.
+ */
+declare function collectNamedTypes(rootType: BoundType, rootName: string, scope: Scope, nameTransform: (hint: string) => string, nestedPrefix?: string): {
+  namedTypes: Map<string, string>;
+  typeDecls: NamedType[];
+};
+/**
+ * Create a type name resolver from a namedTypes map.
+ * Returns a function that maps a BoundType to its assigned name (if any).
+ */
+declare function resolveTypeName(namedTypes: Map<string, string>): (type: BoundType) => string | undefined;
+//#endregion
+//#region src/backend/find-doc.d.ts
+/**
+ * Find a description from an IR node, traversing through wrapper nodes.
+ *
+ * The parser's `wrapNode` hoists doc metadata to the outermost wrapper node,
+ * but the solver's simplify pass can collapse sequences, burying descriptions
+ * deeper in the tree.
+ *
+ * This traversal is type-aware: it only enters sequences when the corresponding
+ * BoundType is not a struct. Struct sequences have their own field collection
+ * call, so entering them would steal nested struct children's descriptions.
+ *
+ * @param node - The IR node to search for a description.
+ * @param fieldType - The BoundType of the field, used to determine traversal boundaries.
+ */
+declare function findDoc(node: Expr, fieldType: BoundType): string | undefined;
+//#endregion
+//#region src/backend/find-struct-node.d.ts
+/**
+ * Find the sequence node whose child bindings match a struct type's fields.
+ *
+ * Traverses through optional, repeat, and alternative wrappers to find the
+ * sequence that directly contains the struct's field bindings. This is necessary
+ * because the solver may collapse `seq(lit("--flag"), terminal)` into the terminal,
+ * burying bindings deeper in the tree.
+ *
+ * Uses a two-phase check for sequences:
+ * 1. Direct binding check (`ctx.resolve`) - matches when bindings are on immediate children
+ * 2. Recursive binding check (`resolveFieldBinding`) - matches when solver collapsed
+ *    a seq(lit, terminal) and the binding is buried deeper
+ *
+ * Phase 1 is tried first to avoid falsely matching an outer sequence when an inner
+ * sequence is the actual struct owner (e.g. `seq(lit("--flag"), seq(field1, field2))`).
+ */
+declare function findStructNode(node: Expr, ctx: CodegenContext, structType: Extract<BoundType, {
+  kind: "struct";
+}>): Extract<Expr, {
+  kind: "sequence";
+}> | undefined;
+//#endregion
+//#region src/backend/resolve-field-binding.d.ts
+/**
+ * Resolve a struct child node to its field binding, handling collapsed sequences.
+ *
+ * When the solver's simplify pass collapses `seq(lit("--flag"), terminal)` into
+ * just the terminal, the binding ends up on the inner node while metadata (doc,
+ * defaultValue) may remain on the outermost wrapper. This function recursively
+ * descends through collapsed sequences to find the binding, tracking the outermost
+ * node for metadata recovery.
+ *
+ * Uses type identity (`===`) to verify the binding matches the struct's field type,
+ * preventing cross-nesting name collisions where an inner struct has a field with
+ * the same name as the outer struct.
+ */
+declare function resolveFieldBinding(node: Expr, ctx: CodegenContext, structType: Extract<BoundType, {
+  kind: "struct";
+}>, outermost?: Expr): {
+  binding: Binding;
+  wrapperNode: Expr;
+} | undefined;
+//#endregion
+//#region src/backend/resolve-output-tokens.d.ts
+/**
+ * Compact consecutive literal tokens. Backends that emit string concatenation
+ * benefit from a shorter token stream; backends that template each token
+ * individually can ignore this and use `output.tokens` directly.
+ */
+declare function compactTokens(tokens: ResolvedToken[]): ResolvedToken[];
+/**
+ * One output ready for codegen. `gate` is the wrapper sequence (outermost
+ * first); the backend renders each atom as the appropriate scope-introducing
+ * statement, then emits the path expression inside the innermost layer.
+ */
+interface OutputEmitPlan {
+  name: string;
+  gate: GateAtom[];
+  tokens: ResolvedToken[];
+  resolved: ResolvedOutput;
+}
+declare function planOutput(scopeGate: GateAtom[], output: ResolvedOutput, bindings: BindingRegistry): OutputEmitPlan;
+/**
+ * Does the output have any conditional wrapper? Equivalent to "is at least one
+ * atom a `present` or `variant`?". `iter` alone means the output emits a list
+ * and is not conditionally absent.
+ */
+declare function isGated(plan: OutputEmitPlan): boolean;
+/** Does the output iterate (emit zero-or-more values)? */
+declare function isIterated(plan: OutputEmitPlan): boolean;
+/**
+ * Convenience for backends emitting all outputs of a scope at once. The caller
+ * provides the scope's gate (typically `bindings.get(scope.scope)?.gate ?? []`).
+ */
+declare function planScope(scope: OutputScope, scopeGate: GateAtom[], bindings: BindingRegistry): OutputEmitPlan[];
+//#endregion
+//#region src/backend/sig-entries.d.ts
+/**
+ * One entry of a kwarg-style signature, shared across language backends. Each
+ * entry describes a single user-facing parameter of the `_params()` factory
+ * and the kwarg wrapper:
+ * - `sigType`/`sigDefault` go directly into the function signature
+ * - `isOptional`/`hasExplicitDefault` drive the dict-build branches (required
+ *   and explicitly-defaulted fields are always set; optional-no-default fields
+ *   are conditionally set when not None/null)
+ * - `doc` is rendered into the per-param doc block (Args / @param)
+ *
+ * `name` is the scrubbed host identifier (used in the signature and function
+ * body); `wireKey` is the Boutiques field name (used as the dict key /
+ * TypedDict field key). They diverge when the wire key collides with a host
+ * reserved word, is not a valid identifier, or shadows a local in the emitting
+ * function (e.g. wire `float` -> host `float_`, wire `4d_input` -> host
+ * `v_4d_input`).
+ */
+interface SigEntry {
+  /** Scrubbed host identifier - safe to use in signatures and as a local. */
+  name: string;
+  /** Boutiques field name - used as the dict key / TypedDict field key. */
+  wireKey: string;
+  sigType: string;
+  /** Rendered default expression in the host language, or undefined for required-no-default. */
+  sigDefault?: string;
+  /** True iff the BoundType is `optional` (i.e. dict-build conditionally includes). */
+  isOptional: boolean;
+  /** True iff the field carries an explicit defaultValue in its FieldInfo. */
+  hasExplicitDefault: boolean;
+  doc?: string;
+}
+/** Per-backend rendering hooks for `buildSigEntries`. */
+interface SigOptions {
+  /** Render a non-optional BoundType as a language-native type expression. */
+  renderType: (t: BoundType) => string;
+  /** Suffix appended to `renderType(inner)` for optional fields (e.g. ` | None`, ` | null`). */
+  nullableSuffix: string;
+  /** Default expression for optional-no-default fields (e.g. `None`, `null`). */
+  nullableDefault: string;
+  /** Render a JS scalar default as a host-language literal (e.g. `True`/`true`). */
+  renderDefault: (v: string | number | boolean) => string;
+}
+/**
+ * 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.
+ */
+declare function buildSigEntries(rootType: Extract<BoundType, {
+  kind: "struct";
+}>, fieldInfo: Map<string, FieldInfo>, registerLocal: (wireKey: string) => string, opts: SigOptions): SigEntry[];
+//#endregion
+//#region src/backend/type-keys.d.ts
+/**
+ * Stable, fully structural identity key for any BoundType.
+ *
+ * Two types share a key iff they are structurally identical - same shape AND
+ * same leaf types/literal values, recursively. This is what `collectNamedTypes`
+ * dedups on: distinct nominal types must get distinct keys so each gets its own
+ * generated name.
+ *
+ * Keying on field/variant *names* alone is too coarse: discriminated-union
+ * variants that differ only by their `@type` literal (e.g. ANTs' `transform_*`
+ * variants, all `{ "@type": <literal>, gradient_step: float }`) would collapse
+ * to one identity, emitting `Transform = TransformRigid | TransformRigid | ...`
+ * and breaking discriminated-union narrowing. Including the field types (and
+ * thus the `@type` literal value) keeps them distinct.
+ */
+declare function typeKey(type: BoundType): string;
+/** Stable identity key for a struct type (field names + field types). */
+declare function structKey(type: Extract<BoundType, {
+  kind: "struct";
+}>): string;
+/** Stable identity key for a union type (variant names + variant types). */
+declare function unionKey(type: Extract<BoundType, {
+  kind: "union";
+}>): string;
+//#endregion
+//#region src/backend/python/python.d.ts
+declare function generatePython(ctx: CodegenContext, packageScope?: Scope): string;
+declare class PythonBackend implements Backend {
+  readonly name = "python";
+  readonly target = "python";
+  emitApp(ctx: CodegenContext, scope?: Scope): EmittedApp;
+  newPackageScope(): Scope;
+  emitPackage(pkg: PackageMeta, apps: EmittedApp[]): EmittedPackage;
+  emitProject(proj: ProjectMeta, packages: EmittedPackage[]): EmitResult;
+}
+//#endregion
+//#region src/backend/snippet-core.d.ts
+/**
+ * Per-language rendering hooks for the call-site snippet renderer. The recursive
+ * structure (struct -> object literal, union -> picked variant, list -> array)
+ * is language-agnostic; only leaf-literal syntax, object keys, and indentation
+ * differ, and those are supplied here.
+ */
+interface SnippetDialect {
+  /** One indentation level (e.g. `"    "` for Python, `"  "` for TypeScript). */
+  indentUnit: string;
+  /** Render a string value as a host literal (quoted). */
+  string(value: string): string;
+  /** Render a boolean value as a host literal (`True`/`true`). */
+  boolean(value: boolean): string;
+  /** Render a number value as a host literal. */
+  number(value: number): string;
+  /** Host literal for a null/None value. */
+  null: string;
+  /** Render an object-literal key from a wire key, quoting when not a bare identifier. */
+  objKey(wireKey: string): string;
+}
+/** Options shared by both language renderers. */
+interface SnippetOptions {
+  /**
+   * Module the package is imported from (e.g. `"niwrap"`). Defaults to the
+   * project name on the context. When unset and no project name is available,
+   * Python falls back to a bare `import <pkg>` and TypeScript omits the import.
+   */
+  packageRoot?: string;
+  /** Whether to prepend an import line. Defaults to `true`. */
+  includeImport?: boolean;
+}
+/**
+ * Render a struct config as a host object literal (Python dict / TS object).
+ * Keys are the Boutiques wire names (the generated TypedDict / interface keys) -
+ * nested structs have no constructor function in the generated code, so callers
+ * build them as plain object literals.
+ *
+ * `@type` is emitted from the struct's literal discriminator field when present
+ * (union variants carry a required, load-bearing `@type`); for the root call the
+ * tag is injected via `injectAtType` (the root's `@type` is derived from
+ * `pkg/appId`, not stored as a field). Non-`@type` literal fields have no
+ * runtime representation and are skipped.
+ */
+declare function renderStructLiteral(value: unknown, type: Extract<BoundType, {
+  kind: "struct";
+}>, indent: string, d: SnippetDialect, injectAtType?: string): string;
+/**
+ * Render a config value to a host-language expression, guided by its BoundType.
+ *
+ * `indent` is the leading whitespace of the line the value starts on; multi-line
+ * forms (object/array literals) place their members one level deeper and close
+ * back at `indent`. The renderer follows the BoundType tree for shape and reads
+ * the parallel config object for values, so unknown / absent keys are simply
+ * omitted (a partial config produces a partial snippet).
+ */
+declare function renderValue(value: unknown, type: BoundType, indent: string, d: SnippetDialect): string;
+//#endregion
+//#region src/backend/python/snippet.d.ts
+/**
+ * Render a Python call snippet for one tool from a config object (the params
+ * dict the form produces, keyed by Boutiques wire names).
+ *
+ * Struct-rooted tools use the ergonomic kwarg wrapper -
+ * `fsl.bet(infile=..., fractional_intensity=0.5)` - whose keyword names are the
+ * *scrubbed host* identifiers (`float` -> `float_`), not the wire keys; the
+ * per-field mapping comes from the same `buildSigEntries` the generated wrapper
+ * is built from, so the snippet matches the real signature. Nested structs /
+ * union variants / lists-of-structs have no constructor in the generated code,
+ * so they render as plain dict literals keyed by wire names.
+ *
+ * Union- (or otherwise non-struct-) rooted tools have no kwarg wrapper; the
+ * single dict-style `<tool>` entry is called with one object-literal argument.
+ *
+ * The snippet matches the *standalone* (single-descriptor) emission of the same
+ * context - which is how the hub compiles - not a catalog emission where a
+ * shared package scope could suffix-bump a name.
+ *
+ * @param ctx - The compiled context (compile -> pipeline -> solve ->
+ *   resolveOutputs -> createContext, as in the CLI's `readAndCompile`).
+ * @param config - The params object, keyed by Boutiques *wire* names (not host
+ *   identifiers). Every union-typed value - including the root of a union-rooted
+ *   tool - must carry its `@type` discriminator so the variant can be matched;
+ *   the root struct's `@type` is supplied by the renderer, so omit it there.
+ * @param opts - Import and package-root options.
+ */
+declare function renderPythonCall(ctx: CodegenContext, config: Record<string, unknown>, opts?: SnippetOptions): string;
+//#endregion
+//#region src/backend/schema/jsonschema.d.ts
+interface JsonSchema {
+  type?: string | string[];
+  items?: JsonSchema;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+  oneOf?: JsonSchema[];
+  enum?: (string | number)[];
+  const?: string | number;
+  [key: string]: unknown;
+}
+declare function generateSchema(ctx: CodegenContext): JsonSchema;
+/**
+ * JSON Schema for a tool's **Outputs object**: the set of files it produces
+ * (resolved outputs + mutable inputs surfaced as outputs) plus its captured
+ * stdout/stderr streams. Built from the same `collectOutputFields` /
+ * `streamFields` source of truth the Python and TypeScript backends use to type
+ * the Outputs dataclass/interface, so the three describe the same shape.
+ *
+ * Field encoding (mirrors how the language backends type each field):
+ * - required single -> `{ type: "string", x-styx-type: "path" }`
+ * - optional single -> `{ type: ["string", "null"], x-styx-type: "path" }`
+ * - list output     -> `{ type: "array", items: { type: "string", x-styx-type: "path" } }`
+ * - stream field    -> `{ type: "array", items: { type: "string" } }` (lines of
+ *   text, NOT paths - the absent `x-styx-type` lets a consumer tell them apart)
+ *
+ * EVERY field is `required`: unlike the inputs schema (where an optional param
+ * key is genuinely omitted, so "not in `required`" is faithful), an Outputs
+ * field is always present - a gated single is `null`, a gated list is an empty
+ * array. So optionality is carried by the `null` type branch, and a strict
+ * validator accepts the actual emitted object (e.g. `{ "out_file": null }`).
+ */
+declare function generateOutputsSchema(ctx: CodegenContext): JsonSchema;
+declare class JsonSchemaBackend implements Backend {
+  readonly name = "json-schema";
+  readonly target = "json-schema";
+  /** One scope per package so per-tool schema file stems stay unique in the suite directory. */
+  newPackageScope(): Scope;
+  emitApp(ctx: CodegenContext, scope?: Scope): EmittedApp;
+}
+//#endregion
+//#region src/backend/string-case.d.ts
+declare function snakeCase(s: string): string;
+declare function screamingSnakeCase(s: string): string;
+declare function pascalCase(s: string): string;
+declare function camelCase(s: string): string;
+//#endregion
+//#region src/backend/styxdefs-compat.d.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.
+ */
+declare const STYXDEFS_COMPAT: {
+  /** PEP 508 specifier for the Python `styxdefs` package. */readonly python: ">=0.7.0,<0.8.0"; /** npm semver range for the `styxdefs` package. */
+  readonly 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.
+ */
+declare const PYTHON_RUNNER_DEPS: readonly ["styxdocker", "styxsingularity", "styxgraph"];
+//#endregion
+//#region src/backend/typescript/typescript.d.ts
+declare function generateTypeScript(ctx: CodegenContext, packageScope?: Scope): string;
+declare class TypeScriptBackend implements Backend {
+  readonly name = "typescript";
+  readonly target = "typescript";
+  emitApp(ctx: CodegenContext, scope?: Scope): EmittedApp;
+  newPackageScope(): Scope;
+  emitPackage(pkg: PackageMeta, apps: EmittedApp[]): EmittedPackage;
+  emitProject(proj: ProjectMeta, packages: EmittedPackage[]): EmitResult;
+}
+//#endregion
+//#region src/backend/typescript/snippet.d.ts
+/**
+ * Render a TypeScript call snippet for one tool from a config object (keyed by
+ * Boutiques wire names).
+ *
+ * The generated v2 kwarg wrapper takes *positional* arguments, which can't skip
+ * a middle optional - so the runnable object-style entry is the dict-style
+ * `<tool>Execute(params)` (struct roots). The snippet builds the params object
+ * literal (wire-keyed, with the root `@type` injected) and passes it there.
+ * Union- (or otherwise non-struct-) rooted tools call the dict-style `<tool>`
+ * entry the same way. Nested structs / union variants / lists-of-structs have no
+ * constructor in the generated code and render as object literals.
+ *
+ * The snippet matches the *standalone* (single-descriptor) emission of the same
+ * context - which is how the hub compiles - not a catalog emission where a
+ * shared package scope could suffix-bump a name.
+ *
+ * @param ctx - The compiled context (compile -> pipeline -> solve ->
+ *   resolveOutputs -> createContext, as in the CLI's `readAndCompile`).
+ * @param config - The params object, keyed by Boutiques *wire* names. Every
+ *   union-typed value - including the root of a union-rooted tool - must carry
+ *   its `@type` discriminator so the variant can be matched; the root struct's
+ *   `@type` is supplied by the renderer, so omit it there.
+ * @param opts - Import and package-root options.
+ */
+declare function renderTypeScriptCall(ctx: CodegenContext, config: Record<string, unknown>, opts?: SnippetOptions): string;
+//#endregion
+//#region src/index.d.ts
+declare function compile(source: string, filenameOrOptions?: string | {
+  format?: FormatName;
+  filename?: string;
+}): ParseResult;
+//#endregion
+export { AccessPath, AccessSegment, Alternative, AppMeta, Backend, Binding, BindingId, BindingRegistry, BoundType, BoundVariant, BoutiquesBackend, CodeBuilder, CodegenContext, Documentation, EmitError, EmitResult, EmitWarning, EmittedApp, EmittedPackage, Expr, FieldInfo, Float, FormatName, Frontend, GateAtom, Int, JsonSchema, JsonSchemaBackend, Literal, MediaTypeIdentifier, NamedType, NamingStrategy, NodeMeta, NodeRef, Optional, Output, OutputDiagnostic, OutputDiagnosticLevel, OutputEmitPlan, OutputResolution, OutputScope, OutputToken, OutputValidationResult, PYTHON_RUNNER_DEPS, PackageMeta, ParseError, ParseResult, ParseWarning, Pass, PassResult, PassStatus, Path, ProjectMeta, PythonBackend, Repeat, ResolvedOutput, ResolvedToken, STYXDEFS_COMPAT, ScalarKind, Scope, Sequence, SigEntry, SigOptions, SnippetDialect, SnippetOptions, SolveOptions, SolveResult, SourceLocation, Str, StreamOutput, StructuralNode, Terminal, TypeMap, TypeScriptBackend, alt, 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 };
+//# sourceMappingURL=index.d.mts.map