paratix 0.14.0 → 0.15.0

package/dist/{chunk-475OT32R.js → chunk-GB5QZWUM.js}

@@ -10541,18 +10541,19 @@ var op = {
   }
 };
 
-// src/modules/package.ts
-var EXEC_OPTS12 = { ignoreExitCode: true, silent: true };
-function execOptions(options) {
-  if (options?.timeout === void 0) return EXEC_OPTS12;
-  return { ...EXEC_OPTS12, timeout: options.timeout };
+// src/modules/packageVersion.ts
+var VERSION_EXEC_OPTS = { ignoreExitCode: true, silent: true };
+function isPackageSpec(value) {
+  return "name" in value && typeof value.name === "string";
 }
 function splitPackagesAndOptions(values) {
   const packages = [];
   let options;
   for (const [index, value] of values.entries()) {
     if (typeof value === "string") {
-      packages.push(value);
+      packages.push({ name: value, version: void 0 });
+    } else if (isPackageSpec(value)) {
+      packages.push({ name: value.name, version: value.version });
     } else if (index === values.length - 1) {
       options = value;
     }
@@ -10560,16 +10561,135 @@ function splitPackagesAndOptions(values) {
   return { options, packages };
 }
 var PACKAGE_NAME_PATTERN = new RegExp("^[a-z0-9][a-z0-9+._\\-]*[a-z0-9.]$", "v");
-function validatePackageNames(moduleName, packages) {
+var PACKAGE_VERSION_PATTERN = new RegExp("^[A-Za-z0-9][\\w.+~:\\-]*$", "v");
+function isValidPackageName(packageName) {
+  const isSingleAlnum = packageName.length === 1 && new RegExp("^[a-z0-9]$", "v").test(packageName);
+  return isSingleAlnum || PACKAGE_NAME_PATTERN.test(packageName);
+}
+function validatePackages(moduleName, packages) {
   if (packages.length === 0) {
     throw new Error(`${moduleName}: at least one package name is required`);
   }
-  for (const packageName of packages) {
-    const isSingleAlnum = packageName.length === 1 && new RegExp("^[a-z0-9]$", "v").test(packageName);
-    if (!isSingleAlnum && !PACKAGE_NAME_PATTERN.test(packageName)) {
-      throw new Error(`${moduleName}: invalid package name ${JSON.stringify(packageName)}`);
+  const seenVersions = /* @__PURE__ */ new Map();
+  for (const { name, version } of packages) {
+    if (!isValidPackageName(name)) {
+      throw new Error(`${moduleName}: invalid package name ${JSON.stringify(name)}`);
+    }
+    if (version !== void 0 && !PACKAGE_VERSION_PATTERN.test(version)) {
+      throw new Error(
+        `${moduleName}: invalid package version ${JSON.stringify(version)} for ${JSON.stringify(name)}`
+      );
+    }
+    if (seenVersions.has(name) && seenVersions.get(name) !== version) {
+      throw new Error(
+        `${moduleName}: conflicting versions requested for package ${JSON.stringify(name)}`
+      );
     }
+    seenVersions.set(name, version);
+  }
+}
+function installToken(pm, packageName, version) {
+  if (version === void 0) return shellQuote(packageName);
+  const separator = pm === "dnf" || pm === "yum" ? "-" : "=";
+  return shellQuote(`${packageName}${separator}${version}`);
+}
+function parseApkVersion(out, packageName) {
+  if (out.length === 0) return null;
+  const firstToken = out.split(new RegExp("\\s+", "v"))[0] ?? "";
+  const prefix = `${packageName}-`;
+  if (!firstToken.startsWith(prefix)) return null;
+  const version = firstToken.slice(prefix.length);
+  return version.length > 0 ? version : null;
+}
+async function getInstalledVersion(ssh2, pm, packageName) {
+  const quoted = shellQuote(packageName);
+  if (pm === "apk") {
+    const raw = await ssh2.output(`apk version -v ${quoted}`);
+    return parseApkVersion(raw.trim(), packageName);
+  }
+  if (pm === "apt") {
+    const raw = await ssh2.output(`dpkg-query -W -f='\${Version}' ${quoted} 2>/dev/null`);
+    const aptVersion = raw.trim();
+    return aptVersion.length > 0 ? aptVersion : null;
+  }
+  const result = await ssh2.exec(
+    `rpm -q --qf '%|EPOCH?{%{EPOCH}:}:{}|%{VERSION}-%{RELEASE}\\n' ${quoted}`,
+    VERSION_EXEC_OPTS
+  );
+  if (result.code !== 0) return null;
+  const lines = result.stdout.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+  return lines.at(-1) ?? null;
+}
+async function versionsEqual(parameters) {
+  const { installed, pinned, pm, ssh: ssh2 } = parameters;
+  if (pm === "apt") {
+    return ssh2.test(`dpkg --compare-versions ${shellQuote(installed)} eq ${shellQuote(pinned)}`);
   }
+  return installed === pinned;
+}
+function describePackages(packages) {
+  return packages.map((p) => p.version === void 0 ? p.name : `${p.name}=${p.version}`).join(", ");
+}
+function aptInstallCommand(tokens, hasPin) {
+  return hasPin ? `DEBIAN_FRONTEND=noninteractive apt-get install -y --allow-downgrades -- ${tokens}` : `DEBIAN_FRONTEND=noninteractive apt-get install -y -- ${tokens}`;
+}
+var DOWNGRADE_COMMANDS = {
+  dnf: (tokens) => `dnf downgrade -y -- ${tokens}`,
+  yum: (tokens) => `yum downgrade -y -- ${tokens}`
+};
+function buildInstallCommand(baseInstall, pm, packages) {
+  const tokens = packages.map((p) => installToken(pm, p.name, p.version)).join(" ");
+  const hasPin = packages.some((p) => p.version !== void 0);
+  return pm === "apt" ? aptInstallCommand(tokens, hasPin) : baseInstall(tokens);
+}
+async function installedIsHigher(ssh2, installed, pinned) {
+  if (installed === pinned) return false;
+  const result = await ssh2.exec(
+    `printf '%s\\n%s\\n' ${shellQuote(pinned)} ${shellQuote(installed)} | sort -V | tail -n1`,
+    VERSION_EXEC_OPTS
+  );
+  if (result.code !== 0) return false;
+  return result.stdout.trim() === installed;
+}
+async function collectDowngradeTokens(ssh2, pm, packages) {
+  const downgrade = [];
+  const install = [];
+  for (const package_ of packages) {
+    if (package_.version === void 0) {
+      install.push(package_);
+      continue;
+    }
+    const installed = await getInstalledVersion(ssh2, pm, package_.name);
+    if (installed !== null && await installedIsHigher(ssh2, installed, package_.version)) {
+      downgrade.push(installToken(pm, package_.name, package_.version));
+    } else {
+      install.push(package_);
+    }
+  }
+  return { downgrade, install };
+}
+async function runVersionedInstall(parameters) {
+  const { baseInstall, execOpts, label, packages, pm, ssh: ssh2 } = parameters;
+  const failure = (result) => failedCommand(`[package.installed: ${label}] package installation failed`, result);
+  let installTargets = packages;
+  if (pm === "dnf" || pm === "yum") {
+    const split = await collectDowngradeTokens(ssh2, pm, packages);
+    installTargets = split.install;
+    if (split.downgrade.length > 0) {
+      const down = await ssh2.exec(DOWNGRADE_COMMANDS[pm](split.downgrade.join(" ")), execOpts);
+      if (down.code !== 0) return failure(down);
+    }
+  }
+  if (installTargets.length === 0) return null;
+  const install = await ssh2.exec(buildInstallCommand(baseInstall, pm, installTargets), execOpts);
+  return install.code === 0 ? null : failure(install);
+}
+
+// src/modules/package.ts
+var EXEC_OPTS12 = { ignoreExitCode: true, silent: true };
+function execOptions(options) {
+  if (options?.timeout === void 0) return EXEC_OPTS12;
+  return { ...EXEC_OPTS12, timeout: options.timeout };
 }
 var pmCache = /* @__PURE__ */ new WeakMap();
 var INSTALL_COMMANDS = {
@@ -10635,35 +10755,45 @@ async function isPackageInstalled(ssh2, pm, packageName) {
     }
   }
 }
+async function isPackageSatisfied(ssh2, pm, target) {
+  if (target.version === void 0) {
+    return isPackageInstalled(ssh2, pm, target.name);
+  }
+  const installed = await getInstalledVersion(ssh2, pm, target.name);
+  if (installed === null) return false;
+  return versionsEqual({ installed, pinned: target.version, pm, ssh: ssh2 });
+}
 async function hasAnyMissingPackage(ssh2, pm, packages) {
-  for (const packageName of packages) {
-    if (!await isPackageInstalled(ssh2, pm, packageName)) return true;
+  for (const package_ of packages) {
+    if (!await isPackageSatisfied(ssh2, pm, package_)) return true;
   }
   return false;
 }
 async function collectStillMissingPackages(ssh2, pm, packages) {
   const stillMissing = [];
-  for (const verifyName of packages) {
-    if (!await isPackageInstalled(ssh2, pm, verifyName)) {
-      stillMissing.push(verifyName);
+  for (const package_ of packages) {
+    if (!await isPackageSatisfied(ssh2, pm, package_)) {
+      stillMissing.push(package_.name);
     }
   }
   return stillMissing;
 }
 async function runInstallAndVerify(parameters) {
   const { options, packages, pm, ssh: ssh2 } = parameters;
-  const quoted = packages.map((p) => shellQuote(p)).join(" ");
-  const result = await ssh2.exec(INSTALL_COMMANDS[pm](quoted), execOptions(options));
-  if (result.code !== 0) {
-    return failedCommand(
-      `[package.installed: ${packages.join(", ")}] package installation failed`,
-      result
-    );
-  }
+  const label = describePackages(packages);
+  const failure = await runVersionedInstall({
+    baseInstall: INSTALL_COMMANDS[pm],
+    execOpts: execOptions(options),
+    label,
+    packages,
+    pm,
+    ssh: ssh2
+  });
+  if (failure) return failure;
   const stillMissing = await collectStillMissingPackages(ssh2, pm, packages);
   if (stillMissing.length > 0) {
     return failed(
-      `[package.installed: ${packages.join(", ")}] packages still missing after install: ${stillMissing.join(", ")}`
+      `[package.installed: ${label}] packages still missing after install: ${stillMissing.join(", ")}`
     );
   }
   return { status: "changed" };
@@ -10678,8 +10808,9 @@ var pkg = {
    * Pass an `UpgradeOptions` object as the last argument to override the SSH
    * timeout for slow remove operations.
    *
-   * @param packagesAndOptions - One or more package names, optionally followed
-   *   by an `UpgradeOptions` object as the last argument.
+   * @param packagesAndOptions - One or more package names (bare strings or
+   *   `PackageSpec` objects without a `version`), optionally followed by an
+   *   `UpgradeOptions` object as the last argument.
    * @returns A Module that removes the packages if any are present.
    *
    * @example
@@ -10688,28 +10819,33 @@ var pkg = {
    */
   absent(...packagesAndOptions) {
     const { options, packages } = splitPackagesAndOptions(packagesAndOptions);
-    validatePackageNames("package.absent", packages);
+    validatePackages("package.absent", packages);
+    for (const p of packages) {
+      if (p.version !== void 0) {
+        throw new Error(
+          `package.absent: version pinning is not supported (package ${JSON.stringify(p.name)})`
+        );
+      }
+    }
+    const names = packages.map((p) => p.name);
+    const label = names.join(", ");
     return {
       async apply(ssh2) {
-        if (!ssh2)
-          return failed(`[package.absent: ${packages.join(", ")}] SSH connection is required`);
+        if (!ssh2) return failed(`[package.absent: ${label}] SSH connection is required`);
         const pm = await detectPackageManager(ssh2);
-        if (!pm) return missingPackageManager(`package.absent: ${packages.join(", ")}`);
+        if (!pm) return missingPackageManager(`package.absent: ${label}`);
         let anyInstalled = false;
-        for (const packageName of packages) {
+        for (const packageName of names) {
           if (await isPackageInstalled(ssh2, pm, packageName)) {
             anyInstalled = true;
             break;
           }
         }
         if (!anyInstalled) return { status: "ok" };
-        const quoted = packages.map((p) => shellQuote(p)).join(" ");
+        const quoted = names.map((p) => shellQuote(p)).join(" ");
         const result = await ssh2.exec(REMOVE_COMMANDS[pm](quoted), execOptions(options));
         if (result.code !== 0) {
-          return failedCommand(
-            `[package.absent: ${packages.join(", ")}] package removal failed`,
-            result
-          );
+          return failedCommand(`[package.absent: ${label}] package removal failed`, result);
         }
         return { status: "changed" };
       },
@@ -10717,12 +10853,12 @@ var pkg = {
         if (!ssh2) return NEEDS_APPLY;
         const pm = await detectPackageManager(ssh2);
         if (!pm) return NEEDS_APPLY;
-        for (const p of packages) {
+        for (const p of names) {
           if (await isPackageInstalled(ssh2, pm, p)) return NEEDS_APPLY;
         }
         return "ok";
       },
-      name: `package.absent: ${packages.join(", ")}`
+      name: `package.absent: ${label}`
     };
   },
   /**
@@ -10734,24 +10870,32 @@ var pkg = {
    * Pass an `UpgradeOptions` object as the last argument to override the SSH
    * timeout for slow install operations.
    *
-   * @param packagesAndOptions - One or more package names, optionally followed
-   *   by an `UpgradeOptions` object as the last argument.
+   * Pass a `PackageSpec` (`{ name, version }`) to pin a package to an exact
+   * version; `check` then reports drift against the installed version and
+   * `apply` converges on the pin, including a downgrade. No package holds are
+   * created — only the requested version is installed.
+   *
+   * @param packagesAndOptions - One or more packages (bare name strings or
+   *   `PackageSpec` objects), optionally followed by an `UpgradeOptions` object
+   *   as the last argument.
    * @returns A Module that installs missing packages.
    *
    * @example
    * pkg.installed("git", "curl", "unzip")
    * pkg.installed("texlive-full", { timeout: 900_000 })
+   * pkg.installed({ name: "grafana", version: "13.1.0" })
    */
   installed(...packagesAndOptions) {
     const { options, packages } = splitPackagesAndOptions(packagesAndOptions);
-    validatePackageNames("package.installed", packages);
+    validatePackages("package.installed", packages);
+    const label = describePackages(packages);
     return {
       async apply(ssh2) {
         if (!ssh2) {
-          return failed(`[package.installed: ${packages.join(", ")}] SSH connection is required`);
+          return failed(`[package.installed: ${label}] SSH connection is required`);
         }
         const pm = await detectPackageManager(ssh2);
-        if (!pm) return missingPackageManager(`package.installed: ${packages.join(", ")}`);
+        if (!pm) return missingPackageManager(`package.installed: ${label}`);
         const anyMissing = await hasAnyMissingPackage(ssh2, pm, packages);
         if (!anyMissing) return { status: "ok" };
         return runInstallAndVerify({ options, packages, pm, ssh: ssh2 });
@@ -10761,11 +10905,11 @@ var pkg = {
         const pm = await detectPackageManager(ssh2);
         if (!pm) return NEEDS_APPLY;
         for (const p of packages) {
-          if (!await isPackageInstalled(ssh2, pm, p)) return NEEDS_APPLY;
+          if (!await isPackageSatisfied(ssh2, pm, p)) return NEEDS_APPLY;
         }
         return "ok";
       },
-      name: `package.installed: ${packages.join(", ")}`
+      name: `package.installed: ${label}`
     };
   },
   /**

package/dist/cli.js

@@ -6262,7 +6262,7 @@ async function runApplyCommand(file, options, run = runPlaybook) {
   if (options.diff && !options.dryRun) {
     throw new CliUsageError("--diff requires --dry-run");
   }
-  printCliHeader("0.14.0-5a61f29");
+  printCliHeader("0.15.0-645d2fd");
   const environmentOverrides = applyCliEnvironmentOverrides(options.env, {
     firstRun: options.firstRun
   });
@@ -6300,7 +6300,7 @@ function renderSubcommandOptionsHelp(command) {
   return ["", `Options for "paratix ${command.name()} <file>":`, ...rows].join("\n");
 }
 var program = new Command();
-program.name("paratix").description("Idempotent VPS setup tool in TypeScript").version("0.14.0-5a61f29");
+program.name("paratix").description("Idempotent VPS setup tool in TypeScript").version("0.15.0-645d2fd");
 var applyCommand = program.command("apply <file>").description("Apply a server definition").option(
   "--diff",
   "When combined with --dry-run, show a unified diff per module that would change.",

package/dist/{index-DlZISXJx.d.ts → index-Da9ccU5K.d.ts}

@@ -339,6 +339,27 @@ type UpgradeOptions = {
     /** Override the SSH layer's command timeout (milliseconds). */
     timeout?: number;
 };
+/**
+ * A package to install, optionally pinned to an exact version.
+ *
+ * A bare string package name is equivalent to `{ name }` (no version pin). The
+ * package-manager-specific version syntax (`name=version`, `name-version`) is
+ * never accepted as a pass-through string — it is built from the structured
+ * `name`/`version` fields so the raw PM syntax can never leak into a playbook.
+ */
+type PackageSpec = {
+    /** Package name (validated against {@link PACKAGE_NAME_PATTERN}). */
+    name: string;
+    /**
+     * Exact version to pin to. When set, `check` reports drift against the
+     * installed version and `apply` converges on this version (including a
+     * downgrade). When omitted, only presence is enforced.
+     */
+    version?: string;
+};
+/** Argument accepted by the variadic `installed`/`absent` package methods. */
+type PackageArgument = PackageSpec | string | UpgradeOptions;
+
 /**
  * Distro-agnostic package management module.
  *
@@ -367,15 +388,16 @@ declare const pkg: {
      * Pass an `UpgradeOptions` object as the last argument to override the SSH
      * timeout for slow remove operations.
      *
-     * @param packagesAndOptions - One or more package names, optionally followed
-     *   by an `UpgradeOptions` object as the last argument.
+     * @param packagesAndOptions - One or more package names (bare strings or
+     *   `PackageSpec` objects without a `version`), optionally followed by an
+     *   `UpgradeOptions` object as the last argument.
      * @returns A Module that removes the packages if any are present.
      *
      * @example
      * pkg.absent("vim", "nano")
      * pkg.absent("vim", "nano", { timeout: 600_000 })
      */
-    absent(...packagesAndOptions: Array<string | UpgradeOptions>): Module;
+    absent(...packagesAndOptions: PackageArgument[]): Module;
     /**
      * Ensure the given packages are installed.
      *
@@ -385,15 +407,22 @@ declare const pkg: {
      * Pass an `UpgradeOptions` object as the last argument to override the SSH
      * timeout for slow install operations.
      *
-     * @param packagesAndOptions - One or more package names, optionally followed
-     *   by an `UpgradeOptions` object as the last argument.
+     * Pass a `PackageSpec` (`{ name, version }`) to pin a package to an exact
+     * version; `check` then reports drift against the installed version and
+     * `apply` converges on the pin, including a downgrade. No package holds are
+     * created — only the requested version is installed.
+     *
+     * @param packagesAndOptions - One or more packages (bare name strings or
+     *   `PackageSpec` objects), optionally followed by an `UpgradeOptions` object
+     *   as the last argument.
      * @returns A Module that installs missing packages.
      *
      * @example
      * pkg.installed("git", "curl", "unzip")
      * pkg.installed("texlive-full", { timeout: 900_000 })
+     * pkg.installed({ name: "grafana", version: "13.1.0" })
      */
-    installed(...packagesAndOptions: Array<string | UpgradeOptions>): Module;
+    installed(...packagesAndOptions: PackageArgument[]): Module;
     /**
      * Refresh the package manager's package lists once per dated flag.
      *
@@ -2108,4 +2137,4 @@ declare const user: {
     present(name: string, options?: UserOptions): Module;
 };
 
-export { op as A, pkg as B, quadlet as C, releaseUpgrade as D, type Environment as E, rsync as F, script as G, service as H, ssh as I, sshd as J, swap as K, sysctl as L, type Module as M, NEEDS_APPLY as N, type OrchestrationStep as O, system as P, systemd as Q, timer as R, type SshdPortMetaEntry as S, ufw as T, user as U, type UpgradeOptions as V, type ModuleMetaEntry as a, type MetaEnvironmentValue as b, type EnvironmentMetaEntry as c, type SystemHostMetaEntry as d, type SystemRebootMetaEntry as e, type ModuleResult as f, type ExecResult as g, type ModuleStatus as h, type SshConnection as i, type ShutdownSignal as j, type ServerDefinition as k, type EnvironmentValue as l, type ExecOptions as m, type SshConfig as n, apt as o, archive as p, command as q, compose as r, cron as s, download as t, file as u, git as v, group as w, hostname as x, mount as y, net as z };
+export { op as A, pkg as B, quadlet as C, releaseUpgrade as D, type Environment as E, rsync as F, script as G, service as H, ssh as I, sshd as J, swap as K, sysctl as L, type Module as M, NEEDS_APPLY as N, type OrchestrationStep as O, system as P, systemd as Q, timer as R, type SshdPortMetaEntry as S, ufw as T, user as U, type PackageSpec as V, type UpgradeOptions as W, type ModuleMetaEntry as a, type MetaEnvironmentValue as b, type EnvironmentMetaEntry as c, type SystemHostMetaEntry as d, type SystemRebootMetaEntry as e, type ModuleResult as f, type ExecResult as g, type ModuleStatus as h, type SshConnection as i, type ShutdownSignal as j, type ServerDefinition as k, type EnvironmentValue as l, type ExecOptions as m, type SshConfig as n, apt as o, archive as p, command as q, compose as r, cron as s, download as t, file as u, git as v, group as w, hostname as x, mount as y, net as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { E as Environment, M as Module, a as ModuleMetaEntry, b as MetaEnvironmentValue, c as EnvironmentMetaEntry, S as SshdPortMetaEntry, d as SystemHostMetaEntry, e as SystemRebootMetaEntry, f as ModuleResult, g as ExecResult, h as ModuleStatus, i as SshConnection, O as OrchestrationStep, j as ShutdownSignal, k as ServerDefinition } from './index-DlZISXJx.js';
-export { l as EnvironmentValue, m as ExecOptions, N as NEEDS_APPLY, n as SshConfig, o as apt, p as archive, q as command, r as compose, s as cron, t as download, u as file, v as git, w as group, x as hostname, y as mount, z as net, A as op, B as package, C as quadlet, D as releaseUpgrade, F as rsync, G as script, H as service, I as ssh, J as sshd, K as swap, L as sysctl, P as system, Q as systemd, R as timer, T as ufw, U as user } from './index-DlZISXJx.js';
+import { E as Environment, M as Module, a as ModuleMetaEntry, b as MetaEnvironmentValue, c as EnvironmentMetaEntry, S as SshdPortMetaEntry, d as SystemHostMetaEntry, e as SystemRebootMetaEntry, f as ModuleResult, g as ExecResult, h as ModuleStatus, i as SshConnection, O as OrchestrationStep, j as ShutdownSignal, k as ServerDefinition } from './index-Da9ccU5K.js';
+export { l as EnvironmentValue, m as ExecOptions, N as NEEDS_APPLY, n as SshConfig, o as apt, p as archive, q as command, r as compose, s as cron, t as download, u as file, v as git, w as group, x as hostname, y as mount, z as net, A as op, B as package, C as quadlet, D as releaseUpgrade, F as rsync, G as script, H as service, I as ssh, J as sshd, K as swap, L as sysctl, P as system, Q as systemd, R as timer, T as ufw, U as user } from './index-Da9ccU5K.js';
 
 /**
  * Fail the run if a condition on the current env is not satisfied.

package/dist/index.js

@@ -61,7 +61,7 @@ import {
   user,
   validateHostLabel,
   validateSshConfig
-} from "./chunk-475OT32R.js";
+} from "./chunk-GB5QZWUM.js";
 
 // src/conditionalModules.ts
 function createConditionalApplyState(environment) {

package/dist/modules/index.d.ts

@@ -1 +1 @@
-export { V as UpgradeOptions, o as apt, p as archive, q as command, r as compose, s as cron, t as download, u as file, v as git, w as group, x as hostname, y as mount, z as net, A as op, B as package, C as quadlet, D as releaseUpgrade, F as rsync, G as script, H as service, I as ssh, J as sshd, K as swap, L as sysctl, P as system, Q as systemd, R as timer, T as ufw, U as user } from '../index-DlZISXJx.js';
+export { V as PackageSpec, W as UpgradeOptions, o as apt, p as archive, q as command, r as compose, s as cron, t as download, u as file, v as git, w as group, x as hostname, y as mount, z as net, A as op, B as package, C as quadlet, D as releaseUpgrade, F as rsync, G as script, H as service, I as ssh, J as sshd, K as swap, L as sysctl, P as system, Q as systemd, R as timer, T as ufw, U as user } from '../index-Da9ccU5K.js';

package/dist/modules/index.js

@@ -27,7 +27,7 @@ import {
   timer,
   ufw,
   user
-} from "../chunk-475OT32R.js";
+} from "../chunk-GB5QZWUM.js";
 export {
   apt,
   archive,

package/llm-guide.md

@@ -277,12 +277,12 @@ that are expected to respond more slowly.
 
 Import with renaming: `import { package as pkg } from "paratix/modules"`. The word `package` is reserved in JavaScript, so you must alias it.
 
-| Method              | Signature                                                          | Idempotent           |
-| ------------------- | ------------------------------------------------------------------ | -------------------- |
-| `package.installed` | `(...packagesAndOptions: Array<string \| UpgradeOptions>): Module` | Yes                  |
-| `package.absent`    | `(...packagesAndOptions: Array<string \| UpgradeOptions>): Module` | Yes                  |
-| `package.update`    | `(date: string, options?: UpgradeOptions): Module`                 | Yes (versioned flag) |
-| `package.upgrade`   | `(date: string, options?: UpgradeOptions): Module`                 | Yes (versioned flag) |
+| Method              | Signature                                                                         | Idempotent           |
+| ------------------- | --------------------------------------------------------------------------------- | -------------------- |
+| `package.installed` | `(...packagesAndOptions: Array<string \| PackageSpec \| UpgradeOptions>): Module` | Yes                  |
+| `package.absent`    | `(...packagesAndOptions: Array<string \| PackageSpec \| UpgradeOptions>): Module` | Yes                  |
+| `package.update`    | `(date: string, options?: UpgradeOptions): Module`                                | Yes (versioned flag) |
+| `package.upgrade`   | `(date: string, options?: UpgradeOptions): Module`                                | Yes (versioned flag) |
 
 #### `UpgradeOptions`
 
@@ -293,10 +293,10 @@ type UpgradeOptions = {
 }
 ```
 
-For `package.installed` / `package.absent`, pass the options object as the **last** argument
-after the package names; existing variadic call sites such as `pkg.installed("git", "curl")`
-keep working unchanged. Use a longer `timeout` for slow operations on production servers
-with large update backlogs:
+Für `package.installed` / `package.absent` wird das Options-Objekt als **letztes** Argument
+nach den Paketnamen übergeben; bestehende variadische Aufrufe wie `pkg.installed("git", "curl")`
+funktionieren unverändert weiter. Verwende einen höheren `timeout` für langsame Operationen auf
+Produktionsservern mit großem Update-Rückstand:
 
 ```typescript
 pkg.upgrade("2026-05-01", { timeout: 900_000 })
@@ -304,6 +304,57 @@ pkg.installed("texlive-full", { timeout: 900_000 })
 apt.distUpgrade("2026-05-01", { timeout: 1_200_000 })
 ```
 
+#### `PackageSpec` — Versions-Pinning
+
+```typescript
+type PackageSpec = {
+  name: string
+  version?: string // Exakte Zielversion. Ohne `version` wird nur die Anwesenheit erzwungen.
+}
+```
+
+Ein Paket kann auf eine exakte Version festgenagelt werden, indem statt eines Strings ein
+`PackageSpec`-Objekt übergeben wird. Ein bloßer String `"grafana"` ist äquivalent zu
+`{ name: "grafana" }` (kein Pin). Die paketmanager-spezifische Syntax (`name=version`,
+`name-version`) wird **niemals** als Pass-through-String akzeptiert — ein String mit `=` bleibt
+ein ungültiger Paketname. Die Argumente werden über ihre **Form** unterschieden, nicht über die
+Position: ein Objekt **mit** `name`-Feld ist ein `PackageSpec` (darf auch an letzter Stelle
+stehen), ein Objekt **ohne** `name`-Feld an letzter Position ist das `UpgradeOptions`-Objekt.
+
+```typescript
+pkg.installed({ name: "grafana", version: "13.1.0" })
+pkg.installed("curl", { name: "grafana", version: "13.1.0" }, { timeout: 600_000 })
+```
+
+Übersetzung des Install-Tokens je Paketmanager:
+
+| Paketmanager | Install-Token  | Beispiel               |
+| ------------ | -------------- | ---------------------- |
+| apt          | `name=version` | `grafana=13.1.0`       |
+| apk          | `name=version` | `grafana=13.1.0-r0`    |
+| dnf / yum    | `name-version` | `grafana-13.1.0-1.el9` |
+
+Semantik:
+
+- **`check`** vergleicht die installierte gegen die gepinnte Version; jede Abweichung ergibt
+  `needs-apply`. Ohne gepinnte Version bleibt es eine reine Anwesenheitsprüfung.
+- **`apply`** installiert exakt die gepinnte Version — auch als **Downgrade**. Für apt wird bei
+  gepinnter Version automatisch `--allow-downgrades` ergänzt; für dnf/yum wird bei einer bereits
+  installierten höheren Version `dnf downgrade` / `yum downgrade` statt `install` verwendet
+  (apk installiert die exakte Version auch abwärts ohne Extra-Flag). Die Richtungsbestimmung für
+  dnf/yum nutzt einen versionsbewussten Vergleich auf dem Zielhost (`sort -V`), damit mehrstellige
+  Komponenten wie `13.9.0` vs. `13.10.0` korrekt geordnet werden.
+- Nach der Installation wird zusätzlich die Version verifiziert: eine Teil- oder Falschversions-
+  Installation meldet `failed`, nicht `changed`.
+- **Kein Hold.** Es wird ausschließlich die Version installiert — es werden **keine**
+  `apt-mark hold`-Marker und **keine** `preferences.d`-Dateien angelegt. Ohne einen erneuten
+  Lauf mit gepinnter Version kann ein späterer `apt upgrade` das Paket also wieder anheben.
+
+Gültige Versionen beginnen alphanumerisch und dürfen `[A-Za-z0-9]` sowie `. + ~ : _ -` enthalten
+(deckt apt-Epoch/Revision wie `1:2.3-1ubuntu0.2` und rpm-`version-release` wie `13.1.0-1.el9` ab).
+Whitespace und Shell-Metazeichen werden abgelehnt. `package.absent` ist rein namensbasiert; ein
+`PackageSpec` mit gesetzter `version` führt dort zu einem klaren Fehler.
+
 ### `quadlet`
 
 | Method                | Signature                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Idempotent |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paratix",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Idempotent VPS setup tool in TypeScript",
   "type": "module",
   "files": [