tubeless 0.1.0

package/docs/llms.txt

@@ -0,0 +1,62 @@
+# tubeless
+
+> Dependency-free TypeScript primitives for typed, observable data pipelines and their CLI programs.
+
+Start:
+
+- README: ../README.md
+- First pipeline: ./getting-started.md
+- CLI: ./cli.md
+- Local studio: ./studio.md
+- Choose a pattern: ./recipes.md
+- Execution semantics: ./concepts.md
+
+Agent instructions:
+
+- Canonical guide: ./agent-guide.md
+- Maintain stable step IDs.
+- Use optional step names only as display overrides; dependencies and selection use IDs.
+- Use pipeline.toMermaid() to generate static graph documentation.
+- Use tubeless inspect with a pipeline module path for a read-only inventory of identity plus the default plan.
+- Use tubeless plan with a pipeline or marked command module to preview target, exact-step, and dry-run selection without executing or supplying domain options. Prefer the marked command when both are exported. Use command.plan() or tubeless plan; do not simulate planning with --plan.
+- Use tubeless graph with a pipeline module path to print Mermaid without a wrapper script.
+- Use tubeless run only with a definePipelineCommand module; put the command's validated application arguments after --.
+- Set dryRun: "skip" on external side effects, or provide a side-effect-free dryRun handler.
+- Use context.log, context.signal, context.sleep, and progress APIs.
+- Use createPipelineTestRuntime from tubeless/testing for deterministic tests with captured logs, statuses, progress, clock, and cancellation.
+- Compile generated agent submissions with bun run eval:agent --; runtime tests, provider invocation, and semantic assessment remain externally controlled.
+- Use definePipelineCommand for pipeline-backed scripts.
+- Omit mapOptions only when validated CLI flags already satisfy same-name pipeline options; map renamed, loaded, or derived values explicitly.
+- Declare public goals with targets: [step] on definePipeline, then select their
+  IDs to include required inputs and failure gates. stepIds is an exact filter
+  for any step and cannot be combined with targets.
+- Use PipelinePlanStep.selectionReasons for selection explanations; it includes
+  target IDs and immediate dependents, so consumers should not rebuild the graph.
+- Branch on PipelineError code/phase/kind, not message text. Original thrown
+  codes use sourceCode; failed and dependency-blocked reports expose diagnostic metadata.
+- Use requireOutputs for finalizers that need specific completed step outputs.
+- Use createSteps(optionsSchema), outputSchema, and resultSchema for optional
+  dependency-free Standard Schema validation. run supports async schemas;
+  synchronous plan does not invoke schemas.
+- Run make check from the package root after package changes.
+
+Advanced:
+
+- Child pipelines: ./child-pipeline-composition.md
+- Public exports: ./api-reference.md
+- Machine-readable surface: ./api-report.json
+- Agent evaluation cases: ./agent-evaluations.md
+
+Executable examples:
+
+- ../examples/typed-import.ts
+- ../examples/validated-boundaries.ts
+- ../examples/publish-with-gates.ts
+- ../examples/conditional-step.ts
+- ../examples/best-effort.ts
+- ../examples/child-pipeline.ts
+- ../examples/fan-out-progress.ts
+- ../examples/resumable-enrichment.ts
+- ../examples/cli-job.ts
+- ../examples/cancellation-and-testing.ts
+- ../examples/tracing.ts

package/docs/recipes.md

