@barnum/barnum 0.3.0 → 0.4.0

package/src/run.ts

@@ -8,9 +8,22 @@ import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import type { Action, Config, ExtractOutput, Pipeable } from "./ast.js";
+import {
+  type Action,
+  type Config,
+  type ExtractOutput,
+  toAction,
+} from "./ast.js";
 import { chain } from "./chain.js";
-import { constant } from "./builtins.js";
+import { constant } from "./builtins/index.js";
+
+/** Log verbosity for the barnum engine runtime. Passed to the CLI's `--log-level`. */
+export type LogLevel = "off" | "error" | "warn" | "info" | "debug" | "trace";
+
+export interface RunPipelineOptions {
+  /** Engine log verbosity. Default: "off" (only handler stderr is visible). */
+  logLevel?: LogLevel;
+}
 
 const __dirname = import.meta.dirname;
 
@@ -101,12 +114,17 @@ function resolveWorker(): string {
   return path.resolve(__dirname, "../src/worker.ts");
 }
 
-/** Build the barnum binary if using the local dev path. */
-function buildBinary(): void {
+/** Build the barnum binary if using the local dev path. Skips if binary already exists. */
+function buildBinaryIfNeeded(binaryPath: string): void {
+  if (existsSync(binaryPath)) {
+    return;
+  }
   const repoRoot = path.resolve(__dirname, "../../..");
+  // eslint-disable-next-line no-console
+  console.error("[barnum] building CLI binary (cargo build -p barnum_cli)...");
   execFileSync("cargo", ["build", "-p", "barnum_cli"], {
     cwd: repoRoot,
-    stdio: "ignore",
+    stdio: "inherit",
   });
 }
 
@@ -114,54 +132,64 @@ function buildBinary(): void {
 export function runPipeline<TPipeline extends Action>(
   pipeline: TPipeline,
   input?: unknown,
+  options?: RunPipelineOptions,
 ): Promise<ExtractOutput<TPipeline>> {
   const workflow =
     input === undefined
       ? pipeline
-      : (chain(constant(input) as Pipeable, pipeline as Pipeable) as Action);
-  return spawnBarnum({ workflow });
+      : toAction(chain(toAction(constant(input)), toAction(pipeline)));
+  return spawnBarnum({ workflow }, options?.logLevel);
 }
 
 /** Spawn the barnum CLI with the given config. Returns the parsed final value from stdout. */
-function spawnBarnum<TOut>(config: Config): Promise<TOut> {
+function spawnBarnum<TOut>(config: Config, logLevel?: LogLevel): Promise<TOut> {
   const binaryResolution = resolveBinary();
   if (binaryResolution.kind === "Local") {
-    buildBinary();
+    buildBinaryIfNeeded(binaryResolution.path);
   }
   const executor = resolveExecutor();
   const worker = resolveWorker();
   const configJson = JSON.stringify(config);
 
+  const cliArgs = [
+    "run",
+    "--config",
+    configJson,
+    "--executor",
+    executor,
+    "--worker",
+    worker,
+  ];
+  if (logLevel) {
+    cliArgs.push("--log-level", logLevel);
+  }
+
   return new Promise<TOut>((resolve, reject) => {
-    const child = nodeSpawn(
-      binaryResolution.path,
-      [
-        "run",
-        "--config",
-        configJson,
-        "--executor",
-        executor,
-        "--worker",
-        worker,
-      ],
-      {
-        stdio: ["inherit", "pipe", "inherit"],
-      },
-    );
+    const child = nodeSpawn(binaryResolution.path, cliArgs, {
+      stdio: ["inherit", "pipe", "pipe"],
+    });
 
     const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
 
     child.stdout?.on("data", (chunk: Buffer) => {
       stdoutChunks.push(chunk);
     });
 
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderrChunks.push(chunk);
+      process.stderr.write(chunk);
+    });
+
     child.on("error", (error) => {
       reject(new Error(`Failed to spawn barnum: ${error.message}`));
     });
 
     child.on("close", (code) => {
       if (code !== 0) {
-        reject(new Error(`barnum exited with code ${code}`));
+        const stderr = Buffer.concat(stderrChunks).toString("utf8").trim();
+        const detail = stderr ? `\n${stderr}` : "";
+        reject(new Error(`barnum exited with code ${code}${detail}`));
         return;
       }
       const stdout = Buffer.concat(stdoutChunks).toString("utf8").trim();

package/src/runtime.ts

@@ -0,0 +1,16 @@
+// Runtime value constructors
+export { ok, err, some, none } from "./values.js";
+
+// Handler creation
+export {
+  createHandler,
+  createHandlerWithConfig,
+  type Handler,
+} from "./handler.js";
+
+// Schema builders
+export { resultSchema, optionSchema } from "./schemas.js";
+export { taggedUnionSchema } from "./builtins/index.js";
+
+// Types only
+export type { Result, Option, TaggedUnion } from "./ast.js";

package/src/schemas.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import type { Result, Option } from "./ast.js";
+
+export function resultSchema<TValue, TError>(
+  okSchema: z.ZodType<TValue>,
+  errSchema: z.ZodType<TError>,
+): z.ZodType<Result<TValue, TError>> {
+  return z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("Result.Ok"), value: okSchema }),
+    z.object({ kind: z.literal("Result.Err"), value: errSchema }),
+  ]) as z.ZodType<Result<TValue, TError>>;
+}
+
+export function optionSchema<TValue>(
+  valueSchema: z.ZodType<TValue>,
+): z.ZodType<Option<TValue>> {
+  return z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("Option.Some"), value: valueSchema }),
+    z.object({ kind: z.literal("Option.None"), value: z.null() }),
+  ]) as z.ZodType<Option<TValue>>;
+}

