@crewhaus/tool-pkgmgr 0.7.0

package/dist/lib/unknown.js

@@ -0,0 +1,85 @@
+/**
+ * The vocabulary for "I could not find out" — `@crewhaus/tool-host`'s
+ * `lib/unknown.ts`, reproduced here because that package exports its tools
+ * and not its library, and the rule it encodes is the one this package is
+ * most likely to break.
+ *
+ * A caller asks whether `curl` is installed in order to decide something:
+ * whether to install it, whether to pick a different strategy, whether to
+ * tell an operator the host is not ready. Every one of those decisions is
+ * made WRONGLY, and silently, if a probe that could not answer comes back as
+ * "no":
+ *
+ *   - `dpkg-query` is not on the host (this is a Fedora box)  -> "not installed"
+ *   - `dnf --cacheonly` has no cached metadata                -> "not available"
+ *   - `apt-cache policy` printed German labels                -> "no candidate"
+ *   - `winget list` printed a row whose name was truncated    -> wrong version
+ *   - the command hit its deadline                            -> "not installed"
+ *   - `brew info` exited non-zero for a reason nobody parsed  -> "not installed"
+ *
+ * So: a fact that could not be established is `null` in the result AND
+ * carries an entry here naming the field, the probe that was tried, and why
+ * it did not answer. A boolean is never defaulted to false, a version is
+ * never defaulted to "latest", and a status is `"unknown"` rather than
+ * `"not-installed"` unless the manager gave its own documented not-found
+ * signal. `every null is explained` in index.test.ts walks each tool's output
+ * and fails if any null is missing its entry, so the rule cannot rot.
+ */
+/** Collects unknowns for one tool call. */
+export class Unknowns {
+    facts = new Map();
+    add(field, probe, reason) {
+        // First writer wins: the innermost probe that failed is the specific one,
+        // and a later generic "this section is unavailable" must not overwrite it.
+        if (!this.facts.has(field))
+            this.facts.set(field, { field, probe, reason });
+    }
+    has(field) {
+        return this.facts.has(field);
+    }
+    get size() {
+        return this.facts.size;
+    }
+    /**
+     * Sorted by field, so two calls against the same machine return the same
+     * bytes rather than whatever order the probes happened to fail in.
+     */
+    list() {
+        return [...this.facts.values()].sort((a, b) => a.field < b.field ? -1 : a.field > b.field ? 1 : 0);
+    }
+}
+/**
+ * Describe a failed command, keeping apart the cases a caller acts on
+ * differently: a manager that is NOT INSTALLED (this is the wrong host, or
+ * ask a different manager), one that TIMED OUT (the answer is unknown and
+ * retrying may work), and one that RAN AND FAILED (its stderr is the lead).
+ */
+export function commandFailureReason(result) {
+    if (result.missing)
+        return "the command is not installed on this host";
+    if (result.timedOut) {
+        return result.abandoned === true
+            ? "the command did not finish within its timeout and could not be reaped"
+            : "the command did not finish within its timeout";
+    }
+    const detail = firstLine(result.stderr);
+    return detail === ""
+        ? `the command exited ${result.code}`
+        : `the command exited ${result.code}: ${detail}`;
+}
+/**
+ * The first non-empty line, capped.
+ *
+ * A manager's usage message can be forty lines long — `dnf` prints its whole
+ * option grammar on a bad flag — and none of it belongs in a result a model
+ * has to read.
+ */
+export function firstLine(text, max = 200) {
+    const line = text
+        .split("\n")
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    if (line === undefined)
+        return "";
+    return line.length <= max ? line : `${line.slice(0, max - 1)}…`;
+}

package/dist/paths.d.ts

