paratix 0.16.1 → 0.17.0

package/dist/{chunk-KC7XBI77.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
         });
@@ -10715,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 };
@@ -10946,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`).
@@ -10968,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;
@@ -10985,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
@@ -11011,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.1-728d4e1");
+  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.1-728d4e1");
+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-jbXRUlJ6.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.

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-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';
+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-KC7XBI77.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-jbXRUlJ6.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-KC7XBI77.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`
 
@@ -288,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`
 
@@ -542,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.
@@ -782,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
@@ -885,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.1",
+  "version": "0.17.0",
   "description": "Idempotent VPS setup tool in TypeScript",
   "type": "module",
   "files": [