paratix 0.13.0 → 0.14.0

package/README.md

@@ -119,19 +119,21 @@ Paratix can also manage file-backed swap directly. Use `swap.file(...)` to provi
 
 ## CLI
 
+`paratix --help` lists these options directly, so they are discoverable without drilling into `paratix apply --help` first.
+
 ```text
 paratix apply <file> [options]
 
 Options:
-  --diff
-  --dry-run
-  --env <key=value>
-  --env-file <path>
-  --filter <names>
-  --first-run
-  --reconnect-timeout <seconds>
-  --verbose
-  --help
+  --diff                         Combined with --dry-run: unified diff per changed module
+  --dry-run                      Only check, do not apply (some runtime restarts stay unverified)
+  --env <key=value...>           Set environment values for the playbook (repeatable)
+  --env-file <path>              Load environment values from a dotenv file
+  --filter <names>               Run only the named recipes/modules (comma-separated, repeatable)
+  --first-run                    Set PARATIX_FIRST_RUN=true before loading the playbook
+  --reconnect-timeout <seconds>  SSH reconnect timeout for reboots/port changes (max 86400)
+  --verbose                      Show full stack traces on error
+  --help                         Show help
 ```
 
 `--filter <names>` restricts the run to the named recipes and modules. Names are matched anywhere in the tree, and every node that is not selected is shown as `skipped` instead of being executed. The option is comma-separated and repeatable, so `--filter rybbit,palamedes-examples` and `--filter rybbit --filter palamedes-examples` are equivalent. Selecting a recipe runs its whole subtree; a recipe that is not selected but contains a selected descendant is still descended into, so only the matching children run while its siblings are skipped. If several nodes share the same name, every one of them is selected. An unknown filter name aborts the run before it connects (exit code 2). The final run summary counts only top-level nodes, so nested skipped nodes are still shown but are not added to the `skipped` tally. `--filter` composes with `--dry-run` and the other flags.
@@ -145,7 +147,9 @@ Options:
 ## Documentation
 
 - For project scaffolding, see [`create-paratix`](https://www.npmjs.com/package/create-paratix).
-- For detailed authoring guidance and module reference inside this repo, see [llm-guide.md](./llm-guide.md).
+- See the complete [TypeScript API and Module Reference](./llm-guide.md).
+- For common runtime and connection failures, see [Troubleshooting](../../docs/user-guide/troubleshooting.md).
+- Before upgrading an existing project, see the [migration notes](../../docs/user-guide/migration.md).
 
 ## License
 

package/dist/{chunk-XIRORNO3.js → chunk-475OT32R.js}

@@ -3245,6 +3245,15 @@ async function commandCheckPassed(ssh2, check, secrets) {
   });
   return result.code === 0;
 }
