paratix 0.8.0 → 0.10.0

package/dist/{chunk-FFQ6FR4N.js → chunk-M7GETOJ5.js}

@@ -173,6 +173,11 @@ async function setFlag(ssh2, flagName) {
 // src/modules/apt.ts
 var NONINTERACTIVE = "DEBIAN_FRONTEND=noninteractive";
 var APT_REPOSITORY_MODE = "0644";
+var APT_BASE_EXEC_OPTS = { ignoreExitCode: true, silent: true };
+function aptExecOptions(options) {
+  if (options?.timeout === void 0) return APT_BASE_EXEC_OPTS;
+  return { ...APT_BASE_EXEC_OPTS, timeout: options.timeout };
+}
 var PPA_PREFIX = "ppa:";
 function parseDebconfOutput(stdout) {
   const values = {};
@@ -292,30 +297,31 @@ var 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) {
+  distUpgrade(date, options) {
     const flagName = `apt-dist-upgrade-${date}`;
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[apt.distUpgrade] SSH connection is required for ${date}`);
-        const update = await ssh2.exec(`${NONINTERACTIVE} apt-get update`, {
-          ignoreExitCode: true,
-          silent: true
-        });
+        const pipelineOptions = aptExecOptions(options);
+        const update = await ssh2.exec(`${NONINTERACTIVE} apt-get update`, pipelineOptions);
         if (update.code !== 0)
           return failedCommand("[apt.distUpgrade] apt-get update failed", update);
-        const configure = await ssh2.exec(`${NONINTERACTIVE} dpkg --configure -a`, {
-          ignoreExitCode: true,
-          silent: true
-        });
+        const configure = await ssh2.exec(`${NONINTERACTIVE} dpkg --configure -a`, pipelineOptions);
         if (configure.code !== 0)
           return failedCommand("[apt.distUpgrade] dpkg --configure -a failed", configure);
-        const upgrade = await ssh2.exec(`${NONINTERACTIVE} apt-get dist-upgrade -y`, {
-          ignoreExitCode: true,
-          silent: true
-        });
+        const upgrade = await ssh2.exec(`${NONINTERACTIVE} apt-get dist-upgrade -y`, pipelineOptions);
         if (upgrade.code !== 0)
           return failedCommand("[apt.distUpgrade] apt-get dist-upgrade failed", upgrade);
         await setVersionedFlag(ssh2, flagName, "apt-dist-upgrade-");
@@ -1117,7 +1123,48 @@ function hasMarkedJob(lines, marker, cronJob) {
   const index = lines.indexOf(marker);
   return index !== -1 && index + 1 < lines.length && lines[index + 1] === cronJob;
 }
+function assertCronName(name) {
+  if (new RegExp("[\\n\\r]", "v").test(name)) {
+    throw new Error(`cron: name must not contain newlines: ${JSON.stringify(name)}`);
+  }
+}
 var 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(user2, name) {
+    assertCronName(name);
+    const marker = `# paratix: ${name}`;
+    return {
+      async apply(ssh2) {
+        if (!ssh2) return failed(`[cron.absent: ${name} (${user2})] SSH connection is required`);
+        const lines = await readCrontab(ssh2, user2);
+        const markerIndex = lines.indexOf(marker);
+        if (markerIndex === -1) return { status: "ok" };
+        lines.splice(markerIndex, 2);
+        await writeCrontab(ssh2, user2, lines);
+        return { status: "changed" };
+      },
+      async check(ssh2) {
+        if (!ssh2) return NEEDS_APPLY;
+        const lines = await readCrontab(ssh2, user2);
+        return lines.includes(marker) ? NEEDS_APPLY : "ok";
+      },
+      name: `cron.absent: ${name} (${user2})`
+    };
+  },
   /**
    * Ensure a cron job is present in (or absent from) a user's crontab.
    *
@@ -1134,9 +1181,7 @@ var cron = {
    * @returns A Module that manages the cron job entry.
    */
   job(user2, name, options) {
-    if (new RegExp("[\\n\\r]", "v").test(name)) {
-      throw new Error(`cron.job: name must not contain newlines: ${JSON.stringify(name)}`);
-    }
+    assertCronName(name);
     if (new RegExp("[\\n\\r]", "v").test(options.job)) {
       throw new Error(`cron.job: job must not contain newlines: ${JSON.stringify(options.job)}`);
     }
@@ -3137,6 +3182,22 @@ var op = {
 
 // src/modules/package.ts
 var EXEC_OPTS6 = { ignoreExitCode: true, silent: true };
+function execOptions(options) {
+  if (options?.timeout === void 0) return EXEC_OPTS6;
+  return { ...EXEC_OPTS6, timeout: options.timeout };
+}
+function splitPackagesAndOptions(values) {
+  const packages = [];
+  let options;
+  for (const [index, value] of values.entries()) {
+    if (typeof value === "string") {
+      packages.push(value);
+    } else if (index === values.length - 1) {
+      options = value;
+    }
+  }
+  return { options, packages };
+}
 var pmCache = /* @__PURE__ */ new WeakMap();
 var INSTALL_COMMANDS = {
   apk: (pkgs) => `apk add ${pkgs}`,
@@ -3157,10 +3218,14 @@ var UPDATE_COMMANDS = {
   yum: "yum makecache"
 };
 var UPGRADE_COMMANDS = {
-  apk: "apk update && apk upgrade",
-  apt: "DEBIAN_FRONTEND=noninteractive dpkg --configure -a && DEBIAN_FRONTEND=noninteractive apt-get update && DEBIAN_FRONTEND=noninteractive apt-get upgrade -y",
-  dnf: "dnf upgrade -y",
-  yum: "yum update -y"
+  apk: ["apk update", "apk upgrade"],
+  apt: [
+    "DEBIAN_FRONTEND=noninteractive dpkg --configure -a",
+    "DEBIAN_FRONTEND=noninteractive apt-get update",
+    "DEBIAN_FRONTEND=noninteractive apt-get upgrade -y"
+  ],
+  dnf: ["dnf upgrade -y"],
+  yum: ["yum update -y"]
 };
 function missingPackageManager(moduleName) {
   return failed(`[${moduleName}] No supported package manager found (apt, dnf, yum, apk)`);
@@ -3200,13 +3265,19 @@ var pkg = {
    * 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.
+   * 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(...packages) {
+  absent(...packagesAndOptions) {
+    const { options, packages } = splitPackagesAndOptions(packagesAndOptions);
     if (packages.length === 0) {
       throw new Error("package.absent: at least one package name is required");
     }
@@ -3217,7 +3288,7 @@ var pkg = {
         const pm = await detectPackageManager(ssh2);
         if (!pm) return missingPackageManager(`package.absent: ${packages.join(", ")}`);
         const quoted = packages.map((p) => shellQuote(p)).join(" ");
-        const result = await ssh2.exec(REMOVE_COMMANDS[pm](quoted), EXEC_OPTS6);
+        const result = await ssh2.exec(REMOVE_COMMANDS[pm](quoted), execOptions(options));
         if (result.code !== 0) {
           return failedCommand(
             `[package.absent: ${packages.join(", ")}] package removal failed`,
@@ -3244,13 +3315,19 @@ var pkg = {
    * 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.
+   * 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(...packages) {
+  installed(...packagesAndOptions) {
+    const { options, packages } = splitPackagesAndOptions(packagesAndOptions);
     if (packages.length === 0) {
       throw new Error("package.installed: at least one package name is required");
     }
@@ -3262,7 +3339,7 @@ var pkg = {
         const pm = await detectPackageManager(ssh2);
         if (!pm) return missingPackageManager(`package.installed: ${packages.join(", ")}`);
         const quoted = packages.map((p) => shellQuote(p)).join(" ");
-        const result = await ssh2.exec(INSTALL_COMMANDS[pm](quoted), EXEC_OPTS6);
+        const result = await ssh2.exec(INSTALL_COMMANDS[pm](quoted), execOptions(options));
         if (result.code !== 0) {
           return failedCommand(
             `[package.installed: ${packages.join(", ")}] package installation failed`,
@@ -3292,19 +3369,21 @@ var pkg = {
    * 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) {
+  update(date, options) {
     const flagName = `package-update-${date}`;
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[package.update: ${date}] SSH connection is required`);
         const pm = await detectPackageManager(ssh2);
         if (!pm) return missingPackageManager(`package.update: ${date}`);
-        const result = await ssh2.exec(UPDATE_COMMANDS[pm], EXEC_OPTS6);
+        const result = await ssh2.exec(UPDATE_COMMANDS[pm], execOptions(options));
         if (result.code !== 0) {
           return failedCommand(`[package.update: ${date}] package index refresh failed`, result);
         }
@@ -3326,27 +3405,34 @@ var pkg = {
    * 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.
+   * 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) {
+  upgrade(date, options) {
     const flagName = `package-upgrade-${date}`;
     return {
       async apply(ssh2) {
         if (!ssh2) return failed(`[package.upgrade: ${date}] SSH connection is required`);
         const pm = await detectPackageManager(ssh2);
         if (!pm) return missingPackageManager(`package.upgrade: ${date}`);
-        const result = await ssh2.exec(UPGRADE_COMMANDS[pm], EXEC_OPTS6);
-        if (result.code !== 0) {
-          return failedCommand(`[package.upgrade: ${date}] package upgrade failed`, result);
+        const pipelineOptions = execOptions(options);
+        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);
+          }
         }
         await setVersionedFlag(ssh2, flagName, "package-upgrade-");
         return { status: "changed" };
@@ -5574,6 +5660,312 @@ var systemd = {
   }
 };
 
+// src/modules/timerHelpers.ts
+var SYSTEMD_DIRECTORY = "/etc/systemd/system";
+var TIMER_NAME_PATTERN = new RegExp("^[A-Za-z0-9_\\-]+$", "v");
+var ENVIRONMENT_KEY_PATTERN = new RegExp("^[A-Za-z_]\\w*$", "v");
+var ENVIRONMENT_VALUE_NEEDS_QUOTING = new RegExp('[\\s"\\\\]', "v");
+function assertNoNewline(field, value) {
+  if (new RegExp("[\\n\\r]", "v").test(value)) {
+    throw new Error(`timer.scheduled: ${field} must not contain newlines: ${JSON.stringify(value)}`);
+  }
+}
+function assertNotBlank(field, value) {
+  if (value.trim().length === 0) {
+    throw new Error(`timer.scheduled: ${field} must not be empty: ${JSON.stringify(value)}`);
+  }
+}
+function normalizeOnCalendar(onCalendar) {
+  const entries = Array.isArray(onCalendar) ? onCalendar : [onCalendar];
+  if (entries.length === 0) {
+    throw new Error("timer.scheduled: onCalendar must contain at least one entry");
+  }
+  for (const entry of entries) {
+    assertNoNewline("onCalendar entry", entry);
+    if (entry.trim().length === 0) {
+      throw new Error("timer.scheduled: onCalendar entries must not be empty");
+    }
+  }
+  return entries;
+}
+function quoteEnvironmentValue(value) {
+  if (!ENVIRONMENT_VALUE_NEEDS_QUOTING.test(value)) return value;
+  const escaped = value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
+  return `"${escaped}"`;
+}
+function renderServiceUnit(name, options) {
+  const description = options.description ?? `Paratix scheduled task: ${name}`;
+  const lines = ["[Unit]", `Description=${description}`, "", "[Service]", "Type=oneshot"];
+  if (options.user != null) lines.push(`User=${options.user}`);
+  if (options.group != null) lines.push(`Group=${options.group}`);
+  if (options.workingDirectory != null) {
+    lines.push(`WorkingDirectory=${options.workingDirectory}`);
+  }
+  if (options.environment) {
+    for (const [key, value] of Object.entries(options.environment)) {
+      lines.push(`Environment=${key}=${quoteEnvironmentValue(value)}`);
+    }
+  }
+  lines.push(`ExecStart=${options.exec}`);
+  return `${lines.join("\n")}
+`;
+}
+function renderTimerUnit(name, options) {
+  const description = options.description ?? `Paratix scheduled task: ${name}`;
+  const persistent = options.persistent ?? true;
+  const lines = ["[Unit]", `Description=${description} (timer)`, "", "[Timer]"];
+  for (const entry of normalizeOnCalendar(options.onCalendar)) {
+    lines.push(`OnCalendar=${entry}`);
+  }
+  if (persistent) lines.push("Persistent=true");
+  if (options.randomizedDelaySec != null) {
+    lines.push(`RandomizedDelaySec=${String(options.randomizedDelaySec)}`);
+  }
+  if (options.accuracySec != null) lines.push(`AccuracySec=${String(options.accuracySec)}`);
+  lines.push(`Unit=${name}.service`, "", "[Install]", "WantedBy=timers.target");
+  return `${lines.join("\n")}
+`;
+}
+function validateEnvironment(environment) {
+  for (const [key, value] of Object.entries(environment)) {
+    if (!ENVIRONMENT_KEY_PATTERN.test(key)) {
+      throw new Error(
+        `timer.scheduled: environment key must match ${String(ENVIRONMENT_KEY_PATTERN)}, got: ${JSON.stringify(key)}`
+      );
+    }
+    assertNoNewline(`environment[${key}]`, value);
+  }
+}
+function validatePresentOptions(options) {
+  assertNoNewline("exec", options.exec);
+  assertNotBlank("exec", options.exec);
+  const optionalStringFields = [
+    ["description", options.description],
+    ["user", options.user],
+    ["group", options.group],
+    ["workingDirectory", options.workingDirectory]
+  ];
+  for (const [field, value] of optionalStringFields) {
+    if (value != null) {
+      assertNoNewline(field, value);
+      assertNotBlank(field, value);
+    }
+  }
+  if (options.randomizedDelaySec != null) {
+    assertNoNewline("randomizedDelaySec", String(options.randomizedDelaySec));
+  }
+  if (options.accuracySec != null) {
+    assertNoNewline("accuracySec", String(options.accuracySec));
+  }
+  if (options.environment) validateEnvironment(options.environment);
+  normalizeOnCalendar(options.onCalendar);
+}
+function assertTimerName(name) {
+  if (!TIMER_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `timer: name must match ${String(TIMER_NAME_PATTERN)}, got: ${JSON.stringify(name)}`
+    );
+  }
+}
+function buildTimerLocations(name) {
+  return {
+    servicePath: `${SYSTEMD_DIRECTORY}/${name}.service`,
+    timerPath: `${SYSTEMD_DIRECTORY}/${name}.timer`,
+    timerUnit: `${name}.timer`
+  };
+}
+function buildTimerPaths(name, options) {
+  return {
+    ...buildTimerLocations(name),
+    serviceContent: renderServiceUnit(name, options),
+    timerContent: renderTimerUnit(name, options)
+  };
+}
+
+// src/modules/timer.ts
+var SYSTEMCTL5 = "systemctl";
+var UNIT_FILE_MODE = "0644";
+async function fileMatches(ssh2, path, expected) {
+  if (!await ssh2.exists(path)) return false;
+  const remote = await ssh2.readFile(path);
+  return remote.trim() === expected.trim();
+}
+async function checkPresent2(ssh2, paths) {
+  if (!await fileMatches(ssh2, paths.servicePath, paths.serviceContent)) return NEEDS_APPLY;
+  if (!await fileMatches(ssh2, paths.timerPath, paths.timerContent)) return NEEDS_APPLY;
+  const enabled = await ssh2.test(`${SYSTEMCTL5} is-enabled --quiet ${shellQuote(paths.timerUnit)}`);
+  if (!enabled) return NEEDS_APPLY;
+  const active = await ssh2.test(`${SYSTEMCTL5} is-active --quiet ${shellQuote(paths.timerUnit)}`);
+  return active ? "ok" : NEEDS_APPLY;
+}
+async function checkAbsent2(ssh2, locations) {
+  if (await ssh2.exists(locations.servicePath)) return NEEDS_APPLY;
+  if (await ssh2.exists(locations.timerPath)) return NEEDS_APPLY;
+  return "ok";
+}
+async function syncUnitFiles(ssh2, name, paths) {
+  const serviceMatched = await fileMatches(ssh2, paths.servicePath, paths.serviceContent);
+  const timerMatched = await fileMatches(ssh2, paths.timerPath, paths.timerContent);
+  if (!serviceMatched) {
+    await ssh2.writeFile(paths.servicePath, paths.serviceContent, { mode: UNIT_FILE_MODE });
+  }
+  if (!timerMatched) {
+    await ssh2.writeFile(paths.timerPath, paths.timerContent, { mode: UNIT_FILE_MODE });
+  }
+  if (!serviceMatched || !timerMatched) {
+    const reload = await ssh2.exec(`${SYSTEMCTL5} daemon-reload`, {
+      ignoreExitCode: true,
+      silent: true
+    });
+    if (reload.code !== 0) {
+      return {
+        failure: failedCommand(`[timer.scheduled: ${name}] systemctl daemon-reload failed`, reload),
+        ok: false
+      };
+    }
+  }
+  return { ok: true, serviceMatched, timerMatched };
+}
+async function isTimerFullyActive(ssh2, timerUnit) {
+  const enabled = await ssh2.test(`${SYSTEMCTL5} is-enabled --quiet ${shellQuote(timerUnit)}`);
+  if (!enabled) return false;
+  return ssh2.test(`${SYSTEMCTL5} is-active --quiet ${shellQuote(timerUnit)}`);
+}
+async function applyPresent(ssh2, name, paths) {
+  const sync = await syncUnitFiles(ssh2, name, paths);
+  if (!sync.ok) return sync.failure;
+  if (sync.serviceMatched && sync.timerMatched && await isTimerFullyActive(ssh2, paths.timerUnit)) {
+    return { status: "ok" };
+  }
+  const enable = await ssh2.exec(`${SYSTEMCTL5} enable --now ${shellQuote(paths.timerUnit)}`, {
+    ignoreExitCode: true,
+    silent: true
+  });
+  if (enable.code !== 0) {
+    return failedCommand(`[timer.scheduled: ${name}] systemctl enable --now failed`, enable);
+  }
+  if (!sync.timerMatched) {
+    const restart = await ssh2.exec(`${SYSTEMCTL5} restart ${shellQuote(paths.timerUnit)}`, {
+      ignoreExitCode: true,
+      silent: true
+    });
+    if (restart.code !== 0) {
+      return failedCommand(`[timer.scheduled: ${name}] systemctl restart failed`, restart);
+    }
+  }
+  return { status: "changed" };
+}
+async function applyAbsent(ssh2, context) {
+  const { locations, module, name } = context;
+  const serviceExists = await ssh2.exists(locations.servicePath);
+  const timerExists = await ssh2.exists(locations.timerPath);
+  if (!serviceExists && !timerExists) return { status: "ok" };
+  await ssh2.exec(`${SYSTEMCTL5} disable --now ${shellQuote(locations.timerUnit)}`, {
+    ignoreExitCode: true,
+    silent: true
+  });
+  const remove = await ssh2.exec(
+    `rm -f ${shellQuote(locations.timerPath)} ${shellQuote(locations.servicePath)}`,
+    { ignoreExitCode: true, silent: true }
+  );
+  if (remove.code !== 0) {
+    return failedCommand(`[${module}: ${name}] failed to remove unit files`, remove);
+  }
+  const reload = await ssh2.exec(`${SYSTEMCTL5} daemon-reload`, {
+    ignoreExitCode: true,
+    silent: true
+  });
+  if (reload.code !== 0) {
+    return failedCommand(`[${module}: ${name}] systemctl daemon-reload failed`, reload);
+  }
+  return { status: "changed" };
+}
+var timer = {
+  /**
+   * Ensure a systemd timer-driven scheduled task does not exist.
+   *
+   * Disables and stops `<name>.timer`, removes both `<name>.service` and
+   * `<name>.timer` from `/etc/systemd/system/`, and reloads systemd. The
+   * `disable --now` step also removes the timer's `wants/` symlink. Failure
+   * to disable a unit that does not exist is ignored, so this method is
+   * safe to apply repeatedly.
+   *
+   * Behaves like `timer.scheduled(name, { exec: "<unused>", onCalendar: "<unused>", state: "absent" })`,
+   * but does not require placeholder values for `exec` or `onCalendar` and
+   * reports failures with a `timer.absent` prefix instead of `timer.scheduled`.
+   *
+   * @param name - Base unit name without extension. Must match
+   *   `^[A-Za-z0-9_\-]+$`.
+   * @returns A Module that ensures the timer-driven scheduled task is absent.
+   */
+  absent(name) {
+    assertTimerName(name);
+    const locations = buildTimerLocations(name);
+    return {
+      async apply(ssh2) {
+        if (!ssh2) return failed(`[timer.absent: ${name}] SSH connection is required`);
+        return applyAbsent(ssh2, { locations, module: "timer.absent", name });
+      },
+      async check(ssh2) {
+        if (!ssh2) return NEEDS_APPLY;
+        return checkAbsent2(ssh2, locations);
+      },
+      name: `timer.absent: ${name}`
+    };
+  },
+  /**
+   * Ensure a systemd timer-driven scheduled task is present (or absent).
+   *
+   * Generates `<name>.service` (`Type=oneshot`, no `[Install]` section since
+   * it is triggered exclusively by the timer) and `<name>.timer` under
+   * `/etc/systemd/system/`, reloads systemd, and runs
+   * `systemctl enable --now <name>.timer`. When the timer unit content
+   * changed, the timer is restarted so a new `OnCalendar=` schedule is picked
+   * up immediately. With `state: "absent"`, the timer is disabled and
+   * stopped, both unit files are removed, and systemd is reloaded.
+   *
+   * Validation of `exec`, `description`, `user`, `group`, `workingDirectory`,
+   * `environment` and `onCalendar` only runs when `state` is `"present"`,
+   * so callers can pass placeholder values when removing a timer.
+   *
+   * @param name - Base unit name without extension. Used as `<name>.service`
+   *   and `<name>.timer`. Must match `^[A-Za-z0-9_\-]+$`.
+   * @param options - Schedule, command, optional service hardening, and state.
+   * @returns A Module that manages the timer-driven scheduled task.
+   */
+  scheduled(name, options) {
+    assertTimerName(name);
+    const state = options.state ?? "present";
+    if (state === "absent") {
+      const locations = buildTimerLocations(name);
+      return {
+        async apply(ssh2) {
+          if (!ssh2) return failed(`[timer.scheduled: ${name}] SSH connection is required`);
+          return applyAbsent(ssh2, { locations, module: "timer.scheduled", name });
+        },
+        async check(ssh2) {
+          if (!ssh2) return NEEDS_APPLY;
+          return checkAbsent2(ssh2, locations);
+        },
+        name: `timer.scheduled: ${name}`
+      };
+    }
+    validatePresentOptions(options);
+    const paths = buildTimerPaths(name, options);
+    return {
+      async apply(ssh2) {
+        if (!ssh2) return failed(`[timer.scheduled: ${name}] SSH connection is required`);
+        return applyPresent(ssh2, name, paths);
+      },
+      async check(ssh2) {
+        if (!ssh2) return NEEDS_APPLY;
+        return checkPresent2(ssh2, paths);
+      },
+      name: `timer.scheduled: ${name}`
+    };
+  }
+};
+
 // src/modules/ufw.ts
 var UFW = "ufw";
 var ufw = {
@@ -5838,7 +6230,8 @@ export {
   swap,
   system,
   systemd,
+  timer,
   ufw,
   user
 };
-//# sourceMappingURL=chunk-FFQ6FR4N.js.map
+//# sourceMappingURL=chunk-M7GETOJ5.js.map