Protocol types

These are the FScript shapes exchanged with Terrabuild. They are ordinary FScript records and discriminated unions; see the FScript type-system documentation for the language rules.

All types below are registered by Terrabuild under Protocol.* names. The declarations describe their visible shapes; use the supplied types directly without redeclaring them.

ExtensionContext

Terrabuild supplies this context to the handler marked Default while discovering project metadata:

type ExtensionContext =
  { Debug: bool
    Directory: string
    CI: bool }

ActionContext

Terrabuild supplies this context to command handlers:

type BatchContext =
  { Hash: string
    TempDir: string
    ProjectPaths: string list
    BatchCommands: string list }

type ActionContext =
  { Debug: bool
    CI: bool
    Command: string
    Hash: string
    Directory: string
    Batch: BatchContext option }

• Command is the requested target action.
• Hash identifies the current execution context.
• Directory is the project directory.
• Batch is Some during batch resolution and None for an individual action.

Contexts are structurally matched, so handlers should request only the fields they use:

export let dispatch (context: {| Command: string |}) (args: string option) =
  // ...

ProjectInfo

The handler marked Default returns project metadata:

type DependencyResolution =
  | Path
  | Scope

type ProjectInfo =
  { Id: string option
    DependencyResolution: DependencyResolution option
    Outputs: string list
    Dependencies: string list }

• Id supplies a canonical identity inside the extension scope. When absent, Terrabuild uses the workspace-relative project path.
• DependencyResolution = Some Path interprets dependencies as paths relative to the current project directory.
• DependencyResolution = Some Scope interprets dependencies as identifiers in the current extension scope.
• DependencyResolution = None defaults to Path.
• Outputs contributes default artifact patterns.
• Dependencies contributes discovered project dependencies.

Outputs and dependencies are sets semantically; avoid returning duplicates.

ShellOperation

Each operation describes one process Terrabuild should execute:

type ShellOperation =
  { Command: string
    Arguments: string
    ErrorLevel: int }

ErrorLevel is the highest accepted exit code. Operations execute in list order.

CommandResult

Every command handler returns:

type CommandResult =
  { Batchable: bool
    Operations: ShellOperation list
    PreserveProvenance: ProvenanceEffect }

• Batchable = true means the returned operation is valid for the supplied batch context.
• Batchable = false requires individual execution.
• Operations may contain one or more ordered shell operations.

Batchability belongs to the result, not the descriptor.

Descriptor flags

The script's final value maps exported function names to these flags:

type Cacheability = Never | Local | External | Remote
type ExportFlag = Dispatch | Default | Cache of Cacheability

{ [nameof dispatch] = [Dispatch; Cache Never] }

• Dispatch selects the fallback command handler.
• Default selects the project-metadata handler.
• Cache Never, Cache Local, Cache External, and Cache Remote specify command cacheability.

Only one function may be marked Dispatch, and only one may be marked Default. Descriptor keys must name functions declared with export let.

ProvenanceEffect = Preserved | Broken | Unaffected is a required command result field. Set Broken for operations that modify managed dependencies, Preserved when they retain them, or Unaffected when they do not affect provenance.