package/src/try-catch.ts

@@ -1,11 +1,12 @@
 import {
-  type Action,
   type Pipeable,
   type TypedAction,
+  toAction,
   typedAction,
   buildRestartBranchAction,
-  TAG_BREAK,
 } from "./ast.js";
+import { chain } from "./chain.js";
+import { tag } from "./builtins/index.js";
 import { allocateRestartHandlerId } from "./effect-id.js";
 
 // ---------------------------------------------------------------------------
@@ -25,7 +26,7 @@ import { allocateRestartHandlerId } from "./effect-id.js";
  *
  * Compiled form (restart+Branch, same substrate as loop/earlyReturn):
  *   `Chain(Tag("Continue"),`
- *     `RestartHandle(id, ExtractIndex(0),`
+ *     `RestartHandle(id, GetIndex(0),`
  *       `Branch({ Continue: body, Break: recovery })))`
  *
  * throwError = `Chain(Tag("Break"), RestartPerform(id))`
@@ -39,15 +40,18 @@ export function tryCatch<TIn, TOut, TError>(
 ): TypedAction<TIn, TOut> {
   const restartHandlerId = allocateRestartHandlerId();
 
-  const throwError = typedAction<TError, never>({
-    kind: "Chain",
-    first: TAG_BREAK,
-    rest: { kind: "RestartPerform", restart_handler_id: restartHandlerId },
-  });
+  const throwError = typedAction<TError, never>(
+    toAction(
+      chain(toAction(tag("Break", "LoopResult")), {
+        kind: "RestartPerform",
+        restart_handler_id: restartHandlerId,
+      }),
+    ),
+  );
 
-  const bodyAction = body(throwError) as Action;
+  const bodyAction = toAction(body(throwError));
 
   return typedAction(
-    buildRestartBranchAction(restartHandlerId, bodyAction, recovery as Action),
+    buildRestartBranchAction(restartHandlerId, bodyAction, toAction(recovery)),
   );
 }

package/src/values.ts