@@ -0,0 +1,51 @@
+# Recipe index
+
+Every linked TypeScript example is compiled by the package typecheck. Start with
+the smallest example matching the workflow rather than assembling primitives
+from the API inventory.
+
+| Intent                                        | Executable recipe                                                        | Main primitives                                                    |
+| --------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| Sequential import or ETL                      | [`typed-import.ts`](../examples/typed-import.ts)                         | `createSteps`, `dependsOn`, `requireOutputs`, `targets`            |
+| Validate options, outputs, and results        | [`validated-boundaries.ts`](../examples/validated-boundaries.ts)         | Standard Schema, `outputSchema`, `resultSchema`                    |
+| Inspect, plan, or graph a pipeline module     | [`typed-import.ts`](../examples/typed-import.ts)                         | `tubeless inspect`, `tubeless plan`, `tubeless graph`, `toMermaid` |
+| Safe write/publish preview                    | [`publish-with-gates.ts`](../examples/publish-with-gates.ts)             | `dryRun`, `optionalDependsOn`, `skipAfterFailureOf`                |
+| Deliberately omit unnecessary work            | [`conditional-step.ts`](../examples/conditional-step.ts)                 | `step.skippable`, valued skip, skip-aware output typing            |
+| Preserve independent work after failure       | [`best-effort.ts`](../examples/best-effort.ts)                           | `continueOnError`, structured `run` result                         |
+| Compose one reusable workflow                 | [`child-pipeline.ts`](../examples/child-pipeline.ts)                     | `fromPipeline`, `mapOptions`, `mapResult`                          |
+| Fan out over runtime items                    | [`fan-out-progress.ts`](../examples/fan-out-progress.ts)                 | `forEachPipeline`, stable keys, concurrency, progress              |
+| Show determinate progress                     | [`fan-out-progress.ts`](../examples/fan-out-progress.ts)                 | `reportProgress`, mapped-child progress                            |
+| Retry and rate-limit remote calls             | [`resumable-enrichment.ts`](../examples/resumable-enrichment.ts)         | `withRetry`, `RateLimiter`, injected sleep and signal              |
+| Resume durable long-running work              | [`resumable-enrichment.ts`](../examples/resumable-enrichment.ts)         | `dryRun`, `openCheckpoint`, `withCheckpointedBatch`                |
+| Expose and run a typed command-line program   | [`cli-job.ts`](../examples/cli-job.ts)                                   | `definePipelineCommand`, conditional `mapOptions`, `tubeless run`  |
+| Render plans and diagnostics                  | [`rendering.ts`](../examples/rendering.ts)                               | `renderPipelinePlan`, `renderPipelineError`                        |
+| Handle cancellation and deterministic testing | [`cancellation-and-testing.ts`](../examples/cancellation-and-testing.ts) | `createPipelineTestRuntime`, captured status/progress              |
+| Export JSON or OpenTelemetry lifecycle events | [`tracing.ts`](../examples/tracing.ts)                                   | trace context, attempt events, JSON exporter                       |
+| Persist, inspect, and explicitly launch runs  | [`local-observability.ts`](../examples/local-observability.ts)           | SQLite store, `createPipelineRunProjector`, `definePipelineStudio` |
+
+## Selection rules
+
+1. Use an ordinary step for one unit of domain work.
+2. Set `dryRun: "skip"` or provide a side-effect-free `dryRun` handler before
+   exposing side-effecting work through CLI dry-run support.
+3. Use `step.skippable` only for a successful policy decision, never to hide an error.
+4. Use a child pipeline when the child has value independently; use a normal
+   helper function when it does not.
+5. Use `forEachPipeline` when every item needs child-pipeline lifecycle and
+   reporting. Use `runConcurrent` for lightweight worker functions.
+6. Use `definePipelineCommand` for pipeline scripts; use `defineCommand` only
+   when the script is not centered on a pipeline. Preview selection with
+   `command.plan()` or `tubeless plan`; do not simulate planning with `--plan`.
+7. Declare public goals with `targets: [step]` on the pipeline, select their IDs
+   for goal-oriented execution, and use `stepIds` only for an exact filter. Use
+   `requireOutputs` when the final domain result is not meaningful without
+   specific step outputs. Read plan `selectionReasons` instead of recreating
+   target-closure logic in a CLI or application.
+8. Use `tubeless/render` when plans or diagnostics cross a human or JSON
+   presentation boundary; do not duplicate selection-reason or error formatting.
+   Use `tubeless/reporter` for optional TTY run reporters; do not import them
+   from `tubeless`.
+
+For semantics behind these choices, read [core concepts](./concepts.md).
+For workbench commands, read [the CLI](./cli.md). For the local run UI, read
+[the studio](./studio.md).

