paratix 0.5.0 → 0.7.0

package/README.md

@@ -104,6 +104,8 @@ 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.
+
 ### Guards
 
 Paratix also supports declarative host-state guards. Use `when.packageInstalled(...)`, `when.commandExists(...)`, `when.fileExists(...)`, `when.pathExists(...)`, `when.symlinkExists(...)`, or `when.socketExists(...)` and their inverted forms to gate modules or recipes on remote host state without shell-heavy playbooks.

package/dist/{chunk-LI47NIKN.js → chunk-D4CS2GCH.js}

@@ -9,7 +9,7 @@ import {
   shellQuote,
   sshdPortMeta,
   validateMode
-} from "./chunk-MHPFGCEY.js";
+} from "./chunk-JJRF37BP.js";
 
 // src/moduleFailure.ts
 function firstNonEmptyLine(text) {
@@ -3360,57 +3360,157 @@ var pkg = {
   }
 };
 
-// src/modules/quadlet.ts
+// src/modules/quadletHelpers.ts
 var CONTAINERS_SYSTEMD_DIRECTORY = "/etc/containers/systemd";
-var QUADLET_FILE_MODE = "0644";
-var SYSTEMCTL = "systemctl";
-var UNIT_NAME_PATTERN2 = new RegExp("^[\\w@.\\-]+$", "v");
+var QUADLET_PULL_CHANGED_OUTPUT_PATTERNS = [
+  "Copying blob",
+  "Copying config",
+  "Downloaded newer image",
+  "Pulling fs layer",
+  "Storing signatures",
+  "Writing manifest"
+];
 function sanitizeQuadletValue(value) {
   return value.replaceAll(new RegExp("[\\n\\r]", "gv"), "");
 }
 function renderQuadletLine(key, value) {
   return `${key}=${sanitizeQuadletValue(value)}`;
 }
-function renderQuadletSection(name, lines) {
-  return [`[${name}]`, ...lines, ""].join("\n");
-}
-function validateQuadletName(name) {
-  if (!UNIT_NAME_PATTERN2.test(name)) {
-    throw new Error(`quadlet.container: name must match ${String(UNIT_NAME_PATTERN2)}, got: ${name}`);
-  }
-}
-function renderQuadletEnvironment(environment) {
-  return Object.entries(environment).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => renderQuadletLine("Environment", `${key}=${value}`));
-}
 function renderQuadletRepeated(key, values) {
   return values.map((value) => renderQuadletLine(key, value));
 }
