@styx-api/core 0.1.0

package/src/backend/boutiques/index.ts

@@ -0,0 +1 @@
+export { BoutiquesBackend, generateBoutiques } from "./boutiques.js";

package/src/backend/code-builder.ts

@@ -0,0 +1,49 @@
+/** Line-buffer abstraction for code emission. */
+export class CodeBuilder {
+  private readonly lines: string[] = [];
+  private depth = 0;
+  private readonly indentStr: string;
+
+  constructor(indent = "    ") {
+    this.indentStr = indent;
+  }
+
+  /** Append a line at the current indentation level. */
+  line(text: string): this {
+    this.lines.push(this.indentStr.repeat(this.depth) + text);
+    return this;
+  }
+
+  /** Append a blank line. */
+  blank(): this {
+    this.lines.push("");
+    return this;
+  }
+
+  /** Append a comment line. */
+  comment(text: string, prefix = "// "): this {
+    return this.line(`${prefix}${text}`);
+  }
+
+  /** Run a callback with increased indentation. */
+  indent(fn: () => void): this {
+    this.depth++;
+    fn();
+    this.depth--;
+    return this;
+  }
+
+  /** Append all lines from another CodeBuilder at the current indentation level. */
+  append(other: CodeBuilder): this {
+    const prefix = this.indentStr.repeat(this.depth);
+    for (const line of other.lines) {
+      this.lines.push(line === "" ? "" : prefix + line);
+    }
+    return this;
+  }
+
+  /** Return the built code as a string. */
+  toString(): string {
+    return this.lines.join("\n");
+  }
+}

package/src/backend/collect-field-info.ts

@@ -0,0 +1,50 @@
+import type { BoundType } from "../bindings/index.js";
+import type { CodegenContext } from "../manifest/index.js";
+import { findDoc } from "./find-doc.js";
+import { findStructNode } from "./find-struct-node.js";
+import { resolveFieldBinding } from "./resolve-field-binding.js";
+
+/**
+ * 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.
+ */
+export 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).
+ */
+export function collectFieldInfo(
+  ctx: CodegenContext,
+  structType: Extract<BoundType, { kind: "struct" }>,
+): Map<string, FieldInfo> {
+  const info = new Map<string, FieldInfo>();
+
+  const structNode = findStructNode(ctx.expr, ctx, structType);
+  if (!structNode) return info;
+
+  for (const child of structNode.attrs.nodes) {
+    const match = resolveFieldBinding(child, ctx, structType);
+    if (!match) continue;
+    const { binding, wrapperNode } = match;
+    const fieldInfo: FieldInfo = {};
+    const fieldType = structType.fields[binding.name]!;
+    // Check wrapper node first (doc may be hoisted there), then binding node
+    const doc = findDoc(wrapperNode, fieldType) ?? findDoc(binding.node, fieldType);
+    if (doc) fieldInfo.doc = doc;
+    const defaultValue = wrapperNode.meta?.defaultValue ?? binding.node.meta?.defaultValue;
+    if (defaultValue !== undefined) fieldInfo.defaultValue = defaultValue;
+    info.set(binding.name, fieldInfo);
+  }
+
+  return info;
+}

package/src/backend/collect-named-types.ts

