paratix 0.13.0 → 0.15.0

package/README.md

@@ -119,19 +119,21 @@ Paratix can also manage file-backed swap directly. Use `swap.file(...)` to provi
 
 ## CLI
 
+`paratix --help` lists these options directly, so they are discoverable without drilling into `paratix apply --help` first.
+
 ```text
 paratix apply <file> [options]
 
 Options:
-  --diff
-  --dry-run
-  --env <key=value>
-  --env-file <path>
-  --filter <names>
-  --first-run
-  --reconnect-timeout <seconds>
-  --verbose
-  --help
+  --diff                         Combined with --dry-run: unified diff per changed module
+  --dry-run                      Only check, do not apply (some runtime restarts stay unverified)
+  --env <key=value...>           Set environment values for the playbook (repeatable)
+  --env-file <path>              Load environment values from a dotenv file
+  --filter <names>               Run only the named recipes/modules (comma-separated, repeatable)
+  --first-run                    Set PARATIX_FIRST_RUN=true before loading the playbook
+  --reconnect-timeout <seconds>  SSH reconnect timeout for reboots/port changes (max 86400)
+  --verbose                      Show full stack traces on error
+  --help                         Show help
 ```
 
 `--filter <names>` restricts the run to the named recipes and modules. Names are matched anywhere in the tree, and every node that is not selected is shown as `skipped` instead of being executed. The option is comma-separated and repeatable, so `--filter rybbit,palamedes-examples` and `--filter rybbit --filter palamedes-examples` are equivalent. Selecting a recipe runs its whole subtree; a recipe that is not selected but contains a selected descendant is still descended into, so only the matching children run while its siblings are skipped. If several nodes share the same name, every one of them is selected. An unknown filter name aborts the run before it connects (exit code 2). The final run summary counts only top-level nodes, so nested skipped nodes are still shown but are not added to the `skipped` tally. `--filter` composes with `--dry-run` and the other flags.
@@ -145,7 +147,9 @@ Options:
 ## Documentation
 
 - For project scaffolding, see [`create-paratix`](https://www.npmjs.com/package/create-paratix).
-- For detailed authoring guidance and module reference inside this repo, see [llm-guide.md](./llm-guide.md).
+- See the complete [TypeScript API and Module Reference](./llm-guide.md).
+- For common runtime and connection failures, see [Troubleshooting](../../docs/user-guide/troubleshooting.md).
+- Before upgrading an existing project, see the [migration notes](../../docs/user-guide/migration.md).
 
 ## License
 

package/dist/{chunk-XIRORNO3.js → chunk-GB5QZWUM.js}

@@ -3245,6 +3245,15 @@ async function commandCheckPassed(ssh2, check, secrets) {
   });
   return result.code === 0;
 }
