paratix 0.12.6 → 0.13.0

package/dist/{index-udpAybq3.d.ts → index-DwKdTyHo.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. */

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-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';
 
 /**
  * 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-CWGQ2MYN.js";
+} from "./chunk-XIRORNO3.js";
 
 // src/conditionalModules.ts
 function createConditionalApplyState(environment) {
@@ -607,6 +607,9 @@ var MODULE_NAME_WIDTH = 56;
 var MIN_MODULE_NAME_WIDTH = 12;
 var OUTPUT_INDENT_UNIT = "  ";
 var SPINNER_FRAME_INTERVAL_MS = 80;
+var ASCII_ESC = 27;
+var ANSI_HIDE_CURSOR = `${String.fromCharCode(ASCII_ESC)}[?25l`;
+var ANSI_SHOW_CURSOR = `${String.fromCharCode(ASCII_ESC)}[?25h`;
 var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
 var STATUS_ICONS = {
   changed: pc.yellow("\u21BA"),
@@ -615,10 +618,22 @@ var STATUS_ICONS = {
   skipped: pc.dim("\u2298"),
   waiting: pc.cyan("\u23F8")
 };
-var activeSpinner = null;
-var activeRecipeGuideDepths = [];
-var pendingRecipeClosureGuideDepths = [];
-var recipeOutputDepth = -1;
+var LIVE_OUTPUT_STATE_KEY = /* @__PURE__ */ Symbol.for("paratix.output.liveState");
+function getSharedLiveOutputState() {
+  const registry = globalThis;
+  const existing = registry[LIVE_OUTPUT_STATE_KEY];
+  if (existing != null) return existing;
+  const created = {
+    activeRecipeGuideDepths: [],
+    activeSpinner: null,
+    cursorHidden: false,
+    pendingRecipeClosureGuideDepths: [],
+    recipeOutputDepth: -1
+  };
+  registry[LIVE_OUTPUT_STATE_KEY] = created;
+  return created;
+}
+var liveOutputState = getSharedLiveOutputState();
 function supportsAnimatedModuleOutput() {
   return process.stdout.isTTY && typeof process.stdout.clearLine === "function" && typeof process.stdout.cursorTo === "function";
 }
@@ -645,7 +660,7 @@ function getModuleStatusText(status) {
   }
 }
 function getCurrentOutputDepth() {
-  return Math.max(recipeOutputDepth, 0);
+  return Math.max(liveOutputState.recipeOutputDepth, 0);
 }
 function getGuideDot(depth) {
   return depth % 2 === 0 ? pc.gray("\xB7") : pc.cyan("\xB7");
@@ -653,7 +668,7 @@ function getGuideDot(depth) {
 function buildGuideIndent(baseIndent, options) {
   const indentCharacters = Array.from(baseIndent);
   const guideDepths = [
-    ...options?.activeGuideDepths ?? activeRecipeGuideDepths,
+    ...options?.activeGuideDepths ?? liveOutputState.activeRecipeGuideDepths,
     ...options?.extraGuideDepths ?? []
   ];
   for (const guideDepth of guideDepths) {
@@ -664,16 +679,16 @@ function buildGuideIndent(baseIndent, options) {
   return indentCharacters.join("");
 }
 function clearPendingRecipeClosureGuides() {
-  pendingRecipeClosureGuideDepths = [];
+  liveOutputState.pendingRecipeClosureGuideDepths = [];
 }
 function getModuleIndent() {
-  if (recipeOutputDepth < 0) {
+  if (liveOutputState.recipeOutputDepth < 0) {
     return OUTPUT_INDENT_UNIT;
   }
   return OUTPUT_INDENT_UNIT.repeat(getCurrentOutputDepth() + 2);
 }
 function getRecipeHeaderIndent() {
-  if (recipeOutputDepth < 0) return "";
+  if (liveOutputState.recipeOutputDepth < 0) return "";
   return OUTPUT_INDENT_UNIT.repeat(getCurrentOutputDepth() + 1);
 }
 function getErrorIndent() {
@@ -683,13 +698,13 @@ function getContinuationIndent() {
   return `${getModuleIndent()}   `;
 }
 async function withRecipeOutputScope(scopedOperation) {
-  recipeOutputDepth += 1;
+  liveOutputState.recipeOutputDepth += 1;
   try {
     return await scopedOperation();
   } finally {
-    activeRecipeGuideDepths = activeRecipeGuideDepths.filter((depth) => depth !== recipeOutputDepth);
-    pendingRecipeClosureGuideDepths = [recipeOutputDepth];
-    recipeOutputDepth -= 1;
+    liveOutputState.activeRecipeGuideDepths = liveOutputState.activeRecipeGuideDepths.filter((depth) => depth !== liveOutputState.recipeOutputDepth);
+    liveOutputState.pendingRecipeClosureGuideDepths = [liveOutputState.recipeOutputDepth];
+    liveOutputState.recipeOutputDepth -= 1;
   }
 }
 function renderModuleLine(parameters) {
@@ -702,15 +717,28 @@ function renderModuleLine(parameters) {
   const alignedNameWidth = Math.max(MODULE_NAME_WIDTH - baseIndent.length, MIN_MODULE_NAME_WIDTH);
   return `${indent}${icon}  ${name.padEnd(alignedNameWidth)}  ${statusText}${detailSuffix}`;
 }
+function hideCursor() {
+  if (liveOutputState.cursorHidden) return;
+  if (!supportsAnimatedModuleOutput()) return;
+  process.stdout.write(ANSI_HIDE_CURSOR);
+  liveOutputState.cursorHidden = true;
+}
+function showCursor() {
+  if (!liveOutputState.cursorHidden) return;
+  process.stdout.write(ANSI_SHOW_CURSOR);
+  liveOutputState.cursorHidden = false;
+}
 function writeAnimatedModuleLine(line) {
+  hideCursor();
   process.stdout.clearLine(0);
   process.stdout.cursorTo(0);
   process.stdout.write(fitAnimatedModuleLine(line, process.stdout.columns));
 }
 function stopAnimatedModuleLine(clearCurrentLine = false) {
-  if (activeSpinner == null) return;
-  clearInterval(activeSpinner.interval);
-  activeSpinner = null;
+  showCursor();
+  if (liveOutputState.activeSpinner == null) return;
+  clearInterval(liveOutputState.activeSpinner.interval);
+  liveOutputState.activeSpinner = null;
   if (clearCurrentLine && supportsAnimatedModuleOutput()) {
     process.stdout.clearLine(0);
     process.stdout.cursorTo(0);
@@ -745,7 +773,7 @@ function startModuleSpinner(name, detail) {
     }, SPINNER_FRAME_INTERVAL_MS)
   };
   if (typeof spinner.interval.unref === "function") spinner.interval.unref();
-  activeSpinner = spinner;
+  liveOutputState.activeSpinner = spinner;
   writeAnimatedModuleLine(
     renderModuleLine({
       detail: displayModule.detail,
@@ -760,8 +788,8 @@ function printRecipeHeader(name) {
   clearPendingRecipeClosureGuides();
   const header = pc.bold(pc.blue(`[${name}]`));
   console.log(`${buildGuideIndent(getRecipeHeaderIndent())}${header}`);
-  if (recipeOutputDepth >= 0) {
-    activeRecipeGuideDepths = [...activeRecipeGuideDepths, recipeOutputDepth];
+  if (liveOutputState.recipeOutputDepth >= 0) {
+    liveOutputState.activeRecipeGuideDepths = [...liveOutputState.activeRecipeGuideDepths, liveOutputState.recipeOutputDepth];
   }
 }
 function colorizeDiffLine(line) {
@@ -815,7 +843,7 @@ function printRenderedModuleResult(parameters) {
     status: parameters.status
   });
   const diffLines = parameters.diff == null ? [] : renderDiffLines(parameters.diff);
-  const usesSpinner = supportsAnimatedModuleOutput() && activeSpinner != null;
+  const usesSpinner = supportsAnimatedModuleOutput() && liveOutputState.activeSpinner != null;
   if (usesSpinner) {
     stopAnimatedModuleLine();
     writeAnimatedModuleLine(line);
@@ -838,7 +866,7 @@ function printRecipeModuleResult(name, status, detail, diff) {
   printRenderedModuleResult({
     detail,
     diff,
-    extraGuideDepths: pendingRecipeClosureGuideDepths,
+    extraGuideDepths: liveOutputState.pendingRecipeClosureGuideDepths,
     name,
     status
   });
@@ -1163,11 +1191,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;
   }
@@ -1234,7 +1262,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,
@@ -1441,7 +1469,6 @@ function createRecipeDryRunApply(name, modules, needsDryRunApply) {
     const result = await dryRunRecipeModule({
       environment,
       recipeModule: {
-        _isRecipe: true,
         _modules: modules,
         async apply() {
           await Promise.resolve();
@@ -1451,6 +1478,7 @@ function createRecipeDryRunApply(name, modules, needsDryRunApply) {
           await Promise.resolve();
           return "ok";
         },
+        kind: "recipe",
         name
       },
       shutdownSignal: parameters?.shutdownSignal,
@@ -1470,7 +1498,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,
@@ -1498,6 +1525,7 @@ function recipe(name, modules, options) {
       }
       return "ok";
     },
+    kind: "recipe",
     name
   };
 }
@@ -1606,4 +1634,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-DwKdTyHo.js';

package/dist/modules/index.js

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

package/llm-guide.md

@@ -481,23 +481,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paratix",
-  "version": "0.12.6",
+  "version": "0.13.0",
   "description": "Idempotent VPS setup tool in TypeScript",
   "type": "module",
   "files": [
@@ -21,8 +21,9 @@
     "tsx": "^4.22.3"
   },
   "devDependencies": {
-    "@types/node": "24.12.4",
+    "@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"
   }
 }