@crewhaus/tool-pkgmgr 0.7.0

package/dist/lib/managers.js

@@ -0,0 +1,266 @@
+export const MANAGER_IDS = Object.freeze([
+    "homebrew",
+    "apt",
+    "dnf",
+    "pacman",
+    "winget",
+    "choco",
+]);
+/**
+ * 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 const PKGMGR_COMMANDS = Object.freeze({
+    brewVersion: Object.freeze(["brew", "--version"]),
+    brewInfoJson: Object.freeze(["brew", "info", "--json=v2"]),
+    brewListVersions: Object.freeze(["brew", "list", "--formula", "--versions"]),
+    brewDeps: Object.freeze(["brew", "deps", "--formula"]),
+    brewInstall: Object.freeze(["brew", "install", "--formula"]),
+    dpkgVersion: Object.freeze(["dpkg-query", "--version"]),
+    dpkgQuery: Object.freeze([
+        "dpkg-query",
+        "-W",
+        "-f=${binary:Package}\t${Version}\t${db:Status-Abbrev}\n",
+        "--",
+    ]),
+    aptCachePolicy: Object.freeze(["apt-cache", "policy", "--"]),
+    aptSimulate: Object.freeze(["apt-get", "install", "-s", "-y", "--"]),
+    aptInstall: Object.freeze(["apt-get", "install", "-y", "--"]),
+    dnfVersion: Object.freeze(["dnf", "--version"]),
+    rpmQuery: Object.freeze(["rpm", "-q", "--queryformat", "%{NAME}\t%{EVR}\t%{ARCH}\n", "--"]),
+    dnfListAvailable: Object.freeze(["dnf", "--cacheonly", "--quiet", "list", "--available", "--"]),
+    dnfSimulate: Object.freeze(["dnf", "install", "--assumeno", "--"]),
+    dnfInstall: Object.freeze(["dnf", "install", "-y", "--"]),
+    pacmanVersion: Object.freeze(["pacman", "--version"]),
+    pacmanQuery: Object.freeze(["pacman", "-Q", "--"]),
+    pacmanSyncInfo: Object.freeze(["pacman", "-Si", "--"]),
+    pacmanSimulate: Object.freeze(["pacman", "-S", "--print", "--print-format", "%r/%n %v", "--"]),
+    pacmanInstall: Object.freeze(["pacman", "-S", "--noconfirm", "--"]),
+    wingetVersion: Object.freeze(["winget", "--version"]),
+    wingetList: Object.freeze([
+        "winget",
+        "list",
+        "--exact",
+        "--disable-interactivity",
+        "--accept-source-agreements",
+        "--query",
+    ]),
+    chocoVersion: Object.freeze(["choco", "--version"]),
+    /** Chocolatey 2.x: `choco list` is local by default. */
+    chocoListV2: Object.freeze(["choco", "list", "--exact", "--limit-output"]),
+    /** Chocolatey 1.x and 0.x: `list` searches the remote unless told otherwise. */
+    chocoListV1: Object.freeze(["choco", "list", "--local-only", "--exact", "--limit-output"]),
+});
+/** Flat view of the table, for the test that proves no argv is built. */
+export const ALL_PKGMGR_COMMANDS = Object.freeze(Object.values(PKGMGR_COMMANDS));
+/**
+ * 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 const MANAGER_ENV = Object.freeze({
+    homebrew: Object.freeze({
+        // `brew info` will otherwise `git fetch` the taps first: a network call
+        // this package does not make, and a multi-second stall inside a query
+        // that is supposed to read a local checkout.
+        HOMEBREW_NO_AUTO_UPDATE: "1",
+        HOMEBREW_NO_ANALYTICS: "1",
+        HOMEBREW_NO_ENV_HINTS: "1",
+        HOMEBREW_NO_COLOR: "1",
+        // Homebrew's own switch for "there is no human here". Without it a
+        // formula with a caveat or a prompt blocks on stdin.
+        NONINTERACTIVE: "1",
+    }),
+    apt: Object.freeze({
+        // Without this, a package with a debconf question opens a dialog on a
+        // terminal that is not there and apt waits for it forever.
+        DEBIAN_FRONTEND: "noninteractive",
+        APT_LISTCHANGES_FRONTEND: "none",
+    }),
+    dnf: Object.freeze({}),
+    pacman: Object.freeze({}),
+    winget: Object.freeze({}),
+    choco: Object.freeze({}),
+});
+export const MANAGERS = Object.freeze({
+    homebrew: {
+        id: "homebrew",
+        label: "Homebrew",
+        // Linuxbrew is real, and is looked for after the distro managers.
+        platforms: ["darwin", "linux"],
+        detect: PKGMGR_COMMANDS.brewVersion,
+        availableSource: "local-index",
+        install: { supported: true, needsRoot: false },
+        versionPin: {
+            supported: false,
+            reason: "Homebrew installs whatever version the tap currently has and has no flag to select another; the only pin is a versioned formula, which is a different NAME (node@20, python@3.11) rather than a version",
+        },
+        // Homebrew's parser is Ruby's OptionParser wrapped in Homebrew::CLI, and
+        // this package has not recorded its `--` behaviour, so it is not relied on.
+        doubleDash: false,
+        operatorCommand: (operand) => `brew install --formula ${operand}`,
+    },
+    apt: {
+        id: "apt",
+        label: "apt/dpkg",
+        platforms: ["linux"],
+        detect: PKGMGR_COMMANDS.dpkgVersion,
+        availableSource: "local-index",
+        install: { supported: true, needsRoot: true },
+        versionPin: {
+            supported: true,
+            form: "name=version",
+        },
+        doubleDash: true,
+        operatorCommand: (operand) => `sudo apt-get install -y -- ${operand}`,
+    },
+    dnf: {
+        id: "dnf",
+        label: "dnf/rpm",
+        platforms: ["linux"],
+        detect: PKGMGR_COMMANDS.dnfVersion,
+        availableSource: "local-index",
+        install: { supported: true, needsRoot: true },
+        versionPin: {
+            supported: false,
+            reason: "dnf's versioned spec is name-version-release, and joining a name to a version cannot be done unambiguously when the name itself contains a dash — which most rpm names do; pass the full NEVRA (kernel-5.14.0-427.el9) as the package NAME instead, which is exact",
+        },
+        doubleDash: true,
+        operatorCommand: (operand) => `sudo dnf install -y -- ${operand}`,
+    },
+    pacman: {
+        id: "pacman",
+        label: "pacman",
+        platforms: ["linux"],
+        detect: PKGMGR_COMMANDS.pacmanVersion,
+        availableSource: "local-index",
+        install: { supported: true, needsRoot: true },
+        versionPin: {
+            supported: false,
+            reason: "pacman has no version selection: the sync database holds exactly one version per package and there is no flag to ask for another",
+        },
+        doubleDash: true,
+        operatorCommand: (operand) => `sudo pacman -S --noconfirm -- ${operand}`,
+    },
+    winget: {
+        id: "winget",
+        label: "winget",
+        platforms: ["win32"],
+        detect: PKGMGR_COMMANDS.wingetVersion,
+        availableSource: "network-only",
+        availableReason: "winget resolves an available version by querying its source over the network, and this tool makes no network call — only the local install state is read",
+        install: {
+            supported: false,
+            reason: "a winget install runs the package's own installer, which raises a UAC elevation prompt for any machine-scope package; this tool does not raise one and will not start an installer whose end it cannot see",
+        },
+        versionPin: {
+            supported: false,
+            reason: "winget installs are not performed by this tool at all, so there is nothing to pin",
+        },
+        // winget's parser does not document `--` as an end-of-options marker.
+        doubleDash: false,
+        operatorCommand: (operand) => `winget install --exact --id ${operand} --accept-package-agreements --accept-source-agreements`,
+    },
+    choco: {
+        id: "choco",
+        label: "Chocolatey",
+        platforms: ["win32"],
+        detect: PKGMGR_COMMANDS.chocoVersion,
+        availableSource: "network-only",
+        availableReason: "chocolatey resolves an available version with `choco search`, which queries the remote feed; this tool makes no network call — only the local install state is read",
+        install: {
+            supported: false,
+            reason: "chocolatey installs to a machine-wide location and must be run from an elevated shell, and its packages execute arbitrary PowerShell with those rights; this tool does not elevate",
+        },
+        versionPin: {
+            supported: false,
+            reason: "chocolatey installs are not performed by this tool at all, so there is nothing to pin",
+        },
+        doubleDash: false,
+        operatorCommand: (operand) => `choco install ${operand} -y`,
+    },
+});
+/**
+ * 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 function managersForPlatform(platform) {
+    switch (platform) {
+        case "darwin":
+            return ["homebrew"];
+        case "linux":
+            return ["apt", "dnf", "pacman", "homebrew"];
+        case "win32":
+            return ["winget", "choco"];
+        case "other":
+            return [];
+    }
+}
+/**
+ * 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 function buildOperand(manager, name, version) {
+    if (version === undefined)
+        return name;
+    if (manager === "apt")
+        return `${name}=${version}`;
+    // Unreachable through the tools: `checkVersionPin` refuses a version for
+    // every other manager before this is called. Kept total rather than
+    // throwing, so a future caller gets the name rather than an exception.
+    return name;
+}
+/** Append the operand to a frozen prefix, with `--` where the manager takes it. */
+export function withOperand(spec, prefix, operand) {
+    // The prefixes that end in `--` already carry it (it is part of the frozen
+    // constant so the test can see it), so it is never added twice.
+    const endsWithDoubleDash = prefix[prefix.length - 1] === "--";
+    if (spec.doubleDash && !endsWithDoubleDash)
+        return [...prefix, "--", operand];
+    return [...prefix, operand];
+}