@@ -0,0 +1,21 @@
+import type { Result, Option } from "./ast.js";
+
+export function ok<TValue, TError = unknown>(
+  value: TValue,
+): Result<TValue, TError> {
+  return { kind: "Result.Ok", value } as Result<TValue, TError>;
+}
+
+export function err<TValue = unknown, TError = never>(
+  error: TError,
+): Result<TValue, TError> {
+  return { kind: "Result.Err", value: error } as Result<TValue, TError>;
+}
+
+export function some<T>(value: T): Option<T> {
+  return { kind: "Option.Some", value } as Option<T>;
+}
+
+export function none<T = unknown>(): Option<T> {
+  return { kind: "Option.None", value: null } as Option<T>;
+}

package/src/worker.ts

@@ -5,10 +5,20 @@
  *   Rust → stdin:  JSON `{ "value": <any> }`
  *   stdout → Rust: JSON result (handler return value)
  *
+ * stdout is reserved for the protocol. All console output is redirected to
+ * stderr so that handler code can freely use console.log for debugging.
+ *
  * If the handler throws or the module/export can't be resolved, the
  * process exits non-zero. Rust interprets that as a fatal workflow error.
  */
 
+// Redirect all console output to stderr — stdout is the protocol channel.
+// This must happen before any handler code is imported or executed.
+import { Console } from "node:console";
+
+const stderrConsole = new Console({ stdout: process.stderr });
+globalThis.console = stderrConsole;
+
 // Suppress EPIPE — when the Rust binary exits (e.g., a race was resolved),
 // orphan workers get broken pipe on stdout. This is expected, not an error.
 process.stdout.on("error", (error: NodeJS.ErrnoException) => {
@@ -46,8 +56,13 @@ async function main(): Promise<void> {
 
   const result = await handler.__definition.handle({ value: input.value });
 
-  // Write result to stdout
-  process.stdout.write(JSON.stringify(result) ?? "null");
+  // Write result to stdout, then exit. Explicit exit is required because
+  // importing the handler module may leave open handles (timers, servers,
+  // etc.) that keep the Node event loop alive indefinitely.
+  const json = JSON.stringify(result) ?? "null";
+  process.stdout.write(json, () => {
+    process.exit(0);
+  });
 }
 
 main().catch((error) => {

package/dist/builtins.d.ts

@@ -1,257 +0,0 @@
-import { type Action, type Option as OptionT, type Pipeable, type Result as ResultT, type TaggedUnion, type TypedAction } from "./ast.js";
-/**
- * Typed combinators for structural data transformations.
- *
- * All builtins emit `{ kind: "Builtin", builtin: { kind: ... } }` handler
- * kinds. The Rust scheduler executes them inline (no subprocess).
- */
-export declare function constant<TValue>(value: TValue): TypedAction<any, TValue>;
-export declare const identity: TypedAction<any, any>;
-export declare const drop: TypedAction<any, never>;
-/**
- * Wrap input as a tagged union member. Requires the full variant map TDef
- * so the output type carries __def for branch decomposition.
- *
- * Usage: tag<{ Ok: string; Err: number }, "Ok">("Ok")
- *        input: string → output: TaggedUnion<{ Ok: string; Err: number }>
- */
-export declare function tag<TDef extends Record<string, unknown>, TKind extends keyof TDef & string>(kind: TKind): TypedAction<TDef[TKind], TaggedUnion<TDef>>;
-type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
-export declare function merge<TObjects extends Record<string, unknown>[]>(): TypedAction<TObjects, UnionToIntersection<TObjects[number]>>;
-export declare function flatten<TElement>(): TypedAction<TElement[][], TElement[]>;
-export declare function extractField<TObj extends Record<string, unknown>, TField extends keyof TObj & string>(field: TField): TypedAction<TObj, TObj[TField]>;
-export declare function extractIndex<TTuple extends unknown[], TIndex extends number>(index: TIndex): TypedAction<TTuple, TTuple[TIndex]>;
-export declare function pick<TObj extends Record<string, unknown>, TKeys extends (keyof TObj & string)[]>(...keys: TKeys): TypedAction<TObj, Pick<TObj, TKeys[number]>>;
-export declare function dropResult<TInput, TOutput>(action: Pipeable<TInput, TOutput>): TypedAction<TInput, never>;
-/**
- * RAII-style resource management combinator.
- *
- * Runs `create` to acquire a resource, then merges the resource with the
- * original input into a flat object (`TResource & TIn`) for the action.
- * After the action completes, `dispose` receives the resource for cleanup.
- * The overall combinator returns the action's output.
- *
- * ```
- * TIn → create → TResource
- *     → merge(TResource, TIn) → TResource & TIn
- *     → action(TResource & TIn) → TOut
- *     → dispose(TResource) → (discarded)
- *     → TOut
- * ```
- */
-export declare function withResource<TIn extends Record<string, unknown>, TResource extends Record<string, unknown>, TOut, TDisposeOut = unknown>({ create, action, dispose, }: {
-    create: Pipeable<TIn, TResource>;
-    action: Pipeable<TResource & TIn, TOut>;
-    dispose: Pipeable<TResource, TDisposeOut>;
-}): TypedAction<TIn, TOut>;
-/**
- * Run `action` on the input, then merge the action's output fields back
- * into the original input object. The action must accept exactly `TInput`.
- * Use `pick` inside the action's pipe if the inner handler needs a subset.
- *
- * Example:
- *   augment(pipe(pick("file"), migrate))
- *   // { file, outputPath } → { file, outputPath, content, migrated }
- */
-export declare function augment<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>>(action: Pipeable<TInput, TOutput>): TypedAction<TInput, TInput & TOutput>;
-/**
- * Run `action` on the input for its side effects, then discard the action's
- * output and return the original input unchanged. The action must accept
- * exactly `TInput`. Use `pick` inside the action's pipe if the inner
- * handler needs a subset.
- *
- * Constraint: input must be an object (uses augment internally, which
- * relies on all + merge).
- *
- * Example:
- *   pipe(tap(pipe(pick("worktreePath", "description"), implement)), createPR)
- */
-export declare function tap<TInput extends Record<string, unknown>>(action: Pipeable<TInput, any>): TypedAction<TInput, TInput>;
-export declare function range(start: number, end: number): TypedAction<any, number[]>;
-/**
- * Option namespace. All combinators produce TypedAction AST nodes that
- * desugar to branch + existing builtins, except collect which uses the
- * CollectSome builtin.
- */
-export declare const Option: {
-    /**
-     * Wrap a value as Some. `T → Option<T>`
-     *
-     * Equivalent to `tag<OptionDef<T>, "Some">("Some")`.
-     */
-    readonly some: <T>() => TypedAction<T, OptionT<T>>;
-    /**
-     * Produce a None. `never → Option<T>`
-     *
-     * Chain after `.drop()` to discard the current value first.
-     * Equivalent to `tag<OptionDef<T>, "None">("None")`.
-     */
-    readonly none: <T>() => TypedAction<never, OptionT<T>>;
-    /**
-     * Transform the Some value. `Option<T> → Option<U>`
-     *
-     * Desugars to: `branch({ Some: pipe(action, tag("Some")), None: tag("None") })`
-     */
-    readonly map: <T, U>(action: Pipeable<T, U>) => TypedAction<OptionT<T>, OptionT<U>>;
-    /**
-     * Monadic bind (flatMap). If Some, pass the value to action which
-     * returns Option<U>. If None, stay None. `Option<T> → Option<U>`
-     *
-     * This is the most fundamental combinator — map, flatten, and filter
-     * are all derivable from andThen + constructors.
-     *
-     * Desugars to: `branch({ Some: action, None: tag("None") })`
-     */
-    readonly andThen: <T, U>(action: Pipeable<T, OptionT<U>>) => TypedAction<OptionT<T>, OptionT<U>>;
-    /**
-     * Extract the Some value or produce a default from an action.
-     * `Option<T> → T`
-     *
-     * The defaultAction takes no meaningful input (never) and must produce T.
-     * Use `Option.unwrapOr(constant("fallback"))`.
-     *
-     * The None branch drops its void payload before calling defaultAction,
-     * matching Rust's `unwrap_or_else(|| default)` where the closure takes
-     * no arguments.
-     *
-     * Desugars to: `branch({ Some: identity(), None: pipe(drop(), defaultAction) })`
-     */
-    readonly unwrapOr: <T>(defaultAction: Pipeable<never, T>) => TypedAction<OptionT<T>, T>;
-    /**
-     * Unwrap a nested Option. `Option<Option<T>> → Option<T>`
-     *
-     * Desugars to: `branch({ Some: identity(), None: tag("None") })`
-     */
-    readonly flatten: <T>() => TypedAction<OptionT<OptionT<T>>, OptionT<T>>;
-    /**
-     * Conditional keep. If Some, pass value to predicate which returns
-     * Option<T> (some() to keep, none() to discard). If None, stay None.
-     * `Option<T> → Option<T>`
-     *
-     * This has the same signature and desugaring as andThen with T=U.
-     * Named "filter" for readability when the intent is filtering.
-     *
-     * Desugars to: `branch({ Some: predicate, None: tag("None") })`
-     */
-    readonly filter: <T>(predicate: Pipeable<T, OptionT<T>>) => TypedAction<OptionT<T>, OptionT<T>>;
-    /**
-     * Collect Some values from an array, discarding Nones.
-     * `Option<T>[] → T[]`
-     *
-     * This is a builtin handler (CollectSome) — it can't be expressed
-     * as a composition of existing AST nodes because it requires
-     * array-level filtering logic.
-     */
-    readonly collect: <T = any>() => TypedAction<OptionT<T>[], T[]>;
-    /**
-     * Test if the value is Some. `Option<T> → boolean`
-     *
-     * Rarely useful — branch on Some/None directly instead.
-     *
-     * Desugars to: `branch({ Some: pipe(drop(), constant(true)), None: pipe(drop(), constant(false)) })`
-     */
-    readonly isSome: <T>() => TypedAction<OptionT<T>, boolean>;
-    /**
-     * Test if the value is None. `Option<T> → boolean`
-     *
-     * Rarely useful — branch on Some/None directly instead.
-     *
-     * Desugars to: `branch({ Some: pipe(drop(), constant(false)), None: pipe(drop(), constant(true)) })`
-     */
-    readonly isNone: <T>() => TypedAction<OptionT<T>, boolean>;
-};
-/**
- * Result namespace. All combinators produce TypedAction AST nodes that
- * desugar to branch + existing builtins.
- */
-export declare const Result: {
-    /**
-     * Wrap a value as Ok. `TValue → Result<TValue, TError>`
-     */
-    readonly ok: <TValue, TError>() => TypedAction<TValue, ResultT<TValue, TError>>;
-    /**
-     * Wrap a value as Err. `TError → Result<TValue, TError>`
-     */
-    readonly err: <TValue, TError>() => TypedAction<TError, ResultT<TValue, TError>>;
-    /**
-     * Transform the Ok value. `Result<TValue, TError> → Result<TOut, TError>`
-     *
-     * Desugars to: `branch({ Ok: pipe(action, tag("Ok")), Err: tag("Err") })`
-     */
-    readonly map: <TValue, TOut, TError>(action: Pipeable<TValue, TOut>) => TypedAction<ResultT<TValue, TError>, ResultT<TOut, TError>>;
-    /**
-     * Transform the Err value. `Result<TValue, TError> → Result<TValue, TErrorOut>`
-     *
-     * Desugars to: `branch({ Ok: tag("Ok"), Err: pipe(action, tag("Err")) })`
-     */
-    readonly mapErr: <TValue, TError, TErrorOut>(action: Pipeable<TError, TErrorOut>) => TypedAction<ResultT<TValue, TError>, ResultT<TValue, TErrorOut>>;
-    /**
-     * Monadic bind (flatMap) for Ok. If Ok, pass value to action which
-     * returns Result<TOut, TError>. If Err, propagate.
-     *
-     * Desugars to: `branch({ Ok: action, Err: tag("Err") })`
-     */
-    readonly andThen: <TValue, TOut, TError>(action: Pipeable<TValue, ResultT<TOut, TError>>) => TypedAction<ResultT<TValue, TError>, ResultT<TOut, TError>>;
-    /**
-     * Fallback on Err. If Ok, keep it. If Err, pass error to fallback
-     * which returns a new Result.
-     *
-     * Desugars to: `branch({ Ok: tag("Ok"), Err: fallback })`
-     */
-    readonly or: <TValue, TError, TErrorOut>(fallback: Pipeable<TError, ResultT<TValue, TErrorOut>>) => TypedAction<ResultT<TValue, TError>, ResultT<TValue, TErrorOut>>;
-    /**
-     * Replace Ok value with another Result. If Ok, discard value and
-     * return other. If Err, propagate.
-     *
-     * Desugars to: `branch({ Ok: pipe(drop(), other), Err: tag("Err") })`
-     */
-    readonly and: <TValue, TOut, TError>(other: Pipeable<never, ResultT<TOut, TError>>) => TypedAction<ResultT<TValue, TError>, ResultT<TOut, TError>>;
-    /**
-     * Extract Ok or compute default from Err. `Result<TValue, TError> → TValue`
-     *
-     * Takes an action that receives the Err payload and produces a fallback.
-     * Uses covariant output checking so throw tokens (Out=never) are assignable
-     * when TValue is provided explicitly: `Result.unwrapOr<string, string>(throwError)`.
-     *
-     * For inference-free usage with throw tokens, prefer the postfix method:
-     * `handler.unwrapOr(throwError)` — the `this` constraint provides TValue.
-     *
-     * Desugars to: `branch({ Ok: identity(), Err: defaultAction })`
-     */
-    readonly unwrapOr: <TValue, TError>(defaultAction: Action & {
-        __in?: (input: TError) => void;
-        __out?: () => TValue;
-    }) => TypedAction<ResultT<TValue, TError>, TValue>;
-    /**
-     * Unwrap nested Result. `Result<Result<TValue, TError>, TError> → Result<TValue, TError>`
-     *
-     * Desugars to: `branch({ Ok: identity(), Err: tag("Err") })`
-     */
-    readonly flatten: <TValue, TError>() => TypedAction<ResultT<ResultT<TValue, TError>, TError>, ResultT<TValue, TError>>;
-    /**
-     * Convert Ok to Some, Err to None. `Result<TValue, TError> → Option<TValue>`
-     *
-     * Desugars to: `branch({ Ok: tag("Some"), Err: pipe(drop(), tag("None")) })`
-     */
-    readonly toOption: <TValue, TError>() => TypedAction<ResultT<TValue, TError>, OptionT<TValue>>;
-    /**
-     * Convert Err to Some, Ok to None. `Result<TValue, TError> → Option<TError>`
-     *
-     * Desugars to: `branch({ Ok: pipe(drop(), tag("None")), Err: tag("Some") })`
-     */
-    readonly toOptionErr: <TValue, TError>() => TypedAction<ResultT<TValue, TError>, OptionT<TError>>;
-    /**
-     * Swap Result/Option nesting.
-     * `Result<Option<TValue>, TError> → Option<Result<TValue, TError>>`
-     */
-    readonly transpose: <TValue, TError>() => TypedAction<ResultT<OptionT<TValue>, TError>, OptionT<ResultT<TValue, TError>>>;
-    /**
-     * Test if the value is Ok. `Result<TValue, TError> → boolean`
-     */
-    readonly isOk: <TValue, TError>() => TypedAction<ResultT<TValue, TError>, boolean>;
-    /**
-     * Test if the value is Err. `Result<TValue, TError> → boolean`
-     */
-    readonly isErr: <TValue, TError>() => TypedAction<ResultT<TValue, TError>, boolean>;
-};
-export {};