@crewhaus/tool-pkgmgr 0.7.0

package/dist/index.js

@@ -0,0 +1,434 @@
+/**
+ * `@crewhaus/tool-pkgmgr` — asking the SYSTEM package manager what is on this
+ * machine, and installing from it when that can be done honestly.
+ *
+ * Two tools. `PackageQuery` reads: is this package installed, at what
+ * version, and what does the manager's already-downloaded index say is
+ * available. `PackageInstall` writes, and spends most of its code deciding
+ * not to.
+ *
+ * FIVE PROPERTIES HOLD ACROSS BOTH.
+ *
+ * 1. **THE SCOPE IS NARROWER THAN THE CATALOGUE IMPLIES, AND SAYS SO.**
+ *    Reading works on six managers: Homebrew, apt/dpkg, dnf/rpm, pacman,
+ *    winget and chocolatey. Installing works on ONE of them unattended —
+ *    Homebrew, which needs no root and is designed for a user-owned prefix.
+ *    apt, dnf and pacman need root, so this package installs through them
+ *    only when the process it is already running in IS root, and otherwise
+ *    refuses and prints the command the operator would run. winget and
+ *    chocolatey are not installed through at all, because both end in an
+ *    elevation prompt. A narrow tool that says what it did is worth more than
+ *    a broad one that guesses.
+ *
+ * 2. **NO PRIVILEGE ESCALATION, EVER.** Nothing here runs `sudo`, `doas`,
+ *    `runas` or `pkexec`, nothing raises a UAC prompt, and no schema in this
+ *    package accepts a password. `no argv ever names an escalation program`
+ *    in index.test.ts asserts that over every recorded call and over both
+ *    schemas, the way tool-onchain asserts that no schema accepts a private
+ *    key. Being root and BECOMING root are different things: this package
+ *    will use what the process already has and will never ask for more.
+ *
+ * 3. **ARGV IS AN ARRAY, AND ALMOST ALL OF IT IS A CONSTANT.** There is no
+ *    shell here — no `sh -c`, no `cmd /c`, no interpolated command line. Every
+ *    command is a frozen literal in `./lib/managers.ts`, and the only value
+ *    appended to one is a package name that `./lib/names.ts` has accepted. A
+ *    name beginning with `-` is a FLAG, not a package, so it is refused before
+ *    an argv exists rather than defended with a `--` that two of these six
+ *    managers do not document.
+ *
+ * 4. **A DESTRUCTIVE TOOL RESOLVES ITS PLAN THE SAME WAY EVERY TIME.**
+ *    `PackageInstall` declares `destructive: true` because an install can
+ *    replace a working version, and it reports the version it would replace.
+ *    `dryRun` does not take a different path: the plan is resolved by the same
+ *    function either way, and `dryRun` only decides whether the install
+ *    command afterwards runs.
+ *
+ * 5. **"COULD NOT DETERMINE" IS NOT "NO".** A manager that is not on this
+ *    host, a probe that timed out, an empty dnf metadata cache, a winget row
+ *    whose columns could not be split — every one is `unknown` with a named
+ *    reason, never `not-installed`. A caller that reads "not installed" will
+ *    install something, and installing because a probe timed out is how a
+ *    tool breaks a machine.
+ *
+ * The seams are `_setRunner` (every child process), `_setPlatform` and
+ * `_setUid`. The whole suite drives them: CI is a Linux container with no
+ * package manager at all, development is macOS, and a parser checked against
+ * whatever the test host happens to answer is a parser checked against
+ * nothing. The un-injected platform is deliberately hostile — see `./host.ts`.
+ */
+import { buildTool } from "@crewhaus/tool-builder";
+import { z } from "zod";
+import { hostPlatform, isRoot } from "./host";
+import { MANAGERS, MANAGER_IDS, PKGMGR_COMMANDS, buildOperand, withOperand, } from "./lib/managers";
+import { MAX_NAME_LENGTH, checkPackageName, checkVersionSyntax } from "./lib/names";
+import { resolveInstallPlan } from "./lib/plan";
+import { detectManager, newContext, queryPackage, run, } from "./lib/query";
+import { Unknowns, commandFailureReason, firstLine } from "./lib/unknown";
+import { DEFAULT_COMMAND_TIMEOUT_MS, MAX_COMMAND_TIMEOUT_MS } from "./run";
+export { _setRunner } from "./run";
+export { _setPlatform, _setUid, _resetHostSeams } from "./host";
+export { ToolPermissionError } from "./paths";
+/** Compact JSON — the reader is a model, and every byte is context. */
+const json = (value) => JSON.stringify(value);
+const managerSchema = z
+    .enum(MANAGER_IDS)
+    .optional()
+    .describe("which package manager to use; omitted means detect it from the platform (macOS: Homebrew; Linux: apt, then dnf, then pacman, then Linuxbrew; Windows: winget, then chocolatey)");
+const nameSchema = z
+    .string()
+    .min(1)
+    .max(MAX_NAME_LENGTH)
+    .describe("the package name as the manager spells it — a formula or cask for Homebrew, a binary package for apt, an rpm name or full NEVRA for dnf, a package Id for winget");
+const timeoutSchema = z
+    .number()
+    .int()
+    .min(100)
+    .max(MAX_COMMAND_TIMEOUT_MS)
+    .optional()
+    .describe(`milliseconds any single manager command may take before it is SIGTERMed (default ${DEFAULT_COMMAND_TIMEOUT_MS})`);
+/**
+ * The probe trail, trimmed for a result.
+ *
+ * The argv is included verbatim and on purpose: a caller reading "unknown"
+ * needs to see what was actually asked, and it is the evidence behind the
+ * claim that nothing here builds a command out of anything but a constant and
+ * a validated name.
+ */
+function probeJson(probes) {
+    return probes.map((p) => ({
+        argv: p.argv,
+        exitCode: p.exitCode,
+        ...(p.missing === true ? { notInstalled: true } : {}),
+        ...(p.timedOut === true ? { timedOut: true } : {}),
+    }));
+}
+function factsJson(facts) {
+    return {
+        manager: facts.manager,
+        name: facts.name,
+        status: facts.status,
+        installedVersions: facts.installedVersions,
+        knownToManager: facts.knownToManager,
+        available: facts.available,
+        ...(facts.kind !== undefined ? { kind: facts.kind } : {}),
+        ...(facts.pinned !== undefined ? { pinned: facts.pinned } : {}),
+        ...(facts.outdated !== undefined ? { outdated: facts.outdated } : {}),
+        ...(facts.notes.length > 0 ? { notes: facts.notes } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// PackageQuery
+// ---------------------------------------------------------------------------
+export const packageQuery = buildTool({
+    name: "PackageQuery",
+    description: 'Ask the system package manager whether a package is installed, at what version, and what its already-downloaded index says is available. Supports Homebrew, apt/dpkg, dnf/rpm, pacman, winget and chocolatey, detecting the manager from the platform unless you name one; a host with none of them is reported as unknown rather than guessed at. It makes NO network call: every answer comes from a local index, which is why winget and chocolatey report installed state only — their available version lives on a remote source. Nothing is ever defaulted: a manager that is not on this host, a probe that timed out, an empty dnf metadata cache or a winget row whose columns could not be split all come back as status "unknown" with the reason and the exact command that was run, never as "not installed". Read-only: it runs only query commands and changes nothing.',
+    inputSchema: z.object({
+        name: nameSchema,
+        manager: managerSchema,
+        includeAvailable: z
+            .boolean()
+            .optional()
+            .describe("also read what the local index offers, not just what is installed (default true; ignored for winget and chocolatey, whose available version is a network query)"),
+        timeoutMs: timeoutSchema,
+    }),
+    readOnly: true,
+    concurrencySafe: true,
+    scope: "external",
+    ioCapability: "process",
+    execute: async (input, context) => {
+        const platform = hostPlatform();
+        const ctx = newContext(input.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS, context?.signal);
+        const unknowns = new Unknowns();
+        const includeAvailable = input.includeAvailable ?? true;
+        const detection = await detectManager(ctx, platform, input.manager);
+        if (detection.kind === "unknown") {
+            // Rule 5: a host with no package manager — which is what CI is — gets a
+            // typed answer naming what was looked for, not a crash and not a false.
+            return json({
+                tool: "PackageQuery",
+                platform,
+                manager: null,
+                status: "unknown",
+                available: false,
+                reason: detection.reason,
+                managersProbed: detection.tried,
+                probes: probeJson(ctx.probes),
+            });
+        }
+        const manager = detection.manager;
+        const nameRefusal = checkPackageName(manager, input.name);
+        if (nameRefusal !== undefined) {
+            return json({
+                tool: "PackageQuery",
+                platform,
+                manager,
+                status: "refused",
+                reason: nameRefusal,
+                // Nothing was spawned with this name; the only probes are the
+                // manager detection ones above.
+                probes: probeJson(ctx.probes),
+            });
+        }
+        const facts = await queryPackage(ctx, manager, input.name, unknowns, includeAvailable);
+        return json({
+            tool: "PackageQuery",
+            platform,
+            ...factsJson(facts),
+            availableSource: MANAGERS[manager].availableSource,
+            ...(MANAGERS[manager].availableReason !== undefined
+                ? { availableNotProbedBecause: MANAGERS[manager].availableReason }
+                : {}),
+            ...(unknowns.size > 0 ? { unknown: unknowns.list() } : {}),
+            probes: probeJson(ctx.probes),
+        });
+    },
+});
+// ---------------------------------------------------------------------------
+// PackageInstall
+// ---------------------------------------------------------------------------
+/**
+ * A refusal, in the one shape every one of them uses.
+ *
+ * `operatorCommand` is the point of the refusal rather than an apology for
+ * it: this package will not acquire privilege, so the useful thing it can do
+ * is hand back the exact line a human would type.
+ */
+function refusal(fields) {
+    return json({
+        tool: "PackageInstall",
+        platform: fields.platform,
+        manager: fields.manager,
+        dryRun: fields.dryRun,
+        status: "refused",
+        installed: false,
+        reason: fields.reason,
+        ...(fields.operatorCommand !== undefined
+            ? {
+                operatorCommand: fields.operatorCommand,
+                operatorCommandNote: "this tool does not run that command and does not acquire the privilege it needs; run it yourself if you want this change",
+            }
+            : {}),
+        ...(fields.plan !== undefined ? { plan: fields.plan } : {}),
+        probes: probeJson(fields.probes),
+    });
+}
+export const packageInstall = buildTool({
+    name: "PackageInstall",
+    description: "Install a package through the system package manager, or report exactly what installing it would do. DESTRUCTIVE: an install can replace a version that is already working, so the plan names the versions currently on disk before anything runs. Pass dryRun to get that plan and install nothing — it is resolved by the same code the real install uses, and includes the transitive packages the manager says it would add (complete from apt and pacman, resolved-then-declined from dnf, derived from `brew deps` for Homebrew, which has no dry run). THIS TOOL NEVER ACQUIRES PRIVILEGE. It runs no sudo, doas, runas or pkexec and raises no UAC prompt. Homebrew needs no root and is the case that genuinely works unattended; apt, dnf and pacman need root, so they work only when this process is ALREADY root and are otherwise refused with the exact command an operator would run themselves; winget and chocolatey installs are refused outright, because both end in an elevation prompt. A version can only be pinned where the manager can express one — apt can, and every other manager here is refused with the reason rather than quietly installing latest. A package name beginning with '-' is refused, because a manager would read it as a flag.",
+    inputSchema: z.object({
+        name: nameSchema,
+        manager: managerSchema,
+        version: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("an exact version to install. Only apt can express one (name=version); Homebrew, dnf, pacman, winget and chocolatey are refused with the reason rather than installing latest"),
+        dryRun: z
+            .boolean()
+            .optional()
+            .describe("resolve and report the plan, and install nothing (default false). The plan is produced by the same code the real install runs"),
+        timeoutMs: timeoutSchema,
+    }),
+    destructive: true,
+    requireJustification: true,
+    scope: "external",
+    ioCapability: "process",
+    execute: async (input, context) => {
+        const platform = hostPlatform();
+        const dryRun = input.dryRun === true;
+        const ctx = newContext(input.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS, context?.signal);
+        const unknowns = new Unknowns();
+        const detection = await detectManager(ctx, platform, input.manager);
+        if (detection.kind === "unknown") {
+            return json({
+                tool: "PackageInstall",
+                platform,
+                manager: null,
+                dryRun,
+                status: "unavailable",
+                installed: false,
+                reason: detection.reason,
+                managersProbed: detection.tried,
+                probes: probeJson(ctx.probes),
+            });
+        }
+        const manager = detection.manager;
+        const spec = MANAGERS[manager];
+        // ---- refusals, in the order that gives the most useful message --------
+        const nameRefusal = checkPackageName(manager, input.name);
+        if (nameRefusal !== undefined) {
+            return refusal({ platform, manager, reason: nameRefusal, probes: ctx.probes, dryRun });
+        }
+        if (!spec.install.supported) {
+            return refusal({
+                platform,
+                manager,
+                reason: spec.install.reason,
+                operatorCommand: spec.operatorCommand(input.name),
+                probes: ctx.probes,
+                dryRun,
+            });
+        }
+        let requestedVersion = null;
+        if (input.version !== undefined) {
+            if (!spec.versionPin.supported) {
+                // Refusing rather than installing latest is the whole point: a caller
+                // who asked for 1.2.3 and silently got 2.0.0 has been lied to by a
+                // tool they will trust again.
+                return refusal({
+                    platform,
+                    manager,
+                    reason: `${spec.label} cannot express an exact version: ${spec.versionPin.reason}`,
+                    operatorCommand: spec.operatorCommand(input.name),
+                    probes: ctx.probes,
+                    dryRun,
+                });
+            }
+            const versionRefusal = checkVersionSyntax(input.version);
+            if (versionRefusal !== undefined) {
+                return refusal({ platform, manager, reason: versionRefusal, probes: ctx.probes, dryRun });
+            }
+            requestedVersion = input.version;
+        }
+        const operand = buildOperand(manager, input.name, requestedVersion ?? undefined);
+        // ---- resolution: the same code for both paths -------------------------
+        const facts = await queryPackage(ctx, manager, input.name, unknowns, true);
+        const plan = await resolveInstallPlan(ctx, manager, input.name, operand, requestedVersion, facts, unknowns);
+        if (dryRun) {
+            return json({
+                tool: "PackageInstall",
+                platform,
+                manager,
+                dryRun: true,
+                status: "would-install",
+                installed: false,
+                plan,
+                before: factsJson(facts),
+                // Stated on the dry run too, so a caller learns BEFORE it tries that
+                // the real call would be refused on this host.
+                ...(spec.install.needsRoot && !isRoot()
+                    ? {
+                        wouldBeRefused: true,
+                        wouldBeRefusedReason: `${spec.label} needs root to install and this process is not root; this tool does not acquire privilege`,
+                        operatorCommand: spec.operatorCommand(operand),
+                    }
+                    : {}),
+                ...(unknowns.size > 0 ? { unknown: unknowns.list() } : {}),
+                probes: probeJson(ctx.probes),
+            });
+        }
+        // ---- the privilege gate ----------------------------------------------
+        if (spec.install.needsRoot && !isRoot()) {
+            return refusal({
+                platform,
+                manager,
+                reason: `${spec.label} needs root to install a package, and this tool does not acquire privilege — it runs no sudo, doas, runas or pkexec, and takes no password`,
+                operatorCommand: spec.operatorCommand(operand),
+                plan,
+                probes: ctx.probes,
+                dryRun: false,
+            });
+        }
+        if (plan.action === "none") {
+            // Nothing to do, and saying so beats running an install to find out.
+            return json({
+                tool: "PackageInstall",
+                platform,
+                manager,
+                dryRun: false,
+                status: "already-installed",
+                installed: false,
+                plan,
+                before: factsJson(facts),
+                ...(unknowns.size > 0 ? { unknown: unknowns.list() } : {}),
+                probes: probeJson(ctx.probes),
+            });
+        }
+        // ---- the one line that differs from the dry run ------------------------
+        const installArgv = installCommand(manager, operand);
+        const result = await run(ctx, manager, installArgv);
+        if (result.missing || result.timedOut) {
+            return json({
+                tool: "PackageInstall",
+                platform,
+                manager,
+                dryRun: false,
+                // An install that timed out may have done PART of its work, which is
+                // neither "installed" nor "not installed". The verification below is
+                // what turns that into a fact.
+                status: "unknown",
+                installed: false,
+                reason: commandFailureReason(result),
+                plan,
+                probes: probeJson(ctx.probes),
+            });
+        }
+        const failedRoot = result.code !== 0 && /you (are not|must be) root|permission denied/i.test(result.stderr);
+        const after = await queryPackage(ctx, manager, input.name, unknowns, true);
+        const installed = after.status === "installed" &&
+            (facts.status !== "installed" ||
+                JSON.stringify(after.installedVersions) !== JSON.stringify(facts.installedVersions));
+        return json({
+            tool: "PackageInstall",
+            platform,
+            manager,
+            dryRun: false,
+            status: result.code === 0
+                ? after.status === "installed"
+                    ? "installed"
+                    : "unknown"
+                : failedRoot
+                    ? "refused"
+                    : "failed",
+            installed: result.code === 0 && after.status === "installed",
+            // Stated separately from `installed`: a reinstall of the same version
+            // leaves the machine changed in ways the version does not show, and a
+            // caller deciding whether to restart something needs the difference.
+            versionChanged: installed,
+            exitCode: result.code,
+            ...(result.code !== 0
+                ? { reason: firstLine(result.stderr) || firstLine(result.stdout) }
+                : {}),
+            plan,
+            before: factsJson(facts),
+            after: factsJson(after),
+            ...(after.status === "unknown"
+                ? {
+                    verificationNote: "the install command's exit code was read, but re-querying the manager afterwards did not confirm the result, so what is on disk now is not known from this call",
+                }
+                : {}),
+            ...(unknowns.size > 0 ? { unknown: unknowns.list() } : {}),
+            probes: probeJson(ctx.probes),
+        });
+    },
+});
+/**
+ * The install argv for a manager.
+ *
+ * A separate function so the test that asserts no argv names an escalation
+ * program can enumerate every one of them, including the ones only reached
+ * when the process is already root.
+ */
+export function installCommand(manager, operand) {
+    const spec = MANAGERS[manager];
+    switch (manager) {
+        case "homebrew":
+            return withOperand(spec, PKGMGR_COMMANDS.brewInstall, operand);
+        case "apt":
+            return withOperand(spec, PKGMGR_COMMANDS.aptInstall, operand);
+        case "dnf":
+            return withOperand(spec, PKGMGR_COMMANDS.dnfInstall, operand);
+        case "pacman":
+            return withOperand(spec, PKGMGR_COMMANDS.pacmanInstall, operand);
+        // Unreachable: both are refused above before a plan exists. The throw is
+        // the guarantee — a future edit that removes the refusal fails loudly
+        // here instead of quietly starting an elevated installer.
+        case "winget":
+        case "choco":
+            throw new Error(`${spec.label} installs are refused by this package and have no argv`);
+    }
+}
+export const PKGMGR_TOOLS = Object.freeze([
+    packageQuery,
+    packageInstall,
+]);

package/dist/lib/managers.d.ts

@@ -0,0 +1,172 @@
+/**
+ * The six managers, what each one can actually do, and every argv this
+ * package is allowed to run.
+ *
+ * ── ARGV IS A TABLE OF CONSTANTS ──────────────────────────────────────────
+ *
+ * `tool-host` established the rule and it is kept here: every command is a
+ * frozen constant, and the ONLY value this package appends to one is a
+ * package name (or a `name=version` operand) that `../lib/names.ts` has
+ * already accepted. Nothing read out of one command's output is ever fed into
+ * another command's argv — a dependency name parsed from `apt-get -s` output
+ * is reported, never re-spawned. `argv is a constant plus the validated
+ * operand` in index.test.ts asserts that over every recorded call, including
+ * the adversarial ones.
+ *
+ * ── THE SCOPE IS NARROWER THAN THE CATALOGUE IMPLIES, ON PURPOSE ──────────
+ *
+ * Reading is broad: all six managers answer "is this installed, at what
+ * version", and four of them also answer "what does the local index say is
+ * available" without touching the network.
+ *
+ * WRITING is narrow, and the table says why per manager rather than pretending
+ * otherwise. Homebrew on macOS is the case that genuinely works unattended —
+ * it needs no root, it is designed for a writable prefix owned by the user,
+ * and `NONINTERACTIVE=1` is its own documented switch for exactly this. The
+ * three Linux managers need root, so this package installs through them only
+ * when the process it is already running in IS root, and otherwise refuses
+ * with the command an operator would run. The two Windows managers are not
+ * installed through at all, because both end in an elevation prompt this
+ * package will not raise.
+ */
+import type { HostPlatform } from "../host";
+import type { ManagerId } from "./names";
+export type { ManagerId };
+export declare const MANAGER_IDS: readonly ManagerId[];
+/**
+ * Every command this package may run, as literals.
+ *
+ * Flag notes that matter to the parsers downstream:
+ *
+ *   - `brew info --json=v2` is the ONE brew call that answers both halves of
+ *     a query: `installed[]` for what is on disk and `versions.stable` for
+ *     what the tap has. It also covers casks in the same document, so a name
+ *     does not have to be classified before it is looked up.
+ *   - `dpkg-query -W -f=...` is named-field output, not a table. The fields
+ *     are `${db:Status-Abbrev}` rather than `${Status}` because the abbrev is
+ *     three fixed characters (`ii `, `un `, `rc `) that mean the same thing in
+ *     every locale, while `${Status}` is three English words.
+ *   - `apt-cache policy` IS localised, which is why `LC_ALL=C` is pinned in
+ *     `../run.ts`. Without that pin the `Installed:`/`Candidate:` labels come
+ *     back in the operator's language and the parser silently finds nothing —
+ *     the single most common way a package-manager parser fails in the field.
+ *   - `rpm -q --queryformat` rather than `dnf list --installed`: rpm reads the
+ *     local database, needs no repository metadata, and its format string is
+ *     not localised. `dnf` is only asked what is AVAILABLE.
+ *   - `dnf --cacheonly` so the query cannot reach the network. The cost is
+ *     that a host with no cached metadata answers "no matching packages",
+ *     which is indistinguishable from "not in the repos" — so the parser
+ *     looks for dnf's own "no cache" complaint and reports unknown instead of
+ *     "not available". "Could not determine" is not "no" (house rule 6).
+ *   - `pacman -S --print --print-format '%r/%n %v'` is pacman's dry run. It
+ *     prints every target INCLUDING dependencies, with versions, and needs no
+ *     root — the best dry run of the six.
+ *   - `winget list --exact --query` with `--disable-interactivity` and
+ *     `--accept-source-agreements`: without those two, winget can sit waiting
+ *     for a keypress or for an agreement to be accepted, which on a pipe is a
+ *     command that never exits.
+ *   - `choco list --limit-output` is chocolatey's documented machine-readable
+ *     mode: `name|version`, one per line, no headers, no colour. The v1/v2
+ *     split is real — `--local-only` was removed in Chocolatey 2.0 — so the
+ *     version is probed first and the right form is chosen.
+ */
+export declare const PKGMGR_COMMANDS: Readonly<{
+    brewVersion: readonly string[];
+    brewInfoJson: readonly string[];
+    brewListVersions: readonly string[];
+    brewDeps: readonly string[];
+    brewInstall: readonly string[];
+    dpkgVersion: readonly string[];
+    dpkgQuery: readonly string[];
+    aptCachePolicy: readonly string[];
+    aptSimulate: readonly string[];
+    aptInstall: readonly string[];
+    dnfVersion: readonly string[];
+    rpmQuery: readonly string[];
+    dnfListAvailable: readonly string[];
+    dnfSimulate: readonly string[];
+    dnfInstall: readonly string[];
+    pacmanVersion: readonly string[];
+    pacmanQuery: readonly string[];
+    pacmanSyncInfo: readonly string[];
+    pacmanSimulate: readonly string[];
+    pacmanInstall: readonly string[];
+    wingetVersion: readonly string[];
+    wingetList: readonly string[];
+    chocoVersion: readonly string[];
+    /** Chocolatey 2.x: `choco list` is local by default. */
+    chocoListV2: readonly string[];
+    /** Chocolatey 1.x and 0.x: `list` searches the remote unless told otherwise. */
+    chocoListV1: readonly string[];
+}>;
+/** Flat view of the table, for the test that proves no argv is built. */
+export declare const ALL_PKGMGR_COMMANDS: ReadonlyArray<ReadonlyArray<string>>;
+/**
+ * The environment each manager needs on top of the pinned base in `../run.ts`.
+ *
+ * Every entry here exists to stop the manager doing something this package
+ * does not do: reach the network, write analytics, colour its output, or ask
+ * a question on a pipe that nothing will ever answer.
+ */
+export declare const MANAGER_ENV: Readonly<Record<ManagerId, Readonly<Record<string, string>>>>;
+export type InstallSupport = {
+    readonly supported: true;
+    readonly needsRoot: boolean;
+} | {
+    readonly supported: false;
+    readonly reason: string;
+};
+export type VersionPinSupport = {
+    readonly supported: true;
+    readonly form: string;
+} | {
+    readonly supported: false;
+    readonly reason: string;
+};
+export type ManagerSpec = {
+    readonly id: ManagerId;
+    readonly label: string;
+    /** Platforms this manager is looked for on, in detection order. */
+    readonly platforms: readonly HostPlatform[];
+    /** The `--version` probe that decides whether it is installed. */
+    readonly detect: readonly string[];
+    /** Whether "what is available" can be answered without the network. */
+    readonly availableSource: "local-index" | "network-only";
+    /** Why the network-only ones are not asked. */
+    readonly availableReason?: string;
+    readonly install: InstallSupport;
+    readonly versionPin: VersionPinSupport;
+    /**
+     * Whether `--` is appended before the operand.
+     *
+     * Documented per manager rather than assumed. It is defence in depth only:
+     * a leading dash is refused in `names.ts` before this matters, precisely
+     * because the four `false` entries below cannot be defended this way.
+     */
+    readonly doubleDash: boolean;
+    /** The command the operator runs themselves when this package refuses. */
+    readonly operatorCommand: (operand: string) => string;
+};
+export declare const MANAGERS: Readonly<Record<ManagerId, ManagerSpec>>;
+/**
+ * Which managers to look for, in order, on a platform.
+ *
+ * Homebrew comes LAST on Linux: a Linuxbrew installation sits alongside the
+ * distro's manager rather than replacing it, and on a Debian box the answer
+ * to "is curl installed" that an operator means is dpkg's.
+ *
+ * `"other"` is empty, and that is what the hostile default in `../host.ts`
+ * produces for any test that forgets to declare a platform — every backend
+ * refuses, identically, on every machine.
+ */
+export declare function managersForPlatform(platform: HostPlatform): readonly ManagerId[];
+/**
+ * Build the operand a manager receives for a name (optionally version-pinned).
+ *
+ * Kept in one place because it is the ONLY value this package ever appends to
+ * an argv, and the join is manager-specific: `name=version` is apt's grammar
+ * and nobody else's.
+ */
+export declare function buildOperand(manager: ManagerId, name: string, version?: string): string;
+/** Append the operand to a frozen prefix, with `--` where the manager takes it. */
+export declare function withOperand(spec: ManagerSpec, prefix: readonly string[], operand: string): string[];