paratix 0.16.0 → 0.17.0

package/dist/{chunk-56SN6NQH.js → chunk-NXU7K6HY.js}

@@ -104,6 +104,7 @@ function shellQuote(s) {
   return `'${s.replaceAll("'", "'\\''")}'`;
 }
 var DEFAULT_MAX_OUTPUT_BYTES = Number("1048576");
+var CAPTURE_TRUNCATION_MARKER = "\n[output truncated]";
 var CommandError = class _CommandError extends Error {
   /** Full, untruncated standard error of the failed command. */
   fullStderr;
@@ -1367,6 +1368,17 @@ async function setVersionedFlag(ssh2, flagName, flagPrefix) {
   if (result.code === 0) return null;
   return failedCommand(`[moduleHelpers] failed to persist versioned flag ${flagName}`, result);
 }
+async function setFlag(ssh2, flagName) {
+  validateFlagName(flagName, "flagName");
+  const ensureFailure = await ensureFlagsDirectory(ssh2);
+  if (ensureFailure) return ensureFailure;
+  const result = await ssh2.exec(`touch ${FLAGS_DIRECTORY}/${shellQuote(flagName)}`, {
+    ignoreExitCode: true,
+    silent: true
+  });
+  if (result.code === 0) return null;
+  return failedCommand(`[moduleHelpers] failed to persist flag ${flagName}`, result);
+}
 async function applyWithFlagLock(ssh2, parameters) {
   validateFlagName(parameters.flagName, "flagName");
   const lockName = flagLockName(parameters.flagName);
@@ -1473,6 +1485,19 @@ async function tryApplyWithFlagLock(ssh2, parameters) {
   return tryApplyWithFlagLock(ssh2, parameters);
 }
 
+// src/modules/packageUpgradeSummary.ts
+var APT_UPGRADE_SUMMARY_PATTERN = new RegExp("^(?<upgraded>\\d+) upgraded, ", "mv");
+var UNKNOWN_UPGRADE_OUTCOME_DETAIL = "upgrade completed, package count unavailable";
+function describeAptUpgradeOutcome(stdout) {
+  if (stdout.endsWith(CAPTURE_TRUNCATION_MARKER)) return UNKNOWN_UPGRADE_OUTCOME_DETAIL;
+  const captured = APT_UPGRADE_SUMMARY_PATTERN.exec(stdout)?.groups?.upgraded;
+  if (captured == null || captured === "") return UNKNOWN_UPGRADE_OUTCOME_DETAIL;
+  const upgraded = Number(captured);
+  if (!Number.isSafeInteger(upgraded)) return UNKNOWN_UPGRADE_OUTCOME_DETAIL;
+  if (upgraded === 0) return "no packages upgraded";
+  return upgraded === 1 ? "1 package upgraded" : `${upgraded} packages upgraded`;
+}
+
 // src/modules/remoteFileChecks.ts
 import { posix as posix3 } from "path";
 async function isRegularFileWithoutSymlink(ssh2, remotePath) {
@@ -1945,6 +1970,12 @@ var apt = {
    * The pipeline is split into three separate SSH commands so that each step
    * gets its own timeout window and produces a precise failure label.
    *
+   * The marker is written with `setFlag`: the flag name carries only the
+   * date and no call-site identity, so an evicting prefix would be
+   * host-global and two `apt.distUpgrade` calls with different dates would
+   * delete each other's marker on every run. Retired markers are therefore
+   * not pruned, and re-using an earlier date is skipped rather than re-run.
+   *
    * @param date - A date string used as the idempotency key (e.g. `"2024-01-15"`).
    * @param options - Optional per-call overrides (e.g. SSH command `timeout`).
    *   The same `timeout` is applied to every step of the dist-upgrade pipeline.
@@ -1977,9 +2008,9 @@ var apt = {
             );
             if (upgrade.code !== 0)
               return failedCommand("[apt.distUpgrade] apt-get dist-upgrade failed", upgrade);
-            const flagFailure = await setVersionedFlag(ssh2, flagName, "apt-dist-upgrade-");
+            const flagFailure = await setFlag(ssh2, flagName);
             if (flagFailure) return flagFailure;
-            return { status: "changed" };
+            return { detail: describeAptUpgradeOutcome(upgrade.stdout), status: "changed" };
           },
           flagName
         });
@@ -2519,6 +2550,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 +2619,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 +2676,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 +2717,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 +3097,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 +3111,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);
 }
@@ -5354,18 +5394,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) {
@@ -5564,7 +5608,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)) {
@@ -6922,18 +6966,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";
@@ -6949,8 +7002,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;
   }
