IF Commons GitHub

governance/action

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0008-exit-style-consent FR-004

What a headless action is, before any surface draws it (commons headless 0002-headless-governance): its identity, who it is for, what it may do to the world (read, mutate, destructive), whether repeating it is safe, whether it can preview itself, and which of its options only a person may give. A report only reads; an action changes something. From those facts alone decide says whether a run proceeds, previews, asks the person, or is refused, so that a command line, a tool server and a REST route decide it the same way.

This module imports Core alone and names no surface: nothing here prints, prompts or reads the environment.

import { defineAction, decide } from "./action.ts";
const wipe = defineAction({ id: "cache wipe", summary: "Delete the cache.", kind: "action", effect: "destructive", dryRun: true });
decide(wipe, { audience: "human", interactive: false, flagConfirms: true }, { mode: "apply", confirmed: false, given: [] }).kind; // "refuse"

Source: commons/headless/src/governance/action.ts

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

governance.Kindtypeno test imports it
type Kind = "report" | "action";

A report only reads and says what it found; an action changes something.

governance.Effecttypeno test imports it
type Effect = "read" | "mutate" | "destructive";

What a run may do to the world: nothing (read), something that can be undone or redone (mutate), or something that cannot be undone (destructive).

governance.Audiencetypeno test imports it
type Audience = "human" | "machine" | "both";

Who an action is for: a person at a terminal, a program (a script, an agent), or both.