@@ -0,0 +1,103 @@
+import type { BoundType } from "../bindings/index.js";
+import { Scope } from "./scope.js";
+import { structKey, unionKey } from "./type-keys.js";
+
+/** A named compound type (struct or union) discovered during type collection. */
+export 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.
+ */
+export function collectNamedTypes(
+  rootType: BoundType,
+  rootName: string,
+  scope: Scope,
+  nameTransform: (hint: string) => string,
+  nestedPrefix = "",
+): { namedTypes: Map<string, string>; typeDecls: NamedType[] } {
+  const namedTypes = new Map<string, string>();
+  const typeDecls: NamedType[] = [];
+
+  function nameFor(hint: string, isRoot: boolean): string {
+    const cased = isRoot ? nameTransform(hint) : nestedPrefix + nameTransform(hint);
+    // Dedup in the cased (emitted) namespace, folding any disambiguation suffix
+    // back through nameTransform so a collision yields e.g. `Config2`, not the
+    // mixed-case `Config_2`. Uniqueness is still checked on the final form, so
+    // two hints that case-collide get distinct names.
+    return scope.add(cased, nameTransform);
+  }
+
+  function visit(type: BoundType, hint: string, isRoot: boolean): void {
+    switch (type.kind) {
+      case "struct": {
+        const key = structKey(type);
+        if (!namedTypes.has(key)) {
+          const name = nameFor(hint, isRoot);
+          namedTypes.set(key, name);
+          typeDecls.push({ name, type });
+          for (const [fieldName, fieldType] of Object.entries(type.fields)) {
+            visit(fieldType, fieldName, false);
+          }
+        }
+        break;
+      }
+      case "union": {
+        const key = unionKey(type);
+        if (!namedTypes.has(key)) {
+          const name = nameFor(hint, isRoot);
+          namedTypes.set(key, name);
+          typeDecls.push({ name, type });
+          for (const v of type.variants) {
+            visit(v.type, v.name ?? hint, false);
+          }
+        }
+        break;
+      }
+      // Wrappers are transparent: an optional/list at the root still names its
+      // inner type as the root (no prefix), matching the pre-prefix behavior.
+      case "optional":
+        visit(type.inner, hint, isRoot);
+        break;
+      case "list":
+        visit(type.item, hint, isRoot);
+        break;
+      default:
+        break;
+    }
+  }
+
+  visit(rootType, rootName, true);
+  return { namedTypes, typeDecls };
+}
+
+/**
+ * Create a type name resolver from a namedTypes map.
+ * Returns a function that maps a BoundType to its assigned name (if any).
+ */
+export function resolveTypeName(
+  namedTypes: Map<string, string>,
+): (type: BoundType) => string | undefined {
+  return (type) => {
+    if (type.kind === "struct") return namedTypes.get(structKey(type));
+    if (type.kind === "union") return namedTypes.get(unionKey(type));
+    return undefined;
+  };
+}

package/src/backend/collect-output-fields.ts

