Capabilities

One line per custom operation on the four builders, per Input combinator, and per Cmd argument helper. The API reference has full signatures and remarks. Composing reusable blocks has worked examples.

How settings resolve

A stage setting resolves by walking upward: the stage, its parent stage, the parent's parent, then the pipeline. The first level that sets it wins, so a pipeline's workingDir covers every stage under it, and a nested stage overrides it for itself and its children. This applies to workingDir, envVars, the timeouts, acceptExitCodes, the output sink, noPrefixForStep, noStdRedirectForStep and verbosity.

Conditions are the exception. when', whenEnvVar, whenBranch and the platform operations conjoin: a second condition on the same stage narrows it to the logical AND of both. Use whenAny { } to widen.

A command's copies of the pipeline settings are defaults, not overrides: they reach every pipeline the command runs, but only where that pipeline left the setting alone, regardless of write order. noPrefixForStep and noStdRedirectForStep are plain bools with no unset state, so a pipeline setting either one to the value PipelineContext.create already gives it is indistinguishable from leaving it untouched — the command default overwrites it either way.

Timeouts

Three names. Meaning shifts with the builder they sit on.

The unit differs by builder:

• pipeline — int<second>, float seconds or a TimeSpan
• stage — plain int seconds, float seconds or a TimeSpan
• command / rootCommand — int seconds or a TimeSpan

Stage operations

Available inside stage, and inside whenStage, which accepts everything stage does.

A stage nested inside another is one step of its parent. Stages nest to any depth. A block is a value that stage, pipeline or command can yield.

Running a command from inside a step

run and runSensitive cover the case where a command's exit code is the whole result. A step built with run (fun ctx -> ...) reaches for one of these Operation<'T> functions when it needs the command's output as a value:

Captured stdout and stderr are the child's raw bytes, ahead of any prefix or display formatting — application data that can hold secrets. Printing a successful capture is the caller's decision. Neither executeCapture nor attemptCapture does it automatically.

Pipeline operations

Available inside pipeline "name" { } and inside Command.pipeline { }, which takes the name and description of the command that runs it.

command/rootCommand carries no onFailure default. Such a default would have to cover a failure of InputSpec.Read or of CLI parsing, ahead of every pipeline it runs. Nothing observes that failure today.

Producers and dependencies

A Producer<'T> is a typed, named unit of deferred work with its own CLI inputs and its own prerequisites. Declaring one registers its identity and harvests those inputs. Nothing runs until a consumer schedules it.

A producer's handle carries an identity allocated when declared. Two declarations sharing a name and arguments are distinct producers with distinct results. Depending on the same handle from more than one consumer runs it once per invocation and shares that result. An unlisted producer required by a stage runs immediately before that stage, after its own prerequisites. Listing it explicitly (Producer.stage, or yielding it into a pipeline) fixes its position instead. A consumer running under a parallel' or shuffleExecuteSequence scope reads a value published before that scope began. Placing a producer inside such a scope fails validation, naming the producer and the scope.

A required producer that is skipped or fails leaves its consumers skipped, carrying a dependency reason. An Option/ValueOption result models an intentional absence, distinct from a failed producer, and a consumer can handle it directly. Retrying a consumer through retry reuses the successful results of producers outside the retried scope. A producer owned by the retried scope gets a fresh result on each attempt, and a failed attempt leaves no value for the next one to read.

Failure handlers

onFailure registers a FailureContext -> unit handler on a stage or a pipeline. It runs once per failed execution of that scope, after the scope exhausts its retry attempts, and inner handlers run before outer ones — a stage's handler before the pipeline's. A recovered retry, or a cancelled stage, runs no handler. A stage's own timeout and timeoutForStep count as failures of that stage. A cancellation from an ancestor's token, the pipeline's, or the invocation's runs no handler.

The handler reads FailureContext.Primary/.Secondary for the causes recorded, and FailureContext.TryGetOutput producer for a value the invocation has already published — answering ValueNone for a producer that has not run. An exception out of a handler becomes one more cause of the same scope. The original failure stays primary, and successful reporting preserves it. A failing handler triggers no second run of itself.

Known limitations:

• A handler is synchronous and unbounded, with no cleanup operation or budget separate from its own body.
• onFailure has no equivalent on command/rootCommand. A failure of InputSpec.Read or of CLI parsing reaches no handler.
• A stage with no timeoutForStep runs its steps under the attempt's own cancellation source, not a budget of its own. A step still in flight when its scope unwinds keeps its sources undisposed, rather than racing a straggler that may still read them.
• FailureCause.summarise, used in ScopeReports, keeps only the first line of a multi-line capture. Later lines are lost from the report, not merely hidden from the rendering.
• OperationFailedException's message is written by hand for each FailureCause case rather than through FailureCause.describe, so the two can drift.
• whenStageSucceeds (the body of whenStage) reads the policy-folded outcome of the condition stage: one carrying continueStageOnFailure reports itself as succeeded even where it failed.
• The gate placing an unlisted producer immediately before a whenStage consumer evaluates that consumer's condition stage a second time, beyond whenStage's own evaluation.
• PipelineContext.run, called directly rather than through a command's own invocation, skips DependencyPlan.validate: an arrangement validation would reject — a producer inside a parallel' scope, say — runs instead of failing up front.

