paratix 0.12.8 → 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-M3ZQJNKM.js";
+} from "./chunk-XIRORNO3.js";
 
 // src/conditionalModules.ts
 function createConditionalApplyState(environment) {
@@ -1191,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;
   }
@@ -1262,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,
@@ -1469,7 +1469,6 @@ function createRecipeDryRunApply(name, modules, needsDryRunApply) {
     const result = await dryRunRecipeModule({
       environment,
       recipeModule: {
-        _isRecipe: true,
         _modules: modules,
         async apply() {
           await Promise.resolve();
@@ -1479,6 +1478,7 @@ function createRecipeDryRunApply(name, modules, needsDryRunApply) {
           await Promise.resolve();
           return "ok";
         },
+        kind: "recipe",
         name
       },
       shutdownSignal: parameters?.shutdownSignal,
@@ -1498,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,
@@ -1526,6 +1525,7 @@ function recipe(name, modules, options) {
       }
       return "ok";
     },
+    kind: "recipe",
     name
   };
 }
@@ -1634,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-M3ZQJNKM.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.8",
+  "version": "0.13.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"
   }
 }