@@ -0,0 +1,222 @@
+import type { BindingId, GateAtom, ResolvedOutput } from "../bindings/index.js";
+import { outputGate } from "../bindings/index.js";
+import type { Documentation, Expr } from "../ir/index.js";
+import type { CodegenContext } from "../manifest/index.js";
+
+/**
+ * Language-agnostic collection of a tool's Outputs object: the set of output
+ * files it produces (resolved outputs + mutable inputs surfaced as outputs)
+ * plus its captured stdout/stderr streams. Both the Python and TypeScript
+ * backends, and the JSON Schema backend, consume this single source of truth so
+ * the three describe the same Outputs shape (previously this logic was
+ * near-duplicated between the two `outputs-emit.ts` files). Identifier
+ * sanitization is the one language-specific concern, so callers pass an `idOf`
+ * mapping a raw output name to their target language's field identifier; the
+ * dedup space is keyed by that id, matching each backend's own field set.
+ */
+
+/**
+ * A `ResolvedOutput` plus a `mutable` marker. A mutable input file is surfaced
+ * as an output: its single ref token points at the input binding, and the
+ * backend emits a writable-copy call (`mutable_copy` / `mutableCopy`) - the
+ * host path of the copy the runner staged for the matching mutable input -
+ * instead of `output_file` / `outputFile`.
+ */
+export type EmittedOutput = ResolvedOutput & { mutable?: boolean };
+
+/**
+ * The synthetic `root` output: the runner's output directory itself, surfaced as
+ * an always-present, non-gated `OutputPathType` field. Modeled as a regular
+ * `ResolvedOutput` with a single literal `"."` token so it flows through the
+ * exact same collection and emit machinery as every declared output - its empty
+ * gate makes it a required single, rendered as `output_file(".")` /
+ * `outputFile(".")`. Because every tool emits it, every tool returns a
+ * non-empty Outputs object (matching styx v1, which always carried `root`).
+ */
+export function rootOutput(ctx: CodegenContext, idOf: (name: string) => string): EmittedOutput {
+  // Reserve a non-colliding field id. If a tool genuinely declares an output (or
+  // a mutable input surfaced as an output) whose id sanitizes to "root", the
+  // synthetic output-dir field dodges with a trailing "_" so it never silently
+  // clobbers that real output (or flips it optional via shape merging).
+  const taken = new Set<string>();
+  for (const scope of ctx.outputScopes) for (const o of scope.outputs) taken.add(idOf(o.name));
+  for (const o of collectMutableOutputs(ctx)) taken.add(idOf(o.name));
+  let name = "root";
+  while (taken.has(idOf(name))) name += "_";
+  return { name, tokens: [{ kind: "literal", value: "." }] };
+}
+
+/**
+ * Field shape for a single resolved output.
+ *
+ * - `single`: emitted at most once. Optional iff any `present`/`variant` atom
+ *   appears in the gate (the value may be absent under that gate).
+ * - `list`: emitted once per element of an iterated binding (any `iter` atom in
+ *   the gate). A gated list still types as a list - the empty list stands for
+ *   "nothing produced".
+ */
+export type OutputShape = { kind: "single"; optional: boolean } | { kind: "list" };
+
+export function outputShape(gate: GateAtom[]): OutputShape {
+  const iter = gate.some((a) => a.kind === "iter");
+  if (iter) return { kind: "list" };
+  const optional = gate.some((a) => a.kind === "present" || a.kind === "variant");
+  return { kind: "single", optional };
+}
+
+/**
+ * Merge two shapes for outputs that share a field name across scopes/variants.
+ * Any iterated contributor makes the field a list; otherwise it is a single
+ * field that is optional if any contributor is gated.
+ */
+export function mergeShape(a: OutputShape, b: OutputShape): OutputShape {
+  if (a.kind === "list" || b.kind === "list") return { kind: "list" };
+  return { kind: "single", optional: a.optional || b.optional };
+}
+
+/** One collected Outputs field, deduped across same-named outputs. */
+export interface OutputField {
+  /** Backend-sanitized field identifier (via the caller's `idOf`). */
+  id: string;
+  /** First-seen raw output name (the descriptor's output id). */
+  name: string;
+  shape: OutputShape;
+  doc?: string;
+}
+
+/**
+ * Collect the unique Outputs fields in first-seen order, merging the shape and
+ * doc of any outputs that resolve to the same field id. Multiple scopes (e.g.
+ * the arms of a union output) routinely declare the same output name; without
+ * deduping a backend would emit duplicate fields (a Python SyntaxError, a TS
+ * duplicate member). `idOf` maps a raw output name to the target language's
+ * sanitized identifier, so two raw names that collapse to the same identifier
+ * merge into one field - exactly the field set the backend will emit.
+ */
+export function collectOutputFields(
+  ctx: CodegenContext,
+  idOf: (name: string) => string,
+): OutputField[] {
+  const byId = new Map<string, OutputField>();
+  const add = (output: EmittedOutput, scopeGate: GateAtom[]): void => {
+    const gate = outputGate(scopeGate, output, ctx.bindings);
+    const shape = outputShape(gate);
+    const id = idOf(output.name);
+    const doc = output.doc?.description ?? output.doc?.title;
+    const existing = byId.get(id);
+    if (existing) {
+      existing.shape = mergeShape(existing.shape, shape);
+      if (!existing.doc && doc) existing.doc = doc;
+    } else {
+      byId.set(id, { id, name: output.name, shape, doc });
+    }
+  };
+  // The output directory itself, always present and ungated, listed first.
+  add(rootOutput(ctx, idOf), []);
+  for (const scope of ctx.outputScopes) {
+    const scopeBinding = ctx.bindings.get(scope.scope);
+    const scopeGate = scopeBinding?.gate ?? [];
+    for (const output of scope.outputs) add(output, scopeGate);
+  }
+  // Mutable inputs surface as outputs; their binding gate is absolute (rooted),
+  // so the scope gate is empty.
+  for (const output of collectMutableOutputs(ctx)) add(output, []);
+  return [...byId.values()];
+}
+
+/** Has any scope in the context attached at least one output? */
+export function hasAnyOutputs(ctx: CodegenContext): boolean {
+  return ctx.outputScopes.some((s) => s.outputs.length > 0);
+}
+
+/** A captured stream (stdout/stderr), surfaced as a list-of-lines Outputs field. */
+export interface StreamField {
+  /** First-seen raw stream name, bumped with a trailing `_` to dodge collisions. */
+  name: string;
+  /** Backend-sanitized identifier for `name` (via the caller's `idOf`). */
+  id: string;
+  doc?: string;
+}
+
+/**
+ * The stdout/stderr fields declared by the app metadata, in declaration order
+ * (stdout before stderr). Stream outputs are app-level: never gated (always
+ * present when the tool runs), so they bypass the solver/gating machinery and
+ * surface as plain list-of-string fields the wrapper appends to via the
+ * `handle_stdout` / `handle_stderr` (Python) or `handleStdout` / `handleStderr`
+ * (TS) callbacks. A stream whose sanitized id collides with a real output's id
+ * is bumped (raw name gains a trailing `_`, re-sanitized) so it never shadows a
+ * file output / emits a duplicate field.
+ */
+export function streamFields(ctx: CodegenContext, idOf: (name: string) => string): StreamField[] {
+  const out: StreamField[] = [];
+  // Seed with the file/mutable output field ids so a stream whose name collides
+  // with a real output (e.g. an output literally named "stdout") is bumped
+  // rather than emitting a duplicate field / repeated constructor argument.
+  const used = new Set<string>(collectOutputFields(ctx, idOf).map((f) => f.id));
+  const add = (rawName: string, doc?: string): void => {
+    let name = rawName;
+    while (used.has(idOf(name))) name += "_";
+    used.add(idOf(name));
+    out.push({ name, id: idOf(name), doc });
+  };
+  const so = ctx.app?.stdout;
+  const se = ctx.app?.stderr;
+  if (so) add(so.name, so.doc?.description ?? so.doc?.title);
+  if (se) add(se.name, se.doc?.description ?? se.doc?.title);
+  return out;
+}
+
+/** Does the app declare any stdout/stderr stream output? */
+export function hasStreamOutputs(ctx: CodegenContext): boolean {
+  return !!(ctx.app?.stdout || ctx.app?.stderr);
+}
+
+/**
+ * Synthesize one output per mutable file input. Each is a `ResolvedOutput` with
+ * a single ref token to the input binding and the `mutable` marker. The input
+ * binding's solver-assigned gate fully encodes its ancestry (optional/variant/
+ * iterated), so `outputGate([], ...)` yields the correct shape and gating for
+ * free - no scope bucket needed.
+ */
+export function collectMutableOutputs(ctx: CodegenContext): EmittedOutput[] {
+  const out: EmittedOutput[] = [];
+  const seen = new Set<BindingId>();
+  const walk = (node: Expr, inheritedDoc?: Documentation): void => {
+    if (node.kind === "path") {
+      if (node.attrs.mutable) {
+        const binding = ctx.resolve(node);
+        if (binding && !seen.has(binding.id)) {
+          seen.add(binding.id);
+          const doc = node.meta?.doc ?? inheritedDoc;
+          out.push({
+            name: binding.name,
+            tokens: [{ kind: "ref", binding: binding.id }],
+            ...(doc && { doc }),
+            mutable: true,
+          });
+        }
+      }
+      return;
+    }
+    switch (node.kind) {
+      case "sequence":
+        for (const child of node.attrs.nodes) walk(child);
+        break;
+      case "optional":
+      case "repeat":
+        walk(node.attrs.node, node.meta?.doc ?? inheritedDoc);
+        break;
+      case "alternative":
+        for (const alt of node.attrs.alts) walk(alt, node.meta?.doc ?? inheritedDoc);
+        break;
+    }
+  };
+  walk(ctx.expr);
+  return out;
+}
+
+/** Does the tool have any mutable file input (surfaced as an output)? */
+export function hasMutableInputs(ctx: CodegenContext): boolean {
+  return collectMutableOutputs(ctx).length > 0;
+}

