paratix 0.4.0 → 0.5.0

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

@@ -9,7 +9,7 @@ import {
   shellQuote,
   sshdPortMeta,
   validateMode
-} from "./chunk-G3BMCQKU.js";
+} from "./chunk-MHPFGCEY.js";
 
 // src/moduleFailure.ts
 function firstNonEmptyLine(text) {
@@ -676,11 +676,111 @@ function parseContainerStates(stdout) {
 function sanitizeUnitValue(value) {
   return value.replaceAll(new RegExp("[\\n\\r]", "gv"), "");
 }
-function generateSystemdUnit(projectDirectory, name, runtime) {
+function validateGeneratedSystemdUnitContent(content, unitFileName) {
+  if (content.trim() === "") {
+    return failed(`[compose.systemd] generated empty unit content for ${unitFileName}`);
+  }
+  if (!content.includes("[Unit]") || !content.includes("[Service]")) {
+    return failed(`[compose.systemd] generated invalid unit content for ${unitFileName}`);
+  }
+  return null;
+}
+async function verifyNonEmptySystemdUnit(parameters) {
+  const writtenContent = await parameters.connection.readFile(parameters.filePath);
+  if (writtenContent.trim() === "") return "empty";
+  return writtenContent.trim() === parameters.content.trim() ? "matches" : "unexpected";
+}
+async function cleanupComposeSystemdTarget(parameters) {
+  await parameters.connection.exec(`rm -f ${shellQuote(parameters.filePath)}`, {
+    ignoreExitCode: true,
+    silent: true
+  });
+}
+async function rewriteComposeSystemdUnitViaShell(parameters) {
+  const encodedContent = Buffer.from(parameters.content, "utf8").toString("base64");
+  await cleanupComposeSystemdTarget(parameters);
+  const result = await parameters.connection.exec(
+    `printf '%s' ${shellQuote(encodedContent)} | base64 -d > ${shellQuote(parameters.filePath)} && chmod ${shellQuote(SYSTEMD_UNIT_MODE)} ${shellQuote(parameters.filePath)} && chown ${shellQuote("root:root")} ${shellQuote(parameters.filePath)}`,
+    EXEC_OPTS2
+  );
+  if (result.code !== 0) {
+    return failedCommand(
+      `[compose.systemd] shell fallback write failed for ${parameters.unitFileName}`,
+      result
+    );
+  }
+  const fallbackVerification = await verifyNonEmptySystemdUnit(parameters);
+  if (fallbackVerification === "matches") return null;
+  await cleanupComposeSystemdTarget(parameters);
+  if (fallbackVerification === "empty") {
+    return failed(
+      `[compose.systemd] wrote empty unit file for ${parameters.unitFileName} even after shell fallback`
+    );
+  }
+  return failed(
+    `[compose.systemd] wrote unexpected unit content for ${parameters.unitFileName} even after shell fallback`
+  );
+}
+async function applyComposeSystemdUnit(parameters) {
+  await prepareComposeSystemdTarget(parameters);
+  try {
+    await parameters.connection.writeFile(parameters.filePath, parameters.content, {
+      mode: SYSTEMD_UNIT_MODE
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return failed(`[compose.systemd] atomic write failed for ${parameters.unitFileName}: ${reason}`);
+  }
+  const writeVerification = await verifyNonEmptySystemdUnit(parameters);
+  if (writeVerification !== "matches") {
+    const fallbackFailure = await rewriteComposeSystemdUnitViaShell(parameters);
+    if (fallbackFailure != null) return fallbackFailure;
+  }
+  const result = await parameters.connection.exec("systemctl daemon-reload", EXEC_OPTS2);
+  return result.code === 0 ? { status: "changed" } : failedCommand(`[compose.systemd] daemon-reload failed for ${parameters.unitFileName}`, result);
+}
+async function checkComposeSystemdUnit(parameters) {
+  const runtime = await getRuntime(parameters.ssh, parameters.explicitRuntime);
+  if (!runtime) return NEEDS_APPLY;
+  const exists = await parameters.ssh.exists(parameters.filePath);
+  if (!exists) return NEEDS_APPLY;
+  const content = generateSystemdUnit(parameters.projectDirectory, parameters.serviceName, {
+    detached: parameters.detached,
+    runtime
+  });
+  const remoteContent = await parameters.ssh.readFile(parameters.filePath);
+  return remoteContent.trim() === content.trim() ? "ok" : NEEDS_APPLY;
+}
+function resolveComposeSystemdIdentity(options) {
+  const serviceName = options.name ?? `compose-${basename(options.projectDirectory)}`;
+  if (!UNIT_NAME_PATTERN.test(serviceName)) {
+    throw new Error(
+      `compose.systemd: name must match ${String(UNIT_NAME_PATTERN)}, got: ${serviceName}`
+    );
+  }
+  const unitFileName = `${serviceName}.service`;
+  return {
+    filePath: `/etc/systemd/system/${unitFileName}`,
+    serviceName,
+    unitFileName
+  };
+}
+async function prepareComposeSystemdTarget(parameters) {
+  await parameters.connection.exec(`systemctl unmask ${shellQuote(parameters.unitFileName)}`, {
+    ignoreExitCode: true,
+    silent: true
+  });
+  await parameters.connection.exec(`rm -f ${shellQuote(parameters.filePath)}`, {
+    ignoreExitCode: true,
+    silent: true
+  });
+}
+function generateSystemdUnit(projectDirectory, name, options) {
   const safeName = sanitizeUnitValue(name);
   const safeDirectory = sanitizeUnitValue(projectDirectory);
-  const lines = ["[Unit]", `Description=Compose stack: ${safeName}`];
-  if (runtime === "docker") {
+  const composeUpCommand = options.detached ? `/usr/bin/env ${options.runtime} compose up -d --remove-orphans` : `/usr/bin/env ${options.runtime} compose up --remove-orphans`;
+  const lines = ["[Unit]", `Description=Compose stack: ${safeName}`, "Wants=network-online.target"];
+  if (options.runtime === "docker") {
     lines.push("After=network-online.target docker.service");
     lines.push("Requires=docker.service");
   } else {
@@ -692,8 +792,11 @@ function generateSystemdUnit(projectDirectory, name, runtime) {
     "Type=oneshot",
     "RemainAfterExit=yes",
     `WorkingDirectory=${safeDirectory}`,
-    `ExecStart=/usr/bin/env ${runtime} compose up -d`,
-    `ExecStop=/usr/bin/env ${runtime} compose down`,
+    `ExecStart=${composeUpCommand}`,
+    `ExecStop=/usr/bin/env ${options.runtime} compose down`,
+    "TimeoutStartSec=0",
+    "StandardOutput=journal",
+    "StandardError=journal",
     "",
     "[Install]",
     "WantedBy=multi-user.target",
@@ -888,6 +991,7 @@ var compose = {
    * explicitly provided.
    *
    * @param options - Configuration for the systemd unit.
+   * @param options.detached - When true, use `compose up -d`; otherwise start attached.
    * @param options.projectDirectory - The project directory on the remote host.
    * @param options.name - Optional service name (without `.service` suffix).
    * @param options.runtime - Explicit container runtime override.
@@ -895,14 +999,11 @@ var compose = {
    */
   systemd(options) {
     const { projectDirectory, runtime: explicitRuntime } = options;
-    const serviceName = options.name ?? `compose-${basename(projectDirectory)}`;
-    if (!UNIT_NAME_PATTERN.test(serviceName)) {
-      throw new Error(
-        `compose.systemd: name must match ${String(UNIT_NAME_PATTERN)}, got: ${serviceName}`
-      );
-    }
-    const unitFileName = `${serviceName}.service`;
-    const filePath = `/etc/systemd/system/${unitFileName}`;
+    const detached = options.detached ?? false;
+    const { filePath, serviceName, unitFileName } = resolveComposeSystemdIdentity({
+      name: options.name,
+      projectDirectory
+    });
     return {
       async apply(ssh2) {
         const connection = requireComposeSsh(ssh2, "systemd", projectDirectory);
@@ -914,20 +1015,26 @@ var compose = {
           ssh: connection
         });
         if (typeof runtime !== "string") return runtime;
-        const content = generateSystemdUnit(projectDirectory, serviceName, runtime);
-        await connection.writeFile(filePath, content, { mode: SYSTEMD_UNIT_MODE });
-        const result = await connection.exec("systemctl daemon-reload", EXEC_OPTS2);
-        return result.code === 0 ? { status: "changed" } : failedCommand(`[compose.systemd] daemon-reload failed for ${unitFileName}`, result);
+        const content = generateSystemdUnit(projectDirectory, serviceName, { detached, runtime });
+        const validationFailure = validateGeneratedSystemdUnitContent(content, unitFileName);
+        if (validationFailure != null) return validationFailure;
+        return applyComposeSystemdUnit({
+          connection,
+          content,
+          filePath,
+          unitFileName
+        });
       },
       async check(ssh2) {
         if (!ssh2) return NEEDS_APPLY;
-        const rt = await getRuntime(ssh2, explicitRuntime);
-        if (!rt) return NEEDS_APPLY;
-        const exists = await ssh2.exists(filePath);
-        if (!exists) return NEEDS_APPLY;
-        const content = generateSystemdUnit(projectDirectory, serviceName, rt);
-        const remoteContent = await ssh2.readFile(filePath);
-        return remoteContent.trim() === content.trim() ? "ok" : NEEDS_APPLY;
+        return checkComposeSystemdUnit({
+          detached,
+          explicitRuntime,
+          filePath,
+          projectDirectory,
+          serviceName,
+          ssh: ssh2
+        });
       },
       name: `compose.systemd: ${unitFileName}`
     };
@@ -1755,7 +1862,7 @@ function stat(remotePath) {
   };
 }
 
-// src/modules/file.ts
+// src/modules/fileMetadataHelpers.ts
 var DEFAULT_FILE_WRITE_MODE2 = "0644";
 async function readOwnership(ssh2, remotePath) {
   const raw = await ssh2.output(`stat -c '%a %U %G' ${shellQuote(remotePath)}`);
@@ -1794,9 +1901,39 @@ function ownershipMatches(current, options) {
   if (expectsGroup && current.group !== expectedGroup) return false;
   return true;
 }
+function createMetadataModule(kind, remotePath, value) {
+  const name = `file.${kind}: ${remotePath}`;
+  return {
+    async apply(ssh2) {
+      if (!ssh2) return failed(`[${name}] SSH connection is required`);
+      if (kind === "chmod") validateMode(value);
+      await ssh2.exec(`${kind} ${shellQuote(value)} ${shellQuote(remotePath)}`, { silent: true });
+      return { status: "changed" };
+    },
+    async check(ssh2) {
+      if (!ssh2) return NEEDS_APPLY;
+      if (!await ssh2.exists(remotePath)) return NEEDS_APPLY;
+      const ownership = await readOwnership(ssh2, remotePath);
+      const matches = kind === "chmod" ? { mode: value } : { owner: value };
+      return ownershipMatches(ownership, matches) ? "ok" : NEEDS_APPLY;
+    },
+    name
+  };
+}
+
+// src/modules/file.ts
 function splitLines(content) {
   return content.split(new RegExp("\\r?\\n", "v"));
 }
+function findFirstMatchingLineIndex(lines, pattern) {
+  return lines.findIndex((candidateLine) => pattern.test(candidateLine));
+}
+function splitLinesPreservingTrailingNewline(content) {
+  const hasTrailingNewline = new RegExp("\\r?\\n$", "v").test(content);
+  const lines = splitLines(content);
+  if (hasTrailingNewline && lines.at(-1) === "") lines.pop();
+  return { hasTrailingNewline, lines };
+}
 function validateAbsentPath(remotePath) {
   const trimmedPath = remotePath.trim();
   if (trimmedPath.length === 0) {
@@ -1836,6 +1973,12 @@ var file = {
   },
   assemble,
   block,
+  chmod(remotePath, mode) {
+    return createMetadataModule("chmod", remotePath, mode);
+  },
+  chown(remotePath, owner) {
+    return createMetadataModule("chown", remotePath, owner);
+  },
   /**
    * Upload a local file to the remote host.
    * The file is only transferred when the remote SHA-256 differs from the local one.
@@ -1936,13 +2079,17 @@ var file = {
           });
         } else {
           const content = await ssh2.readFile(remotePath);
+          const { hasTrailingNewline, lines } = splitLinesPreservingTrailingNewline(content);
           const pattern = new RegExp(options.match, "mu");
-          if (!pattern.test(content)) {
+          const matchingLineIndex = findFirstMatchingLineIndex(lines, pattern);
+          if (matchingLineIndex === -1) {
             return failed(
               `[file.line: ${remotePath}] No line matching ${options.match} found for replacement`
             );
           }
-          const newContent = content.replace(pattern, line);
+          lines[matchingLineIndex] = line;
+          let newContent = lines.join("\n");
+          if (hasTrailingNewline) newContent += "\n";
           const ownership = await readOwnership(ssh2, remotePath);
           await guardedWriteFile(ssh2, {
             mode: normalizeMode2(ownership.mode),
@@ -1961,7 +2108,8 @@ var file = {
         const lines = splitLines(content);
         if (options?.match != null) {
           const matchPattern = new RegExp(options.match, "mu");
-          const matchedLine = lines.find((candidateLine) => matchPattern.test(candidateLine));
+          const matchedLineIndex = findFirstMatchingLineIndex(lines, matchPattern);
+          const matchedLine = matchedLineIndex === -1 ? void 0 : lines[matchedLineIndex];
           return matchedLine === line ? "ok" : NEEDS_APPLY;
         }
         return lines.includes(line) ? "ok" : NEEDS_APPLY;
@@ -3212,6 +3360,144 @@ var pkg = {
   }
 };
 
+// src/modules/quadlet.ts
+var CONTAINERS_SYSTEMD_DIRECTORY = "/etc/containers/systemd";
+var QUADLET_FILE_MODE = "0644";
+var SYSTEMCTL = "systemctl";
+var UNIT_NAME_PATTERN2 = new RegExp("^[\\w@.\\-]+$", "v");
+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) {
+  if (value == null || value === "") return null;
+  return renderQuadletLine(key, transform == null ? value : transform(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 buildQuadletContainerLines(options) {
+  return compactQuadletLines([
+    renderQuadletLine("Image", options.image),
+    maybeRenderQuadletLine("ContainerName", options.containerName),
+    maybeRenderQuadletLine("AutoUpdate", options.autoUpdate),
+    maybeRenderQuadletLine("Exec", options.exec?.join(" ")),
+    maybeRenderQuadletLine("Restart", options.restart),
+    ...renderQuadletRepeated("Network", options.networks ?? []),
+    ...renderQuadletRepeated("PodmanArgs", options.podmanArgs ?? []),
+    ...renderQuadletRepeated("PublishPort", options.publishPorts ?? []),
+    ...renderQuadletRepeated("Volume", options.volumes ?? []),
+    ...renderQuadletEnvironment(options.environment ?? {})
+  ]);
+}
+function buildQuadletInstallSection(options) {
+  return renderQuadletSection("Install", [
+    renderQuadletLine("WantedBy", options.wantedBy ?? "multi-user.target")
+  ]);
+}
+function generateContainerQuadlet(options) {
+  return [
+    buildQuadletUnitSection(options),
+    renderQuadletSection("Container", buildQuadletContainerLines(options)),
+    buildQuadletInstallSection(options)
+  ].join("\n").trimEnd();
+}
+async function createQuadletDirectory(ssh2) {
+  return ssh2.exec(`mkdir -p ${shellQuote(CONTAINERS_SYSTEMD_DIRECTORY)}`, {
+    ignoreExitCode: true,
+    silent: true
+  });
+}
+async function applyQuadletFile(parameters) {
+  const mkdirResult = await createQuadletDirectory(parameters.ssh);
+  if (mkdirResult.code !== 0) {
+    return failedCommand(
+      `[quadlet.container: ${parameters.name}] failed to create quadlet directory`,
+      mkdirResult
+    );
+  }
+  await parameters.ssh.writeFile(parameters.filePath, parameters.content, {
+    mode: QUADLET_FILE_MODE
+  });
+  const daemonReload = await parameters.ssh.exec(`${SYSTEMCTL} daemon-reload`, {
+    ignoreExitCode: true,
+    silent: true
+  });
+  return daemonReload.code === 0 ? { status: "changed" } : failedCommand(
+    `[quadlet.container: ${parameters.name}] systemctl daemon-reload failed`,
+    daemonReload
+  );
+}
+async function checkQuadletFile(parameters) {
+  const exists = await parameters.ssh.exists(parameters.filePath);
+  if (!exists) return NEEDS_APPLY;
+  const remoteContent = await parameters.ssh.readFile(parameters.filePath);
+  return remoteContent.trim() === parameters.content.trim() ? "ok" : NEEDS_APPLY;
+}
+var quadlet = {
+  /**
+   * Write a Podman Quadlet `.container` definition and reload systemd when it changes.
+   *
+   * The resulting generated service can be controlled with `service.enabled(name)`
+   * 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 content = generateContainerQuadlet(options);
+    return {
+      async apply(ssh2) {
+        if (!ssh2) return failed(`[quadlet.container: ${options.name}] SSH connection is required`);
+        return applyQuadletFile({ content, filePath, name: options.name, ssh: ssh2 });
+      },
+      async check(ssh2) {
+        if (!ssh2) return NEEDS_APPLY;
+        return checkQuadletFile({ content, filePath, ssh: ssh2 });
+      },
+      name: `quadlet.container: ${options.name}`
+    };
+  }
+};
+
 // src/modules/releaseUpgrade.ts
 var NONINTERACTIVE2 = "DEBIAN_FRONTEND=noninteractive";
 var CODENAME_RE = new RegExp("^[a-z]{3,20}$", "v");
@@ -3666,7 +3952,7 @@ var script = {
 };
 
 // src/modules/service.ts
-var SYSTEMCTL = "systemctl";
+var SYSTEMCTL2 = "systemctl";
 var service = {
   /**
    * Ensure a systemd service is disabled and will not start on boot.
@@ -3677,7 +3963,7 @@ var service = {
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[service.disabled: ${name}] SSH connection is required`);
-        const result = await ssh2.exec(`${SYSTEMCTL} disable ${shellQuote(name)}`, {
+        const result = await ssh2.exec(`${SYSTEMCTL2} disable ${shellQuote(name)}`, {
           ignoreExitCode: true,
           silent: true
         });
@@ -3685,7 +3971,7 @@ var service = {
       },
       async check(ssh2) {
         if (!ssh2) return NEEDS_APPLY;
-        const enabled = await ssh2.test(`${SYSTEMCTL} is-enabled --quiet ${shellQuote(name)}`);
+        const enabled = await ssh2.test(`${SYSTEMCTL2} is-enabled --quiet ${shellQuote(name)}`);
         return enabled ? "needs-apply" : "ok";
       },
       name: `service.disabled: ${name}`
@@ -3700,7 +3986,7 @@ var service = {
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[service.enabled: ${name}] SSH connection is required`);
-        const result = await ssh2.exec(`${SYSTEMCTL} enable ${shellQuote(name)}`, {
+        const result = await ssh2.exec(`${SYSTEMCTL2} enable ${shellQuote(name)}`, {
           ignoreExitCode: true,
           silent: true
         });
@@ -3708,7 +3994,7 @@ var service = {
       },
       async check(ssh2) {
         if (!ssh2) return NEEDS_APPLY;
-        return await ssh2.test(`${SYSTEMCTL} is-enabled --quiet ${shellQuote(name)}`) ? "ok" : NEEDS_APPLY;
+        return await ssh2.test(`${SYSTEMCTL2} is-enabled --quiet ${shellQuote(name)}`) ? "ok" : NEEDS_APPLY;
       },
       name: `service.enabled: ${name}`
     };
@@ -3724,7 +4010,7 @@ var service = {
       async apply(ssh2) {
         if (!ssh2) return failed("[service.facts] SSH connection is required");
         const result = await ssh2.exec(
-          `${SYSTEMCTL} list-units --type=service --all --no-pager --no-legend`,
+          `${SYSTEMCTL2} list-units --type=service --all --no-pager --no-legend`,
           { ignoreExitCode: true, silent: true }
         );
         if (result.code !== 0) {
@@ -3759,7 +4045,7 @@ var service = {
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[service.reload: ${name}] SSH connection is required`);
-        const result = await ssh2.exec(`${SYSTEMCTL} reload ${shellQuote(name)}`, {
+        const result = await ssh2.exec(`${SYSTEMCTL2} reload ${shellQuote(name)}`, {
           ignoreExitCode: true,
           silent: true
         });
@@ -3781,7 +4067,7 @@ var service = {
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[service.restart: ${name}] SSH connection is required`);
-        const result = await ssh2.exec(`${SYSTEMCTL} restart ${shellQuote(name)}`, {
+        const result = await ssh2.exec(`${SYSTEMCTL2} restart ${shellQuote(name)}`, {
           ignoreExitCode: true,
           silent: true
         });
@@ -3803,7 +4089,7 @@ var service = {
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[service.running: ${name}] SSH connection is required`);
-        const result = await ssh2.exec(`${SYSTEMCTL} start ${shellQuote(name)}`, {
+        const result = await ssh2.exec(`${SYSTEMCTL2} start ${shellQuote(name)}`, {
           ignoreExitCode: true,
           silent: true
         });
@@ -3811,7 +4097,7 @@ var service = {
       },
       async check(ssh2) {
         if (!ssh2) return NEEDS_APPLY;
-        return await ssh2.test(`${SYSTEMCTL} is-active --quiet ${shellQuote(name)}`) ? "ok" : NEEDS_APPLY;
+        return await ssh2.test(`${SYSTEMCTL2} is-active --quiet ${shellQuote(name)}`) ? "ok" : NEEDS_APPLY;
       },
       name: `service.running: ${name}`
     };
@@ -3825,7 +4111,7 @@ var service = {
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[service.stopped: ${name}] SSH connection is required`);
-        const result = await ssh2.exec(`${SYSTEMCTL} stop ${shellQuote(name)}`, {
+        const result = await ssh2.exec(`${SYSTEMCTL2} stop ${shellQuote(name)}`, {
           ignoreExitCode: true,
           silent: true
         });
@@ -3833,7 +4119,7 @@ var service = {
       },
       async check(ssh2) {
         if (!ssh2) return NEEDS_APPLY;
-        const active = await ssh2.test(`${SYSTEMCTL} is-active --quiet ${shellQuote(name)}`);
+        const active = await ssh2.test(`${SYSTEMCTL2} is-active --quiet ${shellQuote(name)}`);
         return active ? "needs-apply" : "ok";
       },
       name: `service.stopped: ${name}`
@@ -4124,7 +4410,7 @@ var DEFAULT_SSH_PORT3 = 22;
 var PRIVILEGE_SEPARATION_DIRECTORY = "/run/sshd";
 var SSHD_CONFIG_PATH = "/etc/ssh/sshd_config";
 var SSHD_CONFIG_MODE = "0644";
-var SYSTEMCTL2 = "systemctl";
+var SYSTEMCTL3 = "systemctl";
 var REGEXP_SPECIAL = /* @__PURE__ */ new Set(["?", ".", "(", ")", "[", "]", "{", "}", "*", "\\", "^", "+", "|", "$"]);
 function escapeRegExp(s) {
   let result = "";
@@ -4162,14 +4448,14 @@ async function disableSocketActivatedSsh(ssh2) {
   });
 }
 async function resolveSshServiceUnit(ssh2) {
-  const sshdExists = await ssh2.exec(`${SYSTEMCTL2} cat sshd.service >/dev/null 2>&1`, {
+  const sshdExists = await ssh2.exec(`${SYSTEMCTL3} cat sshd.service >/dev/null 2>&1`, {
     ignoreExitCode: true,
     silent: true
   });
   if (sshdExists.code === 0) {
     return "sshd";
   }
-  const sshExists = await ssh2.exec(`${SYSTEMCTL2} cat ssh.service >/dev/null 2>&1`, {
+  const sshExists = await ssh2.exec(`${SYSTEMCTL3} cat ssh.service >/dev/null 2>&1`, {
     ignoreExitCode: true,
     silent: true
   });
@@ -4182,7 +4468,7 @@ async function resolveSshServiceUnit(ssh2) {
 }
 async function reloadSshd(ssh2) {
   const serviceUnit = await resolveSshServiceUnit(ssh2);
-  const result = await ssh2.exec(`${SYSTEMCTL2} reload ${serviceUnit}`, {
+  const result = await ssh2.exec(`${SYSTEMCTL3} reload ${serviceUnit}`, {
     ignoreExitCode: true,
     silent: true
   });
@@ -4263,7 +4549,7 @@ async function applySshdPort(ssh2, targetPort) {
   try {
     await disableSocketActivatedSsh(ssh2);
     const serviceUnit = await resolveSshServiceUnit(ssh2);
-    await ssh2.exec(`${SYSTEMCTL2} restart ${serviceUnit}`, { silent: true });
+    await ssh2.exec(`${SYSTEMCTL3} restart ${serviceUnit}`, { silent: true });
   } catch (error) {
     if (!isRestartDisconnect(error)) {
       ssh2.removePort(targetPort);
@@ -4374,8 +4660,259 @@ var sshd = {
   }
 };
 
-// src/modules/sysctl.ts
+// src/modules/swapFileHelpers.ts
+import { dirname } from "path";
 var EXEC_OPTS8 = { ignoreExitCode: true, silent: true };
+var FSTAB_PATH2 = "/etc/fstab";
+var FSTAB_MODE2 = "0644";
+var KIBI = 1024;
+var POWER_0 = 0;
+var POWER_1 = 1;
+var POWER_2 = 2;
+var POWER_3 = 3;
+var POWER_4 = 4;
+var POWER_5 = 5;
+var SIZE_POWERS = {
+  "": POWER_0,
+  G: POWER_3,
+  K: POWER_1,
+  M: POWER_2,
+  P: POWER_5,
+  T: POWER_4
+};
+function isSizeUnit(unit) {
+  return Object.hasOwn(SIZE_POWERS, unit);
+}
+function normalizeSizeToBytes(size) {
+  if (typeof size === "number") {
+    if (!Number.isInteger(size) || size <= 0) {
+      throw new Error("swap.file: numeric size must be a positive integer byte count");
+    }
+    return size;
+  }
+  const trimmed = size.trim();
+  const match = new RegExp("^(?<value>\\d+)(?<unit>[KMGTP]?)$", "iv").exec(trimmed);
+  if (match?.groups == null) {
+    throw new Error(`swap.file: unsupported size format "${size}"`);
+  }
+  const value = Number.parseInt(match.groups.value, 10);
+  const unit = match.groups.unit.toUpperCase();
+  if (!isSizeUnit(unit)) {
+    throw new Error(`swap.file: unsupported size unit "${unit}"`);
+  }
+  return value * KIBI ** SIZE_POWERS[unit];
+}
+function normalizeSizeForCommand(size) {
+  return typeof size === "number" ? String(size) : size.trim();
+}
+function buildSwapFstabLine(path, priority) {
+  const options = priority == null ? "sw" : `sw,pri=${String(priority)}`;
+  return `${path} none swap ${options} 0 0`;
+}
+function findFstabEntry2(fstabContent, path) {
+  for (const line of fstabContent.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const fields = trimmed.split(new RegExp("\\s+", "v"));
+    if (fields[0] === path) return trimmed;
+  }
+  return null;
+}
+function upsertFstabEntry2(fstabContent, path, newLine) {
+  const lines = fstabContent.split("\n");
+  const index = lines.findIndex((line) => {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) return false;
+    const fields = trimmed.split(new RegExp("\\s+", "v"));
+    return fields[0] === path;
+  });
+  if (index === -1) {
+    while (lines.length > 0 && lines.at(-1)?.trim() === "") {
+      lines.pop();
+    }
+    lines.push(newLine);
+  } else {
+    lines[index] = newLine;
+  }
+  return `${lines.join("\n")}
+`;
+}
+function removeFstabEntry2(fstabContent, path) {
+  const lines = fstabContent.split("\n");
+  const result = lines.filter((line) => {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) return true;
+    const fields = trimmed.split(new RegExp("\\s+", "v"));
+    return fields[0] !== path;
+  });
+  return `${result.join("\n")}
+`;
+}
+async function isSwapActive(ssh2, path) {
+  const activeSwaps = await ssh2.lines("swapon --show=NAME --noheadings");
+  return activeSwaps.some((line) => line.trim() === path);
+}
+async function hasSwapSignature(ssh2, path) {
+  return ssh2.test(`swaplabel ${shellQuote(path)} >/dev/null 2>&1`);
+}
+async function readFileSizeInBytes(ssh2, path) {
+  const output = await ssh2.output(`stat -c %s ${shellQuote(path)}`);
+  return Number.parseInt(output.trim(), 10);
+}
+async function ensureSwapFstabState(parameters) {
+  const fstabContent = await parameters.ssh.readFile(FSTAB_PATH2);
+  const currentEntry = findFstabEntry2(fstabContent, parameters.path);
+  if (parameters.desiredLine == null) {
+    if (currentEntry == null) return false;
+    const removedContent = removeFstabEntry2(fstabContent, parameters.path);
+    await guardedWriteFile(parameters.ssh, {
+      mode: FSTAB_MODE2,
+      newContent: removedContent,
+      originalContent: fstabContent,
+      remotePath: FSTAB_PATH2
+    });
+    return true;
+  }
+  if (currentEntry === parameters.desiredLine) return false;
+  const updatedContent = upsertFstabEntry2(fstabContent, parameters.path, parameters.desiredLine);
+  await guardedWriteFile(parameters.ssh, {
+    mode: FSTAB_MODE2,
+    newContent: updatedContent,
+    originalContent: fstabContent,
+    remotePath: FSTAB_PATH2
+  });
+  return true;
+}
+async function ensureSwapFilePresent(parameters) {
+  const createDirectoryResult = await parameters.ssh.exec(
+    `mkdir -p ${shellQuote(dirname(parameters.path))}`,
+    EXEC_OPTS8
+  );
+  if (createDirectoryResult.code !== 0) {
+    return failedCommand(`[swap.file: ${parameters.path}] mkdir failed`, createDirectoryResult);
+  }
+  const createFileResult = await parameters.ssh.exec(
+    `fallocate -l ${shellQuote(parameters.size)} ${shellQuote(parameters.path)} || dd if=/dev/zero of=${shellQuote(parameters.path)} bs=${shellQuote(parameters.size)} count=1 status=none`,
+    EXEC_OPTS8
+  );
+  if (createFileResult.code !== 0) {
+    return failedCommand(
+      `[swap.file: ${parameters.path}] swap file creation failed`,
+      createFileResult
+    );
+  }
+  const chmodResult = await parameters.ssh.exec(
+    `chmod ${shellQuote(parameters.mode)} ${shellQuote(parameters.path)}`,
+    EXEC_OPTS8
+  );
+  if (chmodResult.code !== 0) {
+    return failedCommand(`[swap.file: ${parameters.path}] chmod failed`, chmodResult);
+  }
+  const makeSwapResult = await parameters.ssh.exec(
+    `mkswap ${shellQuote(parameters.path)}`,
+    EXEC_OPTS8
+  );
+  return makeSwapResult.code === 0 ? true : failedCommand(`[swap.file: ${parameters.path}] mkswap failed`, makeSwapResult);
+}
+function normalizeSwapFileOptions(options) {
+  const state = options.state ?? "present";
+  return {
+    expectedFstabLine: state === "present" ? buildSwapFstabLine(options.path, options.priority) : null,
+    mode: options.mode ?? "0600",
+    path: options.path,
+    sizeBytes: normalizeSizeToBytes(options.size),
+    sizeForCommand: normalizeSizeForCommand(options.size),
+    state
+  };
+}
+async function needsSwapRecreation(ssh2, options) {
+  if (!await ssh2.exists(options.path)) return true;
+  if (await readFileSizeInBytes(ssh2, options.path) !== options.sizeBytes) return true;
+  return !await hasSwapSignature(ssh2, options.path);
+}
+async function hasSwapFstabEntry(ssh2, options) {
+  const currentFstabContent = await ssh2.readFile(FSTAB_PATH2);
+  return findFstabEntry2(currentFstabContent, options.path) === options.expectedFstabLine;
+}
+async function hasNoSwapFstabEntry(ssh2, path) {
+  const currentFstabContent = await ssh2.readFile(FSTAB_PATH2);
+  return findFstabEntry2(currentFstabContent, path) == null;
+}
+
+// src/modules/swapHelpers.ts
+var EXEC_OPTS9 = { ignoreExitCode: true, silent: true };
+async function disableSwap(ssh2, path) {
+  if (!await isSwapActive(ssh2, path)) return false;
+  const result = await ssh2.exec(`swapoff ${shellQuote(path)}`, EXEC_OPTS9);
+  return result.code === 0 ? true : failedCommand(`[swap.file: ${path}] swapoff failed`, result);
+}
+async function removeSwapFile(ssh2, path) {
+  if (!await ssh2.exists(path)) return false;
+  const result = await ssh2.exec(`rm -f ${shellQuote(path)}`, EXEC_OPTS9);
+  return result.code === 0 ? true : failedCommand(`[swap.file: ${path}] rm failed`, result);
+}
+async function recreateSwapFile(ssh2, options) {
+  if (!await needsSwapRecreation(ssh2, options)) return "ok";
+  const disableResult = await disableSwap(ssh2, options.path);
+  if (typeof disableResult !== "boolean") return disableResult;
+  const removeResult = await removeSwapFile(ssh2, options.path);
+  if (typeof removeResult !== "boolean") return removeResult;
+  const createResult = await ensureSwapFilePresent({
+    mode: options.mode,
+    path: options.path,
+    size: options.sizeForCommand,
+    ssh: ssh2
+  });
+  return createResult === true ? "changed" : createResult;
+}
+async function enableSwap(ssh2, path) {
+  if (await isSwapActive(ssh2, path)) return false;
+  const result = await ssh2.exec(`swapon ${shellQuote(path)}`, EXEC_OPTS9);
+  return result.code === 0 ? true : failedCommand(`[swap.file: ${path}] swapon failed`, result);
+}
+async function applyAbsentSwapFile(ssh2, options) {
+  let swapChanged = false;
+  const disableResult = await disableSwap(ssh2, options.path);
+  if (typeof disableResult !== "boolean") return disableResult;
+  if (disableResult) swapChanged = true;
+  if (await ensureSwapFstabState({ desiredLine: null, path: options.path, ssh: ssh2 })) swapChanged = true;
+  const removeResult = await removeSwapFile(ssh2, options.path);
+  if (typeof removeResult !== "boolean") return removeResult;
+  if (removeResult) swapChanged = true;
+  return { status: swapChanged ? "changed" : "ok" };
+}
+async function applyPresentSwapFile(ssh2, options) {
+  let swapChanged = false;
+  const recreateResult = await recreateSwapFile(ssh2, options);
+  if (typeof recreateResult !== "string") return recreateResult;
+  if (recreateResult === "changed") swapChanged = true;
+  const enableResult = await enableSwap(ssh2, options.path);
+  if (typeof enableResult !== "boolean") return enableResult;
+  if (enableResult) swapChanged = true;
+  if (await ensureSwapFstabState({ desiredLine: options.expectedFstabLine, path: options.path, ssh: ssh2 })) {
+    swapChanged = true;
+  }
+  return { status: swapChanged ? "changed" : "ok" };
+}
+async function applySwapFile(ssh2, options) {
+  return options.state === "absent" ? applyAbsentSwapFile(ssh2, options) : applyPresentSwapFile(ssh2, options);
+}
+async function checkAbsent(ssh2, options) {
+  if (await ssh2.exists(options.path)) return NEEDS_APPLY;
+  if (await isSwapActive(ssh2, options.path)) return NEEDS_APPLY;
+  return await hasNoSwapFstabEntry(ssh2, options.path) ? "ok" : NEEDS_APPLY;
+}
+async function checkPresent(ssh2, options) {
+  if (await needsSwapRecreation(ssh2, options)) return NEEDS_APPLY;
+  if (!await isSwapActive(ssh2, options.path)) return NEEDS_APPLY;
+  return await hasSwapFstabEntry(ssh2, options) ? "ok" : NEEDS_APPLY;
+}
+async function checkSwapFile(ssh2, options) {
+  return options.state === "absent" ? checkAbsent(ssh2, options) : checkPresent(ssh2, options);
+}
+
+// src/modules/sysctl.ts
+var EXEC_OPTS10 = { ignoreExitCode: true, silent: true };
 var SYSCTL_DIR = "/etc/sysctl.d";
 var SYSCTL_CONFIG_MODE = "0644";
 function sanitizeKey(key) {
@@ -4411,28 +4948,28 @@ var sysctl = {
         if (!conn) return failed(`[sysctl.set: ${key}] SSH connection is required`);
         if (state === "present") {
           const assignment = `${key}=${value}`;
-          const result = await conn.exec(`sysctl -w ${shellQuote(assignment)}`, EXEC_OPTS8);
+          const result = await conn.exec(`sysctl -w ${shellQuote(assignment)}`, EXEC_OPTS10);
           if (result.code !== 0) {
             return failedCommand(`[sysctl.set: ${key}] sysctl -w failed`, result);
           }
           await conn.writeFile(configPath, expectedContent, { mode: SYSCTL_CONFIG_MODE });
         } else {
-          await conn.exec(`rm -f ${shellQuote(configPath)}`, EXEC_OPTS8);
+          await conn.exec(`rm -f ${shellQuote(configPath)}`, EXEC_OPTS10);
         }
         return { status: "changed" };
       },
       async check(conn) {
         if (!conn) return NEEDS_APPLY;
         if (state === "present") {
-          const result = await conn.exec(`sysctl -n ${shellQuote(key)}`, EXEC_OPTS8);
+          const result = await conn.exec(`sysctl -n ${shellQuote(key)}`, EXEC_OPTS10);
           const currentValue = result.stdout.trim();
           if (currentValue !== value) return NEEDS_APPLY;
-          const configExists = await conn.exec(`test -f ${shellQuote(configPath)}`, EXEC_OPTS8);
+          const configExists = await conn.exec(`test -f ${shellQuote(configPath)}`, EXEC_OPTS10);
           if (configExists.code !== 0) return NEEDS_APPLY;
           const fileContent = await conn.readFile(configPath);
           return fileContent.trim() === expectedContent.trim() ? "ok" : NEEDS_APPLY;
         }
-        const fileExists = await conn.exec(`test -f ${shellQuote(configPath)}`, EXEC_OPTS8);
+        const fileExists = await conn.exec(`test -f ${shellQuote(configPath)}`, EXEC_OPTS10);
         return fileExists.code === 0 ? NEEDS_APPLY : "ok";
       },
       name: state === "present" ? `sysctl.set: ${key}=${value}` : `sysctl.set: absent ${key}`
@@ -4440,6 +4977,53 @@ var sysctl = {
   }
 };
 
+// src/modules/swap.ts
+var swap = {
+  /**
+   * Ensure a file-backed swap area exists, is activated, and is persisted in `/etc/fstab`.
+   *
+   * @param options - Configuration for the swap file.
+   * @param options.mode - File mode applied to the swap file. Defaults to `0600`.
+   * @param options.path - Absolute path to the swap file, e.g. `/swapfile`.
+   * @param options.priority - Optional swap priority written into the fstab entry.
+   * @param options.size - Desired file size as bytes or a shell-friendly size string such as `2G`.
+   * @param options.state - Whether the swap file should be `present` (default) or `absent`.
+   * @returns A Module that manages the swap file lifecycle.
+   */
+  file(options) {
+    const normalized = normalizeSwapFileOptions(options);
+    return {
+      async apply(ssh2) {
+        if (!ssh2) return failed(`[swap.file: ${normalized.path}] SSH connection is required`);
+        return applySwapFile(ssh2, normalized);
+      },
+      async check(ssh2) {
+        if (!ssh2) return NEEDS_APPLY;
+        return checkSwapFile(ssh2, normalized);
+      },
+      name: normalized.state === "present" ? `swap.file: ${normalized.path} (${normalized.sizeForCommand})` : `swap.file: absent ${normalized.path}`
+    };
+  },
+  /**
+   * Persist `vm.swappiness`.
+   *
+   * @param value - Desired swappiness value.
+   * @returns A Module that manages `vm.swappiness`.
+   */
+  swappiness(value) {
+    return sysctl.set("vm.swappiness", String(value));
+  },
+  /**
+   * Persist `vm.vfs_cache_pressure`.
+   *
+   * @param value - Desired VFS cache pressure value.
+   * @returns A Module that manages `vm.vfs_cache_pressure`.
+   */
+  vfsCachePressure(value) {
+    return sysctl.set("vm.vfs_cache_pressure", String(value));
+  }
+};
+
 // src/modules/system.ts
 function parseOsRelease(content) {
   const result = {};
@@ -4610,8 +5194,8 @@ ${message}`);
 };
 
 // src/modules/systemd.ts
-var SYSTEMCTL3 = "systemctl";
-var UNIT_NAME_PATTERN2 = new RegExp("^[\\w@.\\-]+$", "v");
+var SYSTEMCTL4 = "systemctl";
+var UNIT_NAME_PATTERN3 = new RegExp("^[\\w@.\\-]+$", "v");
 var SYSTEMD_UNIT_MODE2 = "0644";
 var systemd = {
   /**
@@ -4623,7 +5207,7 @@ var systemd = {
     return {
       async apply(ssh2) {
         if (!ssh2) return failed("[systemd.daemonReload] SSH connection is required");
-        const result = await ssh2.exec(`${SYSTEMCTL3} daemon-reload`, {
+        const result = await ssh2.exec(`${SYSTEMCTL4} daemon-reload`, {
           ignoreExitCode: true,
           silent: true
         });
@@ -4645,7 +5229,7 @@ var systemd = {
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[systemd.masked: ${name}] SSH connection is required`);
-        const result = await ssh2.exec(`${SYSTEMCTL3} mask ${shellQuote(name)}`, {
+        const result = await ssh2.exec(`${SYSTEMCTL4} mask ${shellQuote(name)}`, {
           ignoreExitCode: true,
           silent: true
         });
@@ -4653,7 +5237,7 @@ var systemd = {
       },
       async check(ssh2) {
         if (!ssh2) return NEEDS_APPLY;
-        const result = await ssh2.exec(`${SYSTEMCTL3} is-enabled ${shellQuote(name)}`, {
+        const result = await ssh2.exec(`${SYSTEMCTL4} is-enabled ${shellQuote(name)}`, {
           ignoreExitCode: true,
           silent: true
         });
@@ -4674,15 +5258,15 @@ var systemd = {
    * @returns A Module that ensures the unit file is present with the given content.
    */
   unit(name, content) {
-    if (!UNIT_NAME_PATTERN2.test(name)) {
-      throw new Error(`systemd.unit: name must match ${String(UNIT_NAME_PATTERN2)}, got: ${name}`);
+    if (!UNIT_NAME_PATTERN3.test(name)) {
+      throw new Error(`systemd.unit: name must match ${String(UNIT_NAME_PATTERN3)}, got: ${name}`);
     }
     const filePath = `/etc/systemd/system/${name}`;
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[systemd.unit: ${name}] SSH connection is required`);
         await ssh2.writeFile(filePath, content, { mode: SYSTEMD_UNIT_MODE2 });
-        const result = await ssh2.exec(`${SYSTEMCTL3} daemon-reload`, {
+        const result = await ssh2.exec(`${SYSTEMCTL4} daemon-reload`, {
           ignoreExitCode: true,
           silent: true
         });
@@ -4707,7 +5291,7 @@ var systemd = {
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[systemd.unmasked: ${name}] SSH connection is required`);
-        const result = await ssh2.exec(`${SYSTEMCTL3} unmask ${shellQuote(name)}`, {
+        const result = await ssh2.exec(`${SYSTEMCTL4} unmask ${shellQuote(name)}`, {
           ignoreExitCode: true,
           silent: true
         });
@@ -4715,7 +5299,7 @@ var systemd = {
       },
       async check(ssh2) {
         if (!ssh2) return NEEDS_APPLY;
-        const result = await ssh2.exec(`${SYSTEMCTL3} is-enabled ${shellQuote(name)}`, {
+        const result = await ssh2.exec(`${SYSTEMCTL4} is-enabled ${shellQuote(name)}`, {
           ignoreExitCode: true,
           silent: true
         });
@@ -4979,6 +5563,7 @@ export {
   mount,
   net,
   op,
+  quadlet,
   releaseUpgrade,
   rsync,
   script,
@@ -4986,9 +5571,10 @@ export {
   ssh,
   sshd,
   sysctl,
+  swap,
   system,
   systemd,
   ufw,
   user
 };
-//# sourceMappingURL=chunk-C45YPXCX.js.map
+//# sourceMappingURL=chunk-LI47NIKN.js.map