governance.ActionFactstypeno test imports it
type ActionFacts = { /** Its words as a person types them (`work build`): lower-case words joined by spaces. */ read… (914 characters)
type ActionFacts = {
  /** Its words as a person types them (`work build`): lower-case words joined by spaces. */
  readonly id: string;
  readonly summary: string;
  readonly kind: Kind;
  readonly effect: Effect;
  /** Whether running it again with the same input changes nothing more. */
  readonly idempotent: boolean;
  readonly audience: Audience;
  /** The tier a caller must hold to see and run it (0010-audience-tiers): the lowest tier of the program's ladder unless it says otherwise. */
  readonly tier: TierName;
  /** Whether `--dry-run` previews what it would change and changes nothing. */
  readonly dryRun: boolean;
  /** Whether `--check` ends with findings where it would change something (a drift check), changing nothing. */
  readonly check: boolean;
  /** The options (by their keys) that only a person may give: a machine surface refuses them. */
  readonly humanOnly: readonly string[];
};

The facts of an action.

governance.ActionDefinitiontypeno test imports it
type ActionDefinition = {
  readonly id: string;
  readonly summary: string;
  readonly kind: Kind;
  readonly effect?: Effect;
  readonly idempotent?: boolean;
  readonly audience?: Audience;
  readonly tier?: TierName;
  readonly dryRun?: boolean;
  readonly check?: boolean;
  readonly humanOnly?: readonly string[];
};

What defineAction takes: the identity and summary, and the facts that are not the defaults of its kind.

governance.defineActionfunctionno test imports it
function defineAction(d: ActionDefinition): ActionFacts

An action's facts with the defaults of its kind: a report reads, is idempotent and has no preview; an action mutates, is not assumed idempotent and has no preview until it says so. Everyone is the audience unless it says otherwise.

governance.ActionRuletypeno test imports it
type ActionRule =
  | "action/id"
  | "action/summary"
  | "action/report-changes"
  | "action/action-reads"
  | "action/destructive-no-preview"
  | "action/idempotent-destructive"
  | "action/human-only-duplicate"
  | "action/check-on-read";

The ways an action's facts can contradict each other.

governance.ActionProblemtypeno test imports it
type ActionProblem = { readonly rule: ActionRule; readonly message: string };

A contradiction in an action's facts.

governance.actionProblemsfunctionno test imports it
function actionProblems(a: ActionFacts): readonly ActionProblem[]

Every contradiction in an action's facts, in the order of the rules.

governance.Modetypeno test imports it
type Mode = "apply" | "dry-run" | "check";

How a run is to treat its effect: do it, preview it, or check for the need of it.

governance.modeOffunctionno test imports it
function modeOf(flags: { readonly dryRun: boolean; readonly check: boolean; }): Result<Mode, string>

The mode the flags ask for; both flags at once are not one mode.

governance.mayChangefunctionno test imports it
function mayChange(mode: Mode): boolean

Whether a run in this mode may change anything.

governance.SurfaceFactstypeno test imports it
type SurfaceFacts = { /** `human` for a person at a terminal or in a window; `machine` for a program that calls it (a … (622 characters)
type SurfaceFacts = {
  /** `human` for a person at a terminal or in a window; `machine` for a program that calls it (a tool server, a REST route). */
  readonly audience: "human" | "machine";
  /** Whether the person can be asked a question now (a terminal on both ends). */
  readonly interactive: boolean;
  /** Whether `--yes` (or its like) may stand for the person's answer: a command line yes, a tool server no. */
  readonly flagConfirms: boolean;
  /** Whether a prior consent (`--consent <id>`) may stand for the answer; the value of `flagConfirms` where it is not said. */
  readonly acceptsConsent?: boolean;
};

What a surface is, for the decision: who is on the other side, whether it can ask, and whether a flag of the invocation may stand for the answer.

governance.Invocationtypeno test imports it
type Invocation = {
  readonly mode: Mode;
  readonly confirmed: boolean;
  readonly given: readonly string[];
  /** The identifier of a consent a person gave earlier, where the invocation carries one. */
  readonly consent?: string;
};

What the invocation gave: its mode, whether it carried the confirmation flag, and the keys of the options it set.

governance.Refusaltypeno test imports it
type Refusal = "human-only-action" | "human-only-option" | "confirmation-needed" | "confirmation-not-accepted" | "consent-needed";

Why a run is refused.

governance.Decisiontypeno test imports it
type Decision =
  | { readonly kind: "proceed" }
  | { readonly kind: "preview" }
  | { readonly kind: "ask" }
  | { readonly kind: "refuse"; readonly reason: Refusal; readonly message: string };

What to do with a run.

governance.humanOnlyGivenfunctionno test imports it
function humanOnlyGiven(a: ActionFacts, given: readonly string[]): readonly string[]

The options of an invocation that only a person may give.

governance.decidefunctionno test imports it
function decide(a: ActionFacts, surface: SurfaceFacts, inv: Invocation, reach?: ReachPolicy | undefined): Decision

What to do with a run, from the action's facts, the surface and the invocation (FR-004, FR-005): refuse what a machine may not do, preview what is asked to be a preview, proceed with what only reads or can be undone, and for what cannot be undone ask the person, accept the flag where the surface lets a flag stand for the answer, and refuse where there is neither. Where the reach policy's confirmation class is consent, an action that changes something proceeds on a prior consent (--consent <id>), asks a person where there is one, and is refused otherwise (consent-needed).

Kindtypeno test imports it
type Kind = "report" | "action";

A report only reads and says what it found; an action changes something.

Effecttypeno test imports it
type Effect = "read" | "mutate" | "destructive";

What a run may do to the world: nothing (read), something that can be undone or redone (mutate), or something that cannot be undone (destructive).

Audiencetypeno test imports it
type Audience = "human" | "machine" | "both";

Who an action is for: a person at a terminal, a program (a script, an agent), or both.

ActionFactstype
type ActionFacts = { /** Its words as a person types them (`work build`): lower-case words joined by spaces. */ read… (914 characters)
type ActionFacts = {
  /** Its words as a person types them (`work build`): lower-case words joined by spaces. */
  readonly id: string;
  readonly summary: string;
  readonly kind: Kind;
  readonly effect: Effect;
  /** Whether running it again with the same input changes nothing more. */
  readonly idempotent: boolean;
  readonly audience: Audience;
  /** The tier a caller must hold to see and run it (0010-audience-tiers): the lowest tier of the program's ladder unless it says otherwise. */
  readonly tier: TierName;
  /** Whether `--dry-run` previews what it would change and changes nothing. */
  readonly dryRun: boolean;
  /** Whether `--check` ends with findings where it would change something (a drift check), changing nothing. */
  readonly check: boolean;
  /** The options (by their keys) that only a person may give: a machine surface refuses them. */
  readonly humanOnly: readonly string[];
};

The facts of an action.

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

ActionDefinitiontypeno test imports it
type ActionDefinition = {
  readonly id: string;
  readonly summary: string;
  readonly kind: Kind;
  readonly effect?: Effect;
  readonly idempotent?: boolean;
  readonly audience?: Audience;
  readonly tier?: TierName;
  readonly dryRun?: boolean;
  readonly check?: boolean;
  readonly humanOnly?: readonly string[];
};

What defineAction takes: the identity and summary, and the facts that are not the defaults of its kind.

defineActionfunction
function defineAction(d: ActionDefinition): ActionFacts

An action's facts with the defaults of its kind: a report reads, is idempotent and has no preview; an action mutates, is not assumed idempotent and has no preview until it says so. Everyone is the audience unless it says otherwise.

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

ActionRuletypeno test imports it
type ActionRule =
  | "action/id"
  | "action/summary"
  | "action/report-changes"
  | "action/action-reads"
  | "action/destructive-no-preview"
  | "action/idempotent-destructive"
  | "action/human-only-duplicate"
  | "action/check-on-read";

The ways an action's facts can contradict each other.

ActionProblemtypeno test imports it
type ActionProblem = { readonly rule: ActionRule; readonly message: string };

A contradiction in an action's facts.

actionProblemsfunction
function actionProblems(a: ActionFacts): readonly ActionProblem[]

Every contradiction in an action's facts, in the order of the rules.

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

Modetype
type Mode = "apply" | "dry-run" | "check";

How a run is to treat its effect: do it, preview it, or check for the need of it.

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

modeOffunction
function modeOf(flags: { readonly dryRun: boolean; readonly check: boolean; }): Result<Mode, string>

The mode the flags ask for; both flags at once are not one mode.

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

mayChangefunction
function mayChange(mode: Mode): boolean

Whether a run in this mode may change anything.

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

SurfaceFactstype
type SurfaceFacts = { /** `human` for a person at a terminal or in a window; `machine` for a program that calls it (a … (622 characters)
type SurfaceFacts = {
  /** `human` for a person at a terminal or in a window; `machine` for a program that calls it (a tool server, a REST route). */
  readonly audience: "human" | "machine";
  /** Whether the person can be asked a question now (a terminal on both ends). */
  readonly interactive: boolean;
  /** Whether `--yes` (or its like) may stand for the person's answer: a command line yes, a tool server no. */
  readonly flagConfirms: boolean;
  /** Whether a prior consent (`--consent <id>`) may stand for the answer; the value of `flagConfirms` where it is not said. */
  readonly acceptsConsent?: boolean;
};

What a surface is, for the decision: who is on the other side, whether it can ask, and whether a flag of the invocation may stand for the answer.

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

Invocationtypeno test imports it
type Invocation = {
  readonly mode: Mode;
  readonly confirmed: boolean;
  readonly given: readonly string[];
  /** The identifier of a consent a person gave earlier, where the invocation carries one. */
  readonly consent?: string;
};

What the invocation gave: its mode, whether it carried the confirmation flag, and the keys of the options it set.

Refusaltypeno test imports it
type Refusal = "human-only-action" | "human-only-option" | "confirmation-needed" | "confirmation-not-accepted" | "consent-needed";

Why a run is refused.

Decisiontype
type Decision =
  | { readonly kind: "proceed" }
  | { readonly kind: "preview" }
  | { readonly kind: "ask" }
  | { readonly kind: "refuse"; readonly reason: Refusal; readonly message: string };

What to do with a run.

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

humanOnlyGivenfunction
function humanOnlyGiven(a: ActionFacts, given: readonly string[]): readonly string[]

The options of an invocation that only a person may give.

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

decidefunction
function decide(a: ActionFacts, surface: SurfaceFacts, inv: Invocation, reach?: ReachPolicy | undefined): Decision

What to do with a run, from the action's facts, the surface and the invocation (FR-004, FR-005): refuse what a machine may not do, preview what is asked to be a preview, proceed with what only reads or can be undone, and for what cannot be undone ask the person, accept the flag where the surface lets a flag stand for the answer, and refuse where there is neither. Where the reach policy's confirmation class is consent, an action that changes something proceeds on a prior consent (--consent <id>), asks a person where there is one, and is refused otherwise (consent-needed).

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

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