package/docs/studio.md

@@ -0,0 +1,86 @@
+# Local studio
+
+Normal pipeline and CLI execution is storage-free. The studio is an optional
+local projection of an append-only SQLite event store. Core does not import it.
+
+Record one workbench run by placing `--store` before the command file:
+
+```sh
+bunx tubeless run --store .tubeless/runs.sqlite ./scripts/import.ts -- --source rows.txt
+```
+
+Open the studio only when you want a browser view:
+
+```sh
+bunx tubeless ui --store .tubeless/runs.sqlite
+```
+
+That form is read-only. It does not guess executable modules from recorded
+definitions. Register marked `definePipelineCommand` exports to make a
+**Run pipeline** action available:
+
+```sh
+bunx tubeless ui \
+  --store .tubeless/runs.sqlite \
+  --command ./scripts/import.ts \
+  --command ./scripts/publish.ts
+```
+
+`--export` selects the export when you register exactly one `--command`. Launch
+forms render each command's structured parameter contract: booleans as
+checkboxes, constrained strings as selects, numbers with their bounds, and
+paths or unconstrained values as text fields. Submitted values go through the
+normal typed command parser without a shell. **Preview plan** uses the dry-run
+and step/target values from the same form; it never creates a run.
+
+Default bind address is `127.0.0.1`, default port is `4317`, and the default
+store is `.tubeless/runs.sqlite`. Browser-triggered execution requires a
+loopback host (`127.0.0.1`, `::1`, or `localhost`). Non-loopback binding is
+rejected when any command is registered. A non-loopback `--host` without
+commands is allowed and stays read-only: the store is visible to anyone who
+can reach the port, and clear-history is not wired. That bind is a risk you
+enable; see [SECURITY.md](../SECURITY.md).
+
+## Checked-in catalog
+
+Declare module references once for a repeatable project catalog:
+
+```ts
+// tubeless.studio.ts
+import { definePipelineStudio } from "tubeless/workbench/studio";
+
+export default definePipelineStudio({
+  cwd: ".",
+  commands: [
+    { file: "./scripts/import.ts", export: "ImportCommand", name: "Import rows" },
+    { file: "./scripts/publish.ts", export: "PublishCommand" },
+  ],
+});
+```
+
+```sh
+bunx tubeless ui --store .tubeless/runs.sqlite ./tubeless.studio.ts
+```
+
+Command paths and `cwd` are relative to the manifest file. Empty or duplicate
+registrations fail before the studio starts. Presentation-name overrides do not
+change run or pipeline identity.
+
+## What the UI shows
+
+The studio combines active and historical runs in one running-first view. Child
+pipeline executions stay beneath their top-level run. Run details include step
+attempts, progress, logs, and structured errors. Nested pipeline steps are
+labeled with the child pipeline and its declared steps; runtime fan-out is
+identified without guessing its item count.
+
+Browser plan, launch, and clear-history requests send
+`x-tubeless-studio-plan`, `x-tubeless-studio-launch`, and
+`x-tubeless-studio-clear-history`. Those requests also require a `Host` header
+that matches the bound authority, and plan/launch require `application/json`.
+The header names are part of the local studio protocol. They are same-origin
+guards, not authentication.
+
+Programmatic callers can compose the same pieces from
+`tubeless/run-store/sqlite` and `tubeless/run-store/ui`. See
+[`local-observability.ts`](../examples/local-observability.ts).

package/examples/best-effort.ts