package/dist/lib/names.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The gate every caller-supplied package name and version passes through
+ * before an argv exists.
+ *
+ * ── WHY THIS FILE IS THE SECURITY BOUNDARY ────────────────────────────────
+ *
+ * A package name is a caller value that reaches an argv, and an argv element
+ * beginning with `-` is a FLAG, not an operand. `PackageInstall({name:"-y"})`
+ * against a manager that does not stop option parsing would not install a
+ * package called `-y`; it would add a flag to a command that modifies the
+ * system. This repository has already shipped exactly that bug once —
+ * `gitBranchCreate({name:"-D"})` ran `git branch -D victim` — and the cheapest
+ * way not to ship it twice is for a leading dash never to reach an argv.
+ *
+ * `--` is the usual defence, and it is used below wherever it is documented
+ * to work. But it is NOT the primary defence here, because the six managers
+ * genuinely differ: `apt-get`, `apt-cache`, `dpkg-query`, `pacman`, `rpm`
+ * (popt) and `dnf` (argparse) all honour `--`, while `winget` and `choco`
+ * have their own parsers that do not document it at all and Homebrew's is a
+ * Ruby `OptionParser` whose behaviour this package has not recorded. A
+ * defence that is true for four of six managers is not a defence. So a name
+ * that begins with `-` is REFUSED, on every manager, before anything is
+ * spawned — and `--` is passed on top, where it is known to work, as the belt
+ * to that brace.
+ *
+ * Everything else a hostile name might contain — a double quote, a backslash,
+ * a newline, `$(id)`, a backtick, `</toast>`, `&`, a NUL — is inert in an
+ * argv array, because this package has no shell (see `../run.ts`). It is
+ * still refused, for a different and simpler reason: none of it is a legal
+ * package name in any of these managers, so accepting it could only ever turn
+ * into a confusing error from a child process instead of a clear refusal from
+ * the tool. The tests assert both halves: that each hostile value is refused,
+ * and that when a name IS accepted it reaches the argv as exactly one element
+ * with byte-identical content.
+ */
+export type ManagerId = "homebrew" | "apt" | "dnf" | "pacman" | "winget" | "choco";
+export type NameRule = {
+    /** Names this manager will accept, anchored. */
+    readonly pattern: RegExp;
+    /** The charset, in words, for the refusal message. */
+    readonly charset: string;
+};
+/**
+ * Per-manager name grammars, each narrowed to what the manager documents.
+ *
+ *   - homebrew: formula and cask tokens are lowercase `a-z0-9@+._-`, and a
+ *     tap-qualified name adds two slashes (`homebrew/cask/firefox`). Upper
+ *     case is allowed through because a tap's user segment can carry it.
+ *   - apt: Debian policy §5.6.1 — `[a-z0-9][a-z0-9+.-]+`, plus an optional
+ *     `:arch` qualifier (`libc6:i386`).
+ *   - dnf: an rpm name is `[A-Za-z0-9._+-]`, and the whole NEVRA form
+ *     (`kernel-5.14.0-427.el9.x86_64`) is spelled with the same characters,
+ *     which is why a version is passed as part of the NAME for dnf rather
+ *     than built into one here (see `versionSupport`).
+ *   - pacman: `[a-z0-9@._+-]` per PKGBUILD(5), plus `repo/name`.
+ *   - winget: an Id is `Publisher.Package`, ASCII alphanumerics with `.`,
+ *     `-` and `_`. A DISPLAY name (which may contain spaces and CJK) is not
+ *     accepted, because it is not what `--exact` matches on and guessing
+ *     which one the caller meant is how a query answers about the wrong app.
+ *   - choco: package ids are `[A-Za-z0-9._-]`.
+ *
+ * Every pattern rejects a leading `-` structurally, and the check below
+ * rejects it again by name so the refusal says WHY rather than "does not
+ * match".
+ */
+export declare const NAME_RULES: Readonly<Record<ManagerId, NameRule>>;
+/** Longest name accepted. Debian's own limit is far shorter; this is a sanity bound. */
+export declare const MAX_NAME_LENGTH = 200;
+/** Longest version specifier accepted. */
+export declare const MAX_VERSION_LENGTH = 100;
+/**
+ * Check one caller-supplied package name.
+ *
+ * Returns the refusal, or `undefined` when the name may become an argv
+ * element. The checks are ordered so the message names the SPECIFIC problem:
+ * "starts with -" is far more useful to a caller than "does not match the
+ * accepted characters", and both are more useful than a manager's own error.
+ */
+export declare function checkPackageName(manager: ManagerId, name: string): string | undefined;
+/**
+ * The version grammars the managers that CAN pin a version accept.
+ *
+ * Only apt is here, and that is the honest answer rather than a gap:
+ *
+ *   - apt expresses an exact version as `name=version`, and a Debian version
+ *     string is `[A-Za-z0-9.+~:-]` (policy §5.6.12). `=` is what makes this
+ *     work and is why the version has its own grammar: a version containing
+ *     `=` would produce `name=1=2`, which apt reads as a different package.
+ *   - dnf CAN take `name-version-release`, and this package will not build
+ *     one, because the join is ambiguous the moment the NAME contains a dash
+ *     — which most rpm names do. A caller who wants an exact rpm passes the
+ *     whole NEVRA as the name; that is unambiguous and needs no guessing.
+ *   - pacman has no version selection at all. There is no flag, and the sync
+ *     database holds exactly one version per package.
+ *   - Homebrew installs the tap's current version. The only pin is a
+ *     versioned FORMULA (`node@20`), which is a different name, not a version.
+ *   - winget and choco can pin, but this package does not install through
+ *     either of them at all (see `./managers.ts`), so the question does not
+ *     arise.
+ *
+ * Every one of those is refused explicitly with that sentence, rather than
+ * silently installing latest — which is the failure mode the refusal exists
+ * to prevent.
+ */
+export declare const DEBIAN_VERSION_PATTERN: RegExp;
+export declare function checkVersionSyntax(version: string): string | undefined;

