Platformtypetype Platform = "linux-x64" | "linux-arm64" | "macos-x64" | "macos-arm64" | "windows-x64";A platform a pin can have a download for.
A tool: a program a computer needs, declared once. It has a pin policy, what it provides and needs, the phase of work that first needs it, the scope it lives in and the bindings that say how a dialect obtains it: a reference to a pin of the packaging ontology (which holds the version and the checksums, so that a declaration never copies a version or a hash), or the names a package manager of the ontology knows. defineTool is the one way to make one, and it refuses with every reason what is not one. A download, as a pin gives it for a platform, is checked by defineDownload.
import { defineTool } from "./tool.ts";
const r = defineTool({
name: "jq",
summary: "A command line JSON processor.",
pin: "exact",
program: "jq",
versionArgs: ["--version"],
phases: ["core"],
scope: "user",
bindings: [{ kind: "pin", pin: "jq" }, { kind: "package", manager: "manager-brew", packages: ["jq"] }],
});
r.kind; // "ok"Platformtypetype Platform = "linux-x64" | "linux-arm64" | "macos-x64" | "macos-arm64" | "windows-x64";A platform a pin can have a download for.
PLATFORMSconstno test imports itconst PLATFORMS: readonly Platform[]Every platform.
Phasetypeno test imports ittype Phase = "core" | "dev" | "test" | "stage" | "publish";The phase of work that first needs a tool.
PHASESconstno test imports itconst PHASES: readonly Phase[]Every phase, from the first needed to the last.
Scopetypeno test imports ittype Scope = "user" | "system";Where a tool lives: in a user's folder, or in the system's.
PinPolicytypeno test imports ittype PinPolicy = "exact" | "release-line" | "rolling";How strictly a tool is pinned.
PIN_POLICIESconstno test imports itconst PIN_POLICIES: readonly PinPolicy[]Every pin policy, from the least strict to the most.
ArtifactFormattypeno test imports ittype ArtifactFormat = "zip" | "tar" | "file";The format of what a download address gives.
Downloadtypetype Download = {
readonly version: Version;
readonly downloadUrl: string;
readonly sha256: Sha256;
readonly archiveFormat: ArtifactFormat;
readonly binPath: string;
};What a pin gives for one platform: the version, the address, the SHA-256 of what is there, its format and the folder of its programs inside it.
Bindingtypeno test imports ittype Binding =
| { readonly kind: "pin"; readonly pin: PinId }
| { readonly kind: "package"; readonly manager: ManagerId; readonly packages: readonly string[]; readonly version?: Version };How a dialect obtains a tool: the download a pin of the ontology gives, or the names of the packages a package manager of the ontology knows (at a version, where one is named).
Tooltypetype Tool = {
readonly name: ToolName;
readonly summary: string;
readonly pin: PinPolicy;
/** The least version … (942 characters)type Tool = {
readonly name: ToolName;
readonly summary: string;
readonly pin: PinPolicy;
/** The least version of a copy found on the computer that may be taken. */
readonly minimum?: Version;
/** The program, or the file, whose presence proves it. */
readonly program: string;
/** How the program is asked its version; none where it cannot be asked. */
readonly versionArgs: readonly string[];
readonly needs: readonly ToolName[];
/** The variables it sets for the programs that run it. */
readonly env: Readonly<Record<string, string>>;
/** The other programs it provides. */
readonly provides: readonly string[];
/** The other names a copy of its program may go by on a computer (Chromium is also `chrome` and `google-chrome`), tried after the program's own. */
readonly alsoNamed: readonly string[];
readonly phases: readonly Phase[];
readonly scope: Scope;
readonly bindings: readonly Binding[];
};A tool. It holds no version and no hash of a pin: it references the pin.
DownloadInputtypetype DownloadInput = { readonly version: string; readonly downloadUrl: string; readonly sha256: string; readonly archiveFormat: string; readonly binPath: string };A download as a source of pins gives it.
BindingInputtypeno test imports ittype BindingInput =
| { readonly kind: "pin"; readonly pin: string }
| { readonly kind: "package"; readonly manager: string; readonly packages: readonly string[]; readonly version?: string };A binding as written.
ToolInputtypetype ToolInput = {
readonly name: string;
readonly summary: string;
readonly pin: string;
readonly minimum?: str… (480 characters)type ToolInput = {
readonly name: string;
readonly summary: string;
readonly pin: string;
readonly minimum?: string;
readonly program: string;
readonly versionArgs: readonly string[];
readonly needs?: readonly string[];
readonly env?: Readonly<Record<string, string>>;
readonly provides?: readonly string[];
readonly alsoNamed?: readonly string[];
readonly phases: readonly string[];
readonly scope: string;
readonly bindings: readonly BindingInput[];
};What defineTool takes.
defineDownloadfunctionfunction defineDownload(input: DownloadInput): Result<Download, readonly string[]>A download from what a source of pins gave, or every reason it is not one: an https address with no user name or password, a SHA-256, a format and a folder inside the unpacked folder.
defineToolfunctionfunction defineTool(input: ToolInput): Result<Tool, readonly string[]>A tool, or every reason the input is not one.