paratix 0.7.0 → 0.9.0

package/README.md

@@ -104,7 +104,7 @@ Signals are deferred side effects such as `service.reload(...)` or `service.rest
 
 For Podman-native services, Paratix now also includes `quadlet.container(...)`. It writes a `.container` file under `/etc/containers/systemd`, reloads systemd when the content changes, and works cleanly with `service.enabled(...)` and `service.running(...)` for the generated service.
 
-When you need a targeted image refresh outside the normal deploy flow, `quadlet.updateImage(...)` pulls exactly one image, reuses existing Podman registry auth on the host, optionally supports `authFile`, and only restarts the generated service when the pull actually downloaded a newer image. Changed runs now also print the new image ID in parentheses in the CLI output.
+When you need a targeted image refresh outside the normal deploy flow, `quadlet.updateImage(...)` pulls exactly one image, reuses existing Podman registry auth on the host, optionally supports `authFile`, and only restarts the generated service when the pull actually downloaded a newer image. Changed runs now also print the new registry digest in parentheses in the CLI output, with a local image ID fallback when no repo digest is available.
 
 ### Guards
 

package/dist/{chunk-IUY5BJHA.js → chunk-47PTUZZR.js}

@@ -2,7 +2,7 @@ import {
   CommandError,
   assertValidModuleMetaEntries,
   mergeEnvironmentFromMeta
-} from "./chunk-JJRF37BP.js";
+} from "./chunk-NRDLYHJL.js";
 
 // src/output.ts
 import pc from "picocolors";
@@ -492,4 +492,4 @@ export {
   printSummary,
   runSignalModules
 };
-//# sourceMappingURL=chunk-IUY5BJHA.js.map
+//# sourceMappingURL=chunk-47PTUZZR.js.map

package/dist/{chunk-D4CS2GCH.js → chunk-7Y2RBVG4.js}

@@ -9,7 +9,7 @@ import {
   shellQuote,
   sshdPortMeta,
   validateMode
-} from "./chunk-JJRF37BP.js";
+} from "./chunk-NRDLYHJL.js";
 
 // src/moduleFailure.ts
 function firstNonEmptyLine(text) {
@@ -173,6 +173,11 @@ async function setFlag(ssh2, flagName) {
 // src/modules/apt.ts
 var NONINTERACTIVE = "DEBIAN_FRONTEND=noninteractive";
 var APT_REPOSITORY_MODE = "0644";
+var APT_BASE_EXEC_OPTS = { ignoreExitCode: true, silent: true };
+function aptExecOptions(options) {
+  if (options?.timeout === void 0) return APT_BASE_EXEC_OPTS;
+  return { ...APT_BASE_EXEC_OPTS, timeout: options.timeout };
+}
 var PPA_PREFIX = "ppa:";
 function parseDebconfOutput(stdout) {
   const values = {};
@@ -292,30 +297,31 @@ var apt = {
    * Run `apt-get update && apt-get dist-upgrade` once per dated flag.
    * Performs a full distribution upgrade with dependency resolution.
    *
+   * The pipeline is split into three separate SSH commands so that each step
+   * gets its own timeout window and produces a precise failure label.
+   *
    * @param date - A date string used as the idempotency key (e.g. `"2024-01-15"`).
+   * @param options - Optional per-call overrides (e.g. SSH command `timeout`).
+   *   The same `timeout` is applied to every step of the dist-upgrade pipeline.
    * @returns A Module that performs the dist-upgrade.
+   *
+   * @example
+   * apt.distUpgrade("2024-01-15")
+   * apt.distUpgrade("2024-01-15", { timeout: 900_000 })
    */
-  distUpgrade(date) {
+  distUpgrade(date, options) {
     const flagName = `apt-dist-upgrade-${date}`;
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[apt.distUpgrade] SSH connection is required for ${date}`);
-        const update = await ssh2.exec(`${NONINTERACTIVE} apt-get update`, {
-          ignoreExitCode: true,
-          silent: true
-        });
+        const pipelineOptions = aptExecOptions(options);
+        const update = await ssh2.exec(`${NONINTERACTIVE} apt-get update`, pipelineOptions);
         if (update.code !== 0)
           return failedCommand("[apt.distUpgrade] apt-get update failed", update);
-        const configure = await ssh2.exec(`${NONINTERACTIVE} dpkg --configure -a`, {
-          ignoreExitCode: true,
-          silent: true
-        });
+        const configure = await ssh2.exec(`${NONINTERACTIVE} dpkg --configure -a`, pipelineOptions);
         if (configure.code !== 0)
           return failedCommand("[apt.distUpgrade] dpkg --configure -a failed", configure);
