paratix 0.15.1 → 0.16.1

package/dist/{chunk-C5KXNY6R.js → chunk-KC7XBI77.js}

@@ -2519,6 +2519,13 @@ async function validateExistingExtractDestination(conn, parameters) {
 // src/modules/fileMetadataHelpers.ts
 var EXEC_OPTS2 = { ignoreExitCode: true, silent: true };
 var DEFAULT_FILE_WRITE_MODE = "0644";
+var EMPTY_OWNERSHIP = {
+  group: "",
+  groupId: "",
+  mode: "",
+  owner: "",
+  ownerId: ""
+};
 function assertValidChownOwnershipSpec(ownerSpec) {
   if (ownerSpec === "") {
     throw new Error("chown ownership spec must not be empty");
@@ -2581,20 +2588,23 @@ function renderGuardedMetadataCommand(kind, remotePath, value) {
   ].join("\n");
 }
 async function readOwnership(ssh2, remotePath) {
-  const result = await ssh2.exec(`stat -c '%a %U %G' ${shellQuote(remotePath)}`, EXEC_OPTS2);
-  if (result.code !== 0) return { group: "", mode: "", owner: "" };
-  const [mode = "", owner = "", group2 = ""] = result.stdout.trim().split(new RegExp("\\s+", "v"));
-  return { group: group2, mode, owner };
+  const result = await ssh2.exec(`stat -c '%a %U %G %u %g' ${shellQuote(remotePath)}`, EXEC_OPTS2);
+  if (result.code !== 0) return { ...EMPTY_OWNERSHIP };
+  const [mode = "", owner = "", group2 = "", ownerId = "", groupId = ""] = result.stdout.trim().split(new RegExp("\\s+", "v"));
+  return { group: group2, groupId, mode, owner, ownerId };
 }
 function normalizeMode(mode) {
   return mode.startsWith("0") ? mode : `0${mode}`;
 }
-function ownershipComponentMatches(expected, actual) {
-  return expected === "" || actual === expected;
+var NUMERIC_ID_PATTERN = new RegExp("^\\d+$", "v");
+function isNumericId(value) {
+  return NUMERIC_ID_PATTERN.test(value);
 }
-function groupOwnershipMatches(expectsGroup, expectedGroup, actualGroup) {
-  if (!expectsGroup) return true;
-  return ownershipComponentMatches(expectedGroup, actualGroup);
+function ownershipComponentMatches(expected, actual, actualId) {
+  if (expected === "") return true;
+  if (actual === expected || actualId === expected) return true;
+  if (!isNumericId(expected) || !isNumericId(actualId)) return false;
+  return Number(expected) === Number(actualId);
 }
 async function resolveWriteMode(ssh2, remotePath, explicitMode) {
   if (explicitMode != null) return explicitMode;
@@ -2635,10 +2645,10 @@ function ownershipMatches(current, options) {
   if (options?.mode != null && current.mode !== options.mode.replace(new RegExp("^0+", "v"), "")) return false;
   if (options?.owner == null) return true;
   const expectsGroup = options.owner.includes(":");
-  const [expectedOwner, expectedGroup = ""] = options.owner.split(":", 2);
-  if (!ownershipComponentMatches(expectedOwner, current.owner)) return false;
-  if (!groupOwnershipMatches(expectsGroup, expectedGroup, current.group)) return false;
-  return true;
+  const [expectedOwner = "", expectedGroup = ""] = options.owner.split(":", 2);
+  if (!ownershipComponentMatches(expectedOwner, current.owner, current.ownerId)) return false;
+  if (!expectsGroup) return true;
+  return ownershipComponentMatches(expectedGroup, current.group, current.groupId);
 }
 function createMetadataModule(kind, remotePath, value) {
   const name = `file.${kind}: ${remotePath}`;
@@ -2676,6 +2686,7 @@ var SILENT = { silent: true };
 var FLAGS_DIR = "/var/lib/paratix/flags";
 var ARCHIVE_MARKER_MODE = "0644";
 var ARCHIVE_OWNER_MEMBER_CONCURRENCY = 8;
+var ARCHIVE_STAT_OWNERSHIP_FIELDS = 4;
 async function mapWithConcurrencyLimit2(items, limit, mapper) {
   if (items.length === 0) return [];
   const results = [];
@@ -3055,11 +3066,9 @@ async function applyExtract(conn, parameters) {
   }
 }
 function ownerMatchesStat(stdout, owner) {
-  const [actualUser = "", actualGroup = ""] = stdout.trim().split(new RegExp("\\s+", "v"), 2);
+  const [actualUser = "", actualGroup = "", actualUserId = "", actualGroupId = ""] = stdout.trim().split(new RegExp("\\s+", "v"), ARCHIVE_STAT_OWNERSHIP_FIELDS);
   const [expectedUser = "", expectedGroup = ""] = owner.split(":", 2);
-  if (expectedUser !== "" && actualUser !== expectedUser) return false;
-  if (expectedGroup !== "" && actualGroup !== expectedGroup) return false;
-  return true;
+  return ownershipComponentMatches(expectedUser, actualUser, actualUserId) && ownershipComponentMatches(expectedGroup, actualGroup, actualGroupId);
 }
 function isStringArray(value) {
   return Array.isArray(value) && value.every((item) => typeof item === "string");
@@ -3071,7 +3080,7 @@ async function extractedMemberOwnerMatches(conn, parameters) {
     EXEC_OPTS3
   );
   if (exists.code !== 0) return false;
-  const stat5 = await conn.exec(`stat -c '%U %G' -- ${shellQuote(path3)}`, EXEC_OPTS3);
+  const stat5 = await conn.exec(`stat -c '%U %G %u %g' -- ${shellQuote(path3)}`, EXEC_OPTS3);
   if (stat5.code !== 0) return false;
   return ownerMatchesStat(stat5.stdout, owner);
 }
@@ -3446,19 +3455,8 @@ async function resolveComposeConfigImages(parameters) {
     `${composeCommand(parameters.runtime, parameters.projectDirectory)} config --format json`,
     EXEC_OPTS4
   );
-  if (result.code !== 0) {
-    return failedCommand(
-      `[compose.pull] failed to resolve images for ${parameters.projectDirectory}`,
-      result
-    );
-  }
-  const images = parseComposeConfigImages(result.stdout);
-  if (images === null) {
-    return failed(
-      `[compose.pull] failed to parse compose config images for ${parameters.projectDirectory}`
-    );
-  }
-  return images;
+  if (result.code !== 0) return null;
+  return parseComposeConfigImages(result.stdout);
 }
 async function inspectComposeImageBeforePull(parameters) {
   const result = await parameters.ssh.exec(
@@ -4194,7 +4192,15 @@ var compose = {
           runtime,
           ssh: connection
         });
-        if (!Array.isArray(images)) return images;
+        if (images === null) {
+          const fallbackResult = await connection.exec(
+            `${composeCommand(runtime, projectDirectory)} pull 2>&1`,
+            EXEC_OPTS4
+          );
+          if (fallbackResult.code !== 0)
+            return failedCommand(`[compose.pull] failed for ${projectDirectory}`, fallbackResult);
+          return { status: "changed" };
+        }
         const beforePull = await snapshotComposeImagesBeforePull({
           images,
           runtime,
@@ -5357,18 +5363,22 @@ function rejectSensitiveHeadersOverHttp(parameters) {
   );
 }
 async function readDownloadOwnership(conn, destination) {
-  const result = await conn.exec(`stat -c '%a %U %G' ${shellQuote(destination)}`, {
+  const result = await conn.exec(`stat -c '%a %U %G %u %g' ${shellQuote(destination)}`, {
     ignoreExitCode: true,
     silent: true
   });
-  if (result.code !== 0) return { group: "", mode: "", owner: "" };
-  const [mode = "", owner = "", group2 = ""] = result.stdout.trim().split(new RegExp("\\s+", "v"));
-  return { group: group2, mode, owner };
+  if (result.code !== 0) return { group: "", groupId: "", mode: "", owner: "", ownerId: "" };
+  const [mode = "", owner = "", group2 = "", ownerId = "", groupId = ""] = result.stdout.trim().split(new RegExp("\\s+", "v"));
+  return { group: group2, groupId, mode, owner, ownerId };
+}
+function downloadComponentMatches(expected, actual, actualId) {
+  if (expected == null) return true;
+  return ownershipComponentMatches(expected, actual, actualId);
 }
 function downloadOwnershipMatches(current, options) {
   if (options.mode != null && current.mode !== options.mode.replace(new RegExp("^0+", "v"), "")) return false;
-  if (options.owner != null && current.owner !== options.owner) return false;
-  if (options.group != null && current.group !== options.group) return false;
+  if (!downloadComponentMatches(options.owner, current.owner, current.ownerId)) return false;
+  if (!downloadComponentMatches(options.group, current.group, current.groupId)) return false;
   return true;
 }
 async function metadataMatches(conn, destination, options) {
@@ -5567,7 +5577,7 @@ function downloadModeDrifted(current, options) {
   return options.mode != null && current.mode !== options.mode.replace(new RegExp("^0+", "v"), "");
 }
 function downloadOwnerDrifted(current, options) {
-  return options.owner != null && current.owner !== options.owner || options.group != null && current.group !== options.group;
+  return !downloadComponentMatches(options.owner, current.owner, current.ownerId) || !downloadComponentMatches(options.group, current.group, current.groupId);
 }
 async function healModeDrift(conn, parameters, current) {
   if (parameters.mode == null || !downloadModeDrifted(current, parameters)) {
@@ -6925,18 +6935,27 @@ ${endMarker}`
   };
 }
 async function readPropertiesState(ssh2, remotePath) {
-  const result = await ssh2.exec(`stat -c '%a %U %G' ${shellQuote(remotePath)}`, EXEC_OPTS6);
-  if (result.code !== 0) return { group: "", mode: "", owner: "" };
-  const [mode = "", owner = "", group2 = ""] = result.stdout.trim().split(new RegExp("\\s+", "v"));
-  return { group: group2, mode, owner };
+  const result = await ssh2.exec(`stat -c '%a %U %G %u %g' ${shellQuote(remotePath)}`, EXEC_OPTS6);
+  if (result.code !== 0) return { group: "", groupId: "", mode: "", owner: "", ownerId: "" };
+  const [mode = "", owner = "", group2 = "", ownerId = "", groupId = ""] = result.stdout.trim().split(new RegExp("\\s+", "v"));
+  return { group: group2, groupId, mode, owner, ownerId };
 }
 function modeMatches(current, desired) {
   return current === desired.replace(new RegExp("^0+", "v"), "");
 }
+function assertValidOwnershipComponent(value, kind) {
+  if (isNumericId(value)) return;
+  if (kind === "user") assertValidUserName(value);
+  else assertValidGroupName(value);
+}
+function propertiesComponentMatches(expected, actual, actualId) {
+  if (expected == null) return true;
+  return ownershipComponentMatches(expected, actual, actualId);
+}
 function assertValidPropertiesOptions(options) {
   if (options.mode != null) validateMode(options.mode);
-  if (options.owner != null) assertValidUserName(options.owner);
-  if (options.group != null) assertValidGroupName(options.group);
+  if (options.owner != null) assertValidOwnershipComponent(options.owner, "user");
+  if (options.group != null) assertValidOwnershipComponent(options.group, "group");
 }
 function isDriftFailure(result) {
   return typeof result !== "boolean";
@@ -6952,8 +6971,8 @@ async function applyModeDrift(context) {
 }
 async function maybeApplyCombinedChown(context) {
   const { current, options, remotePath, ssh: ssh2 } = context;
-  const ownerNeedsUpdate = options.owner != null && current.owner !== options.owner;
-  const groupNeedsUpdate = options.group != null && current.group !== options.group;
+  const ownerNeedsUpdate = options.owner != null && !propertiesComponentMatches(options.owner, current.owner, current.ownerId);
+  const groupNeedsUpdate = options.group != null && !propertiesComponentMatches(options.group, current.group, current.groupId);
   if (!ownerNeedsUpdate || !groupNeedsUpdate || options.owner == null || options.group == null) {
     return false;
   }
@@ -6966,7 +6985,9 @@ async function maybeApplyCombinedChown(context) {
 }
 async function maybeApplySingleChown(context) {
   const { current, options, remotePath, ssh: ssh2 } = context;
-  if (options.owner == null || current.owner === options.owner) return false;
+  if (options.owner == null || propertiesComponentMatches(options.owner, current.owner, current.ownerId)) {
+    return false;
+  }
   const result = await ssh2.exec(renderGuardedChownCommand(options.owner, remotePath), EXEC_OPTS6);
   if (result.code !== 0) {
     return failedCommand(`[file.properties: ${remotePath}] chown failed`, result);
@@ -6975,7 +6996,9 @@ async function maybeApplySingleChown(context) {
 }
 async function maybeApplySingleChgrp(context) {
   const { current, options, remotePath, ssh: ssh2 } = context;
-  if (options.group == null || current.group === options.group) return false;
+  if (options.group == null || propertiesComponentMatches(options.group, current.group, current.groupId)) {
+    return false;
+  }
   const result = await ssh2.exec(renderGuardedChgrpCommand(options.group, remotePath), EXEC_OPTS6);
   if (result.code !== 0) {
     return failedCommand(`[file.properties: ${remotePath}] chgrp failed`, result);
@@ -7014,10 +7037,10 @@ function properties(remotePath, options) {
     async check(ssh2) {
       if (!ssh2) return NEEDS_APPLY;
       if (await isSymlink(ssh2, remotePath)) return NEEDS_APPLY;
-      const { group: group2, mode, owner } = await readPropertiesState(ssh2, remotePath);
+      const { group: group2, groupId, mode, owner, ownerId } = await readPropertiesState(ssh2, remotePath);
       if (options.mode != null && !modeMatches(mode, options.mode)) return NEEDS_APPLY;
-      if (options.owner != null && owner !== options.owner) return NEEDS_APPLY;
-      if (options.group != null && group2 !== options.group) return NEEDS_APPLY;
+      if (!propertiesComponentMatches(options.owner, owner, ownerId)) return NEEDS_APPLY;
+      if (!propertiesComponentMatches(options.group, group2, groupId)) return NEEDS_APPLY;
       return "ok";
     },
     name: `file.properties: ${remotePath}`
@@ -11030,10 +11053,11 @@ async function snapshotQuadletFile(ssh2, filePath) {
     mode: normalizeQuadletMode(rawMode)
   };
 }
-async function restoreQuadletFileSnapshot(ssh2, filePath, snapshot) {
+async function restoreQuadletFileSnapshot(parameters) {
+  const { filePath, label, snapshot, ssh: ssh2 } = parameters;
   if (snapshot.exists) {
     if (await isSymlink(ssh2, filePath)) {
-      throw new Error(`[quadlet.container] refuses to restore through symlink at ${filePath}`);
+      throw new Error(`[${label}] refuses to restore through symlink at ${filePath}`);
     }
     await ssh2.writeFile(filePath, snapshot.content, { mode: snapshot.mode });
     return;
@@ -11041,24 +11065,30 @@ async function restoreQuadletFileSnapshot(ssh2, filePath, snapshot) {
   await ssh2.exec(`rm -f ${shellQuote(filePath)}`, { ignoreExitCode: true, silent: true });
 }
 async function applyQuadletFile(parameters) {
+  const label = parameters.label ?? "quadlet.container";
   const mkdirResult = await parameters.ssh.exec(CONTAINERS_SYSTEMD_DIRECTORY_COMMAND, {
     ignoreExitCode: true,
     silent: true
   });
   if (mkdirResult.code !== 0) {
     return failedCommand(
-      `[quadlet.container: ${parameters.name}] failed to create quadlet directory`,
+      `[${label}: ${parameters.name}] failed to create quadlet directory`,
       mkdirResult
     );
   }
   if (await isSymlink(parameters.ssh, parameters.filePath)) {
     return failed(
-      `[quadlet.container: ${parameters.name}] refuses to write through symlink at ${parameters.filePath}`
+      `[${label}: ${parameters.name}] refuses to write through symlink at ${parameters.filePath}`
     );
   }
   const snapshot = await snapshotQuadletFile(parameters.ssh, parameters.filePath);
   const restoreSnapshot = async () => {
-    await restoreQuadletFileSnapshot(parameters.ssh, parameters.filePath, snapshot);
+    await restoreQuadletFileSnapshot({
+      filePath: parameters.filePath,
+      label,
+      snapshot,
+      ssh: parameters.ssh
+    });
   };
   try {
     await parameters.ssh.writeFile(parameters.filePath, parameters.content, {
@@ -11067,7 +11097,7 @@ async function applyQuadletFile(parameters) {
   } catch (error) {
     const reason = error instanceof Error ? error.message : String(error);
     return withRollbackFailure(
-      failed(`[quadlet.container: ${parameters.name}] failed to write quadlet file: ${reason}`),
+      failed(`[${label}: ${parameters.name}] failed to write quadlet file: ${reason}`),
       restoreSnapshot,
       "quadlet apply failed"
     );
@@ -11078,10 +11108,7 @@ async function applyQuadletFile(parameters) {
   });
   if (daemonReload.code === 0) return { status: "changed" };
   return withRollbackFailure(
-    failedCommand(
-      `[quadlet.container: ${parameters.name}] systemctl daemon-reload failed`,
-      daemonReload
-    ),
+    failedCommand(`[${label}: ${parameters.name}] systemctl daemon-reload failed`, daemonReload),
     restoreSnapshot,
     "quadlet apply failed"
   );
@@ -11117,7 +11144,7 @@ var QUADLET_PULL_CHANGED_OUTPUT_PATTERNS = [
 ];
 function assertQuadletLineValue(key, value) {
   if (QUADLET_CONTROL_CHARACTER_PATTERN.test(value)) {
-    throw new Error(`quadlet.container ${key} values must not contain control characters`);
+    throw new Error(`quadlet ${key} values must not contain control characters`);
   }
 }
 function renderQuadletLine(key, value) {
@@ -11350,6 +11377,37 @@ function parseQuadletImageInspectOutput(output) {
   };
 }
 
+// src/modules/quadletNetworkHelpers.ts
+function getQuadletNetworkFilePath(name) {
+  return `${CONTAINERS_SYSTEMD_DIRECTORY}/${name}.network`;
+}
+function buildQuadletNetworkUnitLines(options) {
+  return compactQuadletLines([
+    renderQuadletLine("NetworkName", options.name),
+    maybeRenderQuadletLine("Driver", options.driver),
+    maybeRenderQuadletLine("IPAMDriver", options.ipamDriver),
+    maybeRenderQuadletBool("Internal", options.internal),
+    maybeRenderQuadletBool("IPv6", options.ipv6),
+    maybeRenderQuadletBool("DisableDNS", options.disableDns),
+    maybeRenderQuadletLine("Subnet", options.subnet),
+    maybeRenderQuadletLine("Gateway", options.gateway),
+    maybeRenderQuadletLine("IPRange", options.ipRange),
+    ...renderQuadletRepeated("DNS", options.dns ?? []),
+    ...renderQuadletKeyValue("Options", options.options ?? {}),
+    ...renderQuadletKeyValue("Label", options.label ?? {}),
+    ...renderQuadletRepeated("PodmanArgs", options.podmanArgs ?? [])
+  ]);
+}
+function generateNetworkQuadlet(options) {
+  const sections = [
+    renderQuadletSection("Unit", [
+      renderQuadletLine("Description", options.description ?? `Podman network: ${options.name}`)
+    ]),
+    renderQuadletSection("Network", buildQuadletNetworkUnitLines(options))
+  ];
+  return sections.join("\n").trimEnd();
+}
+
 // src/modules/quadletValidationHelpers.ts
 var UNIT_NAME_PATTERN2 = new RegExp("^[\\w@.\\-]+$", "v");
 var UNIT_NAME_ALL_DOTS_PATTERN = new RegExp("^\\.+$", "v");
@@ -11424,8 +11482,8 @@ function validateQuadletAuthFilePath(field, value) {
 // src/modules/quadlet.ts
 var QUADLET_RELOAD_HASH_LENGTH = 16;
 var SYSTEMCTL2 = "systemctl";
-function buildQuadletReloadFlag(name, content) {
-  const flagPrefix = `quadlet-container-${sha256String(name).slice(0, QUADLET_RELOAD_HASH_LENGTH)}-`;
+function buildQuadletReloadFlag(kind, name, content) {
+  const flagPrefix = `quadlet-${kind}-${sha256String(name).slice(0, QUADLET_RELOAD_HASH_LENGTH)}-`;
   return {
     flagName: `${flagPrefix}${sha256String(content).slice(0, QUADLET_RELOAD_HASH_LENGTH)}`,
     flagPrefix
@@ -11507,7 +11565,7 @@ async function applyQuadletImageUpdate(parameters) {
     ssh: parameters.ssh
   });
 }
-async function buildQuadletContainerDryRunDiff(ssh2, filePath, desired) {
+async function buildQuadletDryRunDiff(ssh2, filePath, desired) {
   try {
     const exists = await ssh2.exists(filePath);
     const current = exists ? await ssh2.readFile(filePath) : "";
@@ -11518,6 +11576,16 @@ async function buildQuadletContainerDryRunDiff(ssh2, filePath, desired) {
     return void 0;
   }
 }
+async function podmanNetworkExists(ssh2, name) {
+  const result = await ssh2.exec(`podman network exists -- ${shellQuote(name)}`, {
+    ignoreExitCode: true,
+    silent: true
+  });
+  return result.code === 0;
+}
+function quadletNetworkLiveHint(name) {
+  return `network '${name}' already exists; the running network is not recreated automatically \u2014 remove it to apply changed settings`;
+}
 var quadlet = {
   /**
    * Write a Podman Quadlet `.container` definition and reload systemd when it changes.
@@ -11533,11 +11601,11 @@ var quadlet = {
     validateQuadletImageValue("image", options.image);
     const filePath = getQuadletContainerFilePath(options.name);
     const content = generateContainerQuadlet(options);
-    const reloadFlag = buildQuadletReloadFlag(options.name, content);
+    const reloadFlag = buildQuadletReloadFlag("container", options.name, content);
     return {
       async _applyDryRun(ssh2) {
         if (!ssh2) return { status: "changed" };
-        const diff = await buildQuadletContainerDryRunDiff(ssh2, filePath, content);
+        const diff = await buildQuadletDryRunDiff(ssh2, filePath, content);
         if (diff != null) return { diff, status: "changed" };
         const flagPresent = await hasFlag(ssh2, reloadFlag.flagName);
         if (flagPresent) return { status: "changed" };
@@ -11561,6 +11629,67 @@ var quadlet = {
       name: `quadlet.container: ${options.name}`
     };
   },
+  /**
+   * Write a Podman Quadlet `.network` definition and reload systemd when it changes.
+   *
+   * Mirrors {@link quadlet.container}: the unit is written atomically to
+   * `/etc/containers/systemd/<name>.network`, symlinks are refused, and
+   * `systemctl daemon-reload` runs when the content changes. Containers
+   * reference the network via their existing `networks` option
+   * (e.g. `networks: ["app.network"]`).
+   *
+   * When the change lands and a network with the same name is already live on
+   * the host, the result carries an advisory detail: Podman does not recreate
+   * a running network, so changed `subnet`/`gateway`/… only take effect after
+   * the network is removed.
+   *
+   * @param options - Configuration for the Quadlet network definition.
+   * @returns A Module that ensures the Quadlet `.network` file is present and up to date.
+   */
+  network(options) {
+    validateQuadletName(options.name);
+    const filePath = getQuadletNetworkFilePath(options.name);
+    const content = generateNetworkQuadlet(options);
+    const reloadFlag = buildQuadletReloadFlag("network", options.name, content);
+    return {
+      async _applyDryRun(ssh2) {
+        if (!ssh2) return { status: "changed" };
+        const diff = await buildQuadletDryRunDiff(ssh2, filePath, content);
+        if (diff != null) {
+          const liveHint = await podmanNetworkExists(ssh2, options.name) ? quadletNetworkLiveHint(options.name) : void 0;
+          return liveHint == null ? { diff, status: "changed" } : { _dryRunDetail: liveHint, diff, status: "changed" };
+        }
+        const flagPresent = await hasFlag(ssh2, reloadFlag.flagName);
+        return flagPresent ? { status: "changed" } : { _dryRunDetail: "(dry-run, daemon-reload pending)", status: "changed" };
+      },
+      _dryRunDiffProducer: true,
+      async apply(ssh2) {
+        if (!ssh2) return failed(`[quadlet.network: ${options.name}] SSH connection is required`);
+        const contentChanges = await buildQuadletDryRunDiff(ssh2, filePath, content) != null;
+        const result = await applyQuadletFile({
+          content,
+          filePath,
+          label: "quadlet.network",
+          name: options.name,
+          ssh: ssh2
+        });
+        if (result.status !== "changed") return result;
+        const flagFailure = await setVersionedFlag(ssh2, reloadFlag.flagName, reloadFlag.flagPrefix);
+        if (flagFailure) return flagFailure;
+        if (contentChanges && await podmanNetworkExists(ssh2, options.name)) {
+          return { ...result, detail: quadletNetworkLiveHint(options.name) };
+        }
+        return result;
+      },
+      async check(ssh2) {
+        if (!ssh2) return NEEDS_APPLY;
+        const fileResult = await checkQuadletFile({ content, filePath, ssh: ssh2 });
+        if (fileResult !== "ok") return fileResult;
+        return await hasFlag(ssh2, reloadFlag.flagName) ? "ok" : NEEDS_APPLY;
+      },
+      name: `quadlet.network: ${options.name}`
+    };
+  },
   /**
    * Pull the latest image for a Quadlet-managed container and restart the service
    * only when the image changed.

package/dist/cli.js

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

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

@@ -1017,7 +1017,7 @@ type PropertiesOptions = {
 /**
  * Set file or directory ownership and permissions on the remote host.
  * Only the attributes specified in `options` are checked and applied. Drift
- * is detected via `stat -c '%a %U %G'` so `apply` only invokes the relevant
+ * is detected via `stat -c '%a %U %G %u %g'` so `apply` only invokes the relevant
  * `chmod`/`chown`/`chgrp` for fields that actually differ from the desired
  * state. When all desired fields already match, `apply` returns `status: "ok"`
  * instead of falsely reporting a change.
@@ -1466,6 +1466,23 @@ type QuadletImageUpdateOptions = {
     serviceName?: string;
 };
 
+type QuadletNetworkOptions = {
+    description?: string;
+    disableDns?: boolean;
+    dns?: string[];
+    driver?: string;
+    gateway?: string;
+    internal?: boolean;
+    ipamDriver?: string;
+    ipRange?: string;
+    ipv6?: boolean;
+    label?: Record<string, string>;
+    name: string;
+    options?: Record<string, string>;
+    podmanArgs?: string[];
+    subnet?: string;
+};
+
 /**
  * Modules for managing Podman Quadlet definitions.
  *
@@ -1484,6 +1501,24 @@ declare const quadlet: {
      * @returns A Module that ensures the Quadlet file is present and up to date.
      */
     container(options: QuadletContainerOptions): Module;
+    /**
+     * Write a Podman Quadlet `.network` definition and reload systemd when it changes.
+     *
+     * Mirrors {@link quadlet.container}: the unit is written atomically to
+     * `/etc/containers/systemd/<name>.network`, symlinks are refused, and
+     * `systemctl daemon-reload` runs when the content changes. Containers
+     * reference the network via their existing `networks` option
+     * (e.g. `networks: ["app.network"]`).
+     *
+     * When the change lands and a network with the same name is already live on
+     * the host, the result carries an advisory detail: Podman does not recreate
+     * a running network, so changed `subnet`/`gateway`/… only take effect after
+     * the network is removed.
+     *
+     * @param options - Configuration for the Quadlet network definition.
+     * @returns A Module that ensures the Quadlet `.network` file is present and up to date.
+     */
+    network(options: QuadletNetworkOptions): Module;
     /**
      * Pull the latest image for a Quadlet-managed container and restart the service
      * only when the image changed.

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-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';
+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-jbXRUlJ6.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-jbXRUlJ6.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-C5KXNY6R.js";
+} from "./chunk-KC7XBI77.js";
 
 // src/conditionalModules.ts
 function createConditionalApplyState(environment) {

package/dist/modules/index.d.ts

@@ -1 +1 @@
-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';
+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-jbXRUlJ6.js';

package/dist/modules/index.js

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

package/llm-guide.md

@@ -186,6 +186,8 @@ the idiomatic way to ensure a previously installed cron job is gone.
 | `compose.restart` | `(options: { projectDirectory: string; runtime?: "docker" \| "podman" }): Module`                                    | No         |
 | `compose.systemd` | `(options: { detached?: boolean; name?: string; projectDirectory: string; runtime?: "docker" \| "podman" }): Module` | Yes        |
 
+> **`compose.pull` change detection:** `compose.pull` compares image digests before and after the pull to report `ok` (nothing new) vs `changed`. This needs `compose config --format json`. With `runtime: "podman"`, when the compose provider is the Python `podman-compose` (which does not support `--format json`), digest-based detection is unavailable: the pull still runs, but always reports `changed`. The Docker and Compose v2 paths are unaffected.
+
 ### `download`
 
 | Method            | Signature                                                                                                                                                                                                                                                                                                                    | Idempotent |
@@ -222,6 +224,15 @@ 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                 |
 
+**Note on `owner` and `group` values:** Every ownership option accepts either a POSIX name or a
+numeric id — `owner: "www-data:www-data"` and `owner: "65532:65532"` are both valid, and the two
+components may be mixed (`owner: "root:65532"`). Numeric ids are the only option for accounts that
+have no passwd or group entry on the target host, such as `65532` in distroless images or `70` in
+the postgres image. Drift detection compares the declared value against both the name and the id
+reported by the host, so a numerically declared owner converges to `status: "ok"` like a named one.
+`file.properties` keeps `owner` and `group` as separate options and therefore rejects a combined
+`"user:group"` spec.
+
 **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.
 
 **Note on `file.line`:** The `line` value must be a single line without CR/LF characters. Use `file.block` for multiline content.
@@ -360,6 +371,7 @@ Whitespace und Shell-Metazeichen werden abgelehnt. `package.absent` ist rein nam
 | Method                | Signature                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Idempotent |
 | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
 | `quadlet.container`   | `(options: { addCapability?: string[]; addDevice?: string[]; annotation?: Record<string, string>; autoUpdate?: "local" \| "registry"; containerName?: string; description?: string; dns?: string[]; dnsOption?: string[]; dnsSearch?: string[]; dropCapability?: string[]; entrypoint?: string[]; environment?: Record<string, string>; environmentFiles?: string[]; exec?: string[]; exposeHostPort?: string[]; groupAdd?: string[]; healthCmd?: string; healthInterval?: string; healthOnFailure?: "kill" \| "none" \| "restart" \| "stop"; healthRetries?: number; healthStartPeriod?: string; healthTimeout?: string; hostName?: string; image: string; ip?: string; ip6?: string; label?: Record<string, string>; logDriver?: string; mask?: string[]; mount?: string[]; name: string; networks?: string[]; noNewPrivileges?: boolean; notify?: boolean; podmanArgs?: string[]; publishPorts?: string[]; pull?: "always" \| "missing" \| "never" \| "newer"; readOnly?: boolean; restart?: "always" \| "no" \| "on-abnormal" \| "on-abort" \| "on-failure" \| "on-success" \| "on-watchdog"; runInit?: boolean; secret?: string[]; seccompProfile?: string; securityLabelDisable?: boolean; securityLabelType?: string; stopTimeout?: number; sysctl?: Record<string, string>; timeoutStartSec?: number; timeoutStopSec?: number; timezone?: string; tmpfs?: string[]; ulimit?: string[]; unmask?: string[]; user?: string; userNs?: string; volumes?: string[]; wantedBy?: string; workingDir?: string }): Module` | Yes        |
+| `quadlet.network`     | `(options: { description?: string; disableDns?: boolean; dns?: string[]; driver?: string; gateway?: string; internal?: boolean; ipRange?: string; ipamDriver?: string; ipv6?: boolean; label?: Record<string, string>; name: string; options?: Record<string, string>; podmanArgs?: string[]; subnet?: string }): Module` — writes `/etc/containers/systemd/<name>.network`; reference it from a container via `networks: ["<name>.network"]`. When the change lands and a network with the same name is already live, `changed` carries an advisory detail that the running network is not recreated until removed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Yes        |
 | `quadlet.updateImage` | `(options: { authFile?: string; image: string; name: string; serviceName?: string }): Module` — returns `changed` with the new registry digest (or local image ID fallback) in parentheses when a newer image was pulled                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Partial    |
 
 ### `releaseUpgrade`
@@ -803,20 +815,21 @@ Rules:
 
 Diff-producing built-in modules:
 
-| 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. |
+| 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.                                                                                     |
+| `quadlet.network`                           | Unified diff of the `.network` 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. When a network with the same name is already live, the advisory hint is appended too. |
 
 ### Implementing a Diff for a Custom Module
 

package/package.json

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