IF Commons GitHub

install

Written to: 8 requirements: 8 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-native-pinned-install FR-001, 0002-native-pinned-install FR-002, 0002-native-pinned-install FR-003, 0002-native-pinned-install FR-004, 0002-native-pinned-install FR-005, 0002-native-pinned-install FR-006 and 2 more

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"

Source: commons/archon-dialect-native-pinned/src/install.ts

11 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.

describeInstallErrorfunction
function describeInstallError(e: InstallError): string

An install error as one sentence that says what happened and that nothing was written.

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

programFilefunction
function programFile(s: { readonly program: string; readonly binPath: string; readonly os: Os; }): string

The 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.

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

unpackVerifiedfunction
function 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.

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

InstallErrortypeno test imports it
type 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.

InstallSpectype
type 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.

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

Ostypeno test imports it
type Os = "linux" | "macos" | "windows";

The operating systems a tool is installed on.

INSTALL_RECORDconst
const INSTALL_RECORD: ".archon-install.json"

The name of the install record inside a tool's folder.

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

InstallRecordtypeno test imports it
type 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.

installRecordOffunction
function 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.

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

writeInstallRecordfunction
function writeInstallRecord(r: InstallRecord): string

The text of an install record: JSON with its keys in a fixed order, two spaces and a final line break.

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

readInstallRecordfunction
function readInstallRecord(text: string): Result<InstallRecord, string>

An install record from its text, or why it is not one.

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

InstallDrifttypeno test imports it
type 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 it
type 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.

installDriftfunction
function 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.

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

describeDriftfunction
function describeDrift(tool: string, d: InstallDrift): string

An install drift as one sentence.

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

Shimtypeno test imports it
type Shim = { readonly name: string; readonly text: string };

A shim: the file's name below the shim folder and its text.

shimOffunction
function 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.

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

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