paratix 0.10.0 → 0.12.2

package/llm-guide.md

@@ -49,6 +49,7 @@ import {
   apt,
   archive,
   command,
+  compose,
   cron,
   download,
   file,
@@ -56,10 +57,13 @@ import {
   group,
   hostname,
   mount,
+  net,
   op,
   package as pkg,
+  quadlet,
   releaseUpgrade,
   rsync,
+  script,
   service,
   ssh,
   sshd,
@@ -146,9 +150,9 @@ export default server({
 
 ### `command`
 
-| Method          | Signature                                                            | Idempotent        |
-| --------------- | -------------------------------------------------------------------- | ----------------- |
-| `command.shell` | `(cmd: string, options?: { check?: string; name?: string }): Module` | Only with `check` |
+| Method          | Signature                                                                                | Idempotent        |
+| --------------- | ---------------------------------------------------------------------------------------- | ----------------- |
+| `command.shell` | `(cmd: string, options?: { check?: string; name?: string; secrets?: string[] }): Module` | Only with `check` |
 
 ### `cron`
 
@@ -174,11 +178,22 @@ the idiomatic way to ensure a previously installed cron job is gone.
 
 ### `download`
 
-| Method            | Signature                                                                                                                                                                     | Idempotent |
-| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| `download.url`    | `(destination: string, url: string, options?: { force?: boolean; headers?: Record<string, string>; sha256?: string; mode?: string; owner?: string; group?: string }): Module` | Yes        |
-| `download.github` | `(destination: string, options: { repo: string; tag: string; asset: string; token?: string; sha256?: string; mode?: string; owner?: string; group?: string }): Module`        | Yes        |
-| `download.large`  | `(destination: string, url: string, options?: { group?: string; headers?: Record<string, string>; mode?: string; owner?: string; sha256?: string }): Module`                  | Yes (flag) |
+| Method            | Signature                                                                                                                                                                                                                                                                                                                    | Idempotent |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `download.url`    | `(destination: string, url: string, options?: { allowInsecureHttp?: boolean; allowInsecureHttpHeaders?: boolean; allowUnverifiedDownload?: boolean; connectTimeout?: number; force?: boolean; headers?: Record<string, string>; sha256?: string; mode?: string; owner?: string; group?: string; timeout?: number }): Module` | Yes        |
+| `download.github` | `(destination: string, options: { repo: string; tag: string; asset: string; token?: string; allowUnverifiedDownload?: boolean; connectTimeout?: number; sha256?: string; mode?: string; owner?: string; group?: string; timeout?: number }): Module`                                                                         | Yes        |
+| `download.large`  | `(destination: string, url: string, options?: { allowInsecureHttp?: boolean; allowInsecureHttpHeaders?: boolean; allowUnverifiedDownload?: boolean; connectTimeout?: number; group?: string; headers?: Record<string, string>; mode?: string; owner?: string; sha256?: string; timeout?: number }): Module`                  | Yes (flag) |
+
+Downloads require an explicit integrity decision at runtime: provide `sha256`
+for verification, or set `allowUnverifiedDownload: true` when the remote
+artifact is intentionally trusted without a pinned digest. `download.url` and
+`download.large` allow only HTTPS by default; set `allowInsecureHttp: true`
+only when an `http://` source or redirect is intentional. Sensitive headers
+such as `Authorization`, `Cookie`, and `X-Api-Key` are still rejected over
+plaintext HTTP unless `allowInsecureHttpHeaders: true` is also set.
+Curl-based downloads use bounded transfer timing by default (`connectTimeout:
+10000`, `timeout: 300000`, both in milliseconds). Override these options for
+very slow artifact hosts or large downloads.
 
 ### `file`
 
@@ -197,6 +212,10 @@ the idiomatic way to ensure a previously installed cron job is gone.
 | `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" }`.
+
+**Hinweis zu `file.line`:** Der `line`-Wert muss eine einzelne Zeile ohne CR/LF sein. Für mehrzeilige Inhalte `file.block` verwenden.
+
 ### `git`
 
 | Method      | Signature                                                                 | Idempotent |
@@ -223,6 +242,21 @@ the idiomatic way to ensure a previously installed cron job is gone.
 | `mount.present` | `(options: { fstype: string; opts: string; path: string; persist?: boolean; src: string }): Module` | Yes        |
 | `mount.absent`  | `(options: { path: string; persist?: boolean }): Module`                                            | Yes        |
 
+### `net`
+
+| Method          | Signature                                                                                                                                                                                               | Idempotent |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `net.hosts`     | `(ip: string, hostnames: string[], options?: { state?: "absent" \| "present" }): Module`                                                                                                                | Yes        |
+| `net.interface` | `(name: string, options: InterfaceOptions): Module`                                                                                                                                                     | Yes        |
+| `net.request`   | `(url: string, options?: { allowInsecureHttpHeaders?: boolean; body?: string; connectTimeout?: number; headers?: Record<string, string>; method?: string; status?: number; timeout?: number }): Module` | Yes        |
+| `net.resolv`    | `(options: { nameservers: string[]; search?: string[] }): Module`                                                                                                                                       | Yes        |
+| `net.route`     | `(destination: string, gateway: string, options?: { device?: string; state?: "absent" \| "present" }): Module`                                                                                          | Yes        |
+| `net.waitFor`   | `(options: WaitForOptions): Module`                                                                                                                                                                     | Yes        |
+
+`net.request` uses bounded curl timing by default (`connectTimeout: 10000`,
+`timeout: 300000`, both in milliseconds). Override these values for endpoints
+that are expected to respond more slowly.
+
 ### `op`
 
 | Method       | Signature                                      | Idempotent                        |
@@ -269,9 +303,9 @@ apt.distUpgrade("2026-05-01", { timeout: 1_200_000 })
 
 ### `releaseUpgrade`
 
-| Method                   | Signature                                                                       | Idempotent |
-| ------------------------ | ------------------------------------------------------------------------------- | ---------- |
-| `releaseUpgrade.upgrade` | `(options?: { dryRun?: boolean; resolveHost?: () => Promise<string> }): Module` | Yes        |
+| Method                   | Signature                                                                                         | Idempotent |
+| ------------------------ | ------------------------------------------------------------------------------------------------- | ---------- |
+| `releaseUpgrade.upgrade` | `(options?: { dryRun?: boolean; resolveHost?: () => Promise<string>; timeout?: number }): Module` | Yes        |
 
 ### `rsync`
 
@@ -283,6 +317,12 @@ When the active Paratix SSH session already verified the host via `ssh.expectedH
 or `ssh.expectedHostPublicKey`, `rsync.sync()` reuses that verified host key for the external
 rsync SSH process and does not depend on a local `known_hosts` entry.
 
+### `script`
+
+| Method        | Signature                                                                                    | Idempotent           |
+| ------------- | -------------------------------------------------------------------------------------------- | -------------------- |
+| `script.once` | `(name: string, localPath: string, options?: { args?: string[]; version?: string }): Module` | Yes (versioned flag) |
+
 ### `service`
 
 | Method             | Signature                | Idempotent                                                |
@@ -302,6 +342,8 @@ 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.
+
 ### `sshd`
 
 | Method        | Signature                                    | Idempotent                         |
@@ -319,9 +361,9 @@ rsync SSH process and does not depend on a local `known_hosts` entry.
 
 ### `sysctl`
 
-| Method       | Signature                                                                           | Idempotent |
-| ------------ | ----------------------------------------------------------------------------------- | ---------- |
-| `sysctl.set` | `(key: string, value: string, options?: { state?: "absent" \| "present" }): Module` | Yes        |
+| Method       | Signature                                                                                                | Idempotent                                                                                                                                  |
+| ------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sysctl.set` | `(key: string, value: string, options?: { resetValue?: string; state?: "absent" \| "present" }): Module` | Yes for `present`. For `absent`: only the persistence file is removed by default; pass `resetValue` to also restore the live runtime value. |
 
 ### `system`
 
@@ -411,7 +453,7 @@ function myCustomModule(configPath: string, content: string): Module {
 
     async apply(ssh: SshConnection | null, env: Environment): Promise<ModuleResult> {
       if (!ssh) return failed(`[my-module: ${configPath}] SSH connection is required`)
-      await ssh.writeFile(configPath, content)
+      await ssh.writeFile(configPath, content, { mode: "0644" })
       return {
         meta: [meta.env("MY_MODULE_PATH", configPath)],
         status: "changed",
@@ -439,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)`    | `Promise<void>`                         | Write content to remote file.                                                                  |
-| `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 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).                                        |
 
 ### ExecOptions
 
@@ -463,12 +505,18 @@ Methods available on the `ssh` parameter:
 {
   env?: Record<string, string>       // Extra environment variables
   ignoreExitCode?: boolean           // Don't throw on non-zero exit
+  input?: string                     // Payload written to stdin before EOF
+  maxOutputBytes?: number            // Cap stored stdout/stderr bytes
   secrets?: string[]                 // Strings to mask in error output
   silent?: boolean                   // Suppress stdout/stderr
   timeout?: number                   // Abort after N milliseconds
 }
 ```
 
+Prefer `input` for secret payloads instead of shell arguments, so values do not
+leak through process lists, `/proc/<pid>/cmdline`, or SSH logs. Add the same
+values to `secrets` only as an additional masking guard for error output.
+
 ## Template System
 
 Files deployed via `file.template(remotePath, localTemplatePath)` can contain `{{KEY}}` placeholders.
@@ -553,7 +601,7 @@ Conditionally run modules based on package state on the remote host.
 
 ```typescript
 when.packageInstalled("ufw", ufw.disabled())
-when.packageAbsent("docker-ce", package.installed("docker-ce"))
+when.packageAbsent("docker-ce", pkg.installed("docker-ce"))
 ```
 
 ### `when.commandExists(name, ...modules)` / `when.commandMissing(name, ...modules)`
@@ -562,7 +610,7 @@ Conditionally run modules based on whether a command exists on the remote host.
 
 ```typescript
 when.commandExists("docker", service.running("docker"))
-when.commandMissing("docker", package.installed("docker-ce"))
+when.commandMissing("docker", pkg.installed("docker-ce"))
 ```
 
 ### Filesystem guard variants
@@ -661,6 +709,97 @@ async check(ssh) {
 }
 ```
 
+## Dry-Run Diff Output (`--diff`)
+
+Paratix runs a playbook in dry-run mode via `paratix apply <file> --dry-run`, which
+reports per-module `changed (dry-run)` or `ok` based on each module's `check()`.
+
+`--diff` enables a second, opt-in layer: modules that mark themselves as diff
+producers also render a unified-diff block under their status line so the user
+sees _what_ would change, not only _that_ something would change.
+
+```
+$ paratix apply server.ts --dry-run --diff
+  ↺  /etc/ssh/sshd_config                            changed  (dry-run)
+     │ --- /etc/ssh/sshd_config
+     │ +++ /local/path/sshd_config
+     │ -Port 22
+     │ +Port 2222
+```
+
+Rules:
+
+- `--diff` requires `--dry-run`. The CLI rejects `paratix apply <file> --diff`
+  without `--dry-run` before any SSH connection or playbook side effect.
+- Without `--diff`, the dry-run runs are byte-identical to before: no extra
+  remote round-trips, no diff output.
+- Modules that do not opt in keep showing only `changed (dry-run)`.
+- Every diff line is masked through the registered-secret sink and a terminal
+  sanitizer before printing, so secret-laden file contents never leak verbatim.
+- `_dryRunDetail` (inline suffix) and `diff` (multi-line block) are independent
+  output layers — a module may emit both at once; the runner renders detail next
+  to the status line and the diff below it.
+
+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. |
+
+### Implementing a Diff for a Custom Module
+
+A module participates in `--diff` output by setting `_dryRunDiffProducer: true`
+and implementing `_applyDryRun`. The runner calls `_applyDryRun` only when the
+user passed `--diff` and `check()` returned `"needs-apply"`.
+
+```typescript
+import { buildUnifiedDiff } from "paratix/modules" // not exported publicly today
+// or, for scalar drift:
+import { buildKeyValueDiff } from "paratix/modules"
+```
+
+```typescript
+return {
+  _dryRunDiffProducer: true,
+  async _applyDryRun(ssh) {
+    if (!ssh) return { status: "changed" }
+    try {
+      const current = (await ssh.exists(remotePath)) ? await ssh.readFile(remotePath) : ""
+      const diff = buildUnifiedDiff(current, desired, {
+        currentLabel: remotePath,
+        desiredLabel: localPath,
+      })
+      return diff === "" ? { status: "changed" } : { diff, status: "changed" }
+    } catch {
+      // A read failure must not abort the dry-run. Drop the diff and fall back
+      // to the generic "(dry-run)" suffix.
+      return { status: "changed" }
+    }
+  },
+  async check(ssh) {
+    /* unchanged */
+  },
+  async apply(ssh) {
+    /* unchanged */
+  },
+  name: "myModule: ...",
+}
+```
+
+The diff string is plain text — no ANSI codes. The output layer applies colors
+(`-` red, `+` green, headers dimmed) and indentation.
+
 ## Do's and Don'ts
 
 ### DO
@@ -698,6 +837,7 @@ async check(ssh) {
 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.
+16. Do NOT set `ssh.sudoPassword` to a value from `op.resolve()` or `meta.env()` -- `SshConfig` is frozen at server construction time, before any module in `run` executes. Use a static source like `process.env.SUDO_PASSWORD` or a variable populated before the server definition is imported.
 
 ## Testing Patterns
 
@@ -743,7 +883,8 @@ describe("myModule", () => {
 ### `createMockSsh` behavior
 
 - Accepts `Record<string, Partial<ExecResult>>` mapping command strings to responses.
-- Default response: `{ code: 0, stdout: "", stderr: "" }`.
+- Unknown commands fail closed with an error. Add every expected command to the
+  response map, or the helper throws instead of returning a successful default.
 - `ssh.test(cmd)` returns `code === 0`.
 - `ssh.exists(path)` delegates to `ssh.test("[ -e '<path>' ]")`.
 - `ssh.readFile(path)` delegates to `ssh.output("cat '<path>'")`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paratix",
-  "version": "0.10.0",
+  "version": "0.12.2",
   "description": "Idempotent VPS setup tool in TypeScript",
   "type": "module",
   "files": [
@@ -15,17 +15,17 @@
     "paratix": "./dist/cli.js"
   },
   "dependencies": {
-    "commander": "^13.1.0",
+    "commander": "^15.0.0",
     "picocolors": "^1.1.1",
     "ssh2": "^1.16.0",
-    "tsx": "^4.19.0"
+    "tsx": "^4.22.3"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
+    "@types/node": "24.12.4",
     "@types/ssh2": "^1.15.4",
     "tsup": "^8.4.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.1.0"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -55,8 +55,10 @@
   "license": "MIT",
   "scripts": {
     "build": "tsup",
-    "test": "vitest run",
-    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test": "pnpm test:unit && pnpm test:dist",
+    "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:watch": "vitest"
   }
 }