package/src/backend/find-doc.ts

@@ -0,0 +1,38 @@
+import type { BoundType } from "../bindings/index.js";
+import type { Expr } from "../ir/index.js";
+
+/**
+ * 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.
+ */
+export function findDoc(node: Expr, fieldType: BoundType): string | undefined {
+  if (node.meta?.doc?.description) return node.meta.doc.description;
+  switch (node.kind) {
+    case "optional":
+      return findDoc(node.attrs.node, fieldType.kind === "optional" ? fieldType.inner : fieldType);
+    case "repeat":
+      return findDoc(node.attrs.node, fieldType.kind === "list" ? fieldType.item : fieldType);
+    case "sequence": {
+      // Only traverse into sequences that were collapsed (non-struct field types).
+      // Struct sequences have their own collectFieldInfo call for their children.
+      if (fieldType.kind === "struct") return undefined;
+      for (const child of node.attrs.nodes) {
+        const doc = findDoc(child, fieldType);
+        if (doc) return doc;
+      }
+      return undefined;
+    }
+    default:
+      return undefined;
+  }
+}

package/src/backend/find-struct-node.ts

@@ -0,0 +1,66 @@
+import type { BoundType } from "../bindings/index.js";
+import type { Expr } from "../ir/index.js";
+import type { CodegenContext } from "../manifest/index.js";
+import { resolveFieldBinding } from "./resolve-field-binding.js";
+
+/**
+ * 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))`).
+ */
+export function findStructNode(
+  node: Expr,
+  ctx: CodegenContext,
+  structType: Extract<BoundType, { kind: "struct" }>,
+): Extract<Expr, { kind: "sequence" }> | undefined {
+  switch (node.kind) {
+    case "sequence": {
+      // Phase 1: Check if any direct child has a binding matching a struct field
+      for (const child of node.attrs.nodes) {
+        const binding = ctx.resolve(child);
+        if (
+          binding &&
+          binding.name in structType.fields &&
+          binding.type === structType.fields[binding.name]
+        ) {
+          return node;
+        }
+      }
+      // Recurse into child nodes first (prefer deeper matches)
+      for (const child of node.attrs.nodes) {
+        const result = findStructNode(child, ctx, structType);
+        if (result) return result;
+      }
+      // Phase 2: Check via resolveFieldBinding for collapsed sequences
+      // where bindings are buried inside collapsed seq(lit, terminal)
+      for (const child of node.attrs.nodes) {
+        if (resolveFieldBinding(child, ctx, structType)) return node;
+      }
+      return undefined;
+    }
+    case "optional":
+      return findStructNode(node.attrs.node, ctx, structType);
+    case "repeat":
+      return findStructNode(node.attrs.node, ctx, structType);
+    case "alternative": {
+      for (const alt of node.attrs.alts) {
+        const result = findStructNode(alt, ctx, structType);
+        if (result) return result;
+      }
+      return undefined;
+    }
+    default:
+      return undefined;
+  }
+}

