paratix 0.2.0 → 0.3.0

package/README.md

@@ -1,43 +1,49 @@
 # Paratix
 
-Idempotent VPS configuration in TypeScript.
+Idempotent VPS automation in TypeScript.
 
 [![npm version](https://img.shields.io/npm/v/paratix)](https://www.npmjs.com/package/paratix)
 [![license](https://img.shields.io/npm/l/paratix)](https://opensource.org/licenses/MIT)
 [![node](https://img.shields.io/node/v/paratix)](https://nodejs.org/)
 
-## Overview
+Paratix lets you manage Linux servers over SSH with TypeScript playbooks instead of YAML or ad-hoc shell scripts. You describe the desired end state of a machine, run the playbook, and Paratix changes only what is necessary.
 
-Paratix configures Linux servers over SSH using TypeScript playbooks. Each playbook declares the desired state of a server -- packages, files, services, firewall rules -- and Paratix enforces that state idempotently. Every module follows a check/apply pattern: `check` determines whether work is needed, `apply` makes it so.
+It is built for developers and operators who want infrastructure automation that feels like application code: typed, reviewable, composable, and easy to keep in version control. You can start small on a single VPS and still keep a disciplined, repeatable workflow.
 
-If you have used Ansible, the idea is the same. The difference is that you write TypeScript instead of YAML, with full type safety and your existing toolchain.
+The result is a practical server automation tool with a compact mental model: modules check state, modules apply state, recipes group related work, and signals run only when changes actually happened.
 
-## Getting started
+## Features
 
-Scaffold a new project:
+- **Idempotent runs**: rerunning the same playbook on an already configured server is safe.
+- **TypeScript authoring**: use regular `.ts` files with imports, conditions, and editor tooling.
+- **Resilient SSH flow**: reconnects after reboots and SSH port changes when modules require it.
+- **Structured orchestration**: recipes and signals keep service reloads and grouped changes explicit.
+- **Strong bootstrap story**: supports explicit first-run flows and strict host-key handling.
+- **Practical built-in modules**: packages, files, services, users, SSH, firewall, systemd, sysctl, mount, rsync, and more.
+
+## Getting Started
+
+If you want the fastest path, scaffold a project first:
 
 ```bash
 npm create paratix my-server
-# or: pnpm create paratix my-server
-# or: yarn create paratix my-server
-# or: bun create paratix my-server
+cd my-server
+npm run apply:dry
+npm run apply -- --first-run
+npm run apply
 ```
 
-This creates a project with the following structure:
+If you want to install `paratix` directly:
 
-```
-my-server/
-  server.ts          # Your playbook
-  files/             # Templates and config files
-  package.json
-  tsconfig.json
+```bash
+npm install paratix
 ```
 
-Open `server.ts` and define your server:
+Create a playbook:
 
 ```typescript
 import { server } from "paratix"
-import { hostname, package as pkg } from "paratix/modules"
+import { hostname, package as pkg, service } from "paratix/modules"
 
 export default server({
   name: "web-01",
@@ -45,13 +51,19 @@ export default server({
   ssh: {
     user: "root",
     ports: [22],
-    privateKey: "~/.ssh/id_ed25519", // "~" is expanded by Paratix
+    privateKey: "~/.ssh/id_ed25519",
   },
-  run: [hostname.set("web-01"), pkg.update("2025-03-01"), pkg.installed("nginx", "curl", "git")],
+  run: [
+    hostname.set("web-01"),
+    pkg.update("2026-03-01"),
+    pkg.installed("nginx", "curl"),
+    service.enabled("nginx"),
+    service.running("nginx"),
+  ],
 })
 ```
 
-Apply the playbook:
+Apply it:
 
 ```bash
 npx paratix apply server.ts
@@ -63,362 +75,47 @@ Preview changes without applying them:
 npx paratix apply server.ts --dry-run
 ```
 
-For most modules, `--dry-run` reports whether Paratix would change remote state without mutating it.
-For SSH hardening modules, Paratix now goes one step further:
-
-- `sshd.config` validates the prospective config with `sshd -t`
-- `sshd.port` validates the prospective config with `sshd -t`
-
-Runtime effects are still intentionally not executed during `--dry-run`. In particular, reloads,
-restarts, port switches, firewall reachability, and reconnect behavior are reported as limited
-verification in the run output instead of being performed.
-
-## SSH host key migration
-
-Paratix now defaults to strict host-key checking (`ssh.strictHostKeyChecking: "yes"`).
-Existing playbooks that relied on implicit TOFU must now opt in explicitly:
-
-```typescript
-ssh: {
-  user: "root",
-  ports: [22],
-  privateKey: "~/.ssh/id_ed25519", // "~" is expanded by Paratix
-  strictHostKeyChecking: "accept-new", // explicit TOFU opt-in
-}
-```
-
-For a safer bootstrap of brand-new hosts, pin the expected host key instead of using TOFU:
-
-```typescript
-ssh: {
-  user: "root",
-  ports: [22],
-  privateKey: "~/.ssh/id_ed25519", // "~" is expanded by Paratix
-  expectedHostFingerprint: "SHA256:your-known-fingerprint",
-}
-```
-
-You can also pin the full OpenSSH public key with `expectedHostPublicKey`.
-
-## Core concepts
-
-### Playbook
-
-A playbook is a TypeScript file that default-exports a `server()` call. It declares the target host, SSH credentials, environment variables, and an ordered list of modules to run.
-
-```typescript
-import { server } from "paratix"
-
-export default server({
-  name: "web-01",
-  host: "10.0.0.1",
-  ssh: {
-    user: "root",
-    ports: [22],
-    privateKey: "~/.ssh/id_ed25519", // "~" is expanded by Paratix
-    expectedHostFingerprint: "SHA256:your-known-fingerprint",
-  },
-  env: {
-    DOMAIN: "example.com",
-    APP_PORT: 3000,
-  },
-  run: [
-    // modules go here
-  ],
-  signals: [
-    // fire after run if anything changed
-  ],
-})
-```
-
-### Module
-
-A module is the smallest unit of configuration. Each module has a `check` function (is the desired state already in place?) and an `apply` function (enforce the desired state). Modules are idempotent: running them twice produces the same result as running them once.
+## How Paratix Works
 
-```typescript
-import { package as pkg, service } from "paratix/modules"
+### Playbooks
 
-pkg.installed("nginx") // installs nginx if missing, does nothing if present
-service.running("nginx") // starts nginx if stopped, does nothing if running
-```
+A playbook is a TypeScript file that default-exports `server(...)`. It defines the target host, SSH configuration, optional environment values, and an ordered list of modules to run.
 
-### Recipe
+### Modules
 
-A recipe groups related modules into a reusable unit with its own signals. Signals on a recipe fire only when a module inside that recipe reported a change.
+Modules are the smallest units of work. Each module checks whether its target state already exists and only applies changes when needed.
 
-```typescript
-import { recipe } from "paratix"
-import { package as pkg, file, service } from "paratix/modules"
-
-const nginx = recipe(
-  "nginx",
-  [
-    pkg.installed("nginx"),
-    file.template("/etc/nginx/nginx.conf", "./files/nginx.conf.tmpl"),
-    service.enabled("nginx"),
-    service.running("nginx"),
-  ],
-  {
-    signals: [service.reload("nginx")],
-  }
-)
-```
+### Recipes
 
-If the config file changes, `service.reload("nginx")` fires. If nothing changed, the reload is skipped.
+Recipes group related modules into a named unit. They help structure larger playbooks and keep the CLI output readable.
 
 ### Signals
 
-Signals are modules that run only when something changed. Use them for actions like reloading a service after a config file update.
-
-At the server level, `signals` fire when any module in `run` reported a change. Inside a recipe, signals fire only when that recipe's modules changed.
-
-```typescript
-export default server({
-  // ...
-  run: [file.template("/etc/myapp/config.yml", "./files/config.yml.tmpl")],
-  signals: [service.restart("myapp")],
-})
-```
-
-**Note:** `service.restart()` and `service.reload()` always apply when called. Place them in `signals`, not directly in `run`.
-
-### Environment
-
-The `env` object makes values available to templates and conditional logic. Values can be strings, numbers, or async functions (resolved lazily on first access).
-
-```typescript
-export default server({
-  // ...
-  env: {
-    DOMAIN: "example.com",
-    APP_PORT: 3000,
-    DB_PASSWORD: async () => fetchFromVault("db-password"),
-  },
-  run: [
-    /* ... */
-  ],
-})
-```
-
-Modules can return `meta` in their result, which merges into the environment for subsequent modules.
-
-When environment values come from multiple sources, Paratix merges them in this order, with later values winning:
-
-1. `--env-file <path>`
-2. `server({ env })`
-3. `--env <key=value>`
-
-### Templates
-
-`file.template()` deploys a file with `{{KEY}}` placeholders resolved from the environment.
-
-Template file (`files/nginx.conf.tmpl`):
+Signals are deferred side effects such as `service.reload(...)` or `service.restart(...)`. They run when the surrounding scope actually changed, and can also be flushed explicitly with `signals.flush()` when you need a checkpoint inside a larger flow.
 
-```
-server {
-    listen 80;
-    server_name {{DOMAIN}};
-    proxy_pass http://127.0.0.1:{{APP_PORT}};
-}
-```
-
-```typescript
-file.template("/etc/nginx/sites-available/default", "./files/nginx.conf.tmpl")
-```
-
-Use `\{{` to produce a literal `{{` in the output. Unknown keys throw an error at runtime.
+## CLI
 
-## CLI reference
-
-```
-paratix apply <file>
+```text
+paratix apply <file> [options]
 
 Options:
-  --dry-run                Check only, don't apply. Some modules validate prospective config but cannot verify runtime restarts.
-  --env <key=value>        Set environment variable (repeatable)
-  --env-file <path>        Load .env file
-  --reconnect-timeout <s>  SSH reconnect timeout in seconds (default: 300)
-  --verbose                Show full stack traces on error
-  --version                Show version number
-  --help                   Show help
-```
-
-## Module reference
-
-All modules are imported from `"paratix/modules"`.
-
-**Note:** `package` is a reserved word in JavaScript. Import it as: `import { package as pkg } from "paratix/modules"`.
-
-### System
-
-| Namespace  | Methods                     |
-| ---------- | --------------------------- |
-| `hostname` | `set`                       |
-| `system`   | `facts`, `reboot`, `uptime` |
-| `sysctl`   | `set`                       |
-| `mount`    | `present`, `absent`         |
-
-### Packages
-
-| Namespace        | Methods                                       |
-| ---------------- | --------------------------------------------- |
-| `package`        | `installed`, `absent`, `update`, `upgrade`    |
-| `apt`            | `debconf`, `distUpgrade`, `key`, `repository` |
-| `releaseUpgrade` | `upgrade`                                     |
-
-### Files
-
-| Namespace  | Methods                                                                                                 |
-| ---------- | ------------------------------------------------------------------------------------------------------- |
-| `file`     | `absent`, `assemble`, `block`, `copy`, `directory`, `line`, `properties`, `replace`, `stat`, `template` |
-| `archive`  | `extract`                                                                                               |
-| `download` | `url`, `github`, `large`                                                                                |
-| `git`      | `clone`                                                                                                 |
-| `rsync`    | `sync`                                                                                                  |
-
-### Services
-
-| Namespace | Methods                                                                   |
-| --------- | ------------------------------------------------------------------------- |
-| `service` | `running`, `stopped`, `enabled`, `disabled`, `restart`, `reload`, `facts` |
-| `systemd` | `unit`, `daemonReload`, `masked`, `unmasked`                              |
-
-### Users and groups
-
-| Namespace | Methods             |
-| --------- | ------------------- |
-| `user`    | `present`, `absent` |
-| `group`   | `present`, `absent` |
-
-### Network and security
-
-| Namespace | Methods                        |
-| --------- | ------------------------------ |
-| `ufw`     | `enabled`, `rule`              |
-| `ssh`     | `authorizedKeys`, `knownHosts` |
-| `sshd`    | `config`, `port`               |
-
-### Scheduling
-
-| Namespace | Methods |
-| --------- | ------- |
-| `cron`    | `job`   |
-
-### Commands
-
-| Namespace | Methods |
-| --------- | ------- |
-| `command` | `shell` |
-
-### Secrets
-
-| Namespace | Methods   |
-| --------- | --------- |
-| `op`      | `resolve` |
-
-## Custom modules
-
-A custom module is an object with `name`, `check`, and `apply`:
-
-```typescript
-import type { Module, ModuleResult, SshConnection, Environment } from "paratix"
-import { NEEDS_APPLY } from "paratix"
-
-function ensureFile(path: string, content: string): Module {
-  return {
-    name: `ensure-file: ${path}`,
-
-    async check(ssh: SshConnection | null, env: Environment): Promise<"needs-apply" | "ok"> {
-      if (!ssh) return NEEDS_APPLY
-      const current = await ssh.readFile(path).catch(() => null)
-      return current === content ? "ok" : NEEDS_APPLY
-    },
-
-    async apply(ssh: SshConnection | null, env: Environment): Promise<ModuleResult> {
-      if (!ssh) return { status: "failed" }
-      await ssh.writeFile(path, content)
-      return { status: "changed" }
-    },
-  }
-}
-```
-
-Rules for custom modules:
-
-- `check` returns `"ok"` or `NEEDS_APPLY` (use the exported constant, not the string `"needs-apply"`).
-- `apply` returns `{ status }` where status is `"changed"`, `"failed"`, `"ok"`, or `"skipped"`.
-- Always handle the case where `ssh` is `null` (happens for local-only modules).
-- Return `meta` from `apply` to pass data to subsequent modules via the environment.
-- Set `local: true` on the module object if it runs on the local machine instead of over SSH.
-
-## SshConnection API
-
-Methods available on the `ssh` parameter in custom modules:
-
-| Method                        | Returns                   | Description                                                                                               |
-| ----------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `exec(cmd, options?)`         | `Promise<ExecResult>`     | Run a command. Returns `{ code, stdout, stderr }`. Throws on non-zero exit unless `ignoreExitCode: true`. |
-| `test(cmd)`                   | `Promise<boolean>`        | Run a command, return `true` if exit code is 0.                                                           |
-| `output(cmd)`                 | `Promise<string>`         | Run a command, return trimmed stdout.                                                                     |
-| `lines(cmd)`                  | `Promise<string[]>`       | Run a command, return stdout split into lines.                                                            |
-| `exists(path)`                | `Promise<boolean>`        | Check if a remote path exists.                                                                            |
-| `readFile(path)`              | `Promise<string>`         | Read a remote file.                                                                                       |
-| `writeFile(path, content)`    | `Promise<void>`           | Write content to a remote file.                                                                           |
-| `uploadFile(local, remote)`   | `Promise<void>`           | Upload a local file via SFTP.                                                                             |
-| `downloadFile(remote, local)` | `Promise<void>`           | Download a remote file.                                                                                   |
-| `sha256(path)`                | `Promise<string \| null>` | Get SHA-256 hex digest, or `null` if the file does not exist.                                             |
-
-Additional methods (`addPort`, `disconnect`, `getConnectionInfo`, `probeSudo`, `updateHost`) are available for advanced use cases. See the type definitions for details.
-
-## Built-in helpers
-
-Import these from `"paratix"`:
-
-| Helper                         | Description                                                                                       |
-| ------------------------------ | ------------------------------------------------------------------------------------------------- |
-| `recipe(name, modules, opts?)` | Group modules into a reusable unit with optional signals. See [Recipes](#recipe) above.           |
-| `assert(condition, message)`   | Abort the run if `condition` returns false. The condition receives the current environment.       |
-| `when(condition, ...modules)`  | Run modules only if `condition` returns true. Skipped modules report `"skipped"`, not `"failed"`. |
-| `debug(message)`               | Print a debug message during the run.                                                             |
-| `fail(message)`                | Abort the run unconditionally with a failure.                                                     |
-| `pause(message?)`              | Wait for the operator to press Enter before continuing.                                           |
-| `shellQuote(value)`            | Safely quote a string for shell interpolation.                                                    |
-| `NEEDS_APPLY`                  | Constant to return from `check` when work is needed.                                              |
-
-## LLM Guide
-
-This package includes an `llm-guide.md` file that provides detailed information for writing Paratix modules and playbooks. It covers the complete API reference, code patterns, and common mistakes to avoid. When using an LLM to generate Paratix code, point it at this file for best results.
-
-## Integration tests
-
-Paratix ships a separate integration test entry point for real SSH/SFTP checks:
-
-```bash
-pnpm --filter paratix test:integration
-```
-
-For the full workspace review path including integration coverage, use:
-
-```bash
-pnpm agent:check:integration
+  --dry-run
+  --env <key=value>
+  --env-file <path>
+  --first-run
+  --reconnect-timeout <seconds>
+  --verbose
+  --version
+  --help
 ```
 
-These tests are intentionally not part of the default unit test run. They require:
-
-- on macOS: `colima` plus a working Docker CLI connected to the active Colima runtime
-- on Linux/CI: a reachable Docker runtime
-
-The integration suite starts a temporary SSH test container, runs the tests against it and removes the container again afterwards. If `colima` is missing, the suite aborts with a clear error message instead of hanging or silently skipping coverage.
+`--first-run` is meant for explicit bootstrap flows where a fresh server must be hardened first and the rest of the system should only be applied later.
 
-The suite now verifies real remote end state for core modules such as
-`file.directory`, `file.copy`, `file.template`, `command.shell`, `download.url`,
-and `download.large`, including ownership, mode, content, large-download flags,
-and idempotent `check()` behavior against a live server.
+## Documentation
 
-An example GitHub Actions workflow is included as a disabled template in
-`.github/workflows/integration-check.yml.disabled`. Rename it to `.yml` when
-you want the integration path to run on GitHub.
+- 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).
 
 ## License
 
-MIT
+MIT — Copyright 2026 [Sebastian Software GmbH](https://sebastian-software.com)

package/dist/cli.js

@@ -695,7 +695,7 @@ async function loadServerDefinitionFromFile(file, options) {
   return definition;
 }
 var program = new Command();
-program.name("paratix").description("Idempotent VPS setup tool in TypeScript").version("0.2.0");
+program.name("paratix").description("Idempotent VPS setup tool in TypeScript").version("0.3.0");
 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.",
@@ -707,7 +707,7 @@ program.command("apply <file>").description("Apply a server definition").option(
   DEFAULT_RECONNECT_TIMEOUT_SECONDS
 ).option("--verbose", "Show full stack traces on error", false).action(async (file, options) => {
   try {
-    printCliHeader("0.2.0");
+    printCliHeader("0.3.0");
     const environmentOverrides = applyCliEnvironmentOverrides(
       // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- Commander options typed as Record<string, unknown>
       options.env,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paratix",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Idempotent VPS setup tool in TypeScript",
   "type": "module",
   "files": [