@flowwright/core

@flowwright/core is FlowWright’s dependency-free authoring SDK and execution-plan contract. Pipeline closures record intent into a serializable, versioned IR that can be validated before any command executes.

FlowWright · CLI · Authoring guide

Use it

import {
  pipeline,
  stage,
  sh,
  onBranch,
  compilePipeline,
} from "@flowwright/core";

const definition = pipeline({
  name: "web-app",
  stages: [
    stage("Test", async () => {
      await sh`pnpm test`;
    }),
    stage("Deploy", {
      needs: ["test"],
      when: onBranch("main"),
      run: async () => void (await sh`pnpm deploy`),
    }),
  ],
});

const result = await compilePipeline(definition);
if (!result.ok) throw new Error(result.errors[0]?.message);

console.log(result.plan); // serializable ExecutionPlan

sh, artifact, and cache record during compilation; they do not execute commands in this package. The runtime consumes the resulting plan later.

Public surface

| Area | Main exports | |---|---| | Authoring | pipeline, stage, matrix, sh, artifact, cache, hashFiles | | Conditions | onBranch, onTag, and typed WhenDescriptor values | | Recording | buildExecutionPlan, compilePipeline | | Validation | validateExecutionPlan, validation result and error types | | Policy | policy, evaluatePolicy, Policy | | Contracts | ExecutionPlan, stage and step types, ExecEvent, status types, IR_VERSION |

The @flowwright/core/ir subpath exposes the IR contract directly.

Design boundary

pipeline closures ──record──▶ ExecutionPlan ──validate──▶ runtime

• Closures build the plan but never cross the definition-to-execution boundary.
• Stage bodies run once in recording mode with effect primitives replaced by recorders.
• A body that cannot be fully recorded is marked dynamic rather than silently executed.
• The IR remains plain serializable data suitable for validation, policy, storage, and transport.
• This package does not schedule stages, spawn processes, persist runs, or serve HTTP.

Development

$ pnpm --filter @flowwright/core typecheck
$ pnpm --filter @flowwright/core test
$ pnpm --filter @flowwright/core build

Tests cover pipeline recording, stable stage IDs, matrices, command forms, file hashing, IR validation, and policy evaluation.

Requires Node.js 24+. Licensed under MIT.