IF Commons GitHub

logical/plan

Written to: 7 requirements: 7 proved, 0 partly, 0 failing, 0 with no test recorded. 0012-executor-check-mode FR-001, 0012-executor-check-mode FR-002, 0012-executor-check-mode FR-003, 0012-executor-check-mode FR-004, 0012-executor-check-mode FR-005, 0012-executor-check-mode FR-006 and 1 more

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:"); // true

Source: commons/headless/src/logical/plan.ts

11 of 50 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

logical.ExecModetypeno test imports it
type ExecMode = "check" | "apply";

What a run does: look and change nothing (check), or do it (apply).

logical.StepIdtypeno test imports it
type StepId = Brand<string, "step id">;

The identity of a step in a plan, stable across runs: made only by parseStepId.

logical.parseStepIdfunctionno test imports it
function 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 it
type 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 it
type 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 it
type 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 it
function planOf(target: string, steps: readonly ExecStep[]): Result<ExecutionPlan, readonly PlanProblem[]>

A plan from its steps, or everything wrong with it.

logical.canonicalOffunctionno test imports it
function canonicalOf(plan: ExecutionPlan): string

The 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 it
type 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 it
function 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 it
function planHash(plan: ExecutionPlan): PlanHash

The hash of a plan: SHA-256 of its canonical form.

logical.StepOutcometypeno test imports it
type StepOutcome = "unchanged" | "changed" | "applied" | "failed" | "unsupported" | "skipped";

What one step ended as.

logical.StepResulttypeno test imports it
type 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 it
type 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 it
type 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 it
type ExecutionResult = { readonly mode: ExecMode; readonly planHash: PlanHash; readonly steps: readonly StepResult[]; readonly outcome: ExecOutcome };

The result of a run.

logical.Approvaltypeno test imports it
type 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 it
type 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 it
type ExecError = { readonly kind: "plan-changed"; readonly approved: PlanHash; readonly actual: PlanHash };

Why a run did not start.

logical.RunPlanOptionstypeno test imports it
type 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 it
function vectorOf(step: ExecStep, mode: ExecMode): readonly string[] | undefined

The argument vector of a step in a mode; none where the tool has no check mode.

logical.overallOffunctionno test imports it
function overallOf(steps: readonly StepResult[]): ExecOutcome

What a run ended as, from its steps.

logical.runPlanfunctionno test imports it
function 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 it
function 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 it
function progressOf(event: ExecEvent): ProgressEvent | undefined

The 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 it
type ExecMode = "check" | "apply";

What a run does: look and change nothing (check), or do it (apply).

StepIdtypeno test imports it
type StepId = Brand<string, "step id">;

The identity of a step in a plan, stable across runs: made only by parseStepId.

parseStepIdfunction
function 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

ExecSteptype
type 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

ExecutionPlantype
type 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

PlanProblemtypeno test imports it
type 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.

planOffunction
function planOf(target: string, steps: readonly ExecStep[]): Result<ExecutionPlan, readonly PlanProblem[]>

A plan from its steps, or everything wrong with it.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

canonicalOffunction
function canonicalOf(plan: ExecutionPlan): string

The 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

PlanHashtypeno test imports it
type PlanHash = Brand<string, "plan hash">;

The hash of a plan, sha256: and 64 hexadecimal digits: made only by planHash or parsePlanHash.

parsePlanHashfunction
function parsePlanHash(text: string): Result<PlanHash, string>

A plan hash from text (as a signature carries it), or why the text is not one.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

planHashfunction
function planHash(plan: ExecutionPlan): PlanHash

The hash of a plan: SHA-256 of its canonical form.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

StepOutcometypeno test imports it
type StepOutcome = "unchanged" | "changed" | "applied" | "failed" | "unsupported" | "skipped";

What one step ended as.

StepResulttypeno test imports it
type 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.

ExecEventtype
type 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

ExecOutcometypeno test imports it
type 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 it
type ExecutionResult = { readonly mode: ExecMode; readonly planHash: PlanHash; readonly steps: readonly StepResult[]; readonly outcome: ExecOutcome };

The result of a run.

Approvaltypeno test imports it
type 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 it
type 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 it
type ExecError = { readonly kind: "plan-changed"; readonly approved: PlanHash; readonly actual: PlanHash };

Why a run did not start.

RunPlanOptionstypeno test imports it
type 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 it
function vectorOf(step: ExecStep, mode: ExecMode): readonly string[] | undefined

The argument vector of a step in a mode; none where the tool has no check mode.

overallOffunctionno test imports it
function overallOf(steps: readonly StepResult[]): ExecOutcome

What a run ended as, from its steps.

runPlanfunction
function 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

describePlanfunction
function 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.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

progressOffunction
function progressOf(event: ExecEvent): ProgressEvent | undefined

The progress event a command forwards for an execution event, or none where the event adds nothing the surface does not already show.

Imported by 5 tests of the run (5 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.