@@ -0,0 +1,42 @@
+import { createSteps, definePipeline } from "tubeless";
+
+interface AuditOptions {
+  failLinks?: boolean;
+}
+
+const step = createSteps<AuditOptions>();
+
+const checkLinks = step("check-links", {
+  description: "Validate links independently",
+  run: (_inputs, context) => {
+    if (context.options.failLinks) throw new Error("broken links found");
+    return { checked: 12 };
+  },
+});
+
+const checkMetadata = step("check-metadata", {
+  description: "Validate metadata independently",
+  run: () => ({ checked: 8 }),
+});
+
+export const BestEffortAuditPipeline = definePipeline({
+  id: "best-effort-audit",
+  steps: [checkLinks, checkMetadata],
+  finalize: (outputs) => ({
+    links: outputs["check-links"],
+    metadata: outputs["check-metadata"],
+  }),
+});
+
+export async function runBestEffortExample() {
+  const result = await BestEffortAuditPipeline.run({
+    failLinks: true,
+    continueOnError: true,
+  });
+
+  return {
+    errors: result.errors,
+    metadataStillCompleted: result.value?.metadata?.checked === 8,
+    reports: result.steps,
+  };
+}

package/examples/cancellation-and-testing.ts

@@ -0,0 +1,45 @@
+import { createSteps, definePipeline } from "tubeless";
+import { createPipelineTestRuntime } from "tubeless/testing";
+
+interface PollOptions {
+  attempts: number;
+}
+
+const step = createSteps<PollOptions>();
+
+const poll = step("poll", {
+  description: "Poll cooperatively with an injected, cancellation-aware sleep",
+  run: async (_inputs, context) => {
+    for (let attempt = 1; attempt <= context.options.attempts; attempt += 1) {
+      await context.sleep(100, context.signal);
+      context.reportProgress({ completed: attempt, total: context.options.attempts });
+    }
+    return context.options.attempts;
+  },
+});
+
+export const PollPipeline = definePipeline({
+  id: "poll",
+  steps: [poll],
+  finalize: (outputs) => outputs.poll ?? 0,
+});
+
+export async function runWithTestRuntime() {
+  const test = createPipelineTestRuntime({ cwd: "/workspace" });
+  const value: number = await test.runOrThrow(PollPipeline, { attempts: 3 });
+
+  return {
+    elapsedMs: test.clock.now(),
+    latestProgress: test.latestProgress.get("poll"),
+    logs: test.logs,
+    statuses: test.statuses,
+    value,
+  };
+}
+
+export async function runCancelledTest() {
+  const test = createPipelineTestRuntime();
+  test.abort("cancel the test run");
+
+  return test.run(PollPipeline, { attempts: 3 });
+}

package/examples/child-pipeline.ts

@@ -0,0 +1,51 @@
+import { createSteps, definePipeline } from "tubeless";
+
+interface NormalizeOptions {
+  rows: readonly string[];
+}
+
+const normalizeStep = createSteps<NormalizeOptions>();
+
+const normalizeRows = normalizeStep("normalize-rows", {
+  run: (_inputs, context) =>
+    context.options.rows.map((row) => row.trim().toLowerCase()).filter((row) => row.length > 0),
+});
+
+export const NormalizePipeline = definePipeline({
+  id: "normalize",
+  steps: [normalizeRows],
+  targets: [normalizeRows],
+  finalize: (outputs) => outputs["normalize-rows"] ?? [],
+});
+
+interface ImportOptions {
+  lines: readonly string[];
+}
+
+const importStep = createSteps<ImportOptions>();
+
+const normalizedImport = importStep.fromPipeline("normalized-import", {
+  pipeline: NormalizePipeline,
+  mapOptions: (_inputs, context) => ({ rows: context.options.lines }),
+  mapResult: (rows) => ({ count: rows.length, rows }),
+});
+
+export const ChildPipelineImport = definePipeline({
+  id: "child-pipeline-import",
+  steps: [normalizedImport],
+  finalize: (outputs) => outputs["normalized-import"],
+});
+
+export async function runChildPipelineExample() {
+  return ChildPipelineImport.runOrThrow({
+    lines: [" Alpha ", "", "Beta"],
+  });
+}
+
+if (false) {
+  importStep.fromPipeline("invalid-child-selection", {
+    pipeline: NormalizePipeline,
+    // @ts-expect-error Child run options are checked against its declared target IDs.
+    mapOptions: () => ({ rows: [], targets: ["normalise-rows"] }),
+  });
+}

