logical.ExecModetypeno test imports ittype ExecMode = "check" | "apply";What a run does: look and change nothing (check), or do it (apply).
Plan versus apply (commons headless 0012-executor-check-mode): what an Executor is asked to do is a plan of steps, and a plan is run in one of two modes, check (change nothing; say what would change) or apply (do it). A step names the argument vector of each mode (the real tool's own check mode: ansible --check, tofu plan), so a tool without a check mode has none and is reported as unsupported, never run as an apply. The plan has a canonical form and a SHA-256 hash that a signer can sign and a verifier recompute (planHash); an apply names the hash it was approved for and is refused where the plan is not that one. A run streams typed events (started, line, progress, finished) to a surface as it goes, and ends in a typed result.
Pure but for the executor it is given: planOf, canonicalOf, planHash, describePlan, progressOf and overallOf touch nothing; runPlan calls executor.exec and the clock and the terminal are not its business. No signing is done here and no key is held. A plan holds no secret: its argument vectors are hashed, written and shown, so a credential is given to a step through the run's environment (RunOptions.env) or the askpass helper, never in argv.
import { parseStepId, planOf, planHash } from "./plan.ts";
const id = parseStepId("keys");
const plan = id.kind === "ok" ? planOf("host-1", [{ id: id.value, summary: "Keys.", effect: "mutate", apply: ["ansible-playbook", "keys.yml"], check: ["ansible-playbook", "--check", "keys.yml"] }]) : undefined;
plan?.kind === "ok" && planHash(plan.value).startsWith("sha256:"); // truelogical.ExecModetypeno test imports ittype ExecMode = "check" | "apply";What a run does: look and change nothing (check), or do it (apply).
logical.StepIdtypeno test imports ittype StepId = Brand<string, "step id">;The identity of a step in a plan, stable across runs: made only by parseStepId.
logical.parseStepIdfunctionno test imports itfunction parseStepId(text: string): Result<StepId, string>A step id from text, or why the text is not one: the one way a StepId is made.
logical.ExecSteptypeno test imports ittype ExecStep = {
readonly id: StepId;
readonly summary: string;
readonly effect: Effect;
/** The argument vecto… (546 characters)type ExecStep = {
readonly id: StepId;
readonly summary: string;
readonly effect: Effect;
/** The argument vector that does it. */
readonly apply: readonly string[];
/** The argument vector that looks and changes nothing; none where the tool has no check mode. */
readonly check: readonly string[] | undefined;
/** The exit status of the check vector that means something would change (`tofu plan -detailed-exitcode` gives 2); where it is not given a check that succeeds means nothing would. */
readonly changedExit?: number;
};One step of a plan: what it is, what it does to the world, and the argument vector of each mode.
logical.ExecutionPlantypeno test imports ittype ExecutionPlan = {
readonly format: "headless-plan/1";
readonly target: string;
readonly steps: readonly ExecStep[];
};A plan: the target it is for and its steps in order.
logical.PlanProblemtypeno test imports ittype PlanProblem =
| { readonly rule: "plan/target"; readonly message: string }
| { readonly rule: "plan/empty"; rea… (506 characters)type PlanProblem =
| { readonly rule: "plan/target"; readonly message: string }
| { readonly rule: "plan/empty"; readonly message: string }
| { readonly rule: "plan/duplicate-step"; readonly id: string; readonly message: string }
| { readonly rule: "plan/argv"; readonly id: string; readonly message: string }
| { readonly rule: "plan/destructive-no-check"; readonly id: string; readonly message: string }
| { readonly rule: "plan/changed-exit"; readonly id: string; readonly message: string };What is wrong with a plan.
logical.planOffunctionno test imports itfunction planOf(target: string, steps: readonly ExecStep[]): Result<ExecutionPlan, readonly PlanProblem[]>A plan from its steps, or everything wrong with it.
logical.canonicalOffunctionno test imports itfunction canonicalOf(plan: ExecutionPlan): stringThe canonical form of a plan: JSON with the keys of every object in order, no space, the steps and vectors in their order: the same plan is the same text on every runtime.
logical.PlanHashtypeno test imports ittype PlanHash = Brand<string, "plan hash">;The hash of a plan, sha256: and 64 hexadecimal digits: made only by planHash or parsePlanHash.
logical.parsePlanHashfunctionno test imports itfunction parsePlanHash(text: string): Result<PlanHash, string>A plan hash from text (as a signature carries it), or why the text is not one.
logical.planHashfunctionno test imports itfunction planHash(plan: ExecutionPlan): PlanHashThe hash of a plan: SHA-256 of its canonical form.
logical.StepOutcometypeno test imports ittype StepOutcome = "unchanged" | "changed" | "applied" | "failed" | "unsupported" | "skipped";What one step ended as.
logical.StepResulttypeno test imports ittype StepResult = {
readonly id: StepId;
readonly mode: ExecMode;
readonly outcome: StepOutcome;
/** Its exit status; none where it did not run or could not. */
readonly code: number | undefined;
};One step's result.
logical.ExecEventtypeno test imports ittype ExecEvent =
| { readonly kind: "started"; readonly step: StepId; readonly summary: string; readonly mode: ExecMod… (430 characters)type ExecEvent =
| { readonly kind: "started"; readonly step: StepId; readonly summary: string; readonly mode: ExecMode; readonly index: number; readonly total: number }
| { readonly kind: "line"; readonly step: StepId; readonly stream: "stdout" | "stderr"; readonly text: string }
| { readonly kind: "progress"; readonly done: number; readonly total: number }
| { readonly kind: "finished"; readonly result: StepResult };What a run is told to a surface while it goes.
logical.ExecOutcometypeno test imports ittype ExecOutcome = "unchanged" | "changed" | "applied" | "failed" | "incomplete";What a whole run ended as: nothing would change, something would (check), it was applied, a step failed, or it is incomplete (a step is unsupported or was skipped).
logical.ExecutionResulttypeno test imports ittype ExecutionResult = { readonly mode: ExecMode; readonly planHash: PlanHash; readonly steps: readonly StepResult[]; readonly outcome: ExecOutcome };The result of a run.
logical.Approvaltypeno test imports ittype Approval = { readonly kind: "hash"; readonly hash: PlanHash } | { readonly kind: "unsigned" };What approves an apply: the hash of the plan that a person (or a policy) approved, or an explicit statement that nothing was signed.
logical.RunRequesttypeno test imports ittype RunRequest = { readonly mode: "check" } | { readonly mode: "apply"; readonly approval: Approval };What a run is asked: a check, or an apply with its approval.
logical.ExecErrortypeno test imports ittype ExecError = { readonly kind: "plan-changed"; readonly approved: PlanHash; readonly actual: PlanHash };Why a run did not start.
logical.RunPlanOptionstypeno test imports ittype RunPlanOptions = {
/** What each step runs with (the working folder, the environment); never part of the plan or its hash. */
readonly run?: RunOptions;
/** Told as it goes. */
readonly onEvent?: (event: ExecEvent) => void;
/** Whether a failed step stops the rest, which are then skipped; true by default. */
readonly stopOnFailure?: boolean;
readonly signal?: AbortSignal;
};What a run is given besides the plan.
logical.vectorOffunctionno test imports itfunction vectorOf(step: ExecStep, mode: ExecMode): readonly string[] | undefinedThe argument vector of a step in a mode; none where the tool has no check mode.
logical.overallOffunctionno test imports itfunction overallOf(steps: readonly StepResult[]): ExecOutcomeWhat a run ended as, from its steps.
logical.runPlanfunctionno test imports itfunction runPlan(executor: Executor, plan: ExecutionPlan, request: RunRequest, o?: RunPlanOptions): Promise<Result<ExecutionResult, ExecError>>Runs a plan on an executor in a mode. check runs each step's check vector and never an apply vector (a step with none is unsupported); apply runs each step's apply vector, and where it was approved by a hash that is not the plan's gives plan-changed and runs nothing. Each step is a started event, its lines as they come (or, from an executor that does not stream, from its output at the end), a finished event, and a progress event; the result is the steps' results and the run's outcome. An executor that throws makes that step failed, never the run.
logical.describePlanfunctionno test imports itfunction describePlan(plan: ExecutionPlan): readonly string[]What a surface shows of a plan: its target, its hash, and a line for each step with what it does and whether it can be checked. Pure text, no colour.
logical.progressOffunctionno test imports itfunction progressOf(event: ExecEvent): ProgressEvent | undefinedThe progress event a command forwards for an execution event, or none where the event adds nothing the surface does not already show.
ExecModetypeno test imports ittype ExecMode = "check" | "apply";What a run does: look and change nothing (check), or do it (apply).
StepIdtypeno test imports ittype StepId = Brand<string, "step id">;The identity of a step in a plan, stable across runs: made only by parseStepId.
parseStepIdfunctionfunction parseStepId(text: string): Result<StepId, string>A step id from text, or why the text is not one: the one way a StepId is made.
ExecSteptypetype ExecStep = {
readonly id: StepId;
readonly summary: string;
readonly effect: Effect;
/** The argument vecto… (546 characters)type ExecStep = {
readonly id: StepId;
readonly summary: string;
readonly effect: Effect;
/** The argument vector that does it. */
readonly apply: readonly string[];
/** The argument vector that looks and changes nothing; none where the tool has no check mode. */
readonly check: readonly string[] | undefined;
/** The exit status of the check vector that means something would change (`tofu plan -detailed-exitcode` gives 2); where it is not given a check that succeeds means nothing would. */
readonly changedExit?: number;
};One step of a plan: what it is, what it does to the world, and the argument vector of each mode.
ExecutionPlantypetype ExecutionPlan = {
readonly format: "headless-plan/1";
readonly target: string;
readonly steps: readonly ExecStep[];
};A plan: the target it is for and its steps in order.
PlanProblemtypeno test imports ittype PlanProblem =
| { readonly rule: "plan/target"; readonly message: string }
| { readonly rule: "plan/empty"; rea… (506 characters)type PlanProblem =
| { readonly rule: "plan/target"; readonly message: string }
| { readonly rule: "plan/empty"; readonly message: string }
| { readonly rule: "plan/duplicate-step"; readonly id: string; readonly message: string }
| { readonly rule: "plan/argv"; readonly id: string; readonly message: string }
| { readonly rule: "plan/destructive-no-check"; readonly id: string; readonly message: string }
| { readonly rule: "plan/changed-exit"; readonly id: string; readonly message: string };What is wrong with a plan.
planOffunctionfunction planOf(target: string, steps: readonly ExecStep[]): Result<ExecutionPlan, readonly PlanProblem[]>A plan from its steps, or everything wrong with it.
canonicalOffunctionfunction canonicalOf(plan: ExecutionPlan): stringThe canonical form of a plan: JSON with the keys of every object in order, no space, the steps and vectors in their order: the same plan is the same text on every runtime.
PlanHashtypeno test imports ittype PlanHash = Brand<string, "plan hash">;The hash of a plan, sha256: and 64 hexadecimal digits: made only by planHash or parsePlanHash.
parsePlanHashfunctionfunction parsePlanHash(text: string): Result<PlanHash, string>A plan hash from text (as a signature carries it), or why the text is not one.
planHashfunctionfunction planHash(plan: ExecutionPlan): PlanHashThe hash of a plan: SHA-256 of its canonical form.
StepOutcometypeno test imports ittype StepOutcome = "unchanged" | "changed" | "applied" | "failed" | "unsupported" | "skipped";What one step ended as.
StepResulttypeno test imports ittype StepResult = {
readonly id: StepId;
readonly mode: ExecMode;
readonly outcome: StepOutcome;
/** Its exit status; none where it did not run or could not. */
readonly code: number | undefined;
};One step's result.
ExecEventtypetype ExecEvent =
| { readonly kind: "started"; readonly step: StepId; readonly summary: string; readonly mode: ExecMod… (430 characters)type ExecEvent =
| { readonly kind: "started"; readonly step: StepId; readonly summary: string; readonly mode: ExecMode; readonly index: number; readonly total: number }
| { readonly kind: "line"; readonly step: StepId; readonly stream: "stdout" | "stderr"; readonly text: string }
| { readonly kind: "progress"; readonly done: number; readonly total: number }
| { readonly kind: "finished"; readonly result: StepResult };What a run is told to a surface while it goes.
ExecOutcometypeno test imports ittype ExecOutcome = "unchanged" | "changed" | "applied" | "failed" | "incomplete";What a whole run ended as: nothing would change, something would (check), it was applied, a step failed, or it is incomplete (a step is unsupported or was skipped).
ExecutionResulttypeno test imports ittype ExecutionResult = { readonly mode: ExecMode; readonly planHash: PlanHash; readonly steps: readonly StepResult[]; readonly outcome: ExecOutcome };The result of a run.
Approvaltypeno test imports ittype Approval = { readonly kind: "hash"; readonly hash: PlanHash } | { readonly kind: "unsigned" };What approves an apply: the hash of the plan that a person (or a policy) approved, or an explicit statement that nothing was signed.
RunRequesttypeno test imports ittype RunRequest = { readonly mode: "check" } | { readonly mode: "apply"; readonly approval: Approval };What a run is asked: a check, or an apply with its approval.
ExecErrortypeno test imports ittype ExecError = { readonly kind: "plan-changed"; readonly approved: PlanHash; readonly actual: PlanHash };Why a run did not start.
RunPlanOptionstypeno test imports ittype RunPlanOptions = {
/** What each step runs with (the working folder, the environment); never part of the plan or its hash. */
readonly run?: RunOptions;
/** Told as it goes. */
readonly onEvent?: (event: ExecEvent) => void;
/** Whether a failed step stops the rest, which are then skipped; true by default. */
readonly stopOnFailure?: boolean;
readonly signal?: AbortSignal;
};What a run is given besides the plan.
vectorOffunctionno test imports itfunction vectorOf(step: ExecStep, mode: ExecMode): readonly string[] | undefinedThe argument vector of a step in a mode; none where the tool has no check mode.
overallOffunctionno test imports itfunction overallOf(steps: readonly StepResult[]): ExecOutcomeWhat a run ended as, from its steps.
runPlanfunctionfunction runPlan(executor: Executor, plan: ExecutionPlan, request: RunRequest, o?: RunPlanOptions): Promise<Result<ExecutionResult, ExecError>>Runs a plan on an executor in a mode. check runs each step's check vector and never an apply vector (a step with none is unsupported); apply runs each step's apply vector, and where it was approved by a hash that is not the plan's gives plan-changed and runs nothing. Each step is a started event, its lines as they come (or, from an executor that does not stream, from its output at the end), a finished event, and a progress event; the result is the steps' results and the run's outcome. An executor that throws makes that step failed, never the run.
describePlanfunctionfunction describePlan(plan: ExecutionPlan): readonly string[]What a surface shows of a plan: its target, its hash, and a line for each step with what it does and whether it can be checked. Pure text, no colour.
progressOffunctionfunction progressOf(event: ExecEvent): ProgressEvent | undefinedThe progress event a command forwards for an execution event, or none where the event adds nothing the surface does not already show.