ManagerIdtypeno test imports ittype ManagerId = Brand<string, "ManagerId">;The identifier of a package manager (apt, brew, winget, mise): one the ontology states.
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));
}ManagerIdtypeno test imports ittype ManagerId = Brand<string, "ManagerId">;The identifier of a package manager (apt, brew, winget, mise): one the ontology states.
OPERATIONSconstno test imports itconst OPERATIONS: readonly ["Install", "QueryVersion", "QueryInstalled", "Refresh"]The operations a dialect asks for, as the ontology names them.
Operationtypeno test imports ittype 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 ittype CommandName = Operation | "ExactVersion";What a command answers: one of the four operations, or the written form of an exact version.
Wordstypeno test imports ittype Words = readonly string[];A command as words, run without a shell.
CommandSpectypeno test imports ittype 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 ittype Prohibition = { readonly template: Words; readonly reason: string };A command a manager must never be given, with why.
CommandErrortypeno test imports ittype 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 itfunction parseManagerId(text: string): Result<ManagerId, CommandError>The manager the ontology states under this identifier, or why there is none.
parseOperationfunctionno test imports itfunction 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 itfunction managerIds(): readonly ManagerId[]Every manager the ontology states, by identifier.
operationNamesfunctionno test imports itfunction operationNames(): readonly ("Install" | "QueryInstalled" | "QueryVersion" | "Refresh")[]Every operation a dialect may ask for.
wordsOfTemplatefunctionno test imports itfunction 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 charactercommandOffunctionno test imports itfunction 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 itfunction 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: falseprohibitionsOffunctionno test imports itfunction 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 itfunction describeCommandError(e: CommandError): stringThe sentence a reason is told in.
describeCommandError({ kind: "unknown-operation", operation: "Purge" }); // "the reader knows no operation Purge (Install, QueryVersion, QueryInstalled, Refresh)"