package/examples/cli-job.ts

@@ -0,0 +1,86 @@
+import * as fs from "fs";
+import { createSteps, definePipeline, requireOutputs } from "tubeless";
+import { definePipelineCommand } from "tubeless/cli";
+
+interface ImportOptions {
+  lines: readonly string[];
+  limit?: number;
+}
+
+const step = createSteps<ImportOptions>();
+
+const loadRows = step("load-rows", {
+  description: "Read raw input records from the caller.",
+  run: (_inputs, context) => context.options.lines,
+});
+
+const normalizeRows = step("normalize-rows", {
+  dependsOn: [loadRows],
+  description: "Trim, lowercase, drop blanks, and apply the optional --limit.",
+  run: ({ "load-rows": rows }, context) => {
+    const normalized = rows.map((row) => row.trim().toLowerCase()).filter((row) => row.length > 0);
+    return context.options.limit === undefined
+      ? normalized
+      : normalized.slice(0, context.options.limit);
+  },
+});
+
+export const ImportPipeline = definePipeline({
+  id: "import",
+  steps: [loadRows, normalizeRows],
+  targets: [normalizeRows],
+  finalize: requireOutputs([normalizeRows], (outputs) => ({
+    count: outputs["normalize-rows"].length,
+    rows: outputs["normalize-rows"],
+  })),
+});
+
+/**
+ * The kind of entry point a `scripts/*.ts` file would export: flags become a typed,
+ * validated `args` object instead of hand-parsed `process.argv`. `--source`'s `path` type
+ * resolves relative to `context.cwd` and confirms the file exists before `run` sees it.
+ * Pipeline commands also provide exact `--step`, dependency-aware `--target`
+ * for the pipeline's declared goals, and `--continue-on-error`, while
+ * forwarding the universal `--dry-run` flag into the pipeline automatically.
+ * Plan with `command.plan()` or `tubeless plan`, not `--plan`.
+ */
+export const ImportCommand = definePipelineCommand(ImportPipeline, {
+  description: "Normalize a newline-delimited list of input rows.",
+  params: {
+    source: {
+      type: "path",
+      description: "File with one row per line.",
+      mustExist: true,
+      kind: "file",
+    },
+    limit: {
+      type: "number",
+      optional: true,
+      integer: true,
+      min: 1,
+      description: "Only keep the first N normalized rows.",
+    },
+  },
+  mapOptions: (args) => ({
+    lines: fs.readFileSync(args.source, "utf8").split("\n"),
+    limit: args.limit,
+  }),
+  summarize: (result) => [`Normalized ${result.count} row(s).`],
+});
+
+if (false) {
+  const missingLinesParams = { source: { type: "path" } } as const;
+  // @ts-expect-error --source does not supply ImportPipeline's required lines option.
+  definePipelineCommand(ImportPipeline, { params: missingLinesParams });
+
+  const renamedOptionalParams = {
+    lines: { type: "string", multiple: true },
+    max: { type: "number", optional: true },
+  } as const;
+  // @ts-expect-error --max is not a same-name option on ImportPipeline.
+  definePipelineCommand(ImportPipeline, { params: renamedOptionalParams });
+}
+
+if (import.meta.main) {
+  void ImportCommand.main();
+}

package/examples/conditional-step.ts