package/dist/lib/names.js

@@ -0,0 +1,174 @@
+/**
+ * The gate every caller-supplied package name and version passes through
+ * before an argv exists.
+ *
+ * ── WHY THIS FILE IS THE SECURITY BOUNDARY ────────────────────────────────
+ *
+ * A package name is a caller value that reaches an argv, and an argv element
+ * beginning with `-` is a FLAG, not an operand. `PackageInstall({name:"-y"})`
+ * against a manager that does not stop option parsing would not install a
+ * package called `-y`; it would add a flag to a command that modifies the
+ * system. This repository has already shipped exactly that bug once —
+ * `gitBranchCreate({name:"-D"})` ran `git branch -D victim` — and the cheapest
+ * way not to ship it twice is for a leading dash never to reach an argv.
+ *
+ * `--` is the usual defence, and it is used below wherever it is documented
+ * to work. But it is NOT the primary defence here, because the six managers
+ * genuinely differ: `apt-get`, `apt-cache`, `dpkg-query`, `pacman`, `rpm`
+ * (popt) and `dnf` (argparse) all honour `--`, while `winget` and `choco`
+ * have their own parsers that do not document it at all and Homebrew's is a
+ * Ruby `OptionParser` whose behaviour this package has not recorded. A
+ * defence that is true for four of six managers is not a defence. So a name
+ * that begins with `-` is REFUSED, on every manager, before anything is
+ * spawned — and `--` is passed on top, where it is known to work, as the belt
+ * to that brace.
+ *
+ * Everything else a hostile name might contain — a double quote, a backslash,
+ * a newline, `$(id)`, a backtick, `</toast>`, `&`, a NUL — is inert in an
+ * argv array, because this package has no shell (see `../run.ts`). It is
+ * still refused, for a different and simpler reason: none of it is a legal
+ * package name in any of these managers, so accepting it could only ever turn
+ * into a confusing error from a child process instead of a clear refusal from
+ * the tool. The tests assert both halves: that each hostile value is refused,
+ * and that when a name IS accepted it reaches the argv as exactly one element
+ * with byte-identical content.
+ */
+/**
+ * Per-manager name grammars, each narrowed to what the manager documents.
+ *
+ *   - homebrew: formula and cask tokens are lowercase `a-z0-9@+._-`, and a
+ *     tap-qualified name adds two slashes (`homebrew/cask/firefox`). Upper
+ *     case is allowed through because a tap's user segment can carry it.
+ *   - apt: Debian policy §5.6.1 — `[a-z0-9][a-z0-9+.-]+`, plus an optional
+ *     `:arch` qualifier (`libc6:i386`).
+ *   - dnf: an rpm name is `[A-Za-z0-9._+-]`, and the whole NEVRA form
+ *     (`kernel-5.14.0-427.el9.x86_64`) is spelled with the same characters,
+ *     which is why a version is passed as part of the NAME for dnf rather
+ *     than built into one here (see `versionSupport`).
+ *   - pacman: `[a-z0-9@._+-]` per PKGBUILD(5), plus `repo/name`.
+ *   - winget: an Id is `Publisher.Package`, ASCII alphanumerics with `.`,
+ *     `-` and `_`. A DISPLAY name (which may contain spaces and CJK) is not
+ *     accepted, because it is not what `--exact` matches on and guessing
+ *     which one the caller meant is how a query answers about the wrong app.
+ *   - choco: package ids are `[A-Za-z0-9._-]`.
+ *
+ * Every pattern rejects a leading `-` structurally, and the check below
+ * rejects it again by name so the refusal says WHY rather than "does not
+ * match".
+ */
+export const NAME_RULES = Object.freeze({
+    homebrew: {
+        pattern: /^[A-Za-z0-9][A-Za-z0-9@+._-]*(\/[A-Za-z0-9][A-Za-z0-9@+._-]*){0,2}$/,
+        charset: "letters, digits and @ + . _ - , with at most two / segments for a tap-qualified name",
+    },
+    apt: {
+        pattern: /^[a-z0-9][a-z0-9+._-]*(:[a-z0-9][a-z0-9-]*)?$/,
+        charset: "lowercase letters, digits and + . _ - , with an optional :architecture suffix",
+    },
+    dnf: {
+        pattern: /^[A-Za-z0-9][A-Za-z0-9._+-]*$/,
+        charset: "letters, digits and . _ + -",
+    },
+    pacman: {
+        pattern: /^[A-Za-z0-9][A-Za-z0-9@._+-]*(\/[A-Za-z0-9][A-Za-z0-9@._+-]*)?$/,
+        charset: "letters, digits and @ . _ + - , with an optional repository/ prefix",
+    },
+    winget: {
+        pattern: /^[A-Za-z0-9][A-Za-z0-9._-]*$/,
+        charset: "ASCII letters, digits and . _ - (a winget package Id, not its display name)",
+    },
+    choco: {
+        pattern: /^[A-Za-z0-9][A-Za-z0-9._-]*$/,
+        charset: "letters, digits and . _ -",
+    },
+});
+/** Longest name accepted. Debian's own limit is far shorter; this is a sanity bound. */
+export const MAX_NAME_LENGTH = 200;
+/** Longest version specifier accepted. */
+export const MAX_VERSION_LENGTH = 100;
+/**
+ * Check one caller-supplied package name.
+ *
+ * Returns the refusal, or `undefined` when the name may become an argv
+ * element. The checks are ordered so the message names the SPECIFIC problem:
+ * "starts with -" is far more useful to a caller than "does not match the
+ * accepted characters", and both are more useful than a manager's own error.
+ */
+export function checkPackageName(manager, name) {
+    if (name === "")
+        return "the package name is empty";
+    if (name.length > MAX_NAME_LENGTH) {
+        return `the package name is ${name.length} characters, over the ${MAX_NAME_LENGTH}-character limit`;
+    }
+    if (name.includes("\0")) {
+        // execve truncates an argument at a NUL, so a name that reads as harmless
+        // here would arrive at the kernel cut short with whatever followed gone.
+        return "the package name contains a NUL byte, which would be truncated at the execve boundary";
+    }
+    if (/[\n\r]/.test(name)) {
+        return "the package name contains a newline, which no package manager accepts in a name";
+    }
+    if (name.startsWith("-")) {
+        return `the package name starts with "-", which a package manager reads as a FLAG rather than a package (${JSON.stringify(name)}) — this is refused rather than defended with "--", because winget, choco and brew do not all document "--" as an end-of-options marker`;
+    }
+    if (name === "." || name === "..") {
+        return `"${name}" is a path, not a package name`;
+    }
+    // Ordered after the specific checks so a control character or a shell
+    // metacharacter is reported as itself rather than as a charset miss.
+    // \u escapes, not \x, and never the raw bytes biome folds \x into: this
+    // class is rewritten by the formatter, and bun 1.3.11 (what CI runs) rejects
+    // a class carrying raw control bytes as "range out of order" while 1.3.14
+    // (what this machine runs) accepts it. The suppression below must stay on
+    // the line directly above the regex — a comment between them makes the
+    // suppression unused AND leaves the rule unsuppressed, which is two errors.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: refusing control characters is the point
+    if (/[\u0000-\u001f\u007f]/.test(name)) {
+        return "the package name contains a control character";
+    }
+    if (/\s/.test(name)) {
+        return "the package name contains whitespace; a package name is a single token";
+    }
+    const rule = NAME_RULES[manager];
+    if (!rule.pattern.test(name)) {
+        return `${JSON.stringify(name)} is not a valid ${manager} package name — accepted: ${rule.charset}`;
+    }
+    return undefined;
+}
+/**
+ * The version grammars the managers that CAN pin a version accept.
+ *
+ * Only apt is here, and that is the honest answer rather than a gap:
+ *
+ *   - apt expresses an exact version as `name=version`, and a Debian version
+ *     string is `[A-Za-z0-9.+~:-]` (policy §5.6.12). `=` is what makes this
+ *     work and is why the version has its own grammar: a version containing
+ *     `=` would produce `name=1=2`, which apt reads as a different package.
+ *   - dnf CAN take `name-version-release`, and this package will not build
+ *     one, because the join is ambiguous the moment the NAME contains a dash
+ *     — which most rpm names do. A caller who wants an exact rpm passes the
+ *     whole NEVRA as the name; that is unambiguous and needs no guessing.
+ *   - pacman has no version selection at all. There is no flag, and the sync
+ *     database holds exactly one version per package.
+ *   - Homebrew installs the tap's current version. The only pin is a
+ *     versioned FORMULA (`node@20`), which is a different name, not a version.
+ *   - winget and choco can pin, but this package does not install through
+ *     either of them at all (see `./managers.ts`), so the question does not
+ *     arise.
+ *
+ * Every one of those is refused explicitly with that sentence, rather than
+ * silently installing latest — which is the failure mode the refusal exists
+ * to prevent.
+ */
+export const DEBIAN_VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9.+~:-]*$/;
+export function checkVersionSyntax(version) {
+    if (version === "")
+        return "the version is empty";
+    if (version.length > MAX_VERSION_LENGTH) {
+        return `the version is ${version.length} characters, over the ${MAX_VERSION_LENGTH}-character limit`;
+    }
+    if (!DEBIAN_VERSION_PATTERN.test(version)) {
+        return `${JSON.stringify(version)} is not a Debian version string — accepted: letters, digits and . + ~ : - , starting with a letter or digit`;
+    }
+    return undefined;
+}