paratix 0.12.8 → 0.14.0

package/dist/{index-udpAybq3.d.ts → index-DlZISXJx.d.ts}

@@ -157,6 +157,17 @@ type Module = {
      * @returns `"ok"` if the desired state is already present, `"needs-apply"` otherwise.
      */
     check: (ssh: null | SshConnection, environment: Environment) => Promise<"needs-apply" | "ok">;
+    /**
+     * Internal discriminator that distinguishes leaf modules from recipes.
+     *
+     * Leaf modules leave this `undefined` (treated as `"module"`); recipes set
+     * `"recipe"` so the runner can narrow to the recipe contract via the
+     * `isRecipe` type guard instead of an unsafe structural cast. Intentionally
+     * optional so existing custom modules and playbooks stay source-compatible —
+     * they never need to set it.
+     * @internal
+     */
+    kind?: "module" | "recipe";
     /**
      * When true the module runs locally instead of over SSH.
      * The `ssh` parameter will be `null` in check/apply.
@@ -240,8 +251,16 @@ type SshConnection = {
     probeSudo: () => Promise<void>;
     /** Read the full contents of a remote file as a string. */
     readFile: (remotePath: string) => Promise<string>;
-    /** Reconnect the SSH session using the current host and registered port candidates. */
-    reconnect: () => Promise<void>;
+    /**
+     * Reconnect the SSH session using the current host and registered port
+     * candidates. An explicit `reconnectTimeout` in the SSH config always takes
+     * precedence; when it is unset, `options.defaultTimeout` (in milliseconds)
+     * overrides the generic reconnect default for this call — used by the reboot
+     * path to grant a longer window.
+     */
+    reconnect: (options?: {
+        defaultTimeout?: number;
+    }) => Promise<void>;
     /** Remove a previously registered port from the reconnect candidate list. */
     removePort: (port: number) => void;
     /** Return the SHA-256 hex digest of a remote file, or `null` if not found. */
@@ -250,13 +269,13 @@ type SshConnection = {
     test: (command: string) => Promise<boolean>;
     /** Update the target host address (e.g. after a reboot with new IP). */
     updateHost: (host: string) => void;
-    /** Upload a local file to the remote host via SFTP. */
+    /** Upload a local file to the remote host via SFTP. `options.mode` is optional and defaults to `"0600"`. */
     uploadFile: (localPath: string, remotePath: string, options?: {
         mode?: string;
     }) => Promise<void>;
-    /** Write a string to a remote file, creating or overwriting it. */
-    writeFile: (remotePath: string, content: string, options: {
-        mode: string;
+    /** Write a string to a remote file, creating or overwriting it. `options.mode` is optional and defaults to `"0600"`. */
+    writeFile: (remotePath: string, content: string, options?: {
+        mode?: string;
     }) => Promise<void>;
 };
 /** SSH connection parameters for a server. */
@@ -564,6 +583,7 @@ declare const command: {
      *   If it exits `0`, the command is considered already done.
      * @param options.name - An optional display name shown in the run output.
      * @param options.secrets - Secret values that must be redacted from command output.
+     * @param options.timeout - Maximum runtime for the command in milliseconds.
      * @returns A Module that executes the shell command.
      *
      * @example
@@ -576,6 +596,7 @@ declare const command: {
         check?: string;
         name?: string;
         secrets?: string[];
+        timeout?: number;
     }): Module;
 };
 

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-udpAybq3.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-udpAybq3.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-DlZISXJx.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-DlZISXJx.js';
 
 /**
  * Fail the run if a condition on the current env is not satisfied.
@@ -185,11 +185,16 @@ type SignalHooks = {
 
 /**
  * Internal representation of a recipe module.
- * The `_isRecipe` flag lets the runner distinguish recipes from leaf modules.
+ *
+ * The `kind: "recipe"` discriminator lets the runner distinguish recipes from
+ * leaf modules through the {@link isRecipe} type guard, forming a discriminated
+ * union with plain {@link Module} values (which leave `kind` unset). The child
+ * `_modules` and optional `_signals` are recipe-specific data that TypeScript
+ * narrows to once `isRecipe` confirmed the discriminator — no structural cast
+ * is required anywhere.
  * @internal
  */
 type RecipeModule = {
-    _isRecipe: true;
     _modules: Module[];
     _signals?: Module[];
     apply: (ssh: null | SshConnection, environment: Environment, options?: {
@@ -199,6 +204,7 @@ type RecipeModule = {
         signalHooks?: SignalHooks;
         verbose?: boolean;
     }) => Promise<ModuleResult>;
+    kind: "recipe";
 } & Module;
 /**
  * Group a list of modules into a named, self-contained recipe.
@@ -215,8 +221,11 @@ type RecipeModule = {
  * @returns A RecipeModule that groups the child modules.
  *
  * @example
+ * import { recipe } from "paratix"
+ * import { package as pkg, file, service } from "paratix/modules"
+ *
  * export const nginxRecipe = recipe("nginx", [
- *   apt.installed("nginx"),
+ *   pkg.installed("nginx"),
  *   file.template("/etc/nginx/nginx.conf", "./files/nginx.conf.tmpl"),
  *   service.enabled("nginx"),
  * ], {
@@ -239,11 +248,14 @@ declare function recipe(name: string, modules: Module[], options?: {
  * @throws {Error} When any required field is missing or empty.
  *
  * @example
+ * import { server } from "paratix"
+ * import { package as pkg } from "paratix/modules"
+ *
  * export default server({
  *   name: "web-01",
  *   host: "10.0.0.1",
  *   ssh: { user: "root", ports: [22], privateKey: "~/.ssh/id_ed25519" }, // "~" is expanded
- *   run: [apt.installed("nginx")],
+ *   run: [pkg.installed("nginx")],
  * });
  */
 declare function server(config: ServerDefinition): ServerDefinition;

package/dist/index.js

@@ -61,7 +61,7 @@ import {
   user,
   validateHostLabel,
   validateSshConfig
-} from "./chunk-M3ZQJNKM.js";
+} from "./chunk-475OT32R.js";
 
 // src/conditionalModules.ts
 function createConditionalApplyState(environment) {
@@ -536,6 +536,10 @@ var DEFAULT_TERMINAL_COLUMNS = 100;
 var MIN_PACKAGE_COLUMNS_WIDTH = 24;
 var MIN_PACKAGE_COLUMN_WIDTH = 18;
 var MIN_ANIMATED_LINE_COLUMNS = 8;
+var ELAPSED_DISPLAY_THRESHOLD_MS = 1e3;
+var MILLISECONDS_PER_SECOND = 1e3;
+var MILLISECONDS_PER_MINUTE = 6e4;
+var SECONDS_PER_MINUTE = 60;
 function splitPackageModuleName(name) {
   for (const prefix of ["package.installed: ", "package.absent: "]) {
     if (!name.startsWith(prefix)) continue;
@@ -573,6 +577,16 @@ function getPackageSummaryDetail(packageCount, detail) {
   const packageLabel = packageCount === 1 ? "1 package" : `${packageCount} packages`;
   return detail == null ? packageLabel : `${packageLabel} \xB7 ${detail}`;
 }
+function formatModuleElapsed(elapsedMs) {
+  if (!Number.isFinite(elapsedMs) || elapsedMs < ELAPSED_DISPLAY_THRESHOLD_MS) return void 0;
+  if (elapsedMs < MILLISECONDS_PER_MINUTE) {
+    return `${(elapsedMs / MILLISECONDS_PER_SECOND).toFixed(1)}s`;
+  }
+  const totalSeconds = Math.floor(elapsedMs / MILLISECONDS_PER_SECOND);
+  const minutes = Math.floor(totalSeconds / SECONDS_PER_MINUTE);
+  const seconds = totalSeconds % SECONDS_PER_MINUTE;
+  return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+}
 function fitAnimatedModuleLine(line, columns) {
   if (columns === void 0 || columns < MIN_ANIMATED_LINE_COLUMNS) return line;
   const plainLine = stripVTControlCharacters(line);
@@ -624,6 +638,7 @@ function getSharedLiveOutputState() {
   const existing = registry[LIVE_OUTPUT_STATE_KEY];
   if (existing != null) return existing;
   const created = {
+    activeModuleStartedAt: null,
     activeRecipeGuideDepths: [],
     activeSpinner: null,
     cursorHidden: false,
@@ -666,7 +681,7 @@ function getGuideDot(depth) {
   return depth % 2 === 0 ? pc.gray("\xB7") : pc.cyan("\xB7");
 }
 function buildGuideIndent(baseIndent, options) {
-  const indentCharacters = Array.from(baseIndent);
+  const indentCharacters = [...baseIndent];
   const guideDepths = [
     ...options?.activeGuideDepths ?? liveOutputState.activeRecipeGuideDepths,
     ...options?.extraGuideDepths ?? []
@@ -702,20 +717,27 @@ async function withRecipeOutputScope(scopedOperation) {
   try {
     return await scopedOperation();
   } finally {
-    liveOutputState.activeRecipeGuideDepths = liveOutputState.activeRecipeGuideDepths.filter((depth) => depth !== liveOutputState.recipeOutputDepth);
+    liveOutputState.activeRecipeGuideDepths = liveOutputState.activeRecipeGuideDepths.filter(
+      (depth) => depth !== liveOutputState.recipeOutputDepth
+    );
     liveOutputState.pendingRecipeClosureGuideDepths = [liveOutputState.recipeOutputDepth];
     liveOutputState.recipeOutputDepth -= 1;
   }
 }
+function getActiveModuleElapsed() {
+  if (liveOutputState.activeModuleStartedAt == null) return void 0;
+  return formatModuleElapsed(Date.now() - liveOutputState.activeModuleStartedAt);
+}
 function renderModuleLine(parameters) {
-  const { detail, extraGuideDepths = [], name, status, waitingFrame } = parameters;
+  const { detail, elapsed, extraGuideDepths = [], name, status, waitingFrame } = parameters;
   const baseIndent = getModuleIndent();
   const indent = buildGuideIndent(baseIndent, { extraGuideDepths });
   const icon = getModuleIcon(status, waitingFrame);
   const statusText = getModuleStatusText(status);
   const detailSuffix = detail == null ? "" : `  ${pc.dim(detail)}`;
+  const elapsedSuffix = elapsed == null ? "" : `  ${pc.dim(elapsed)}`;
   const alignedNameWidth = Math.max(MODULE_NAME_WIDTH - baseIndent.length, MIN_MODULE_NAME_WIDTH);
-  return `${indent}${icon}  ${name.padEnd(alignedNameWidth)}  ${statusText}${detailSuffix}`;
+  return `${indent}${icon}  ${name.padEnd(alignedNameWidth)}  ${statusText}${detailSuffix}${elapsedSuffix}`;
 }
 function hideCursor() {
   if (liveOutputState.cursorHidden) return;
@@ -745,6 +767,7 @@ function stopAnimatedModuleLine(clearCurrentLine = false) {
   }
 }
 function startModuleSpinner(name, detail) {
+  liveOutputState.activeModuleStartedAt = Date.now();
   if (!supportsAnimatedModuleOutput()) return;
   clearPendingRecipeClosureGuides();
   stopAnimatedModuleLine();
@@ -765,6 +788,7 @@ function startModuleSpinner(name, detail) {
       writeAnimatedModuleLine(
         renderModuleLine({
           detail: spinner.detail,
+          elapsed: getActiveModuleElapsed(),
           name: displayModule.name,
           status: "waiting",
           waitingFrame: SPINNER_FRAMES[spinner.frameIndex]
@@ -777,6 +801,7 @@ function startModuleSpinner(name, detail) {
   writeAnimatedModuleLine(
     renderModuleLine({
       detail: displayModule.detail,
+      elapsed: getActiveModuleElapsed(),
       name: displayModule.name,
       status: "waiting",
       waitingFrame: SPINNER_FRAMES[0]
@@ -789,7 +814,10 @@ function printRecipeHeader(name) {
   const header = pc.bold(pc.blue(`[${name}]`));
   console.log(`${buildGuideIndent(getRecipeHeaderIndent())}${header}`);
   if (liveOutputState.recipeOutputDepth >= 0) {
-    liveOutputState.activeRecipeGuideDepths = [...liveOutputState.activeRecipeGuideDepths, liveOutputState.recipeOutputDepth];
+    liveOutputState.activeRecipeGuideDepths = [
+      ...liveOutputState.activeRecipeGuideDepths,
+      liveOutputState.recipeOutputDepth
+    ];
   }
 }
 function colorizeDiffLine(line) {
@@ -836,8 +864,11 @@ function printRenderedModuleResult(parameters) {
     status: parameters.status,
     terminalColumns: process.stdout.columns
   });
+  const elapsed = getActiveModuleElapsed();
+  liveOutputState.activeModuleStartedAt = null;
   const line = renderModuleLine({
     detail: displayModule.detail,
+    elapsed,
     extraGuideDepths,
     name: displayModule.name,
     status: parameters.status
@@ -964,7 +995,9 @@ function printCauseChain(error) {
       if (visited.has(cause)) return;
       visited.add(cause);
     }
-    console.error(pc.red(`${getErrorIndent()}Cause: ${maskRegisteredSecrets(formatCauseValue(cause))}`));
+    console.error(
+      pc.red(`${getErrorIndent()}Cause: ${maskRegisteredSecrets(formatCauseValue(cause))}`)
+    );
     if (cause instanceof CommandError) {
       printVerboseCommandError(
         maskRegisteredSecrets(cause.fullStdout),
@@ -1191,11 +1224,11 @@ async function runSignalModules(parameters) {
 
 // src/recipe.ts
 var INTERRUPTED_BEFORE_APPLY = /* @__PURE__ */ Symbol("recipe-interrupted-before-apply");
-function isRecipeModuleLike(module) {
-  return module._isRecipe === true;
+function isRecipe(module) {
+  return module.kind === "recipe";
 }
 function printRecipeChildResult(module, result) {
-  if (isRecipeModuleLike(module)) {
+  if (isRecipe(module)) {
     printRecipeModuleResult(module.name, result.status, result.detail);
     return;
   }
@@ -1262,7 +1295,7 @@ async function checkRecipeChild(targetModule, connection, currentEnvironment) {
   return targetModule.check(connection, currentEnvironment);
 }
 async function applyRecipeChild(parameters) {
-  if (isRecipeModuleLike(parameters.targetModule)) {
+  if (isRecipe(parameters.targetModule)) {
     return parameters.targetModule.apply(parameters.connection, parameters.currentEnvironment, {
       onChildStep: parameters.onChildStep,
       onSignalStep: parameters.onSignalStep,
@@ -1469,7 +1502,6 @@ function createRecipeDryRunApply(name, modules, needsDryRunApply) {
     const result = await dryRunRecipeModule({
       environment,
       recipeModule: {
-        _isRecipe: true,
         _modules: modules,
         async apply() {
           await Promise.resolve();
@@ -1479,6 +1511,7 @@ function createRecipeDryRunApply(name, modules, needsDryRunApply) {
           await Promise.resolve();
           return "ok";
         },
+        kind: "recipe",
         name
       },
       shutdownSignal: parameters?.shutdownSignal,
@@ -1498,7 +1531,6 @@ function recipe(name, modules, options) {
     ...modules.some((module) => module._dryRunBlocker === true) ? { _dryRunBlocker: true } : {},
     ...modules.some((module) => module._dryRunMetaProducer === true) ? { _dryRunMetaProducer: true } : {},
     ...applyDryRun == null ? {} : { _applyDryRun: applyDryRun },
-    _isRecipe: true,
     _modules: modules,
     _signals: options?.signals,
     _supportsChildStepHook: true,
@@ -1526,6 +1558,7 @@ function recipe(name, modules, options) {
       }
       return "ok";
     },
+    kind: "recipe",
     name
   };
 }
@@ -1634,4 +1667,3 @@ export {
   user,
   when
 };
-//# sourceMappingURL=index.js.map

package/dist/modules/index.d.ts

@@ -1 +1 @@
-export { V 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-udpAybq3.js';
+export { V 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-DlZISXJx.js';

package/dist/modules/index.js

@@ -27,7 +27,7 @@ import {
   timer,
   ufw,
   user
-} from "../chunk-M3ZQJNKM.js";
+} from "../chunk-475OT32R.js";
 export {
   apt,
   archive,
@@ -58,4 +58,3 @@ export {
   ufw,
   user
 };
-//# sourceMappingURL=index.js.map

package/llm-guide.md

@@ -1,11 +1,18 @@
-# Paratix -- LLM Code Guide
+# Paratix TypeScript API and Module Reference
 
-> This file helps LLMs write correct Paratix code. Read this before generating playbooks or modules.
+This is the complete reference for writing Paratix playbooks and custom modules. It covers the
+TypeScript API, built-in modules, authoring patterns, and common mistakes.
 
 ## Overview
 
 Paratix is a CLI tool for idempotent VPS configuration via SSH using TypeScript playbooks. Each playbook exports a `server()` definition containing an ordered list of modules that are checked and applied over SSH. Modules follow a check/apply pattern: `check` determines if work is needed, `apply` enforces the desired state.
 
+## Agent authoring guidance
+
+When generating or changing Paratix playbooks or custom modules, automated coding agents should use
+this document as the complete API reference. Read the relevant API and module sections before making
+changes, and follow the [Do's and Don'ts](#dos-and-donts) and [testing patterns](#testing-patterns).
+
 ## Imports
 
 Paratix has exactly two import paths:
@@ -150,9 +157,12 @@ export default server({
 
 ### `command`
 
-| Method          | Signature                                                                                | Idempotent        |
-| --------------- | ---------------------------------------------------------------------------------------- | ----------------- |
-| `command.shell` | `(cmd: string, options?: { check?: string; name?: string; secrets?: string[] }): Module` | Only with `check` |
+| Method          | Signature                                                                                                  | Idempotent        |
+| --------------- | ---------------------------------------------------------------------------------------------------------- | ----------------- |
+| `command.shell` | `(cmd: string, options?: { check?: string; name?: string; secrets?: string[]; timeout?: number }): Module` | Only with `check` |
+
+`command.shell` accepts `timeout` in milliseconds to limit the runtime of the applied command. The
+idempotency guard configured through `check` is not affected by this timeout.
 
 ### `cron`
 
@@ -212,9 +222,9 @@ very slow artifact hosts or large downloads.
 | `file.stat`       | `(remotePath: string): Module`                                                                                      | No (always-applies) |
 | `file.template`   | `(remotePath: string, templatePath: string, options?: { mode?: string; owner?: string; strict?: boolean }): Module` | Yes                 |
 
-**Hinweis zu `file.copy` und Default-Mode:** Wenn `options.mode` weggelassen wird, setzt `file.copy` den Modus auf den dokumentierten Default `0644`. Der Modus wird sowohl beim Hochladen (`uploadFile` mit `{ mode }`) als auch in `check` gegen den Soll-Wert verglichen, damit nachfolgende Läufe Mode-Drift (z. B. manuelles `chmod 0600`) als `needs-apply` erkennen. Wer ein restriktiveres Recht braucht (z. B. für Secrets), übergibt explizit `{ mode: "0600" }`.
+**Note on `file.copy` and the default mode:** When `options.mode` is omitted, `file.copy` sets the mode to the documented default of `0644`. The mode is applied during upload (`uploadFile` with `{ mode }`) and compared with the desired value in `check`, so subsequent runs detect mode drift (for example, a manual `chmod 0600`) as `needs-apply`. Pass `{ mode: "0600" }` explicitly when more restrictive permissions are required, such as for secrets.
 
-**Hinweis zu `file.line`:** Der `line`-Wert muss eine einzelne Zeile ohne CR/LF sein. Für mehrzeilige Inhalte `file.block` verwenden.
+**Note on `file.line`:** The `line` value must be a single line without CR/LF characters. Use `file.block` for multiline content.
 
 ### `git`
 
@@ -342,7 +352,7 @@ rsync SSH process and does not depend on a local `known_hosts` entry.
 | `ssh.authorizedKeys` | `(user: string, key: string, options?: { state?: "absent" \| "present" }): Module`                                                     | Yes        |
 | `ssh.knownHosts`     | `(host: string, options?: { expectedFingerprint?: string; port?: number; publicKey?: string; state?: "absent" \| "present" }): Module` | Yes        |
 
-**Trust-Anchor-Pflicht für `ssh.knownHosts` (state `present`):** Im Default-State `present` muss entweder `expectedFingerprint` oder `publicKey` gesetzt sein. Ohne Trust Anchor wirft der Modul-Konstruktor sofort, denn `check` würde sonst jeden vorhandenen `known_hosts`-Eintrag (auch ältere, möglicherweise kompromittierte TOFU-Akzeptanzen) als „ok" werten und den Anchor-Vergleich überspringen. Für `state: "absent"` ist kein Anchor nötig — dort wird der Eintrag ohnehin entfernt.
+**Trust anchor requirement for `ssh.knownHosts` (`state: "present"`):** In the default `present` state, either `expectedFingerprint` or `publicKey` must be set. Without a trust anchor, the module constructor throws immediately because `check` would otherwise treat any existing `known_hosts` entry, including older and potentially compromised TOFU acceptances, as `ok` and skip the anchor comparison. No anchor is required for `state: "absent"`, because that state removes the entry.
 
 ### `sshd`
 
@@ -481,23 +491,23 @@ function myCustomModule(configPath: string, content: string): Module {
 
 Methods available on the `ssh` parameter:
 
-| Method                                           | Return type                             | Description                                                                                    |
-| ------------------------------------------------ | --------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `ssh.exec(cmd, options?)`                        | `Promise<ExecResult>`                   | Run command, get `{ code, stdout, stderr }`. Throws on non-zero unless `ignoreExitCode: true`. |
-| `ssh.test(cmd)`                                  | `Promise<boolean>`                      | Run command, return `true` if exit code is 0.                                                  |
-| `ssh.output(cmd)`                                | `Promise<string>`                       | Run command, return trimmed stdout.                                                            |
-| `ssh.lines(cmd)`                                 | `Promise<string[]>`                     | Run command, return stdout split into lines.                                                   |
-| `ssh.exists(path)`                               | `Promise<boolean>`                      | Check if remote path exists.                                                                   |
-| `ssh.readFile(path)`                             | `Promise<string>`                       | Read remote file content.                                                                      |
-| `ssh.writeFile(path, content, { mode: "0644" })` | `Promise<void>`                         | Write content to remote file. `mode` is required; choose an explicit file mode.                |
-| `ssh.uploadFile(local, remote)`                  | `Promise<void>`                         | Upload local file via SFTP.                                                                    |
-| `ssh.downloadFile(remote, local)`                | `Promise<void>`                         | Download remote file.                                                                          |
-| `ssh.sha256(path)`                               | `Promise<string \| null>`               | Get SHA-256 hex digest, or null if not found.                                                  |
-| `ssh.addPort(port)`                              | `void`                                  | Register an additional port opened on the remote host (advanced).                              |
-| `ssh.disconnect()`                               | `void`                                  | Close the SSH connection.                                                                      |
-| `ssh.getConnectionInfo()`                        | `{ host, port, privateKeyPath?, user }` | Return current connection parameters.                                                          |
-| `ssh.probeSudo()`                                | `Promise<void>`                         | Probe/cache sudo access; prompts interactively if needed.                                      |
-| `ssh.updateHost(host)`                           | `void`                                  | Update the target host address (e.g., after IP change).                                        |
+| Method                                            | Return type                             | Description                                                                                    |
+| ------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `ssh.exec(cmd, options?)`                         | `Promise<ExecResult>`                   | Run command, get `{ code, stdout, stderr }`. Throws on non-zero unless `ignoreExitCode: true`. |
+| `ssh.test(cmd)`                                   | `Promise<boolean>`                      | Run command, return `true` if exit code is 0.                                                  |
+| `ssh.output(cmd)`                                 | `Promise<string>`                       | Run command, return trimmed stdout.                                                            |
+| `ssh.lines(cmd)`                                  | `Promise<string[]>`                     | Run command, return stdout split into lines.                                                   |
+| `ssh.exists(path)`                                | `Promise<boolean>`                      | Check if remote path exists.                                                                   |
+| `ssh.readFile(path)`                              | `Promise<string>`                       | Read remote file content.                                                                      |
+| `ssh.writeFile(path, content, { mode: "0644" })`  | `Promise<void>`                         | Write content to remote file. `mode` is optional and defaults to `"0600"`.                     |
+| `ssh.uploadFile(local, remote, { mode: "0644" })` | `Promise<void>`                         | Upload local file via SFTP. `mode` is optional and defaults to `"0600"`.                       |
+| `ssh.downloadFile(remote, local)`                 | `Promise<void>`                         | Download remote file.                                                                          |
+| `ssh.sha256(path)`                                | `Promise<string \| null>`               | Get SHA-256 hex digest, or null if not found.                                                  |
+| `ssh.addPort(port)`                               | `void`                                  | Register an additional port opened on the remote host (advanced).                              |
+| `ssh.disconnect()`                                | `void`                                  | Close the SSH connection.                                                                      |
+| `ssh.getConnectionInfo()`                         | `{ host, port, privateKeyPath?, user }` | Return current connection parameters.                                                          |
+| `ssh.probeSudo()`                                 | `Promise<void>`                         | Probe/cache sudo access; prompts interactively if needed.                                      |
+| `ssh.updateHost(host)`                            | `void`                                  | Update the target host address (e.g., after IP change).                                        |
 
 ### ExecOptions
 
@@ -666,7 +676,7 @@ fail("This branch should be unreachable")
 
 ### `firstRun.stop(message?)`
 
-Stoppt den aktuellen Lauf kontrolliert, wenn Paratix mit `--first-run` gestartet wurde. Nützlich als explizite Staging-Grenze in Bootstrap-Playbooks.
+Stops the current run cleanly when Paratix was started with `--first-run`. Useful as an explicit staging boundary in bootstrap playbooks.
 
 ```typescript
 firstRun.stop("Bootstrap foundation complete; rerun without --first-run to continue.")
@@ -674,7 +684,7 @@ firstRun.stop("Bootstrap foundation complete; rerun without --first-run to conti
 
 ### `signals.flush(message?)`
 
-Führt alle aktuell offenen Signale des aktiven Scopes sofort aus und setzt deren Pending-Zustand zurück.
+Immediately runs all currently pending signals in the active scope and clears their pending state.
 
 ```typescript
 signals.flush("Reload services before the next bootstrap stage")
@@ -742,20 +752,20 @@ Rules:
 
 Diff-producing built-in modules:
 
-| Modul                                       | Diff-Inhalt                                                                                                                                                                             |
-| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `file.copy`                                 | Unified diff zwischen Remote-Datei und lokaler Quelle.                                                                                                                                  |
-| `file.template`                             | Unified diff zwischen Remote-Datei und gerendertem Template.                                                                                                                            |
-| `sysctl.set`                                | `key = old → new` für die Soll-Konfiguration.                                                                                                                                           |
-| `hostname.set`                              | `hostname = old → new`.                                                                                                                                                                 |
-| `swap.file`                                 | Diff des `/etc/fstab`-Eintrags (oder Entfernung der Zeile bei `state: "absent"`).                                                                                                       |
-| `swap.swappiness`                           | `vm.swappiness = old → new` (via `sysctl.set`).                                                                                                                                         |
-| `swap.vfsCachePressure`                     | `vm.vfs_cache_pressure = old → new` (via `sysctl.set`).                                                                                                                                 |
-| `cron.job` / `cron.absent`                  | Unified diff der Crontab des Ziel-Users.                                                                                                                                                |
-| `timer.scheduled` (present)                 | Konkatenierte Diffs der `.service`- und `.timer`-Unit-Dateien.                                                                                                                          |
-| `timer.scheduled` (absent) / `timer.absent` | Liste der zu entfernenden Unit-Dateien.                                                                                                                                                 |
-| `net.hosts`                                 | Unified diff von `/etc/hosts`.                                                                                                                                                          |
-| `quadlet.container`                         | Unified diff der `.container`-Unit-Datei. Wenn die Datei bereits passt, das `daemon-reload`-Flag aber fehlt, erscheint zusätzlich `(dry-run, daemon-reload pending)` als Detail-Suffix. |
+| Module                                      | Diff content                                                                                                                                                                         |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `file.copy`                                 | Unified diff between the remote file and the local source.                                                                                                                           |
+| `file.template`                             | Unified diff between the remote file and the rendered template.                                                                                                                      |
+| `sysctl.set`                                | `key = old → new` for the desired configuration.                                                                                                                                     |
+| `hostname.set`                              | `hostname = old → new`.                                                                                                                                                              |
+| `swap.file`                                 | Diff of the `/etc/fstab` entry (or removal of the line for `state: "absent"`).                                                                                                       |
+| `swap.swappiness`                           | `vm.swappiness = old → new` (via `sysctl.set`).                                                                                                                                      |
+| `swap.vfsCachePressure`                     | `vm.vfs_cache_pressure = old → new` (via `sysctl.set`).                                                                                                                              |
+| `cron.job` / `cron.absent`                  | Unified diff of the target user's crontab.                                                                                                                                           |
+| `timer.scheduled` (present)                 | Concatenated diffs of the `.service` and `.timer` unit files.                                                                                                                        |
+| `timer.scheduled` (absent) / `timer.absent` | List of unit files to remove.                                                                                                                                                        |
+| `net.hosts`                                 | Unified diff of `/etc/hosts`.                                                                                                                                                        |
+| `quadlet.container`                         | Unified diff of the `.container` unit file. If the file already matches but the `daemon-reload` flag is missing, `(dry-run, daemon-reload pending)` also appears as a detail suffix. |
 
 ### Implementing a Diff for a Custom Module
 
@@ -810,7 +820,7 @@ The diff string is plain text — no ANSI codes. The output layer applies colors
 4. For idempotency with `command.shell()`, always provide a `check` command.
 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 als expliziten Checkpoint, wenn gestufte Flows einen vorgezogenen Signal-Flush brauchen.
+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.
 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.
@@ -831,9 +841,9 @@ The diff string is plain text — no ANSI codes. The output layer applies colors
 9. Do NOT use template syntax `{{key}}` in TypeScript code -- templates are only for files rendered via `file.template()`.
 10. Do NOT use `signals` on the top-level `server()` when you mean a recipe signal -- `server.signals` fire when ANY module in `run` changed.
 11. Do NOT treat `signals.flush()` as a global queue flush -- it only affects the current scope.
-12. `signals.flush()` flusht immer nur den aktuellen Scope:
-    - in einer Recipe deren Recipe-Signale
-    - auf Top-Level `server(...).signals`
+12. `signals.flush()` always flushes only the current scope:
+    - inside a recipe, that recipe's signals
+    - at the top level, `server(...).signals`
 13. Do NOT call `server()` without all required fields (`name`, `host`, `ssh`, `run`) -- it throws at construction time. `name` and `host` must not be empty strings.
 14. Do NOT use empty arrays for `ssh.ports` or empty strings for `ssh.user`/`ssh.privateKey` -- validation rejects these. `ssh.privateKey` may be omitted entirely to use the SSH agent instead.
 15. Do NOT return loose `meta: { ... }` maps from custom modules -- always use typed meta entries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paratix",
-  "version": "0.12.8",
+  "version": "0.14.0",
   "description": "Idempotent VPS setup tool in TypeScript",
   "type": "module",
   "files": [
@@ -23,6 +23,7 @@
   "devDependencies": {
     "@types/node": "24.13.2",
     "@types/ssh2": "^1.15.4",
+    "@vitest/coverage-v8": "4.1.9",
     "tsup": "^8.4.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.7"
@@ -56,9 +57,10 @@
   "scripts": {
     "build": "tsup",
     "test": "pnpm test:unit && pnpm test:dist",
+    "test:coverage": "vitest run --coverage",
     "test:dist": "pnpm build && vitest run --config vitest.distribution.config.ts",
     "test:integration": "pnpm build && vitest run --config vitest.integration.config.ts",
-    "test:unit": "vitest run",
+    "test:unit": "vitest run --coverage",
     "test:watch": "vitest"
   }
 }