paratix 0.8.0 → 0.10.0

package/dist/{user-BJMqDePy.d.ts → user-CJDqZC8n.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).
@@ -270,6 +382,22 @@ type CronJobOptions = {
  * idempotent and safely repeatable.
  */
 declare const cron: {
+    /**
+     * Ensure a cron job is absent from a user's crontab.
+     *
+     * Removes the `# paratix: <name>` marker comment and the crontab line
+     * directly below it. If the marker is not found, the module reports `ok`
+     * without writing the crontab. When the crontab becomes empty after the
+     * removal, it is deleted entirely via `crontab -r`.
+     *
+     * Equivalent to `cron.job(user, name, { job: "<unused>", state: "absent" })`,
+     * but does not require a placeholder `job` argument.
+     *
+     * @param user - The target user whose crontab is managed.
+     * @param name - Unique identifier of the cron job marker to remove.
+     * @returns A Module that ensures the cron job entry is absent.
+     */
+    absent(user: string, name: string): Module;
     /**
      * Ensure a cron job is present in (or absent from) a user's crontab.
      *
@@ -811,88 +939,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 +1486,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

@@ -67,6 +67,7 @@ import {
   sysctl,
   system,
   systemd,
+  timer,
   ufw,
   user,
 } from "paratix/modules"
@@ -133,7 +134,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                  |
 
@@ -151,9 +152,14 @@ export default server({
 
 ### `cron`
 
-| Method     | Signature                                                                                       | Idempotent |
-| ---------- | ----------------------------------------------------------------------------------------------- | ---------- |
-| `cron.job` | `(user: string, name: string, options: { job: string; state?: "absent" \| "present" }): Module` | Yes        |
+| Method        | Signature                                                                                       | Idempotent |
+| ------------- | ----------------------------------------------------------------------------------------------- | ---------- |
+| `cron.job`    | `(user: string, name: string, options: { job: string; state?: "absent" \| "present" }): Module` | Yes        |
+| `cron.absent` | `(user: string, name: string): Module`                                                          | Yes        |
+
+`cron.absent(user, name)` is the dedicated uninstall variant: it removes a
+managed cron entry without requiring a placeholder `job` argument. Use it as
+the idiomatic way to ensure a previously installed cron job is gone.
 
 ### `compose`
 
@@ -227,12 +233,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`
 
@@ -314,6 +340,40 @@ rsync SSH process and does not depend on a local `known_hosts` entry.
 | `systemd.masked`       | `(name: string): Module`                  | Yes                                |
 | `systemd.unmasked`     | `(name: string): Module`                  | Yes                                |
 
+### `timer`
+
+| Method            | Signature                                                                                                                                                                                                                                                                                                                             | Idempotent |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `timer.scheduled` | `(name: string, options: { accuracySec?: number \| string; description?: string; environment?: Record<string, string>; exec: string; group?: string; onCalendar: string \| string[]; persistent?: boolean; randomizedDelaySec?: number \| string; state?: "absent" \| "present"; user?: string; workingDirectory?: string }): Module` | Yes        |
+| `timer.absent`    | `(name: string): Module`                                                                                                                                                                                                                                                                                                              | Yes        |
+
+`timer.absent(name)` is the dedicated uninstall variant: it disables and stops
+the timer, removes both unit files, and reloads systemd, without requiring
+placeholder `exec`/`onCalendar` values.
+
+`timer.scheduled` is the systemd-timer equivalent of `cron.job`. It writes
+`<name>.service` (`Type=oneshot`) and `<name>.timer` to `/etc/systemd/system/`,
+reloads systemd, and runs `systemctl enable --now <name>.timer`. Use it as the
+default for new scheduled tasks: `Persistent=true` is on by default so missed
+runs are caught up after downtime, and logs land in journald (`journalctl -u
+<name>.service`). Cron remains a fit for ad-hoc per-user crontab entries.
+
+```typescript
+timer.scheduled("backup", {
+  exec: "/usr/local/bin/backup",
+  onCalendar: "*-*-* 03:00:00",
+})
+
+timer.scheduled("cleanup", {
+  exec: "/usr/local/bin/cleanup",
+  onCalendar: ["Mon..Fri 02:00", "Sat 04:00"],
+  user: "deploy",
+  randomizedDelaySec: 300,
+})
+
+timer.absent("legacy-task")
+```
+
 ### `ufw`
 
 | Method         | Signature                                                        | Idempotent |

package/package.json

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