+function commandExecOptions(secrets, options) {
+  const execOptions2 = {
+    ignoreExitCode: true,
+    secrets,
+    silent: true
+  };
+  if (options?.timeout !== void 0) execOptions2.timeout = options.timeout;
+  return execOptions2;
+}
 var command = {
   /**
    * Run an arbitrary shell command on the remote host.
@@ -3264,6 +3273,7 @@ var command = {
    *   If it exits `0`, the command is considered already done.
    * @param options.name - An optional display name shown in the run output.
    * @param options.secrets - Secret values that must be redacted from command output.
+   * @param options.timeout - Maximum runtime for the command in milliseconds.
    * @returns A Module that executes the shell command.
    *
    * @example
@@ -3285,11 +3295,7 @@ var command = {
         if (options?.check != null && await commandCheckPassed(ssh2, options.check, secrets)) {
           return { status: "ok" };
         }
-        const result = await ssh2.exec(cmd, {
-          ignoreExitCode: true,
-          secrets,
-          silent: true
-        });
+        const result = await ssh2.exec(cmd, commandExecOptions(secrets, options));
         if (result.code !== 0) {
           return failedCommand(`[${moduleName}] command failed`, {
             ...result,
@@ -10535,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;
     }
@@ -10554,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 = {
@@ -10629,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" };
@@ -10672,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
@@ -10682,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" };
       },
@@ -10711,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}`
     };
   },
   /**
@@ -10728,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 });
@@ -10755,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

@@ -1547,6 +1547,10 @@ var DEFAULT_TERMINAL_COLUMNS = 100;
 var MIN_PACKAGE_COLUMNS_WIDTH = 24;
 var MIN_PACKAGE_COLUMN_WIDTH = 18;
 var MIN_ANIMATED_LINE_COLUMNS = 8;
+var ELAPSED_DISPLAY_THRESHOLD_MS = 1e3;
+var MILLISECONDS_PER_SECOND = 1e3;
+var MILLISECONDS_PER_MINUTE = 6e4;
+var SECONDS_PER_MINUTE = 60;
 function splitPackageModuleName(name) {
   for (const prefix of ["package.installed: ", "package.absent: "]) {
     if (!name.startsWith(prefix)) continue;
@@ -1584,6 +1588,16 @@ function getPackageSummaryDetail(packageCount, detail) {
   const packageLabel = packageCount === 1 ? "1 package" : `${packageCount} packages`;
   return detail == null ? packageLabel : `${packageLabel} \xB7 ${detail}`;
 }
+function formatModuleElapsed(elapsedMs) {
+  if (!Number.isFinite(elapsedMs) || elapsedMs < ELAPSED_DISPLAY_THRESHOLD_MS) return void 0;
+  if (elapsedMs < MILLISECONDS_PER_MINUTE) {
+    return `${(elapsedMs / MILLISECONDS_PER_SECOND).toFixed(1)}s`;
+  }
+  const totalSeconds = Math.floor(elapsedMs / MILLISECONDS_PER_SECOND);
+  const minutes = Math.floor(totalSeconds / SECONDS_PER_MINUTE);
+  const seconds = totalSeconds % SECONDS_PER_MINUTE;
+  return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+}
 function fitAnimatedModuleLine(line, columns) {
   if (columns === void 0 || columns < MIN_ANIMATED_LINE_COLUMNS) return line;
   const plainLine = stripVTControlCharacters(line);
@@ -1835,6 +1849,7 @@ function getSharedLiveOutputState() {
   const existing = registry[LIVE_OUTPUT_STATE_KEY];
   if (existing != null) return existing;
   const created = {
+    activeModuleStartedAt: null,
     activeRecipeGuideDepths: [],
     activeSpinner: null,
     cursorHidden: false,
@@ -1885,7 +1900,7 @@ function getGuideDot(depth) {
   return depth % 2 === 0 ? pc.gray("\xB7") : pc.cyan("\xB7");
 }
 function buildGuideIndent(baseIndent, options) {
-  const indentCharacters = Array.from(baseIndent);
+  const indentCharacters = [...baseIndent];
   const guideDepths = [
     ...options?.activeGuideDepths ?? liveOutputState.activeRecipeGuideDepths,
     ...options?.extraGuideDepths ?? []
@@ -1921,20 +1936,27 @@ async function withRecipeOutputScope(scopedOperation) {
   try {
     return await scopedOperation();
   } finally {
-    liveOutputState.activeRecipeGuideDepths = liveOutputState.activeRecipeGuideDepths.filter((depth) => depth !== liveOutputState.recipeOutputDepth);
+    liveOutputState.activeRecipeGuideDepths = liveOutputState.activeRecipeGuideDepths.filter(
+      (depth) => depth !== liveOutputState.recipeOutputDepth
+    );
     liveOutputState.pendingRecipeClosureGuideDepths = [liveOutputState.recipeOutputDepth];
     liveOutputState.recipeOutputDepth -= 1;
   }
 }
+function getActiveModuleElapsed() {
+  if (liveOutputState.activeModuleStartedAt == null) return void 0;
+  return formatModuleElapsed(Date.now() - liveOutputState.activeModuleStartedAt);
+}
 function renderModuleLine(parameters) {
-  const { detail, extraGuideDepths = [], name, status, waitingFrame } = parameters;
+  const { detail, elapsed, extraGuideDepths = [], name, status, waitingFrame } = parameters;
   const baseIndent = getModuleIndent();
   const indent = buildGuideIndent(baseIndent, { extraGuideDepths });
   const icon = getModuleIcon(status, waitingFrame);
   const statusText = getModuleStatusText(status);
   const detailSuffix = detail == null ? "" : `  ${pc.dim(detail)}`;
+  const elapsedSuffix = elapsed == null ? "" : `  ${pc.dim(elapsed)}`;
   const alignedNameWidth = Math.max(MODULE_NAME_WIDTH - baseIndent.length, MIN_MODULE_NAME_WIDTH);
-  return `${indent}${icon}  ${name.padEnd(alignedNameWidth)}  ${statusText}${detailSuffix}`;
+  return `${indent}${icon}  ${name.padEnd(alignedNameWidth)}  ${statusText}${detailSuffix}${elapsedSuffix}`;
 }
 function hideCursor() {
   if (liveOutputState.cursorHidden) return;
@@ -1967,6 +1989,7 @@ function stopLiveModuleOutput(clearCurrentLine = false) {
   stopAnimatedModuleLine(clearCurrentLine);
 }
 function startModuleSpinner(name, detail) {
+  liveOutputState.activeModuleStartedAt = Date.now();
   if (!supportsAnimatedModuleOutput()) return;
   clearPendingRecipeClosureGuides();
   stopAnimatedModuleLine();
@@ -1987,6 +2010,7 @@ function startModuleSpinner(name, detail) {
       writeAnimatedModuleLine(
         renderModuleLine({
           detail: spinner.detail,
+          elapsed: getActiveModuleElapsed(),
           name: displayModule.name,
           status: "waiting",
           waitingFrame: SPINNER_FRAMES[spinner.frameIndex]
@@ -1999,6 +2023,7 @@ function startModuleSpinner(name, detail) {
   writeAnimatedModuleLine(
     renderModuleLine({
       detail: displayModule.detail,
+      elapsed: getActiveModuleElapsed(),
       name: displayModule.name,
       status: "waiting",
       waitingFrame: SPINNER_FRAMES[0]
@@ -2011,7 +2036,10 @@ function printRecipeHeader(name) {
   const header = pc.bold(pc.blue(`[${name}]`));
   console.log(`${buildGuideIndent(getRecipeHeaderIndent())}${header}`);
   if (liveOutputState.recipeOutputDepth >= 0) {
-    liveOutputState.activeRecipeGuideDepths = [...liveOutputState.activeRecipeGuideDepths, liveOutputState.recipeOutputDepth];
+    liveOutputState.activeRecipeGuideDepths = [
+      ...liveOutputState.activeRecipeGuideDepths,
+      liveOutputState.recipeOutputDepth
+    ];
   }
 }
 function printRunContext(parameters) {
@@ -2065,8 +2093,11 @@ function printRenderedModuleResult(parameters) {
     status: parameters.status,
     terminalColumns: process.stdout.columns
   });
+  const elapsed = getActiveModuleElapsed();
+  liveOutputState.activeModuleStartedAt = null;
   const line = renderModuleLine({
     detail: displayModule.detail,
+    elapsed,
     extraGuideDepths,
     name: displayModule.name,
     status: parameters.status
@@ -2193,7 +2224,9 @@ function printCauseChain(error) {
       if (visited.has(cause)) return;
       visited.add(cause);
     }
-    console.error(pc.red(`${getErrorIndent()}Cause: ${maskRegisteredSecrets(formatCauseValue(cause))}`));
+    console.error(
+      pc.red(`${getErrorIndent()}Cause: ${maskRegisteredSecrets(formatCauseValue(cause))}`)
+    );
     if (cause instanceof CommandError) {
       printVerboseCommandError(
         maskRegisteredSecrets(cause.fullStdout),
@@ -6229,7 +6262,7 @@ async function runApplyCommand(file, options, run = runPlaybook) {
   if (options.diff && !options.dryRun) {
     throw new CliUsageError("--diff requires --dry-run");
   }
-  printCliHeader("0.13.0-33ef8ce");
+  printCliHeader("0.15.0-645d2fd");
   const environmentOverrides = applyCliEnvironmentOverrides(options.env, {
     firstRun: options.firstRun
   });
@@ -6259,9 +6292,16 @@ function exitAfterApplyError(error, verbose) {
   const exitCode = process.exitCode === void 0 || process.exitCode === 0 ? 2 : process.exitCode;
   process.exit(exitCode);
 }
+function renderSubcommandOptionsHelp(command) {
+  const flagsWidth = Math.max(...command.options.map((option) => option.flags.length));
+  const rows = command.options.map(
+    (option) => `  ${option.flags.padEnd(flagsWidth)}  ${option.description}`
+  );
+  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.13.0-33ef8ce");
-program.command("apply <file>").description("Apply a server definition").option(
+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.",
   false
@@ -6269,7 +6309,12 @@ program.command("apply <file>").description("Apply a server definition").option(
   "--dry-run",
   "Only check, do not apply. Some modules validate prospective config but cannot verify runtime restarts.",
   false
-).option("--env <key=value...>", "Set env values", collectEnvironment, {}).option("--env-file <path>", "Load dotenv file").option(
+).option(
+  "--env <key=value...>",
+  "Set environment values passed to the playbook (repeatable; key=value).",
+  collectEnvironment,
+  {}
+).option("--env-file <path>", "Load environment values from a dotenv file.").option(
   "--filter <names>",
   "Run only the named recipes/modules (comma-separated, repeatable). Every other node is shown as skipped.",
   collectFilter,
@@ -6302,6 +6347,7 @@ program.command("apply <file>").description("Apply a server definition").option(
     exitAfterApplyError(error, options.verbose);
   }
 });
+program.addHelpText("after", () => renderSubcommandOptionsHelp(applyCommand));
 function parsePositiveNumber(value, options = {}) {
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed <= 0) {
@@ -6396,6 +6442,7 @@ export {
   parsePositiveNumber,
   parseReconnectTimeoutSeconds,
   printExceptionError,
+  renderSubcommandOptionsHelp,
   resetLastResortHandlerForTests,
   resetTsxRegistrationForTests,
   resolveFilteredRun,

package/dist/{index-DwKdTyHo.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.
      *
@@ -583,6 +612,7 @@ declare const command: {
      *   If it exits `0`, the command is considered already done.
      * @param options.name - An optional display name shown in the run output.
      * @param options.secrets - Secret values that must be redacted from command output.
+     * @param options.timeout - Maximum runtime for the command in milliseconds.
      * @returns A Module that executes the shell command.
      *
      * @example
@@ -595,6 +625,7 @@ declare const command: {
         check?: string;
         name?: string;
         secrets?: string[];
+        timeout?: number;
     }): Module;
 };
 
@@ -2106,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-DwKdTyHo.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-DwKdTyHo.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-XIRORNO3.js";
+} from "./chunk-GB5QZWUM.js";
 
 // src/conditionalModules.ts
 function createConditionalApplyState(environment) {
@@ -536,6 +536,10 @@ var DEFAULT_TERMINAL_COLUMNS = 100;
 var MIN_PACKAGE_COLUMNS_WIDTH = 24;
 var MIN_PACKAGE_COLUMN_WIDTH = 18;
 var MIN_ANIMATED_LINE_COLUMNS = 8;
+var ELAPSED_DISPLAY_THRESHOLD_MS = 1e3;
+var MILLISECONDS_PER_SECOND = 1e3;
+var MILLISECONDS_PER_MINUTE = 6e4;
+var SECONDS_PER_MINUTE = 60;
 function splitPackageModuleName(name) {
   for (const prefix of ["package.installed: ", "package.absent: "]) {
     if (!name.startsWith(prefix)) continue;
@@ -573,6 +577,16 @@ function getPackageSummaryDetail(packageCount, detail) {
   const packageLabel = packageCount === 1 ? "1 package" : `${packageCount} packages`;
   return detail == null ? packageLabel : `${packageLabel} \xB7 ${detail}`;
 }
+function formatModuleElapsed(elapsedMs) {
+  if (!Number.isFinite(elapsedMs) || elapsedMs < ELAPSED_DISPLAY_THRESHOLD_MS) return void 0;
+  if (elapsedMs < MILLISECONDS_PER_MINUTE) {
+    return `${(elapsedMs / MILLISECONDS_PER_SECOND).toFixed(1)}s`;
+  }
+  const totalSeconds = Math.floor(elapsedMs / MILLISECONDS_PER_SECOND);
+  const minutes = Math.floor(totalSeconds / SECONDS_PER_MINUTE);
+  const seconds = totalSeconds % SECONDS_PER_MINUTE;
+  return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+}
 function fitAnimatedModuleLine(line, columns) {
   if (columns === void 0 || columns < MIN_ANIMATED_LINE_COLUMNS) return line;
   const plainLine = stripVTControlCharacters(line);
@@ -624,6 +638,7 @@ function getSharedLiveOutputState() {
   const existing = registry[LIVE_OUTPUT_STATE_KEY];
   if (existing != null) return existing;
   const created = {
+    activeModuleStartedAt: null,
     activeRecipeGuideDepths: [],
     activeSpinner: null,
     cursorHidden: false,
@@ -666,7 +681,7 @@ function getGuideDot(depth) {
   return depth % 2 === 0 ? pc.gray("\xB7") : pc.cyan("\xB7");
 }
 function buildGuideIndent(baseIndent, options) {
-  const indentCharacters = Array.from(baseIndent);
+  const indentCharacters = [...baseIndent];
   const guideDepths = [
     ...options?.activeGuideDepths ?? liveOutputState.activeRecipeGuideDepths,
     ...options?.extraGuideDepths ?? []
@@ -702,20 +717,27 @@ async function withRecipeOutputScope(scopedOperation) {
   try {
     return await scopedOperation();
   } finally {
-    liveOutputState.activeRecipeGuideDepths = liveOutputState.activeRecipeGuideDepths.filter((depth) => depth !== liveOutputState.recipeOutputDepth);
+    liveOutputState.activeRecipeGuideDepths = liveOutputState.activeRecipeGuideDepths.filter(
+      (depth) => depth !== liveOutputState.recipeOutputDepth
+    );
     liveOutputState.pendingRecipeClosureGuideDepths = [liveOutputState.recipeOutputDepth];
     liveOutputState.recipeOutputDepth -= 1;
   }
 }
+function getActiveModuleElapsed() {
+  if (liveOutputState.activeModuleStartedAt == null) return void 0;
+  return formatModuleElapsed(Date.now() - liveOutputState.activeModuleStartedAt);
+}
 function renderModuleLine(parameters) {
-  const { detail, extraGuideDepths = [], name, status, waitingFrame } = parameters;
+  const { detail, elapsed, extraGuideDepths = [], name, status, waitingFrame } = parameters;
   const baseIndent = getModuleIndent();
   const indent = buildGuideIndent(baseIndent, { extraGuideDepths });
   const icon = getModuleIcon(status, waitingFrame);
   const statusText = getModuleStatusText(status);
   const detailSuffix = detail == null ? "" : `  ${pc.dim(detail)}`;
+  const elapsedSuffix = elapsed == null ? "" : `  ${pc.dim(elapsed)}`;
   const alignedNameWidth = Math.max(MODULE_NAME_WIDTH - baseIndent.length, MIN_MODULE_NAME_WIDTH);
-  return `${indent}${icon}  ${name.padEnd(alignedNameWidth)}  ${statusText}${detailSuffix}`;
+  return `${indent}${icon}  ${name.padEnd(alignedNameWidth)}  ${statusText}${detailSuffix}${elapsedSuffix}`;
 }
 function hideCursor() {
   if (liveOutputState.cursorHidden) return;
@@ -745,6 +767,7 @@ function stopAnimatedModuleLine(clearCurrentLine = false) {
   }
 }
 function startModuleSpinner(name, detail) {
+  liveOutputState.activeModuleStartedAt = Date.now();
   if (!supportsAnimatedModuleOutput()) return;
   clearPendingRecipeClosureGuides();
   stopAnimatedModuleLine();
@@ -765,6 +788,7 @@ function startModuleSpinner(name, detail) {
       writeAnimatedModuleLine(
         renderModuleLine({
           detail: spinner.detail,
+          elapsed: getActiveModuleElapsed(),
           name: displayModule.name,
           status: "waiting",
           waitingFrame: SPINNER_FRAMES[spinner.frameIndex]
@@ -777,6 +801,7 @@ function startModuleSpinner(name, detail) {
   writeAnimatedModuleLine(
     renderModuleLine({
       detail: displayModule.detail,
+      elapsed: getActiveModuleElapsed(),
       name: displayModule.name,
       status: "waiting",
       waitingFrame: SPINNER_FRAMES[0]
@@ -789,7 +814,10 @@ function printRecipeHeader(name) {
   const header = pc.bold(pc.blue(`[${name}]`));
   console.log(`${buildGuideIndent(getRecipeHeaderIndent())}${header}`);
   if (liveOutputState.recipeOutputDepth >= 0) {
-    liveOutputState.activeRecipeGuideDepths = [...liveOutputState.activeRecipeGuideDepths, liveOutputState.recipeOutputDepth];
+    liveOutputState.activeRecipeGuideDepths = [
+      ...liveOutputState.activeRecipeGuideDepths,
+      liveOutputState.recipeOutputDepth
+    ];
   }
 }
 function colorizeDiffLine(line) {
@@ -836,8 +864,11 @@ function printRenderedModuleResult(parameters) {
     status: parameters.status,
     terminalColumns: process.stdout.columns
   });
+  const elapsed = getActiveModuleElapsed();
+  liveOutputState.activeModuleStartedAt = null;
   const line = renderModuleLine({
     detail: displayModule.detail,
+    elapsed,
     extraGuideDepths,
     name: displayModule.name,
     status: parameters.status
@@ -964,7 +995,9 @@ function printCauseChain(error) {
       if (visited.has(cause)) return;
       visited.add(cause);
     }
-    console.error(pc.red(`${getErrorIndent()}Cause: ${maskRegisteredSecrets(formatCauseValue(cause))}`));
+    console.error(
+      pc.red(`${getErrorIndent()}Cause: ${maskRegisteredSecrets(formatCauseValue(cause))}`)
+    );
     if (cause instanceof CommandError) {
       printVerboseCommandError(
         maskRegisteredSecrets(cause.fullStdout),

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-DwKdTyHo.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-XIRORNO3.js";
+} from "../chunk-GB5QZWUM.js";
 export {
   apt,
   archive,

package/llm-guide.md

@@ -1,11 +1,18 @@
-# Paratix -- LLM Code Guide
+# Paratix TypeScript API and Module Reference
 
-> This file helps LLMs write correct Paratix code. Read this before generating playbooks or modules.
+This is the complete reference for writing Paratix playbooks and custom modules. It covers the
+TypeScript API, built-in modules, authoring patterns, and common mistakes.
 
 ## Overview
 
 Paratix is a CLI tool for idempotent VPS configuration via SSH using TypeScript playbooks. Each playbook exports a `server()` definition containing an ordered list of modules that are checked and applied over SSH. Modules follow a check/apply pattern: `check` determines if work is needed, `apply` enforces the desired state.
 
+## Agent authoring guidance
+
+When generating or changing Paratix playbooks or custom modules, automated coding agents should use
+this document as the complete API reference. Read the relevant API and module sections before making
+changes, and follow the [Do's and Don'ts](#dos-and-donts) and [testing patterns](#testing-patterns).
+
 ## Imports
 
 Paratix has exactly two import paths:
@@ -150,9 +157,12 @@ export default server({
 
 ### `command`
 
-| Method          | Signature                                                                                | Idempotent        |
-| --------------- | ---------------------------------------------------------------------------------------- | ----------------- |
-| `command.shell` | `(cmd: string, options?: { check?: string; name?: string; secrets?: string[] }): Module` | Only with `check` |
+| Method          | Signature                                                                                                  | Idempotent        |
+| --------------- | ---------------------------------------------------------------------------------------------------------- | ----------------- |
+| `command.shell` | `(cmd: string, options?: { check?: string; name?: string; secrets?: string[]; timeout?: number }): Module` | Only with `check` |
+
+`command.shell` accepts `timeout` in milliseconds to limit the runtime of the applied command. The
+idempotency guard configured through `check` is not affected by this timeout.
 
 ### `cron`
 
@@ -212,9 +222,9 @@ very slow artifact hosts or large downloads.
 | `file.stat`       | `(remotePath: string): Module`                                                                                      | No (always-applies) |
 | `file.template`   | `(remotePath: string, templatePath: string, options?: { mode?: string; owner?: string; strict?: boolean }): Module` | Yes                 |
 
-**Hinweis zu `file.copy` und Default-Mode:** Wenn `options.mode` weggelassen wird, setzt `file.copy` den Modus auf den dokumentierten Default `0644`. Der Modus wird sowohl beim Hochladen (`uploadFile` mit `{ mode }`) als auch in `check` gegen den Soll-Wert verglichen, damit nachfolgende Läufe Mode-Drift (z. B. manuelles `chmod 0600`) als `needs-apply` erkennen. Wer ein restriktiveres Recht braucht (z. B. für Secrets), übergibt explizit `{ mode: "0600" }`.
+**Note on `file.copy` and the default mode:** When `options.mode` is omitted, `file.copy` sets the mode to the documented default of `0644`. The mode is applied during upload (`uploadFile` with `{ mode }`) and compared with the desired value in `check`, so subsequent runs detect mode drift (for example, a manual `chmod 0600`) as `needs-apply`. Pass `{ mode: "0600" }` explicitly when more restrictive permissions are required, such as for secrets.
 
-**Hinweis zu `file.line`:** Der `line`-Wert muss eine einzelne Zeile ohne CR/LF sein. Für mehrzeilige Inhalte `file.block` verwenden.
+**Note on `file.line`:** The `line` value must be a single line without CR/LF characters. Use `file.block` for multiline content.
 
 ### `git`
 
@@ -267,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`
 
@@ -283,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 })
@@ -294,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 |
@@ -342,7 +403,7 @@ rsync SSH process and does not depend on a local `known_hosts` entry.
 | `ssh.authorizedKeys` | `(user: string, key: string, options?: { state?: "absent" \| "present" }): Module`                                                     | Yes        |
 | `ssh.knownHosts`     | `(host: string, options?: { expectedFingerprint?: string; port?: number; publicKey?: string; state?: "absent" \| "present" }): Module` | Yes        |
 
-**Trust-Anchor-Pflicht für `ssh.knownHosts` (state `present`):** Im Default-State `present` muss entweder `expectedFingerprint` oder `publicKey` gesetzt sein. Ohne Trust Anchor wirft der Modul-Konstruktor sofort, denn `check` würde sonst jeden vorhandenen `known_hosts`-Eintrag (auch ältere, möglicherweise kompromittierte TOFU-Akzeptanzen) als „ok" werten und den Anchor-Vergleich überspringen. Für `state: "absent"` ist kein Anchor nötig — dort wird der Eintrag ohnehin entfernt.
+**Trust anchor requirement for `ssh.knownHosts` (`state: "present"`):** In the default `present` state, either `expectedFingerprint` or `publicKey` must be set. Without a trust anchor, the module constructor throws immediately because `check` would otherwise treat any existing `known_hosts` entry, including older and potentially compromised TOFU acceptances, as `ok` and skip the anchor comparison. No anchor is required for `state: "absent"`, because that state removes the entry.
 
 ### `sshd`
 
@@ -666,7 +727,7 @@ fail("This branch should be unreachable")
 
 ### `firstRun.stop(message?)`
 
-Stoppt den aktuellen Lauf kontrolliert, wenn Paratix mit `--first-run` gestartet wurde. Nützlich als explizite Staging-Grenze in Bootstrap-Playbooks.
+Stops the current run cleanly when Paratix was started with `--first-run`. Useful as an explicit staging boundary in bootstrap playbooks.
 
 ```typescript
 firstRun.stop("Bootstrap foundation complete; rerun without --first-run to continue.")
@@ -674,7 +735,7 @@ firstRun.stop("Bootstrap foundation complete; rerun without --first-run to conti
 
 ### `signals.flush(message?)`
 
-Führt alle aktuell offenen Signale des aktiven Scopes sofort aus und setzt deren Pending-Zustand zurück.
+Immediately runs all currently pending signals in the active scope and clears their pending state.
 
 ```typescript
 signals.flush("Reload services before the next bootstrap stage")
@@ -742,20 +803,20 @@ Rules:
 
 Diff-producing built-in modules:
 
-| Modul                                       | Diff-Inhalt                                                                                                                                                                             |
-| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `file.copy`                                 | Unified diff zwischen Remote-Datei und lokaler Quelle.                                                                                                                                  |
-| `file.template`                             | Unified diff zwischen Remote-Datei und gerendertem Template.                                                                                                                            |
-| `sysctl.set`                                | `key = old → new` für die Soll-Konfiguration.                                                                                                                                           |
-| `hostname.set`                              | `hostname = old → new`.                                                                                                                                                                 |
-| `swap.file`                                 | Diff des `/etc/fstab`-Eintrags (oder Entfernung der Zeile bei `state: "absent"`).                                                                                                       |
-| `swap.swappiness`                           | `vm.swappiness = old → new` (via `sysctl.set`).                                                                                                                                         |
-| `swap.vfsCachePressure`                     | `vm.vfs_cache_pressure = old → new` (via `sysctl.set`).                                                                                                                                 |
-| `cron.job` / `cron.absent`                  | Unified diff der Crontab des Ziel-Users.                                                                                                                                                |
-| `timer.scheduled` (present)                 | Konkatenierte Diffs der `.service`- und `.timer`-Unit-Dateien.                                                                                                                          |
-| `timer.scheduled` (absent) / `timer.absent` | Liste der zu entfernenden Unit-Dateien.                                                                                                                                                 |
-| `net.hosts`                                 | Unified diff von `/etc/hosts`.                                                                                                                                                          |
-| `quadlet.container`                         | Unified diff der `.container`-Unit-Datei. Wenn die Datei bereits passt, das `daemon-reload`-Flag aber fehlt, erscheint zusätzlich `(dry-run, daemon-reload pending)` als Detail-Suffix. |
+| Module                                      | Diff content                                                                                                                                                                         |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `file.copy`                                 | Unified diff between the remote file and the local source.                                                                                                                           |
+| `file.template`                             | Unified diff between the remote file and the rendered template.                                                                                                                      |
+| `sysctl.set`                                | `key = old → new` for the desired configuration.                                                                                                                                     |
+| `hostname.set`                              | `hostname = old → new`.                                                                                                                                                              |
+| `swap.file`                                 | Diff of the `/etc/fstab` entry (or removal of the line for `state: "absent"`).                                                                                                       |
+| `swap.swappiness`                           | `vm.swappiness = old → new` (via `sysctl.set`).                                                                                                                                      |
+| `swap.vfsCachePressure`                     | `vm.vfs_cache_pressure = old → new` (via `sysctl.set`).                                                                                                                              |
+| `cron.job` / `cron.absent`                  | Unified diff of the target user's crontab.                                                                                                                                           |
+| `timer.scheduled` (present)                 | Concatenated diffs of the `.service` and `.timer` unit files.                                                                                                                        |
+| `timer.scheduled` (absent) / `timer.absent` | List of unit files to remove.                                                                                                                                                        |
+| `net.hosts`                                 | Unified diff of `/etc/hosts`.                                                                                                                                                        |
+| `quadlet.container`                         | Unified diff of the `.container` unit file. If the file already matches but the `daemon-reload` flag is missing, `(dry-run, daemon-reload pending)` also appears as a detail suffix. |
 
 ### Implementing a Diff for a Custom Module
 
@@ -810,7 +871,7 @@ The diff string is plain text — no ANSI codes. The output layer applies colors
 4. For idempotency with `command.shell()`, always provide a `check` command.
 5. Use `{{KEY|shell}}` or `{{KEY|raw}}` placeholders in `.tmpl` files — strict mode is on by default and bare `{{KEY}}` will throw. Provide values via `env` in `server()`.
 6. Use `service.restart()` and `service.reload()` as `signals` in recipes, not directly in `run`.
-7. Use `signals.flush()` only als expliziten Checkpoint, wenn gestufte Flows einen vorgezogenen Signal-Flush brauchen.
+7. Use `signals.flush()` only as an explicit checkpoint when staged flows require an early signal flush.
 8. Always pass a date string to `package.upgrade()` and `package.update()` -- it is the idempotency key.
 9. Specify `ssh.ports` as an array -- the runner tries each port in order.
 10. Custom modules must implement both `check` and `apply`, both async.
@@ -831,9 +892,9 @@ The diff string is plain text — no ANSI codes. The output layer applies colors
 9. Do NOT use template syntax `{{key}}` in TypeScript code -- templates are only for files rendered via `file.template()`.
 10. Do NOT use `signals` on the top-level `server()` when you mean a recipe signal -- `server.signals` fire when ANY module in `run` changed.
 11. Do NOT treat `signals.flush()` as a global queue flush -- it only affects the current scope.
-12. `signals.flush()` flusht immer nur den aktuellen Scope:
-    - in einer Recipe deren Recipe-Signale
-    - auf Top-Level `server(...).signals`
+12. `signals.flush()` always flushes only the current scope:
+    - inside a recipe, that recipe's signals
+    - at the top level, `server(...).signals`
 13. Do NOT call `server()` without all required fields (`name`, `host`, `ssh`, `run`) -- it throws at construction time. `name` and `host` must not be empty strings.
 14. Do NOT use empty arrays for `ssh.ports` or empty strings for `ssh.user`/`ssh.privateKey` -- validation rejects these. `ssh.privateKey` may be omitted entirely to use the SSH agent instead.
 15. Do NOT return loose `meta: { ... }` maps from custom modules -- always use typed meta entries.

package/package.json

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