describeInstallErrorfunctionfunction describeInstallError(e: InstallError): stringAn install error as one sentence that says what happened and that nothing was written.
What an install of a pinned tool is, as pure functions (reshaped from the workspaces manager's own, commons ergonex 0002-workspace-model FR-039): the bytes of a downloaded artifact are checked against the pinned SHA-256 before anything is unpacked, an archive is unpacked in memory with every path checked, the install record keeps the SHA-256 of each file so that a change since can be found, and a shim puts a command in one folder. No file is read or written here and no network is reached.
A hash that differs is hash-mismatch and nothing is returned: there is no function here that gives files for bytes that did not match. An archive is refused whole for a path that leaves the folder, a path twice, or a link that cannot be installed safely (links.ts says which are: a relative target that stays inside the folder, names what the archive holds (a link may name a link) and passes through no other link). A tar is read whether it is plain, gzipped or xz-compressed, found by its first bytes. The program of a tool is found at its folder with its name, with .exe added on Windows where the name has no extension.
import { programFile } from "./install.ts";
programFile({ program: "bun", binPath: "bun-linux-x64", os: "linux" }); // "bun-linux-x64/bun"describeInstallErrorfunctionfunction describeInstallError(e: InstallError): stringAn install error as one sentence that says what happened and that nothing was written.
programFilefunctionfunction programFile(s: { readonly program: string; readonly binPath: string; readonly os: Os; }): stringThe path of the program inside an install: its folder, and its name with .exe where the system is Windows and the name has no extension.
unpackVerifiedfunctionfunction unpackVerified(spec: InstallSpec, bytes: Uint8Array<ArrayBufferLike>): Promise<Result<Unpacked, InstallError>>The files and symbolic links of a downloaded artifact, once the bytes are the pinned bytes: the hash is checked first and nothing is unpacked for a hash that differs.
InstallErrortypeno test imports ittype InstallError =
| { readonly kind: "hash-mismatch"; readonly url: string; readonly expected: Sha256; readonly actual: Sha256 }
| { readonly kind: "unpack"; readonly error: ArchiveError }
| { readonly kind: "duplicate-path"; readonly path: string }
| LinkRefusal
| { readonly kind: "missing-program"; readonly path: string };Why a tool was not installed; nothing is written for any of them.
InstallSpectypetype InstallSpec = {
readonly tool: string;
readonly version: string;
readonly platform: string;
readonly os: Os;
readonly program: string;
readonly downloadUrl: string;
readonly sha256: Sha256;
readonly archiveFormat: "zip" | "tar" | "file";
readonly binPath: string;
};What an install is made from: the tool, and the download its pin gave for the platform.
Ostypeno test imports ittype Os = "linux" | "macos" | "windows";The operating systems a tool is installed on.
INSTALL_RECORDconstconst INSTALL_RECORD: ".archon-install.json"The name of the install record inside a tool's folder.
InstallRecordtypeno test imports ittype InstallRecord = {
readonly tool: string;
readonly version: string;
readonly platform: string;
readonly url:… (535 characters)type InstallRecord = {
readonly tool: string;
readonly version: string;
readonly platform: string;
readonly url: string;
/** The SHA-256 of the pinned artifact. */
readonly artifactSha256: string;
/** The path of the program inside the folder. */
readonly program: string;
/** The SHA-256 of each file, by its path inside the folder. */
readonly files: Readonly<Record<string, string>>;
/** The target of each symbolic link, by its path inside the folder. */
readonly links: Readonly<Record<string, string>>;
};What an install left: the tool, the artifact it came from, the program and the SHA-256 of each file, written beside the files.
installRecordOffunctionfunction installRecordOf(spec: InstallSpec, unpacked: Unpacked): Promise<InstallRecord>The record of an install: names the tool and the pin and holds the hash of every file.
writeInstallRecordfunctionfunction writeInstallRecord(r: InstallRecord): stringThe text of an install record: JSON with its keys in a fixed order, two spaces and a final line break.
readInstallRecordfunctionfunction readInstallRecord(text: string): Result<InstallRecord, string>An install record from its text, or why it is not one.
InstallDrifttypeno test imports ittype InstallDrift =
| { readonly kind: "changed"; readonly path: string }
| { readonly kind: "missing"; readonly path: string }
| { readonly kind: "extra"; readonly path: string }
| { readonly kind: "unpinned"; readonly reason: string };What a comparison of an installed folder with its record found.
FoundFoldertypeno test imports ittype FoundFolder = { readonly files: Readonly<Record<string, string>>; readonly links: Readonly<Record<string, string>> };What was found in a tool's folder: the SHA-256 of each file by its path, and the target of each symbolic link by its path.
installDriftfunctionfunction installDrift(record: InstallRecord, found: FoundFolder, pinSha256?: string | undefined): readonly InstallDrift[]Compares what was found in a tool's folder with its record, and the record with the pin; every file or link changed, missing or extra is told, in the order of the paths, files before links.
describeDriftfunctionfunction describeDrift(tool: string, d: InstallDrift): stringAn install drift as one sentence.
Shimtypeno test imports ittype Shim = { readonly name: string; readonly text: string };A shim: the file's name below the shim folder and its text.
shimOffunctionfunction shimOf(os: Os, command: string, exe: string): Result<Shim, string>The shim of one command of a tool: a POSIX sh script that runs the installed program with its arguments (command), or on Windows a .cmd file (command.cmd). exe is the absolute path of the installed program; a path that cannot be put in the file safely (a line break anywhere, a ", %, ^, &, |, < or > on Windows) is refused.