IF Commons GitHub

supply-chain/commands

Written to: 1 requirement: 0 proved, 0 partly, 0 failing, 1 with no test recorded. 0001-ontologies FR-001

What a manager runs for an operation, read from the packaging ontology as typed values (commons 0002-packaging FR-024 to FR-027): for a manager id and an operation, the executable, the environment, whether it needs administrator rights, the command as a list of words, its non-interactive form and whether it was run on a real computer; for a manager, the written form of an exact version and the commands it forbids. A manager dialect (brew, apt, winget, mise) asks this module and nothing else: it parses no RDF and copies no template.

A manager is named by a branded value made only by parseManagerId, which accepts the identifiers the ontology states and no others; an operation is the closed union Operation. A command is words, never a shell string, with {package}, {packages} and {version} where the ontology holds them, so that a caller runs it without a shell. verified is true only where the ontology's command carries pm:verifiedOn; one of origin memory or unverified is verified: false. Where the ontology states no command, the answer is not-defined: nothing here supplies one.

import { commandOf, parseManagerId, describeCommandError } from "@intellectual-frontiers/ontology/supply-chain/commands";

const brew = parseManagerId("brew");
if (brew.kind === "ok") {
  const q = commandOf(brew.value, "QueryVersion");
  if (q.kind === "ok") console.log(q.value.template); // ["brew", "list", "--versions", "{package}"]
  else console.error(describeCommandError(q.error));
}

Source: commons/ontology/src/supply-chain/commands.ts

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

ManagerIdtypeno test imports it
type ManagerId = Brand<string, "ManagerId">;

The identifier of a package manager (apt, brew, winget, mise): one the ontology states.

OPERATIONSconstno test imports it
const OPERATIONS: readonly ["Install", "QueryVersion", "QueryInstalled", "Refresh"]

The operations a dialect asks for, as the ontology names them.

Operationtypeno test imports it
type Operation = (typeof OPERATIONS)[number];

One operation of a manager: install, the version of an installed package, whether a package is installed, and the refresh of the package index.

CommandNametypeno test imports it
type CommandName = Operation | "ExactVersion";

What a command answers: one of the four operations, or the written form of an exact version.

Wordstypeno test imports it
type Words = readonly string[];

A command as words, run without a shell.

CommandSpectypeno test imports it
type CommandSpec = { readonly manager: ManagerId; /** The program the manager is (`apt-get` for `apt`); the words of… (1012 characters)
type CommandSpec = {
  readonly manager: ManagerId;
  /** The program the manager is (`apt-get` for `apt`); the words of a template start with the program of its own form, which may be another (`apt`). */
  readonly executable: string;
  /** The variables the manager's commands run with, as the ontology holds them (`NAME=value`, words separated by spaces); absent where it has none. */
  readonly environment?: string;
  readonly needsAdministrator: boolean;
  /** The command a person runs, with `{package}`, `{packages}` and `{version}` where names and versions stand. */
  readonly template: Words;
  /** The form a harness runs without a question, where the ontology states one. */
  readonly nonInteractive?: Words;
  /** Of `QueryInstalled`, the exit status that says the package is not installed; absent where the ontology states none. */
  readonly missingExitStatus?: number;
  /** True only where the command carries `pm:verifiedOn`: it was run on a real computer. */
  readonly verified: boolean;
};

One command of one manager, as the ontology states it.

Prohibitiontypeno test imports it
type Prohibition = { readonly template: Words; readonly reason: string };

A command a manager must never be given, with why.

CommandErrortypeno test imports it
type CommandError =
  | { readonly kind: "unknown-manager"; readonly manager: string }
  | { readonly kind: "unknown-operation"; readonly operation: string }
  | { readonly kind: "not-defined"; readonly manager: ManagerId; readonly operation: CommandName }
  | { readonly kind: "malformed"; readonly manager: ManagerId; readonly operation: CommandName; readonly reason: string };

Why a command is not given.

parseManagerIdfunctionno test imports it
function parseManagerId(text: string): Result<ManagerId, CommandError>

The manager the ontology states under this identifier, or why there is none.

parseOperationfunctionno test imports it
function parseOperation(text: string): Result<"Install" | "QueryInstalled" | "QueryVersion" | "Refresh", CommandError>

The operation of this name (Install, QueryVersion, QueryInstalled, Refresh), or why there is none.

managerIdsfunctionno test imports it
function managerIds(): readonly ManagerId[]

Every manager the ontology states, by identifier.

operationNamesfunctionno test imports it
function operationNames(): readonly ("Install" | "QueryInstalled" | "QueryVersion" | "Refresh")[]

Every operation a dialect may ask for.

wordsOfTemplatefunctionno test imports it
function wordsOfTemplate(template: string): Result<Words, string>

The words of a template, or why it is none: a template that is empty or holds a quotation, an escape or a shell character is refused, because a command is run without a shell.

wordsOfTemplate("brew list --versions {package}"); // ok: ["brew", "list", "--versions", "{package}"]
wordsOfTemplate("ls | wc"); // err: the template holds a shell character
commandOffunctionno test imports it
function commandOf(manager: ManagerId, operation: "Install" | "QueryInstalled" | "QueryVersion" | "Refresh"): Result<CommandSpec, CommandError>

The command of a manager for an operation, or why there is none.

const apt = parseManagerId("apt");
if (apt.kind === "ok") commandOf(apt.value, "Install"); // ok: { executable: "apt-get", environment: "DEBIAN_FRONTEND=noninteractive", verified: true, ... }
exactVersionOffunctionno test imports it
function exactVersionOf(manager: ManagerId): Result<CommandSpec, CommandError>

How a manager writes one package at one exact version ({package} and {version} in the words), in the shape of commandOf, or not-defined where the ontology states none.

const winget = parseManagerId("winget");
if (winget.kind === "ok") exactVersionOf(winget.value); // ok: template ["winget", "install", "--exact", "--id", "{package}", "--version", "{version}"], verified: false
prohibitionsOffunctionno test imports it
function prohibitionsOf(manager: ManagerId): readonly Prohibition[]

The commands the ontology forbids for a manager, each with its reason (pacman -Sy: a refresh alone leaves a rolling release partly upgraded); none where it forbids none.

const pacman = parseManagerId("pacman");
if (pacman.kind === "ok") prohibitionsOf(pacman.value)[0]; // { template: ["pacman", "-Sy"], reason: "Refreshing the package list alone ..." }
describeCommandErrorfunctionno test imports it
function describeCommandError(e: CommandError): string

The sentence a reason is told in.

describeCommandError({ kind: "unknown-operation", operation: "Purge" }); // "the reader knows no operation Purge (Install, QueryVersion, QueryInstalled, Refresh)"

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