package/src/backend/index.ts

@@ -0,0 +1,39 @@
+export type {
+  Backend,
+  EmitError,
+  EmitResult,
+  EmittedApp,
+  EmittedPackage,
+  EmitWarning,
+  TypeMap,
+} from "./backend.js";
+export { BoutiquesBackend, generateBoutiques } from "./boutiques/index.js";
+export { CodeBuilder } from "./code-builder.js";
+export type { FieldInfo } from "./collect-field-info.js";
+export { collectFieldInfo } from "./collect-field-info.js";
+export type { NamedType } from "./collect-named-types.js";
+export { collectNamedTypes, resolveTypeName } from "./collect-named-types.js";
+export { findDoc } from "./find-doc.js";
+export { findStructNode } from "./find-struct-node.js";
+export { resolveFieldBinding } from "./resolve-field-binding.js";
+export type { OutputEmitPlan } from "./resolve-output-tokens.js";
+export {
+  compactTokens,
+  isGated,
+  isIterated,
+  outputGate,
+  planOutput,
+  planScope,
+} from "./resolve-output-tokens.js";
+export { generatePython, PythonBackend, renderPythonCall } from "./python/index.js";
+export { Scope } from "./scope.js";
+export type { JsonSchema } from "./schema/index.js";
+export { generateOutputsSchema, generateSchema, JsonSchemaBackend } from "./schema/index.js";
+export { buildSigEntries } from "./sig-entries.js";
+export type { SigEntry, SigOptions } from "./sig-entries.js";
+export { renderStructLiteral, renderValue } from "./snippet-core.js";
+export type { SnippetDialect, SnippetOptions } from "./snippet-core.js";
+export { camelCase, pascalCase, screamingSnakeCase, snakeCase } from "./string-case.js";
+export { PYTHON_RUNNER_DEPS, STYXDEFS_COMPAT } from "./styxdefs-compat.js";
+export { structKey, typeKey, unionKey } from "./type-keys.js";
+export { generateTypeScript, renderTypeScriptCall, TypeScriptBackend } from "./typescript/index.js";