@@ -0,0 +1,41 @@
+import { createSteps, definePipeline } from "tubeless";
+
+interface CacheOptions {
+  cachedValue?: string;
+  refresh: boolean;
+}
+
+const step = createSteps<CacheOptions>();
+
+const resolveValue = step.skippable("resolve-value", {
+  description: "Reuse a cached value unless a refresh is required",
+  skip: (_inputs, context) =>
+    !context.options.refresh && context.options.cachedValue !== undefined
+      ? { reason: "cached value is current", value: context.options.cachedValue }
+      : false,
+  run: async () => "fresh-value",
+});
+
+const formatValue = step("format-value", {
+  dependsOn: [resolveValue],
+  description: "Format the resolved value for the caller",
+  run: ({ "resolve-value": value }) => {
+    // A skippable step is always typed as T | undefined, even when this
+    // policy skip publishes a value. Keep absence handling explicit.
+    if (value === undefined) throw new Error("resolve-value produced no value");
+    return value.toUpperCase();
+  },
+});
+
+export const ConditionalCachePipeline = definePipeline({
+  id: "conditional-cache",
+  steps: [resolveValue, formatValue],
+  finalize: (outputs) => outputs["format-value"] ?? "",
+});
+
+export async function runConditionalCacheExample() {
+  return ConditionalCachePipeline.runOrThrow({
+    cachedValue: "cached-value",
+    refresh: false,
+  });
+}

package/examples/fan-out-progress.ts

@@ -0,0 +1,53 @@
+import { createSteps, definePipeline } from "tubeless";
+
+interface ShardOptions {
+  records: readonly string[];
+  shardId: string;
+}
+
+const shardStep = createSteps<ShardOptions>();
+
+const processRecords = shardStep("process-records", {
+  description: "Process every record in one shard",
+  run: async (_inputs, context) => {
+    const processed: string[] = [];
+    for (const [index, record] of context.options.records.entries()) {
+      processed.push(record.toUpperCase());
+      context.reportProgress({
+        completed: index + 1,
+        message: record,
+        total: context.options.records.length,
+      });
+    }
+    return { processed, shardId: context.options.shardId };
+  },
+});
+
+export const ShardPipeline = definePipeline({
+  id: "process-shard",
+  steps: [processRecords],
+  finalize: (outputs) => outputs["process-records"],
+});
+
+interface FanOutOptions {
+  concurrency: number;
+  shards: readonly { id: string; records: readonly string[] }[];
+}
+
+const fanOutStep = createSteps<FanOutOptions>();
+
+const processShards = fanOutStep.forEachPipeline("process-shards", {
+  pipeline: ShardPipeline,
+  description: "Process shards with bounded concurrency and stable identities",
+  items: (_inputs, context) => context.options.shards,
+  key: (shard) => shard.id,
+  concurrency: (_inputs, context) => context.options.concurrency,
+  progress: { itemNoun: "shards" },
+  mapOptions: (shard) => ({ records: shard.records, shardId: shard.id }),
+});
+
+export const FanOutPipeline = definePipeline({
+  id: "fan-out",
+  steps: [processShards],
+  finalize: (outputs) => outputs["process-shards"] ?? [],
+});

package/examples/local-observability.ts