@@ -0,0 +1,42 @@
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export declare class ToolPermissionError extends CrewhausError {
+    readonly name = "ToolPermissionError";
+    readonly toolName: string;
+    readonly path: string;
+    constructor(toolName: string, attemptedPath: string);
+}
+/**
+ * A validated path, in both forms the tools need.
+ *
+ * `real` has every in-workspace symlink already resolved and is what I/O
+ * should use — operating on it closes most of the check-to-use window.
+ * `abs` is the lexical resolution, which is what a tool must use when the
+ * question is about the link ITSELF (`Stat` reporting a symlink target,
+ * `RemovePath` deleting a link rather than its destination).
+ */
+export type SafePath = {
+    readonly abs: string;
+    readonly real: string;
+    /** The path as the caller wrote it, for echoing back in results. */
+    readonly given: string;
+    /** Slash-separated path relative to the workspace root. */
+    readonly rel: string;
+};
+/** The workspace root, resolved. Every path is contained within it. */
+export declare function workspaceRoot(): string;
+export declare function resolveSafe(toolName: string, rel: string, root?: string): SafePath;
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export declare function toPosix(p: string): string;
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export declare function isInside(parent: string, candidate: string): boolean;
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export declare function archiveEntryEscapes(name: string): boolean;

package/dist/paths.js