Migrating work out of InputSpec.Read

InputSpec<'T>.Read is a projection, ParseResult -> 'T, called once per invocation to bind the CLI values a stage declared. Effects belong in a step or a producer, not in Read: a Read that shells out or writes a file runs on every path that resolves inputs, --help and --explain included, since resolution happens ahead of the flag check.

Before, doing the work inside Read:

let publish =
    input {
        let! tag = Input.option<string> "--tag" |> Input.def "v0.0.0"
        // Runs on every resolution of this input, --help and --explain included.
        let manifest = fetchManifest tag
        return stage "publish" {
            run (cmd $"deploy --version {manifest.Version}")
        }
    }

After, the same CLI option feeding a producer, and the stage consuming its typed result:

let tag = Input.option<string> "--tag" |> Input.def "v0.0.0"

let manifest: Producer<Manifest> =
    Producer.define "manifest" (InputSpec.ofInput tag) DependencySpec.empty (fun tag () ->
        Operation.ofAsync (fetchManifestAsync tag))

let publish =
    pipeline "release" {
        stage "publish" {
            retry 2
            onFailure (fun context ->
                context.TryGetOutput manifest
                |> ValueOption.iter (fun manifest -> printfn $"publish failed for {manifest.Version}"))
            consumes (DependencySpec.require manifest) (fun manifest ->
                execute (cmd $"deploy --version {manifest.Version}"))
        }
    }

Read now binds only the option. --help and --explain resolve it without running fetchManifest or deploy, since a producer runs only where its consumer is scheduled. The consumer's retry repeats the deploy alone: manifest is required, not retried, so a failing deploy re-reads the same published value rather than re-fetching it. Its onFailure reads that same value back out of the failure it is given. The CLI layer stays applicative: tag is still an ordinary ActionInput<string>, readable without a ParseResult, exactly as before.

Command operations

Available inside command "name" { } and rootCommand argv { } / rootCommandOfScript { }, except for the three marked as root-only.

A command yields stages directly — command "test" { Stages.restore; Stages.test } — and consecutive stages become one implicit pipeline carrying the command's name and description. Command.pipeline { } is that same pipeline written out, for when it needs pipeline-level settings. pipeline "name" { } is for several pipelines under one command, or a pipeline that needs its own name.

Condition builders

whenAll { }, whenAny { } and whenNot { } take these. Each yields a single condition to a stage. An empty whenAll/whenNot is always active. An empty whenAny never is.

whenEnv { } describes one environment variable in place of a wall of overloads: name, description, value, acceptValues and optional. whenStage "name" { } runs a stage for its result — everything stage accepts is accepted, and the stage runs for real, side effects included.

whenSome value build and whenOk value build are functions rather than operations. Each returns a StageContext list: the stage built from the bound value, or []. The absent case is an empty list, not an inactive stage requiring a name. build receives the value already unwrapped, inside the condition that guards it.

Input combinators

Declaring functions:

Shaping combinators, all ActionInput<'T> -> ActionInput<'T> and all pipeable:

InputSpec<'T>

InputSpec<'T> is public at Partas.Build. A stage factory parameterised by an option needs no open Partas.Build.Internal:

let build (projects: InputSpec<string list>) = input {
    let! projects = projects
    and! config = Options.config
    ...
}

The input { let! … and! … return … } CE is the usual way to build one; inputs is the same builder under a second name (src/Partas.Build/Builders/Inputs.fs binds both). It is applicative: bind every source in a single let!/and! group. A sequential second let! is a compile error (FS0708): the input set must be readable before anything is parsed. An input { } nested inside another's return produces an InputSpec<InputSpec<_>>, which nothing accepts — pass the source in as an InputSpec instead.

Cmd

A Cmd keeps the executable and its arguments apart all the way to ProcessStartInfo.ArgumentList, so the platform does the escaping.

Args

The arguments a script was given, as distinct from the ones its host was given.

dotnet fsi build.fsx -- test --quick does not reach the process with its -- intact: the dotnet driver consumes one before fsi sees the command line. Args.script locates the script's own filename instead of splitting on a separator.

Baked

Ready-made declarations for the options every build CLI ends up wanting. They ship in their own package, Partas.Build.Baked.

Each declaration is a BuildOption<'T> carrying both forms: .option is the flag, .argument the positional equivalent. BuildOption.map, .mapOpt and .mapArg apply an Input.* combinator to both forms or to one.

Reference

• Overview — the layers, and a first pipeline.
• Composing reusable blocks — blocks, nesting, and composition across files.
• Stage CE run overloads.
• API reference — full signatures and remarks.