@@ -0,0 +1,80 @@
+import { createSteps, defaultPipelineContext, definePipeline, requireOutputs } from "tubeless";
+import { createPipelineRunProjector, type StoredPipelineEvent } from "tubeless/run-store";
+import { openSqlitePipelineRunStore } from "tubeless/run-store/sqlite";
+import { definePipelineStudio } from "tubeless/workbench/studio";
+import {
+  startPipelineRunStudio,
+  type PipelineRunStudioLauncher,
+  type PipelineRunStudioServer,
+} from "tubeless/run-store/ui";
+
+const step = createSteps<{ rows: readonly string[] }>();
+const normalize = step("normalize", {
+  description: "Normalize imported rows for publication.",
+  run: (_inputs, context) => {
+    context.log.log("normalizing", context.options.rows.length, "rows");
+    return context.options.rows.map((row) => row.trim().toLowerCase());
+  },
+});
+
+export const LocallyObservedPipeline = definePipeline({
+  id: "locally-observed-import",
+  steps: [normalize],
+  targets: [normalize],
+  finalize: requireOutputs([normalize], ({ normalize }) => normalize),
+});
+
+/** A checked-in catalog can register many command modules in one place. */
+export const LocalStudioConfig = definePipelineStudio({
+  commands: [{ file: "./cli-job.ts", export: "ImportCommand", name: "Import rows" }],
+});
+
+/**
+ * Fold paged store events without walking the full history on every refresh.
+ * Append only newer pages. Duplicate and out-of-order ids are ignored; `0` is a
+ * valid first id. `projectPipelineRunStore` remains the one-shot wrapper.
+ */
+export function snapshotFromPages(pages: readonly (readonly StoredPipelineEvent[])[]) {
+  const projector = createPipelineRunProjector();
+  for (const page of pages) projector.append(page);
+  return projector.snapshot();
+}
+
+/** Recording is opt-in; ordinary calls to the pipeline remain storage-free. */
+export async function runWithLocalHistory(
+  rows: readonly string[],
+  filename = ".tubeless/runs.sqlite"
+): Promise<readonly string[]> {
+  const store = await openSqlitePipelineRunStore(filename);
+  try {
+    return await LocallyObservedPipeline.runOrThrow(
+      { rows },
+      {
+        ...defaultPipelineContext(),
+        tracing: { exporter: store },
+      }
+    );
+  } finally {
+    await store.close();
+  }
+}
+
+/** The UI is another optional reader of the same append-only store. */
+export async function serveLocalStudio(
+  filename = ".tubeless/runs.sqlite",
+  launcher?: PipelineRunStudioLauncher
+): Promise<PipelineRunStudioServer> {
+  const store = await openSqlitePipelineRunStore(filename);
+  const server = await startPipelineRunStudio({
+    history: { clear: () => store.clearHistory() },
+    launcher,
+    store,
+  });
+  return {
+    ...server,
+    close: async () => {
+      await server.close();
+      await store.close();
+    },
+  };
+}

package/examples/publish-with-gates.ts

@@ -0,0 +1,56 @@
+import { createSteps, definePipeline } from "tubeless";
+
+interface PublishOptions {
+  source: string;
+}
+
+interface Artifact {
+  body: string;
+  size: number;
+}
+
+const step = createSteps<PublishOptions>();
+
+const buildArtifact = step("build-artifact", {
+  description: "Build an artifact that can be validated and published.",
+  run: (_inputs, context): Artifact => ({
+    body: context.options.source.trim(),
+    size: context.options.source.trim().length,
+  }),
+});
+
+const validateArtifact = step("validate-artifact", {
+  dependsOn: [buildArtifact],
+  description: "Fail before publishing if the artifact is empty.",
+  run: ({ "build-artifact": artifact }) => {
+    if (artifact.size === 0) {
+      throw new Error("artifact is empty");
+    }
+    return { valid: true };
+  },
+});
+
+const publishArtifact = step("publish-artifact", {
+  dependsOn: [buildArtifact],
+  optionalDependsOn: [validateArtifact],
+  skipAfterFailureOf: [validateArtifact],
+  description: "Publish only on real runs, and only after validation has not failed.",
+  dryRun: "skip",
+  run: ({ "build-artifact": artifact }) => ({
+    publishedId: `artifact-${artifact.size}`,
+  }),
+});
+
+export const PublishPipeline = definePipeline({
+  id: "publish",
+  steps: [buildArtifact, validateArtifact, publishArtifact],
+  finalize: (outputs) => ({
+    artifact: outputs["build-artifact"],
+    publishedId: outputs["publish-artifact"]?.publishedId,
+    valid: outputs["validate-artifact"]?.valid === true,
+  }),
+});
+
+export async function runPublishDryRunExample() {
+  return PublishPipeline.runOrThrow({ source: "release notes", dryRun: true });
+}