paratix 0.9.0 → 0.10.0

package/dist/{chunk-7Y2RBVG4.js → chunk-M7GETOJ5.js}

@@ -1123,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.
    *
@@ -1140,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)}`);
     }
@@ -5621,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 = {
@@ -5885,7 +6230,8 @@ export {
   swap,
   system,
   systemd,
+  timer,
   ufw,
   user
 };
-//# sourceMappingURL=chunk-7Y2RBVG4.js.map
+//# sourceMappingURL=chunk-M7GETOJ5.js.map