paratix 0.8.0 → 0.9.0

package/dist/cli.js

@@ -698,7 +698,7 @@ async function loadServerDefinitionFromFile(file, options) {
   return definition;
 }
 var program = new Command();
-program.name("paratix").description("Idempotent VPS setup tool in TypeScript").version("0.8.0-93d397c");
+program.name("paratix").description("Idempotent VPS setup tool in TypeScript").version("0.9.0-e478726");
 program.command("apply <file>").description("Apply a server definition").option(
   "--dry-run",
   "Only check, do not apply. Some modules validate prospective config but cannot verify runtime restarts.",
@@ -710,7 +710,7 @@ program.command("apply <file>").description("Apply a server definition").option(
   DEFAULT_RECONNECT_TIMEOUT_SECONDS
 ).option("--verbose", "Show full stack traces on error", false).action(async (file, options) => {
   try {
-    printCliHeader("0.8.0-93d397c");
+    printCliHeader("0.9.0-e478726");
     const environmentOverrides = applyCliEnvironmentOverrides(
       // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Commander options typed as Record<string, unknown>
       options.env,

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { E as Environment, M as Module, a as ModuleMetaEntry, b as MetaEnvironmentValue, c as EnvironmentMetaEntry, d as SshdPortMetaEntry, e as SystemHostMetaEntry, f as SystemRebootMetaEntry, g as ModuleResult, h as ExecResult, i as ModuleStatus, j as SshConnection, O as OrchestrationStep, S as ServerDefinition } from './types-Cl2Muw1x.js';
 export { k as EnvironmentValue, l as ExecOptions, N as NEEDS_APPLY, m as SshConfig } from './types-Cl2Muw1x.js';
-export { a as apt, b as archive, c as command, d as compose, e as cron, f as download, g as file, h as git, i as group, j as hostname, m as mount, n as net, o as op, p as package, q as quadlet, r as releaseUpgrade, k as rsync, s as script, l as service, t as ssh, u as sshd, v as sysctl, w as system, x as systemd, y as ufw, z as user } from './user-BJMqDePy.js';
+export { a as apt, b as archive, c as command, d as compose, e as cron, f as download, g as file, h as git, i as group, j as hostname, m as mount, n as net, o as op, p as package, q as quadlet, r as releaseUpgrade, k as rsync, s as script, l as service, t as ssh, u as sshd, v as sysctl, w as system, x as systemd, y as ufw, z as user } from './user-B9lkXr0X.js';
 
 /**
  * Fail the run if a condition on the current env is not satisfied.

package/dist/index.js

@@ -39,7 +39,7 @@ import {
   systemd,
   ufw,
   user
-} from "./chunk-FFQ6FR4N.js";
+} from "./chunk-7Y2RBVG4.js";
 import {
   CommandError,
   assertValidModuleMetaEntries,

package/dist/modules/index.d.ts

@@ -1,4 +1,4 @@
-export { a as apt, b as archive, c as command, d as compose, e as cron, f as download, g as file, h as git, i as group, j as hostname, m as mount, n as net, o as op, p as package, q as quadlet, r as releaseUpgrade, k as rsync, s as script, l as service, t as ssh, u as sshd, v as sysctl, w as system, x as systemd, y as ufw, z as user } from '../user-BJMqDePy.js';
+export { U as UpgradeOptions, a as apt, b as archive, c as command, d as compose, e as cron, f as download, g as file, h as git, i as group, j as hostname, m as mount, n as net, o as op, p as package, q as quadlet, r as releaseUpgrade, k as rsync, s as script, l as service, t as ssh, u as sshd, v as sysctl, w as system, x as systemd, y as ufw, z as user } from '../user-B9lkXr0X.js';
 import { M as Module } from '../types-Cl2Muw1x.js';
 
 /**

package/dist/modules/index.js

@@ -26,7 +26,7 @@ import {
   systemd,
   ufw,
   user
-} from "../chunk-FFQ6FR4N.js";
+} from "../chunk-7Y2RBVG4.js";
 import "../chunk-NRDLYHJL.js";
 export {
   apt,

package/dist/{user-BJMqDePy.d.ts → user-B9lkXr0X.d.ts}

@@ -1,5 +1,108 @@
 import { M as Module } from './types-Cl2Muw1x.js';
 
+/** Per-call overrides for package operations that can take a long time. */
+type UpgradeOptions = {
+    /** Override the SSH layer's command timeout (milliseconds). */
+    timeout?: number;
+};
+/**
+ * Distro-agnostic package management module.
+ *
+ * Automatically detects the system package manager (apt, dnf, yum, apk)
+ * and delegates to the appropriate commands. All methods are idempotent.
+ *
+ * For Debian/Ubuntu-specific configuration (debconf pre-seeding, GPG keys,
+ * apt repositories) use the `apt` module instead.
+ *
+ * @example
+ * // Install packages
+ * pkg.installed("git", "curl")
+ *
+ * @example
+ * // Refresh package lists and upgrade all packages on a specific date
+ * pkg.update("2024-01-15")
+ * pkg.upgrade("2024-01-15")
+ */
+declare const pkg: {
+    /**
+     * Ensure the given packages are not installed.
+     *
+     * The check phase queries the package database for each package individually;
+     * the remove command is only executed when at least one package is present.
+     *
+     * Pass an `UpgradeOptions` object as the last argument to override the SSH
+     * timeout for slow remove operations.
+     *
+     * @param packagesAndOptions - One or more package names, optionally followed
+     *   by an `UpgradeOptions` object as the last argument.
+     * @returns A Module that removes the packages if any are present.
+     *
+     * @example
+     * pkg.absent("vim", "nano")
+     * pkg.absent("vim", "nano", { timeout: 600_000 })
+     */
+    absent(...packagesAndOptions: Array<string | UpgradeOptions>): Module;
+    /**
+     * Ensure the given packages are installed.
+     *
+     * The check phase queries the package database for each package individually;
+     * the install command is only executed when at least one package is missing.
+     *
+     * Pass an `UpgradeOptions` object as the last argument to override the SSH
+     * timeout for slow install operations.
+     *
+     * @param packagesAndOptions - One or more package names, optionally followed
+     *   by an `UpgradeOptions` object as the last argument.
+     * @returns A Module that installs missing packages.
+     *
+     * @example
+     * pkg.installed("git", "curl", "unzip")
+     * pkg.installed("texlive-full", { timeout: 900_000 })
+     */
+    installed(...packagesAndOptions: Array<string | UpgradeOptions>): Module;
+    /**
+     * Refresh the package manager's package lists once per dated flag.
+     *
+     * 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.
+     *
+     * @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`).
+     * @returns A Module that refreshes package lists.
+     *
+     * @example
+     * pkg.update("2024-01-15")
+     * pkg.update("2024-01-15", { timeout: 600_000 })
+     */
+    update(date: string, options?: UpgradeOptions): Module;
+    /**
+     * Upgrade all installed packages once per dated flag.
+     *
+     * 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.
+     *
+     * 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
+     * SSH `timeout`). For full dependency resolution use `apt.distUpgrade`.
+     *
+     * @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 upgrade pipeline.
+     * @returns A Module that upgrades all packages.
+     *
+     * @example
+     * pkg.upgrade("2024-01-15")
+     * pkg.upgrade("2024-01-15", { timeout: 900_000 })
+     *
+     * @see apt.distUpgrade
+     */
+    upgrade(date: string, options?: UpgradeOptions): Module;
+};
+
 /**
  * Modules for Debian/Ubuntu-specific apt configuration.
  *
@@ -35,10 +138,19 @@ declare const apt: {
      * Run `apt-get update && apt-get dist-upgrade` once per dated flag.
      * Performs a full distribution upgrade with dependency resolution.
      *
+     * The pipeline is split into three separate SSH commands so that each step
+     * gets its own timeout window and produces a precise failure label.
+     *
      * @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.
      * @returns A Module that performs the dist-upgrade.
+     *
+     * @example
+     * apt.distUpgrade("2024-01-15")
+     * apt.distUpgrade("2024-01-15", { timeout: 900_000 })
      */
-    distUpgrade(date: string): Module;
+    distUpgrade(date: string, options?: UpgradeOptions): Module;
     /**
      * Import a GPG key into `/etc/apt/keyrings/` for use with signed repositories.
      * @param name - Key file name (without `.gpg` extension).
@@ -811,88 +923,6 @@ declare const op: {
     resolve(references: Record<string, string>): Module;
 };
 
-/**
- * Distro-agnostic package management module.
- *
- * Automatically detects the system package manager (apt, dnf, yum, apk)
- * and delegates to the appropriate commands. All methods are idempotent.
- *
- * For Debian/Ubuntu-specific configuration (debconf pre-seeding, GPG keys,
- * apt repositories) use the `apt` module instead.
- *
- * @example
- * // Install packages
- * pkg.installed("git", "curl")
- *
- * @example
- * // Refresh package lists and upgrade all packages on a specific date
- * pkg.update("2024-01-15")
- * pkg.upgrade("2024-01-15")
- */
-declare const pkg: {
-    /**
-     * Ensure the given packages are not installed.
-     *
-     * The check phase queries the package database for each package individually;
-     * the remove command is only executed when at least one package is present.
-     *
-     * @param packages - One or more package names to remove.
-     * @returns A Module that removes the packages if any are present.
-     *
-     * @example
-     * pkg.absent("vim", "nano")
-     */
-    absent(...packages: string[]): Module;
-    /**
-     * Ensure the given packages are installed.
-     *
-     * The check phase queries the package database for each package individually;
-     * the install command is only executed when at least one package is missing.
-     *
-     * @param packages - One or more package names to install.
-     * @returns A Module that installs missing packages.
-     *
-     * @example
-     * pkg.installed("git", "curl", "unzip")
-     */
-    installed(...packages: string[]): Module;
-    /**
-     * Refresh the package manager's package lists once per dated flag.
-     *
-     * 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.
-     *
-     * @param date - A date string used as the idempotency key (e.g. `"2024-01-15"`).
-     * @returns A Module that refreshes package lists.
-     *
-     * @example
-     * pkg.update("2024-01-15")
-     */
-    update(date: string): Module;
-    /**
-     * Upgrade all installed packages once per dated flag.
-     *
-     * 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.
-     *
-     * On apt systems this runs `apt-get update && apt-get upgrade -y` (not
-     * `dist-upgrade`); use `apt.distUpgrade` for full dependency resolution.
-     *
-     * @param date - A date string used as the idempotency key (e.g. `"2024-01-15"`).
-     * @returns A Module that upgrades all packages.
-     *
-     * @example
-     * pkg.upgrade("2024-01-15")
-     *
-     * @see apt.distUpgrade
-     */
-    upgrade(date: string): Module;
-};
-
 type QuadletAutoUpdate = "local" | "registry";
 type QuadletHealthOnFailure = "kill" | "none" | "restart" | "stop";
 type QuadletPullPolicy = "always" | "missing" | "never" | "newer";
@@ -1440,4 +1470,4 @@ declare const user: {
     present(name: string, options?: UserOptions): Module;
 };
 
-export { apt as a, archive as b, command as c, compose as d, cron as e, download as f, file as g, git as h, group as i, hostname as j, rsync as k, service as l, mount as m, net as n, op as o, pkg as p, quadlet as q, releaseUpgrade as r, script as s, ssh as t, sshd as u, sysctl as v, system as w, systemd as x, ufw as y, user as z };
+export { type UpgradeOptions as U, apt as a, archive as b, command as c, compose as d, cron as e, download as f, file as g, git as h, group as i, hostname as j, rsync as k, service as l, mount as m, net as n, op as o, pkg as p, quadlet as q, releaseUpgrade as r, script as s, ssh as t, sshd as u, sysctl as v, system as w, systemd as x, ufw as y, user as z };

package/llm-guide.md

@@ -133,7 +133,7 @@ export default server({
 | Method            | Signature                                                                                | Idempotent           |
 | ----------------- | ---------------------------------------------------------------------------------------- | -------------------- |
 | `apt.debconf`     | `(packageName: string, selections: Record<string, string>): Module`                      | Yes                  |
-| `apt.distUpgrade` | `(date: string): Module`                                                                 | Yes (versioned flag) |
+| `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                  |
 
@@ -227,12 +227,32 @@ export default server({
 
 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` | `(...packages: string[]): Module` | Yes                  |
-| `package.absent`    | `(...packages: string[]): Module` | Yes                  |
-| `package.update`    | `(date: string): Module`          | Yes (versioned flag) |
-| `package.upgrade`   | `(date: string): Module`          | Yes (versioned flag) |
+| Method              | Signature                                                          | Idempotent           |
+| ------------------- | ------------------------------------------------------------------ | -------------------- |
+| `package.installed` | `(...packagesAndOptions: Array<string \| UpgradeOptions>): Module` | Yes                  |
+| `package.absent`    | `(...packagesAndOptions: Array<string \| UpgradeOptions>): Module` | Yes                  |
+| `package.update`    | `(date: string, options?: UpgradeOptions): Module`                 | Yes (versioned flag) |
+| `package.upgrade`   | `(date: string, options?: UpgradeOptions): Module`                 | Yes (versioned flag) |
+
+#### `UpgradeOptions`
+
+```typescript
+type UpgradeOptions = {
+  timeout?: number // Override SSH command timeout (ms). Same value applies to every step
+  // of multi-step pipelines (apt upgrade, apk upgrade, apt dist-upgrade).
+}
+```
+
+For `package.installed` / `package.absent`, pass the options object as the **last** argument
+after the package names; existing variadic call sites such as `pkg.installed("git", "curl")`
+keep working unchanged. Use a longer `timeout` for slow operations on production servers
+with large update backlogs:
+
+```typescript
+pkg.upgrade("2026-05-01", { timeout: 900_000 })
+pkg.installed("texlive-full", { timeout: 900_000 })
+apt.distUpgrade("2026-05-01", { timeout: 1_200_000 })
+```
 
 ### `quadlet`
 

package/package.json

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