-function maybeRenderQuadletLine(key, value, transform) {
+function renderQuadletKeyValue(key, record) {
+  return Object.entries(record).sort(([left], [right]) => left.localeCompare(right)).map(([k, v]) => renderQuadletLine(key, `${k}=${v}`));
+}
+function maybeRenderQuadletLine(key, value) {
   if (value == null || value === "") return null;
-  return renderQuadletLine(key, transform == null ? value : transform(value));
+  return renderQuadletLine(key, value);
+}
+function maybeRenderQuadletBool(key, value) {
+  if (value == null) return null;
+  return renderQuadletLine(key, String(value));
+}
+function maybeRenderQuadletNumber(key, value) {
+  if (value == null) return null;
+  return renderQuadletLine(key, String(value));
 }
 function compactQuadletLines(lines) {
   return lines.filter((line) => line != null);
 }
-function buildQuadletUnitSection(options) {
-  return renderQuadletSection("Unit", [
-    renderQuadletLine("Description", options.description ?? `Podman container: ${options.name}`),
-    "Wants=network-online.target",
-    "After=network-online.target"
-  ]);
+function renderQuadletSection(name, lines) {
+  return [`[${name}]`, ...lines, ""].join("\n");
 }
-function buildQuadletContainerLines(options) {
-  return compactQuadletLines([
+function buildQuadletIdentityLines(options) {
+  return [
     renderQuadletLine("Image", options.image),
     maybeRenderQuadletLine("ContainerName", options.containerName),
     maybeRenderQuadletLine("AutoUpdate", options.autoUpdate),
+    maybeRenderQuadletLine("Pull", options.pull),
+    maybeRenderQuadletLine("Entrypoint", options.entrypoint?.join(" ")),
     maybeRenderQuadletLine("Exec", options.exec?.join(" ")),
-    maybeRenderQuadletLine("Restart", options.restart),
+    maybeRenderQuadletLine("WorkingDir", options.workingDir),
+    maybeRenderQuadletLine("User", options.user),
+    maybeRenderQuadletLine("UserNS", options.userNs)
+  ];
+}
+function buildQuadletNetworkLines(options) {
+  return [
+    maybeRenderQuadletLine("HostName", options.hostName),
     ...renderQuadletRepeated("Network", options.networks ?? []),
-    ...renderQuadletRepeated("PodmanArgs", options.podmanArgs ?? []),
+    ...renderQuadletRepeated("DNS", options.dns ?? []),
+    ...renderQuadletRepeated("DNSOption", options.dnsOption ?? []),
+    ...renderQuadletRepeated("DNSSearch", options.dnsSearch ?? []),
+    maybeRenderQuadletLine("IP", options.ip),
+    maybeRenderQuadletLine("IP6", options.ip6)
+  ];
+}
+function buildQuadletSecurityLines(options) {
+  return [
+    ...renderQuadletRepeated("AddCapability", options.addCapability ?? []),
+    ...renderQuadletRepeated("DropCapability", options.dropCapability ?? []),
+    maybeRenderQuadletBool("SecurityLabelDisable", options.securityLabelDisable),
+    maybeRenderQuadletLine("SecurityLabelType", options.securityLabelType),
+    maybeRenderQuadletLine("SeccompProfile", options.seccompProfile),
+    maybeRenderQuadletBool("NoNewPrivileges", options.noNewPrivileges),
+    maybeRenderQuadletBool("ReadOnly", options.readOnly)
+  ];
+}
+function buildQuadletRuntimeLines(options) {
+  return [
+    maybeRenderQuadletBool("Notify", options.notify),
+    maybeRenderQuadletBool("RunInit", options.runInit),
+    maybeRenderQuadletLine("LogDriver", options.logDriver),
+    maybeRenderQuadletLine("Timezone", options.timezone),
+    maybeRenderQuadletNumber("StopTimeout", options.stopTimeout)
+  ];
+}
+function buildQuadletStorageLines(options) {
+  return [
     ...renderQuadletRepeated("PublishPort", options.publishPorts ?? []),
+    ...renderQuadletRepeated("ExposeHostPort", options.exposeHostPort ?? []),
     ...renderQuadletRepeated("Volume", options.volumes ?? []),
-    ...renderQuadletEnvironment(options.environment ?? {})
+    ...renderQuadletRepeated("Mount", options.mount ?? []),
+    ...renderQuadletRepeated("Tmpfs", options.tmpfs ?? []),
+    ...renderQuadletRepeated("AddDevice", options.addDevice ?? [])
+  ];
+}
+function buildQuadletMetadataLines(options) {
+  return [
+    ...renderQuadletRepeated("Secret", options.secret ?? []),
+    ...renderQuadletEnvironment(options.environment ?? {}),
+    ...renderQuadletRepeated("EnvironmentFile", options.environmentFiles ?? []),
+    ...renderQuadletKeyValue("Label", options.label ?? {}),
+    ...renderQuadletKeyValue("Annotation", options.annotation ?? {})
+  ];
+}
+function renderQuadletEnvironment(environment) {
+  return Object.entries(environment).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => renderQuadletLine("Environment", `${key}=${value}`));
+}
+function buildQuadletTuningLines(options) {
+  return [
+    ...renderQuadletKeyValue("Sysctl", options.sysctl ?? {}),
+    ...renderQuadletRepeated("Ulimit", options.ulimit ?? []),
+    ...renderQuadletRepeated("GroupAdd", options.groupAdd ?? []),
+    ...renderQuadletRepeated("Mask", options.mask ?? []),
+    ...renderQuadletRepeated("Unmask", options.unmask ?? [])
+  ];
+}
+function buildQuadletHealthcheckLines(options) {
+  if (options.healthCmd == null) return [];
+  return compactQuadletLines([
+    renderQuadletLine("HealthCmd", options.healthCmd),
+    maybeRenderQuadletLine("HealthInterval", options.healthInterval),
+    maybeRenderQuadletLine("HealthTimeout", options.healthTimeout),
+    maybeRenderQuadletNumber("HealthRetries", options.healthRetries),
+    maybeRenderQuadletLine("HealthStartPeriod", options.healthStartPeriod),
+    maybeRenderQuadletLine("HealthOnFailure", options.healthOnFailure)
+  ]);
+}
+function buildQuadletContainerLines(options) {
+  return compactQuadletLines([
+    ...buildQuadletIdentityLines(options),
+    ...buildQuadletNetworkLines(options),
+    ...buildQuadletSecurityLines(options),
+    ...buildQuadletRuntimeLines(options),
+    ...renderQuadletRepeated("PodmanArgs", options.podmanArgs ?? []),
+    ...buildQuadletStorageLines(options),
+    ...buildQuadletMetadataLines(options),
+    ...buildQuadletTuningLines(options),
+    ...buildQuadletHealthcheckLines(options)
+  ]);
+}
+function buildQuadletServiceLines(options) {
+  return compactQuadletLines([
+    maybeRenderQuadletLine("Restart", options.restart),
+    maybeRenderQuadletNumber("TimeoutStartSec", options.timeoutStartSec),
+    maybeRenderQuadletNumber("TimeoutStopSec", options.timeoutStopSec)
+  ]);
+}
+function buildQuadletUnitSection(options) {
+  return renderQuadletSection("Unit", [
+    renderQuadletLine("Description", options.description ?? `Podman container: ${options.name}`),
+    "Wants=network-online.target",
+    "After=network-online.target"
   ]);
 }
 function buildQuadletInstallSection(options) {
@@ -3418,15 +3518,59 @@ function buildQuadletInstallSection(options) {
     renderQuadletLine("WantedBy", options.wantedBy ?? "multi-user.target")
   ]);
 }
+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`;
+}
+function getQuadletContainerServiceName(options) {
+  return options.serviceName ?? options.name;
+}
+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)) {
+    throw new Error(`quadlet: name must match ${String(UNIT_NAME_PATTERN2)}, got: ${name}`);
+  }
+}
+function shellQuoteForQuadlet(value) {
+  const escapedQuote = "'\\''";
+  return `'${value.replaceAll("'", escapedQuote)}'`;
+}
+
+// src/modules/quadlet.ts
+var CONTAINERS_SYSTEMD_DIRECTORY_COMMAND = "mkdir -p '/etc/containers/systemd'";
+var QUADLET_FILE_MODE = "0644";
+var SYSTEMCTL = "systemctl";
 function generateContainerQuadlet(options) {
-  return [
+  const serviceLines = buildQuadletServiceLines(options);
+  const sections = [
     buildQuadletUnitSection(options),
     renderQuadletSection("Container", buildQuadletContainerLines(options)),
+    ...serviceLines.length > 0 ? [renderQuadletSection("Service", serviceLines)] : [],
     buildQuadletInstallSection(options)
-  ].join("\n").trimEnd();
+  ];
+  return sections.join("\n").trimEnd();
 }
 async function createQuadletDirectory(ssh2) {
-  return ssh2.exec(`mkdir -p ${shellQuote(CONTAINERS_SYSTEMD_DIRECTORY)}`, {
+  return ssh2.exec(CONTAINERS_SYSTEMD_DIRECTORY_COMMAND, {
     ignoreExitCode: true,
     silent: true
   });
@@ -3457,6 +3601,58 @@ async function checkQuadletFile(parameters) {
   const remoteContent = await parameters.ssh.readFile(parameters.filePath);
   return remoteContent.trim() === parameters.content.trim() ? "ok" : NEEDS_APPLY;
 }
+async function inspectQuadletImageId(parameters) {
+  const inspectResult = await parameters.ssh.exec(parameters.inspectCommand, {
+    ignoreExitCode: true,
+    silent: true
+  });
+  if (inspectResult.code !== 0) {
+    return failedCommand(
+      `[quadlet.updateImage: ${parameters.name}] podman image inspect failed`,
+      inspectResult
+    );
+  }
+  const imageId = readQuadletImageIdFromInspectOutput(inspectResult.stdout);
+  if (imageId == null) {
+    return failed(
+      `[quadlet.updateImage: ${parameters.name}] podman image inspect returned no image ID`
+    );
+  }
+  return imageId;
+}
+async function restartQuadletService(parameters) {
+  const restartResult = await parameters.ssh.exec(
+    `${SYSTEMCTL} restart ${shellQuote(parameters.serviceName)}`,
+    {
+      ignoreExitCode: true,
+      silent: true
+    }
+  );
+  return restartResult.code === 0 ? { detail: formatQuadletImageIdDetail(parameters.imageId), status: "changed" } : failedCommand(
+    `[quadlet.updateImage: ${parameters.name}] systemctl restart failed`,
+    restartResult
+  );
+}
+async function applyQuadletImageUpdate(parameters) {
+  const pullResult = await parameters.ssh.exec(parameters.pullCommand, {
+    ignoreExitCode: true,
+    silent: true
+  });
+  if (pullResult.code !== 0) {
+    return failedCommand(`[quadlet.updateImage: ${parameters.name}] podman pull failed`, pullResult);
+  }
+  if (!quadletPullOutputIndicatesChange(pullResult.stdout)) {
+    return { status: "ok" };
+  }
+  const imageId = await inspectQuadletImageId(parameters);
+  if (typeof imageId !== "string") return imageId;
+  return restartQuadletService({
+    imageId,
+    name: parameters.name,
+    serviceName: parameters.serviceName,
+    ssh: parameters.ssh
+  });
+}
 var quadlet = {
   /**
    * Write a Podman Quadlet `.container` definition and reload systemd when it changes.
@@ -3465,24 +3661,11 @@ var quadlet = {
    * and `service.running(name)`.
    *
    * @param options - Configuration for the Quadlet container definition.
-   * @param options.name - Quadlet base name without `.container`.
-   * @param options.image - Container image reference.
-   * @param options.description - Optional systemd unit description.
-   * @param options.containerName - Optional explicit Podman container name.
-   * @param options.autoUpdate - Optional Podman auto-update policy.
-   * @param options.environment - Optional environment variables.
-   * @param options.exec - Optional command and arguments for `Exec=`.
-   * @param options.networks - Optional `Network=` entries.
-   * @param options.podmanArgs - Optional `PodmanArgs=` entries.
-   * @param options.publishPorts - Optional `PublishPort=` entries.
-   * @param options.restart - Optional `Restart=` policy in the `[Container]` section.
-   * @param options.volumes - Optional `Volume=` entries.
-   * @param options.wantedBy - Optional install target. Defaults to `multi-user.target`.
    * @returns A Module that ensures the Quadlet file is present and up to date.
    */
   container(options) {
     validateQuadletName(options.name);
-    const filePath = `${CONTAINERS_SYSTEMD_DIRECTORY}/${options.name}.container`;
+    const filePath = getQuadletContainerFilePath(options.name);
     const content = generateContainerQuadlet(options);
     return {
       async apply(ssh2) {
@@ -3495,6 +3678,40 @@ var quadlet = {
       },
       name: `quadlet.container: ${options.name}`
     };
+  },
+  /**
+   * Pull the latest image for a Quadlet-managed container and restart the service
+   * only when the image changed.
+   *
+   * Accepts the same `name` and `image` fields as `quadlet.container(...)`, so a
+   * shared config object can drive both deployment and targeted image refreshes.
+   *
+   * @param options - Image pull and restart configuration for the Quadlet service.
+   * @returns A Module that updates the image and conditionally restarts the service.
+   */
+  updateImage(options) {
+    validateQuadletName(options.name);
+    if (options.serviceName != null) validateQuadletName(options.serviceName);
+    const pullCommand = buildQuadletImagePullCommand(options);
+    const inspectCommand = buildQuadletImageInspectCommand(options.image);
+    const serviceName = getQuadletContainerServiceName(options);
+    return {
+      async apply(ssh2) {
+        if (!ssh2) return failed(`[quadlet.updateImage: ${options.name}] SSH connection is required`);
+        return applyQuadletImageUpdate({
+          inspectCommand,
+          name: options.name,
+          pullCommand,
+          serviceName,
+          ssh: ssh2
+        });
+      },
+      // eslint-disable-next-line @typescript-eslint/require-await -- Signal-style module
+      async check() {
+        return NEEDS_APPLY;
+      },
+      name: `quadlet.updateImage: ${options.name}`
+    };
   }
 };
 
@@ -5577,4 +5794,4 @@ export {
   ufw,
   user
 };
-//# sourceMappingURL=chunk-LI47NIKN.js.map
+//# sourceMappingURL=chunk-D4CS2GCH.js.map