+function commandExecOptions(secrets, options) {
+  const execOptions2 = {
+    ignoreExitCode: true,
+    secrets,
+    silent: true
+  };
+  if (options?.timeout !== void 0) execOptions2.timeout = options.timeout;
+  return execOptions2;
+}
 var command = {
   /**
    * Run an arbitrary shell command on the remote host.
@@ -3264,6 +3273,7 @@ var 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
@@ -3285,11 +3295,7 @@ var command = {
         if (options?.check != null && await commandCheckPassed(ssh2, options.check, secrets)) {
           return { status: "ok" };
         }
-        const result = await ssh2.exec(cmd, {
-          ignoreExitCode: true,
-          secrets,
-          silent: true
-        });
+        const result = await ssh2.exec(cmd, commandExecOptions(secrets, options));
         if (result.code !== 0) {
           return failedCommand(`[${moduleName}] command failed`, {
             ...result,

package/dist/cli.js

@@ -1547,6 +1547,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;
@@ -1584,6 +1588,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);
@@ -1835,6 +1849,7 @@ function getSharedLiveOutputState() {
   const existing = registry[LIVE_OUTPUT_STATE_KEY];
   if (existing != null) return existing;
   const created = {
+    activeModuleStartedAt: null,
     activeRecipeGuideDepths: [],
     activeSpinner: null,
     cursorHidden: false,
@@ -1885,7 +1900,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 ?? []
@@ -1921,20 +1936,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;
@@ -1967,6 +1989,7 @@ function stopLiveModuleOutput(clearCurrentLine = false) {
   stopAnimatedModuleLine(clearCurrentLine);
 }
 function startModuleSpinner(name, detail) {
+  liveOutputState.activeModuleStartedAt = Date.now();
   if (!supportsAnimatedModuleOutput()) return;
   clearPendingRecipeClosureGuides();
   stopAnimatedModuleLine();
@@ -1987,6 +2010,7 @@ function startModuleSpinner(name, detail) {
       writeAnimatedModuleLine(
         renderModuleLine({
           detail: spinner.detail,
+          elapsed: getActiveModuleElapsed(),
           name: displayModule.name,
           status: "waiting",
           waitingFrame: SPINNER_FRAMES[spinner.frameIndex]
@@ -1999,6 +2023,7 @@ function startModuleSpinner(name, detail) {
   writeAnimatedModuleLine(
     renderModuleLine({
       detail: displayModule.detail,
+      elapsed: getActiveModuleElapsed(),
       name: displayModule.name,
       status: "waiting",
       waitingFrame: SPINNER_FRAMES[0]
@@ -2011,7 +2036,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 printRunContext(parameters) {
@@ -2065,8 +2093,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
@@ -2193,7 +2224,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),
@@ -6229,7 +6262,7 @@ async function runApplyCommand(file, options, run = runPlaybook) {
   if (options.diff && !options.dryRun) {
     throw new CliUsageError("--diff requires --dry-run");
   }
-  printCliHeader("0.13.0-33ef8ce");
+  printCliHeader("0.14.0-5a61f29");
   const environmentOverrides = applyCliEnvironmentOverrides(options.env, {
     firstRun: options.firstRun
   });
@@ -6259,9 +6292,16 @@ function exitAfterApplyError(error, verbose) {
   const exitCode = process.exitCode === void 0 || process.exitCode === 0 ? 2 : process.exitCode;
   process.exit(exitCode);
 }
+function renderSubcommandOptionsHelp(command) {
+  const flagsWidth = Math.max(...command.options.map((option) => option.flags.length));
+  const rows = command.options.map(
+    (option) => `  ${option.flags.padEnd(flagsWidth)}  ${option.description}`
+  );
+  return ["", `Options for "paratix ${command.name()} <file>":`, ...rows].join("\n");
+}
 var program = new Command();
-program.name("paratix").description("Idempotent VPS setup tool in TypeScript").version("0.13.0-33ef8ce");
-program.command("apply <file>").description("Apply a server definition").option(
+program.name("paratix").description("Idempotent VPS setup tool in TypeScript").version("0.14.0-5a61f29");
+var applyCommand = program.command("apply <file>").description("Apply a server definition").option(
   "--diff",
   "When combined with --dry-run, show a unified diff per module that would change.",
   false
@@ -6269,7 +6309,12 @@ program.command("apply <file>").description("Apply a server definition").option(
   "--dry-run",
   "Only check, do not apply. Some modules validate prospective config but cannot verify runtime restarts.",
   false
-).option("--env <key=value...>", "Set env values", collectEnvironment, {}).option("--env-file <path>", "Load dotenv file").option(
+).option(
+  "--env <key=value...>",
+  "Set environment values passed to the playbook (repeatable; key=value).",
+  collectEnvironment,
+  {}
+).option("--env-file <path>", "Load environment values from a dotenv file.").option(
   "--filter <names>",
   "Run only the named recipes/modules (comma-separated, repeatable). Every other node is shown as skipped.",
   collectFilter,
@@ -6302,6 +6347,7 @@ program.command("apply <file>").description("Apply a server definition").option(
     exitAfterApplyError(error, options.verbose);
   }
 });
+program.addHelpText("after", () => renderSubcommandOptionsHelp(applyCommand));
 function parsePositiveNumber(value, options = {}) {
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed <= 0) {
@@ -6396,6 +6442,7 @@ export {
   parsePositiveNumber,
   parseReconnectTimeoutSeconds,
   printExceptionError,
+  renderSubcommandOptionsHelp,
   resetLastResortHandlerForTests,
   resetTsxRegistrationForTests,
   resolveFilteredRun,

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

@@ -583,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
@@ -595,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-DwKdTyHo.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-DwKdTyHo.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.

package/dist/index.js

@@ -61,7 +61,7 @@ import {
   user,
   validateHostLabel,
   validateSshConfig
-} from "./chunk-XIRORNO3.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),

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-DwKdTyHo.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-XIRORNO3.js";
+} from "../chunk-475OT32R.js";
 export {
   apt,
   archive,

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`
 
@@ -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.13.0",
+  "version": "0.14.0",
   "description": "Idempotent VPS setup tool in TypeScript",
   "type": "module",
   "files": [