@@ -0,0 +1,158 @@
+/**
+ * Path containment — the gate every caller-supplied path in this package
+ * passes through before any syscall touches it.
+ *
+ * The approach is the one `@crewhaus/tool-fs` uses, and for the same reasons:
+ * a lexical check alone is fooled by a symlink that lives inside the
+ * workspace and points outside it (CWE-59), so the real path is checked too.
+ * The workspace root is `process.cwd()`, matching tool-fs, so a harness that
+ * trusts one tool's boundary gets the same boundary here.
+ */
+import { lstatSync, readlinkSync, realpathSync } from "node:fs";
+import * as path from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+/** Raised when a caller-supplied path resolves outside the workspace root. */
+export class ToolPermissionError extends CrewhausError {
+    name = "ToolPermissionError";
+    toolName;
+    path;
+    constructor(toolName, attemptedPath) {
+        super("tool", `tool "${toolName}" rejected path "${attemptedPath}": resolved location escapes the workspace root`);
+        this.toolName = toolName;
+        this.path = attemptedPath;
+    }
+}
+/** The workspace root, resolved. Every path is contained within it. */
+export function workspaceRoot() {
+    return path.resolve(process.cwd());
+}
+/**
+ * Resolve `rel` inside the workspace, or throw `ToolPermissionError`.
+ *
+ * The leaf is allowed not to exist — every tool here that creates something
+ * needs to validate a destination before it is made — so the deepest
+ * EXISTING ancestor is realpath'd and the missing tail re-appended. Any
+ * failure other than that walk fails closed.
+ */
+/**
+ * True when the NAME exists, whether or not it leads anywhere.
+ *
+ * `existsSync` FOLLOWS symlinks, so it answers false for a link whose target
+ * is missing — and that is exactly the case that matters: a dangling link is
+ * still a door, because `open(…, "w")` through `evil -> /outside/x` CREATES
+ * `/outside/x`. Probing with `lstat` keeps the link's name in the part of the
+ * path that gets resolved, rather than in the "does not exist yet" tail that
+ * is re-appended to the root verbatim and so passes the containment check.
+ */
+function nameExists(p) {
+    try {
+        lstatSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `target` would actually land, with every symlink on the way already
+ * followed — including one whose own target does not exist yet.
+ *
+ * `realpathSync` gives up with ENOENT on a dangling link, which would leave
+ * that link unresolved and let it stand in for a plain missing file. So the
+ * deepest ancestor that exists as a NAME is resolved, a dangling one is
+ * followed a hop by hand, and the components that do not exist are appended.
+ * The result is the path an `open` would create, which is the only path worth
+ * checking containment against.
+ */
+function resolveLocation(target, depth = 0) {
+    if (depth > 40)
+        throw new Error(`symlink chain at "${target}" is too long to resolve`);
+    let probe = target;
+    const tail = [];
+    while (!nameExists(probe)) {
+        tail.unshift(path.basename(probe));
+        const parent = path.dirname(probe);
+        if (parent === probe)
+            break; // reached the filesystem root
+        probe = parent;
+    }
+    let probeReal;
+    try {
+        probeReal = realpathSync(probe);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        // The name is there but `realpath` cannot finish it: a symlink with a
+        // missing target. `readlinkSync` throws EINVAL on anything else, which
+        // fails closed.
+        const link = readlinkSync(probe);
+        // A RELATIVE target resolves against the directory that actually CONTAINS
+        // the link, which is not the link's lexical parent when that parent is
+        // itself reached through a symlink. `<root>/dirlink/x -> ../y` with
+        // `dirlink` pointing out of the root really lands at `<elsewhere>/y`, but
+        // measured from the lexical parent it reads as `<root>/y` — an in-root
+        // path the caller's path does not lead to. So the parent is made real
+        // first. An absolute target ignores the base.
+        const base = realpathSync(path.dirname(probe));
+        probeReal = resolveLocation(path.resolve(base, link), depth + 1);
+    }
+    return tail.length > 0 ? path.join(probeReal, ...tail) : probeReal;
+}
+export function resolveSafe(toolName, rel, root = workspaceRoot()) {
+    const rootResolved = path.resolve(root);
+    const abs = path.resolve(rootResolved, rel);
+    // 1) Lexical containment — rejects `..` and absolute escapes. The trailing
+    //    separator avoids the `/root` vs `/root-sibling` prefix pitfall.
+    if (abs !== rootResolved && !abs.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new ToolPermissionError(toolName, rel);
+    }
+    let real;
+    try {
+        const rootReal = realpathSync(rootResolved);
+        real = resolveLocation(abs);
+        // 2) Symlink-aware containment. The real path must land inside the real
+        //    root, so an in-workspace symlink pointing at /etc is refused here.
+        if (real !== rootReal && !real.startsWith(`${rootReal}${path.sep}`)) {
+            throw new ToolPermissionError(toolName, rel);
+        }
+    }
+    catch (err) {
+        if (err instanceof ToolPermissionError)
+            throw err;
+        throw new ToolPermissionError(toolName, rel);
+    }
+    return {
+        abs,
+        real,
+        given: rel,
+        rel: toPosix(path.relative(rootResolved, abs)),
+    };
+}
+/** A path relative to the workspace root, with `/` separators on every OS. */
+export function toPosix(p) {
+    return path.sep === "/" ? p : p.split(path.sep).join("/");
+}
+/**
+ * True when `candidate` is `parent` or lives underneath it. Both must already
+ * be absolute. Used to keep an archive entry, or a symlink inside an
+ * extracted tree, from reaching outside its destination.
+ */
+export function isInside(parent, candidate) {
+    const p = path.resolve(parent);
+    const c = path.resolve(candidate);
+    return c === p || c.startsWith(`${p}${path.sep}`);
+}
+/**
+ * Reject an archive member name that would escape its destination: an
+ * absolute path, a Windows drive prefix, or any `..` segment. Checked on the
+ * NAME, before extraction, because after extraction the damage is done.
+ */
+export function archiveEntryEscapes(name) {
+    const normalized = name.replace(/\\/g, "/");
+    if (normalized.startsWith("/"))
+        return true;
+    if (/^[A-Za-z]:/.test(normalized))
+        return true;
+    return normalized.split("/").some((segment) => segment === "..");
+}

package/dist/run.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The one place this package starts a child process, and the seam every test
+ * drives instead of the machine.
+ *
+ * The conventions are `@crewhaus/tool-proc`'s (`src/spawn.ts`) and
+ * `@crewhaus/tool-host`'s (`src/run.ts`), copied rather than re-invented —
+ * those packages export their tools and not their runners, and reaching past
+ * an exports map would be worse than a documented copy:
+ *
+ *   - ARGV IS AN ARRAY. There is no shell in this package. No `sh -c`, no
+ *     `cmd /c`, no interpolated command line, nothing that could turn a
+ *     package name into syntax. `assertArgv` refuses anything that would make
+ *     that untrue before a process exists.
+ *   - EVERY RUN HAS A DEADLINE. SIGTERM at the deadline, SIGKILL after a
+ *     grace period, and a bounded drain so a manager that forks (apt-get
+ *     forks dpkg; brew forks git) cannot hold the pipe open past its death.
+ *   - THE ENVIRONMENT IS PINNED, AND PINNED NON-INTERACTIVE. Every parser
+ *     here reads English keywords out of a manager's output, and `apt-cache
+ *     policy`, `dnf`, `pacman` and `brew` all translate theirs through
+ *     gettext, so `LC_ALL=C` is what makes the bytes the same on a German
+ *     laptop and an English CI box. `DEBIAN_FRONTEND=noninteractive` and
+ *     `NONINTERACTIVE=1` are the other half: a manager that opens a dialog or
+ *     asks a question on a pipe is a command that never exits, and this
+ *     package's whole contract is that it does not hang and does not prompt.
+ *
+ * `_setRunner` replaces all of it. Every parser in this package is fed from
+ * output recorded on a real machine, because CI is a Linux container with no
+ * package manager at all and this was written on macOS: a parser checked
+ * against whatever the test host happens to answer is a parser checked
+ * against nothing.
+ */
+/**
+ * Per-stream cap.
+ *
+ * `apt-get install -s` on a package with a large dependency closure prints a
+ * line per unpacked package, and `brew info --json=v2` for a formula with
+ * many bottles is tens of kilobytes. The cap is generous because the flag
+ * matters more than the number: a truncated simulation parses perfectly and
+ * is simply MISSING packages, so every reader below treats a truncated stream
+ * as "could not determine" rather than as the answer.
+ */
+export declare const MAX_OUTPUT_CHARS = 512000;
+/** Default per-command deadline. Every command here reads a local index. */
+export declare const DEFAULT_COMMAND_TIMEOUT_MS = 20000;
+/** Ceiling a caller may raise a deadline to. An install is the slow case. */
+export declare const MAX_COMMAND_TIMEOUT_MS = 600000;
+/** `PATH` for a child when the harness itself has none. */
+export declare const FALLBACK_PATH = "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin";
+export type RunRequest = {
+    /** The program and each argument as separate strings. Never a shell line. */
+    readonly argv: readonly string[];
+    readonly timeoutMs: number;
+    /** Extra pinned variables for this command (see `MANAGER_ENV`). */
+    readonly env?: Readonly<Record<string, string>>;
+    readonly maxOutputChars?: number;
+    readonly signal?: AbortSignal;
+};
+export type RunResult = {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly timedOut: boolean;
+    /**
+     * True when the program itself is not installed (ENOENT on spawn).
+     *
+     * This is the distinction the whole package turns on: "there is no `dnf` on
+     * this host" is a different fact from "`dnf` ran and said the package is
+     * not there", and reporting the first as the second is the bug class rule 6
+     * names.
+     */
+    readonly missing: boolean;
+    /**
+     * The stream hit the cap and what came back is a PREFIX of what the command
+     * printed. Optional because a recorded fixture states only what its case is
+     * about; absent reads as "not truncated", which a short fixture is.
+     */
+    readonly stdoutTruncated?: boolean;
+    readonly stderrTruncated?: boolean;
+    /** Set when the child outlived even the SIGKILL grace and was left behind. */
+    readonly abandoned?: boolean;
+};
+export type Runner = (request: RunRequest) => Promise<RunResult>;
+export declare function assertArgv(argv: readonly string[]): string | undefined;
+/**
+ * The child's environment: pinned, minimal, and the same on every machine.
+ *
+ * `PATH` and `HOME` are forwarded because a manager cannot be found without
+ * the first and Homebrew cannot find its prefix without the second. Nothing
+ * else from the harness is, so the harness's API keys are not in `apt-get`'s
+ * environment. The Windows four are forwarded because `winget.exe` and
+ * `choco.exe` are not resolvable without them.
+ *
+ * `LC_ALL`/`LANG`/`TZ` are pinned rather than forwarded — see the header.
+ */
+export declare function buildEnv(extra?: Readonly<Record<string, string>>, source?: NodeJS.ProcessEnv): Record<string, string>;
+/** Cut a stream at the cap, saying whether anything was dropped. */
+export declare function capText(text: string, max: number): {
+    text: string;
+    truncated: boolean;
+};
+/** Run `argv` to completion, or kill it when the deadline passes. */
+export declare function runHostCommand(request: RunRequest): Promise<RunResult>;
+/**
+ * Test seam. Pass a function to answer every command from recorded output;
+ * pass `undefined` to go back to spawning for real.
+ */
+export declare function _setRunner(runner: Runner | undefined): void;
+/**
+ * True when a runner is installed.
+ *
+ * Read by `host.ts` to decide the platform default, and by the one smoke test
+ * that is allowed to touch the real host so it can skip itself. See
+ * `hostPlatform()` for why the two seams are tied together.
+ */
+export declare function _runnerInstalled(): boolean;