@@ -6963,7 +7016,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);
@@ -6972,7 +7027,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);
@@ -7011,10 +7068,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}`
@@ -10689,6 +10746,7 @@ async function runVersionedInstall(parameters) {
 
 // src/modules/package.ts
 var EXEC_OPTS12 = { ignoreExitCode: true, silent: true };
+var PACKAGE_INDEX_REFRESHED_DETAIL = "marker was missing, package index refreshed";
 function execOptions(options) {
   if (options?.timeout === void 0) return EXEC_OPTS12;
   return { ...EXEC_OPTS12, timeout: options.timeout };
@@ -10920,7 +10978,16 @@ var pkg = {
    * A flag file at `${FLAGS_DIRECTORY}/package-update-<date>` is created after
    * a successful run. On the next run the flag is detected and the module
    * reports `"ok"` without running the update again. Changing `date` to a new
-   * value invalidates all previous flags for this operation.
+   * value selects a new flag file, so the update runs once more.
+   *
+   * The marker is written with `setFlag`, not `setVersionedFlag`: the flag
+   * name carries no call-site identity, only the date. An evicting prefix
+   * would therefore be host-global, and two `package.update` calls with
+   * different dates would delete each other's marker on every run so that
+   * neither could ever converge. Two consequences are accepted deliberately:
+   * markers for retired dates are not pruned (one empty file per distinct
+   * date), and re-using an earlier date is skipped rather than re-run,
+   * because that marker still exists.
    *
    * @param date - A date string used as the idempotency key (e.g. `"2024-01-15"`).
    * @param options - Optional per-call overrides (e.g. SSH command `timeout`).
@@ -10942,9 +11009,9 @@ var pkg = {
         if (result.code !== 0) {
           return failedCommand(`[package.update: ${date}] package index refresh failed`, result);
         }
-        const flagFailure = await setVersionedFlag(ssh2, flagName, "package-update-");
+        const flagFailure = await setFlag(ssh2, flagName);
         if (flagFailure) return flagFailure;
-        return { status: "changed" };
+        return { detail: PACKAGE_INDEX_REFRESHED_DETAIL, status: "changed" };
       },
       async check(ssh2) {
         if (!ssh2) return NEEDS_APPLY;
@@ -10959,7 +11026,13 @@ var pkg = {
    * A flag file at `${FLAGS_DIRECTORY}/package-upgrade-<date>` is created after
    * a successful run. On the next run the flag is detected and the module
    * reports `"ok"` without running the upgrade again. Changing `date` to a new
-   * value invalidates all previous flags for this operation.
+   * value selects a new flag file, so the upgrade runs once more.
+   *
+   * The marker is written with `setFlag` for the same reason as in
+   * `pkg.update`: the flag name carries only the date, so an
+   * evicting prefix would be host-global and sibling calls could never
+   * converge. Retired markers are therefore not pruned, and re-using an
+   * earlier date is skipped rather than re-run.
    *
    * On apt systems this runs `dpkg --configure -a`, `apt-get update`, and
    * `apt-get upgrade -y` as three separate commands (each subject to its own
@@ -10985,15 +11058,20 @@ var pkg = {
         const pm = await detectPackageManager(ssh2);
         if (!pm) return missingPackageManager(`package.upgrade: ${date}`);
         const pipelineOptions = execOptions(options);
+        let lastStdout = "";
         for (const command2 of UPGRADE_COMMANDS[pm]) {
           const result = await ssh2.exec(command2, pipelineOptions);
           if (result.code !== 0) {
             return failedCommand(`[package.upgrade: ${date}] package upgrade failed`, result);
           }
+          lastStdout = result.stdout;
         }
-        const flagFailure = await setVersionedFlag(ssh2, flagName, "package-upgrade-");
+        const flagFailure = await setFlag(ssh2, flagName);
         if (flagFailure) return flagFailure;
-        return { status: "changed" };
+        return {
+          detail: pm === "apt" ? describeAptUpgradeOutcome(lastStdout) : UNKNOWN_UPGRADE_OUTCOME_DETAIL,
+          status: "changed"
+        };
       },
       async check(ssh2) {
         if (!ssh2) return NEEDS_APPLY;

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.16.0-81f051d");
+  printCliHeader("0.17.0-a7265db");
   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.16.0-81f051d");
+program.name("paratix").description("Idempotent VPS setup tool in TypeScript").version("0.17.0-a7265db");
 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-N3n0FmKh.d.ts → index-CGYwJDTf.d.ts}

@@ -429,7 +429,16 @@ declare const pkg: {
      * A flag file at `${FLAGS_DIRECTORY}/package-update-<date>` is created after
      * a successful run. On the next run the flag is detected and the module
      * reports `"ok"` without running the update again. Changing `date` to a new
-     * value invalidates all previous flags for this operation.
+     * value selects a new flag file, so the update runs once more.
+     *
+     * The marker is written with `setFlag`, not `setVersionedFlag`: the flag
+     * name carries no call-site identity, only the date. An evicting prefix
+     * would therefore be host-global, and two `package.update` calls with
+     * different dates would delete each other's marker on every run so that
+     * neither could ever converge. Two consequences are accepted deliberately:
+     * markers for retired dates are not pruned (one empty file per distinct
+     * date), and re-using an earlier date is skipped rather than re-run,
+     * because that marker still exists.
      *
      * @param date - A date string used as the idempotency key (e.g. `"2024-01-15"`).
      * @param options - Optional per-call overrides (e.g. SSH command `timeout`).
@@ -446,7 +455,13 @@ declare const pkg: {
      * A flag file at `${FLAGS_DIRECTORY}/package-upgrade-<date>` is created after
      * a successful run. On the next run the flag is detected and the module
      * reports `"ok"` without running the upgrade again. Changing `date` to a new
-     * value invalidates all previous flags for this operation.
+     * value selects a new flag file, so the upgrade runs once more.
+     *
+     * The marker is written with `setFlag` for the same reason as in
+     * `pkg.update`: the flag name carries only the date, so an
+     * evicting prefix would be host-global and sibling calls could never
+     * converge. Retired markers are therefore not pruned, and re-using an
+     * earlier date is skipped rather than re-run.
      *
      * On apt systems this runs `dpkg --configure -a`, `apt-get update`, and
      * `apt-get upgrade -y` as three separate commands (each subject to its own
@@ -504,6 +519,12 @@ declare const apt: {
      * The pipeline is split into three separate SSH commands so that each step
      * gets its own timeout window and produces a precise failure label.
      *
+     * The marker is written with `setFlag`: the flag name carries only the
+     * date and no call-site identity, so an evicting prefix would be
+     * host-global and two `apt.distUpgrade` calls with different dates would
+     * delete each other's marker on every run. Retired markers are therefore
+     * not pruned, and re-using an earlier date is skipped rather than re-run.
+     *
      * @param date - A date string used as the idempotency key (e.g. `"2024-01-15"`).
      * @param options - Optional per-call overrides (e.g. SSH command `timeout`).
      *   The same `timeout` is applied to every step of the dist-upgrade pipeline.
@@ -1017,7 +1038,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.

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-N3n0FmKh.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-N3n0FmKh.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-CGYwJDTf.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-CGYwJDTf.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-56SN6NQH.js";
+} from "./chunk-NXU7K6HY.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-N3n0FmKh.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-CGYwJDTf.js';

package/dist/modules/index.js

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

package/llm-guide.md

@@ -142,12 +142,12 @@ export default server({
 
 ### `apt`
 
-| Method            | Signature                                                                                | Idempotent           |
-| ----------------- | ---------------------------------------------------------------------------------------- | -------------------- |
-| `apt.debconf`     | `(packageName: string, selections: Record<string, string>): Module`                      | Yes                  |
-| `apt.distUpgrade` | `(date: string, options?: UpgradeOptions): Module`                                       | Yes (versioned flag) |
-| `apt.key`         | `(name: string, url: string, options: { fingerprint: string }): Module`                  | Yes                  |
-| `apt.repository`  | `(nameOrPpa: string, source?: string, options?: { signedBy?: false \| string }): Module` | Yes                  |
+| Method            | Signature                                                                                | Idempotent       |
+| ----------------- | ---------------------------------------------------------------------------------------- | ---------------- |
+| `apt.debconf`     | `(packageName: string, selections: Record<string, string>): Module`                      | Yes              |
+| `apt.distUpgrade` | `(date: string, options?: UpgradeOptions): Module`                                       | Yes (dated flag) |
+| `apt.key`         | `(name: string, url: string, options: { fingerprint: string }): Module`                  | Yes              |
+| `apt.repository`  | `(nameOrPpa: string, source?: string, options?: { signedBy?: false \| string }): Module` | Yes              |
 
 ### `archive`
 
@@ -224,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.
@@ -279,12 +288,12 @@ that are expected to respond more slowly.
 
 Import with renaming: `import { package as pkg } from "paratix/modules"`. The word `package` is reserved in JavaScript, so you must alias it.
 
-| Method              | Signature                                                                         | Idempotent           |
-| ------------------- | --------------------------------------------------------------------------------- | -------------------- |
-| `package.installed` | `(...packagesAndOptions: Array<string \| PackageSpec \| UpgradeOptions>): Module` | Yes                  |
-| `package.absent`    | `(...packagesAndOptions: Array<string \| PackageSpec \| UpgradeOptions>): Module` | Yes                  |
-| `package.update`    | `(date: string, options?: UpgradeOptions): Module`                                | Yes (versioned flag) |
-| `package.upgrade`   | `(date: string, options?: UpgradeOptions): Module`                                | Yes (versioned flag) |
+| Method              | Signature                                                                         | Idempotent       |
+| ------------------- | --------------------------------------------------------------------------------- | ---------------- |
+| `package.installed` | `(...packagesAndOptions: Array<string \| PackageSpec \| UpgradeOptions>): Module` | Yes              |
+| `package.absent`    | `(...packagesAndOptions: Array<string \| PackageSpec \| UpgradeOptions>): Module` | Yes              |
+| `package.update`    | `(date: string, options?: UpgradeOptions): Module`                                | Yes (dated flag) |
+| `package.upgrade`   | `(date: string, options?: UpgradeOptions): Module`                                | Yes (dated flag) |
 
 #### `UpgradeOptions`
 
@@ -533,6 +542,7 @@ function myCustomModule(configPath: string, content: string): Module {
 - Prefer `failedCommand("...", result)` when you used `ssh.exec(..., { ignoreExitCode: true })` and want stdout/stderr preserved for central runner output.
 - Return `NEEDS_APPLY` (the exported constant), never the string literal `"needs-apply"`.
 - `ModuleResult.status` must be one of: `"changed"`, `"failed"`, `"ok"`, `"skipped"`.
+- Optionally return `ModuleResult.detail` with a short single-line reason; the runner appends it to the step line. Use it to say what a `changed` step actually did, and leave it unset when the step did no work. See [Status Detail on Changed Steps](#status-detail-on-changed-steps).
 - Use typed `meta` entries in the return value, not loose objects.
 - For normal downstream environment propagation, use `meta.env(name, value)`.
 - `meta.env(...)` accepts strings, numbers, booleans, sync lazy functions, and async lazy functions.
@@ -773,6 +783,43 @@ async check(ssh) {
 }
 ```
 