-        const upgrade = await ssh2.exec(`${NONINTERACTIVE} apt-get dist-upgrade -y`, {
-          ignoreExitCode: true,
-          silent: true
-        });
+        const upgrade = await ssh2.exec(`${NONINTERACTIVE} apt-get dist-upgrade -y`, pipelineOptions);
         if (upgrade.code !== 0)
           return failedCommand("[apt.distUpgrade] apt-get dist-upgrade failed", upgrade);
         await setVersionedFlag(ssh2, flagName, "apt-dist-upgrade-");
@@ -3137,6 +3143,22 @@ var op = {
 
 // src/modules/package.ts
 var EXEC_OPTS6 = { ignoreExitCode: true, silent: true };
+function execOptions(options) {
+  if (options?.timeout === void 0) return EXEC_OPTS6;
+  return { ...EXEC_OPTS6, timeout: options.timeout };
+}
+function splitPackagesAndOptions(values) {
+  const packages = [];
+  let options;
+  for (const [index, value] of values.entries()) {
+    if (typeof value === "string") {
+      packages.push(value);
+    } else if (index === values.length - 1) {
+      options = value;
+    }
+  }
+  return { options, packages };
+}
 var pmCache = /* @__PURE__ */ new WeakMap();
 var INSTALL_COMMANDS = {
   apk: (pkgs) => `apk add ${pkgs}`,
@@ -3157,10 +3179,14 @@ var UPDATE_COMMANDS = {
   yum: "yum makecache"
 };
 var UPGRADE_COMMANDS = {
-  apk: "apk update && apk upgrade",
-  apt: "DEBIAN_FRONTEND=noninteractive dpkg --configure -a && DEBIAN_FRONTEND=noninteractive apt-get update && DEBIAN_FRONTEND=noninteractive apt-get upgrade -y",
-  dnf: "dnf upgrade -y",
-  yum: "yum update -y"
+  apk: ["apk update", "apk upgrade"],
+  apt: [
+    "DEBIAN_FRONTEND=noninteractive dpkg --configure -a",
+    "DEBIAN_FRONTEND=noninteractive apt-get update",
+    "DEBIAN_FRONTEND=noninteractive apt-get upgrade -y"
+  ],
+  dnf: ["dnf upgrade -y"],
+  yum: ["yum update -y"]
 };
 function missingPackageManager(moduleName) {
   return failed(`[${moduleName}] No supported package manager found (apt, dnf, yum, apk)`);
@@ -3200,13 +3226,19 @@ var pkg = {
    * The check phase queries the package database for each package individually;
    * the remove command is only executed when at least one package is present.
    *
-   * @param packages - One or more package names to remove.
+   * 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.
    * @returns A Module that removes the packages if any are present.
    *
    * @example
    * pkg.absent("vim", "nano")
+   * pkg.absent("vim", "nano", { timeout: 600_000 })
    */
-  absent(...packages) {
+  absent(...packagesAndOptions) {
+    const { options, packages } = splitPackagesAndOptions(packagesAndOptions);
     if (packages.length === 0) {
       throw new Error("package.absent: at least one package name is required");
     }
@@ -3217,7 +3249,7 @@ var pkg = {
         const pm = await detectPackageManager(ssh2);
         if (!pm) return missingPackageManager(`package.absent: ${packages.join(", ")}`);
         const quoted = packages.map((p) => shellQuote(p)).join(" ");
-        const result = await ssh2.exec(REMOVE_COMMANDS[pm](quoted), EXEC_OPTS6);
+        const result = await ssh2.exec(REMOVE_COMMANDS[pm](quoted), execOptions(options));
         if (result.code !== 0) {
           return failedCommand(
             `[package.absent: ${packages.join(", ")}] package removal failed`,
@@ -3244,13 +3276,19 @@ var pkg = {
    * The check phase queries the package database for each package individually;
    * the install command is only executed when at least one package is missing.
    *
-   * @param packages - One or more package names to install.
+   * 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.
    * @returns A Module that installs missing packages.
    *
    * @example
    * pkg.installed("git", "curl", "unzip")
+   * pkg.installed("texlive-full", { timeout: 900_000 })
    */
-  installed(...packages) {
+  installed(...packagesAndOptions) {
+    const { options, packages } = splitPackagesAndOptions(packagesAndOptions);
     if (packages.length === 0) {
       throw new Error("package.installed: at least one package name is required");
     }
@@ -3262,7 +3300,7 @@ var pkg = {
         const pm = await detectPackageManager(ssh2);
         if (!pm) return missingPackageManager(`package.installed: ${packages.join(", ")}`);
         const quoted = packages.map((p) => shellQuote(p)).join(" ");
-        const result = await ssh2.exec(INSTALL_COMMANDS[pm](quoted), EXEC_OPTS6);
+        const result = await ssh2.exec(INSTALL_COMMANDS[pm](quoted), execOptions(options));
         if (result.code !== 0) {
           return failedCommand(
             `[package.installed: ${packages.join(", ")}] package installation failed`,
@@ -3292,19 +3330,21 @@ var pkg = {
    * value invalidates all previous flags for this operation.
    *
    * @param date - A date string used as the idempotency key (e.g. `"2024-01-15"`).
+   * @param options - Optional per-call overrides (e.g. SSH command `timeout`).
    * @returns A Module that refreshes package lists.
    *
    * @example
    * pkg.update("2024-01-15")
+   * pkg.update("2024-01-15", { timeout: 600_000 })
    */
-  update(date) {
+  update(date, options) {
     const flagName = `package-update-${date}`;
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[package.update: ${date}] SSH connection is required`);
         const pm = await detectPackageManager(ssh2);
         if (!pm) return missingPackageManager(`package.update: ${date}`);
-        const result = await ssh2.exec(UPDATE_COMMANDS[pm], EXEC_OPTS6);
+        const result = await ssh2.exec(UPDATE_COMMANDS[pm], execOptions(options));
         if (result.code !== 0) {
           return failedCommand(`[package.update: ${date}] package index refresh failed`, result);
         }
@@ -3326,27 +3366,34 @@ var pkg = {
    * reports `"ok"` without running the upgrade again. Changing `date` to a new
    * value invalidates all previous flags for this operation.
    *
-   * On apt systems this runs `apt-get update && apt-get upgrade -y` (not
-   * `dist-upgrade`); use `apt.distUpgrade` for full dependency resolution.
+   * On apt systems this runs `dpkg --configure -a`, `apt-get update`, and
+   * `apt-get upgrade -y` as three separate commands (each subject to its own
+   * SSH `timeout`). For full dependency resolution use `apt.distUpgrade`.
    *
    * @param date - A date string used as the idempotency key (e.g. `"2024-01-15"`).
+   * @param options - Optional per-call overrides (e.g. SSH command `timeout`).
+   *   The same `timeout` is applied to every step of the upgrade pipeline.
    * @returns A Module that upgrades all packages.
    *
    * @example
    * pkg.upgrade("2024-01-15")
+   * pkg.upgrade("2024-01-15", { timeout: 900_000 })
    *
    * @see apt.distUpgrade
    */
-  upgrade(date) {
+  upgrade(date, options) {
     const flagName = `package-upgrade-${date}`;
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[package.upgrade: ${date}] SSH connection is required`);
         const pm = await detectPackageManager(ssh2);
         if (!pm) return missingPackageManager(`package.upgrade: ${date}`);
-        const result = await ssh2.exec(UPGRADE_COMMANDS[pm], EXEC_OPTS6);
-        if (result.code !== 0) {
-          return failedCommand(`[package.upgrade: ${date}] package upgrade failed`, result);
+        const pipelineOptions = execOptions(options);
+        for (const command2 of UPGRADE_COMMANDS[pm]) {
+          const result = await ssh2.exec(command2, pipelineOptions);
+          if (result.code !== 0) {
+            return failedCommand(`[package.upgrade: ${date}] package upgrade failed`, result);
+          }
         }
         await setVersionedFlag(ssh2, flagName, "package-upgrade-");
         return { status: "changed" };
@@ -3522,12 +3569,6 @@ function buildQuadletImagePullCommand(options) {
   const authFileFlag = options.authFile == null ? "" : ` --authfile ${shellQuoteForQuadlet(options.authFile)}`;
   return `podman pull${authFileFlag} ${shellQuoteForQuadlet(options.image)} 2>&1`;
 }
-function buildQuadletImageInspectCommand(image) {
-  return `podman image inspect --format '{{.Id}}' ${shellQuoteForQuadlet(image)}`;
-}
-function formatQuadletImageIdDetail(imageId) {
-  return `(${imageId})`;
-}
 function getQuadletContainerFilePath(name) {
   return `${CONTAINERS_SYSTEMD_DIRECTORY}/${name}.container`;
 }
@@ -3537,13 +3578,6 @@ function getQuadletContainerServiceName(options) {
 function quadletPullOutputIndicatesChange(output) {
   return QUADLET_PULL_CHANGED_OUTPUT_PATTERNS.some((pattern) => output.includes(pattern));
 }
-function readQuadletImageIdFromInspectOutput(output) {
-  for (const line of output.split("\n")) {
-    const trimmed = line.trim();
-    if (trimmed.length > 0) return trimmed;
-  }
-  return null;
-}
 var UNIT_NAME_PATTERN2 = new RegExp("^[\\w@.\\-]+$", "v");
 function validateQuadletName(name) {
   if (!UNIT_NAME_PATTERN2.test(name)) {
@@ -3555,6 +3589,62 @@ function shellQuoteForQuadlet(value) {
   return `'${value.replaceAll("'", escapedQuote)}'`;
 }
 
+// src/modules/quadletImageInspectHelpers.ts
+function shellQuoteForQuadletImageInspect(value) {
+  const escapedQuote = "'\\''";
+  return `'${value.replaceAll("'", escapedQuote)}'`;
+}
+function buildQuadletImageInspectCommand(image) {
+  return `podman image inspect ${shellQuoteForQuadletImageInspect(image)}`;
+}
+function formatQuadletImageIdentifierDetail(imageIdentifier) {
+  return `(${imageIdentifier})`;
+}
+function readQuadletImageIdentifierFromInspectOutput(image, output) {
+  const parsed = parseQuadletImageInspectOutput(output);
+  if (parsed == null) return null;
+  const repoDigest = findQuadletRepoDigest(image, parsed.repoDigests);
+  return repoDigest ?? parsed.id;
+}
+function findQuadletRepoDigest(image, repoDigests) {
+  const repository = getQuadletImageRepository(image);
+  for (const repoDigest of repoDigests) {
+    const separatorIndex = repoDigest.indexOf("@");
+    if (separatorIndex === -1) continue;
+    const repo = repoDigest.slice(0, separatorIndex);
+    const digest = repoDigest.slice(separatorIndex + 1);
+    if (repo === repository && digest.length > 0) return digest;
+  }
+  return null;
+}
+function getQuadletImageRepository(image) {
+  const digestSeparatorIndex = image.indexOf("@");
+  if (digestSeparatorIndex !== -1) return image.slice(0, digestSeparatorIndex);
+  const lastSlashIndex = image.lastIndexOf("/");
+  const lastColonIndex = image.lastIndexOf(":");
+  return lastColonIndex > lastSlashIndex ? image.slice(0, lastColonIndex) : image;
+}
+function parseQuadletImageInspectOutput(output) {
+  try {
+    const parsed = JSON.parse(output);
+    if (!Array.isArray(parsed) || parsed.length === 0) return null;
+    const [firstEntry] = parsed;
+    if (!isQuadletInspectEntry(firstEntry)) return null;
+    const repoDigests = Array.isArray(firstEntry.RepoDigests) ? firstEntry.RepoDigests : [];
+    return {
+      id: typeof firstEntry.Id === "string" && firstEntry.Id.length > 0 ? firstEntry.Id : null,
+      repoDigests: repoDigests.filter(
+        (entry) => typeof entry === "string" && entry.length > 0
+      )
+    };
+  } catch {
+    return null;
+  }
+}
+function isQuadletInspectEntry(value) {
+  return value != null && typeof value === "object";
+}
+
 // src/modules/quadlet.ts
 var CONTAINERS_SYSTEMD_DIRECTORY_COMMAND = "mkdir -p '/etc/containers/systemd'";
 var QUADLET_FILE_MODE = "0644";
@@ -3612,10 +3702,13 @@ async function inspectQuadletImageId(parameters) {
       inspectResult
     );
   }
-  const imageId = readQuadletImageIdFromInspectOutput(inspectResult.stdout);
+  const imageId = readQuadletImageIdentifierFromInspectOutput(
+    parameters.image,
+    inspectResult.stdout
+  );
   if (imageId == null) {
     return failed(
-      `[quadlet.updateImage: ${parameters.name}] podman image inspect returned no image ID`
+      `[quadlet.updateImage: ${parameters.name}] podman image inspect returned no digest or image ID`
     );
   }
   return imageId;
@@ -3628,7 +3721,7 @@ async function restartQuadletService(parameters) {
       silent: true
     }
   );
-  return restartResult.code === 0 ? { detail: formatQuadletImageIdDetail(parameters.imageId), status: "changed" } : failedCommand(
+  return restartResult.code === 0 ? { detail: formatQuadletImageIdentifierDetail(parameters.imageId), status: "changed" } : failedCommand(
     `[quadlet.updateImage: ${parameters.name}] systemctl restart failed`,
     restartResult
   );
@@ -3699,6 +3792,7 @@ var quadlet = {
       async apply(ssh2) {
         if (!ssh2) return failed(`[quadlet.updateImage: ${options.name}] SSH connection is required`);
         return applyQuadletImageUpdate({
+          image: options.image,
           inspectCommand,
           name: options.name,
           pullCommand,
@@ -5794,4 +5888,4 @@ export {
   ufw,
   user
 };
-//# sourceMappingURL=chunk-D4CS2GCH.js.map
+//# sourceMappingURL=chunk-7Y2RBVG4.js.map