+## Status Detail on Changed Steps
+
+A module may return a short `detail` next to its status. The runner appends it to
+the step line, both for top-level modules and for steps inside a recipe:
+
+```
+· · ↺  package.upgrade: 2026-03-01    changed  no packages upgraded  4.1s
+```
+
+The dated-flag modules use this to say **why** they ran. Their step name already
+carries the date, so the detail reports the outcome instead of repeating the key.
+This matters most for the upgrade modules: they report `changed` whenever their
+dated marker is absent, even when the package manager upgraded nothing.
+
+| Module            | Detail on `changed`                                                     |
+| ----------------- | ----------------------------------------------------------------------- |
+| `package.update`  | `marker was missing, package index refreshed`                           |
+| `package.upgrade` | `12 packages upgraded`, `1 package upgraded`, or `no packages upgraded` |
+| `apt.distUpgrade` | same forms as `package.upgrade`                                         |
+
+Rules:
+
+- The count is parsed from apt's upgrade summary. `package.upgrade` also serves
+  `dnf`, `yum` and `apk`, whose summaries differ; those report
+  `upgrade completed, package count unavailable`.
+- The same fallback applies when the summary line is missing from the output, or
+  when the captured output was truncated at `maxOutputBytes`. apt prints its
+  summary last, so a truncated capture loses exactly that line, and reporting no
+  count is preferred over reporting a wrong one.
+- A step that did no work carries no detail: the flag-already-exists path returns
+  a plain `ok`, and failures report through the normal error path.
+- Dry runs keep the generic `changed (dry-run)` suffix. The detail is produced by
+  `apply`, which does not run in dry-run mode.
+
+Custom modules may return `detail` the same way; see
+[Key rules for custom modules](#key-rules-for-custom-modules).
+
 ## Dry-Run Diff Output (`--diff`)
 
 Paratix runs a playbook in dry-run mode via `paratix apply <file> --dry-run`, which
@@ -876,7 +923,7 @@ The diff string is plain text — no ANSI codes. The output layer applies colors
 5. Use `{{KEY|shell}}` or `{{KEY|raw}}` placeholders in `.tmpl` files — strict mode is on by default and bare `{{KEY}}` will throw. Provide values via `env` in `server()`.
 6. Use `service.restart()` and `service.reload()` as `signals` in recipes, not directly in `run`.
 7. Use `signals.flush()` only as an explicit checkpoint when staged flows require an early signal flush.
-8. Always pass a date string to `package.upgrade()` and `package.update()` -- it is the idempotency key.
+8. Always pass a date string to `package.upgrade()` and `package.update()` -- it is the idempotency key. Each distinct date keeps its own flag file, so several calls with different dates coexist; a date that was already applied stays applied and is not re-run. Read the step's [status detail](#status-detail-on-changed-steps) to tell a real upgrade from a step that only wrote its marker.
 9. Specify `ssh.ports` as an array -- the runner tries each port in order.
 10. Custom modules must implement both `check` and `apply`, both async.
 11. Use `shellQuote()` when interpolating dynamic values into shell commands.

package/package.json

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