paratix 0.4.0 → 0.5.0

package/dist/user-CraCJci7.d.ts

@@ -0,0 +1,1392 @@
+import { M as Module } from './types-BPzPHfax.js';
+
+/**
+ * Modules for Debian/Ubuntu-specific apt configuration.
+ *
+ * Provides four apt-specific helpers:
+ * - `debconf` — pre-seed debconf answers for non-interactive installs
+ * - `distUpgrade` — run `apt-get dist-upgrade` with full dependency resolution
+ * - `key` — import a GPG key into `/etc/apt/keyrings/`
+ * - `repository` — add a PPA or custom `.list` source file
+ *
+ * For installing, removing and upgrading packages use the distro-agnostic
+ * `package` module instead.
+ *
+ * @see pkg
+ */
+declare const apt: {
+    /**
+     * Set debconf selections for a package so that installs/upgrades
+     * can proceed non-interactively with the desired answers.
+     *
+     * @param packageName - The package name whose debconf questions to pre-seed.
+     * @param selections - A map of `question -> value` entries where the key is
+     *   the full debconf question name (e.g. `"postfix/main_mailer_type"`).
+     * @returns A Module that applies the debconf selections.
+     *
+     * @example
+     * apt.debconf("postfix", {
+     *   "postfix/main_mailer_type": "Internet Site",
+     *   "postfix/mailname": "example.com",
+     * })
+     */
+    debconf(packageName: string, selections: Record<string, string>): Module;
+    /**
+     * Run `apt-get update && apt-get dist-upgrade` once per dated flag.
+     * Performs a full distribution upgrade with dependency resolution.
+     *
+     * @param date - A date string used as the idempotency key (e.g. `"2024-01-15"`).
+     * @returns A Module that performs the dist-upgrade.
+     */
+    distUpgrade(date: string): Module;
+    /**
+     * Import a GPG key into `/etc/apt/keyrings/` for use with signed repositories.
+     * @param name - Key file name (without `.gpg` extension).
+     * @param url - URL to download the key from.
+     * @param options - Required trust anchor for the downloaded key.
+     * @param options.fingerprint - Expected OpenPGP fingerprint of the repository key.
+     * @returns A Module that imports the GPG key.
+     */
+    key(name: string, url: string, options: {
+        fingerprint: string;
+    }): Module;
+    /**
+     * Add an apt repository source, either as a PPA or a custom source line.
+     *
+     * **PPA form**: pass `"ppa:user/name"` as the first argument (no `source`).
+     * Uses `add-apt-repository` internally.
+     *
+     * **Standard form**: pass a name and a deb source line. The source is
+     * written to `/etc/apt/sources.list.d/<name>.list`. The `signed-by` option
+     * is automatically derived from `name` (pointing to
+     * `/etc/apt/keyrings/<name>.gpg`) unless overridden.
+     *
+     * @param nameOrPpa - Repository name or PPA identifier (e.g. `"ppa:user/name"`).
+     * @param source - The deb source line (omit for PPA form).
+     * @param options - Optional settings.
+     * @param options.signedBy - Override the key name used for `signed-by`
+     *   (`false` to disable auto-derivation, a string to use a different key name).
+     * @returns A Module that configures the repository.
+     *
+     * @example
+     * // PPA form
+     * apt.repository("ppa:ondrej/php")
+     *
+     * @example
+     * // Standard form – signed-by is auto-derived from "nodejs"
+     * apt.repository(
+     *   "nodejs",
+     *   "deb https://deb.nodesource.com/node_20.x nodistro main",
+     * )
+     *
+     * @example
+     * // Standard form with signed-by disabled
+     * apt.repository(
+     *   "internal",
+     *   "deb [arch=amd64] https://packages.example.com stable main",
+     *   { signedBy: false },
+     * )
+     */
+    repository(nameOrPpa: string, source?: string, options?: {
+        signedBy?: false | string;
+    }): Module;
+};
+
+/**
+ * Modules for managing archive extraction on the remote host.
+ */
+declare const archive: {
+    /**
+     * Extract an archive to a destination directory on the remote host.
+     *
+     * Supports tar, tar.gz, tgz, tar.bz2, tar.xz, and zip formats.
+     * Uses a marker file with SHA256 checksum for idempotency.
+     *
+     * @param source - Path to the archive (remote path, or local path when upload is true).
+     * @param destination - The destination directory on the remote host.
+     * @param options - Optional settings.
+     * @param options.owner - Run chown -R after extraction.
+     * @param options.upload - Upload a local file to the remote host before extracting.
+     * @returns A Module that manages the archive extraction.
+     */
+    extract(source: string, destination: string, options?: {
+        owner?: string;
+        upload?: boolean;
+    }): Module;
+};
+
+/**
+ * Modules for running arbitrary shell commands on the remote host.
+ */
+declare const command: {
+    /**
+     * Run an arbitrary shell command on the remote host.
+     *
+     * By default the module always applies (no idempotency). Provide `options.check`
+     * with a shell expression that exits `0` when the desired state is already
+     * present -- in that case the command is skipped.
+     *
+     * @param cmd - The shell command to execute.
+     * @param options - Optional configuration for the command.
+     * @param options.check - An optional shell expression used as the idempotency guard.
+     *   If it exits `0`, the command is considered already done.
+     * @param options.name - An optional display name shown in the run output.
+     * @param options.secrets - Secret values that must be redacted from command output.
+     * @returns A Module that executes the shell command.
+     *
+     * @example
+     * command.shell("curl -fsSL https://example.com/install.sh | bash", {
+     *   check: "which my-tool",
+     *   name: "install my-tool",
+     * })
+     */
+    shell(cmd: string, options?: {
+        check?: string;
+        name?: string;
+        secrets?: string[];
+    }): Module;
+};
+
+type ComposeRuntime = "docker" | "podman";
+/**
+ * Modules for managing Docker Compose / Podman Compose stacks on a remote host.
+ *
+ * All methods auto-detect the container runtime (`docker` or `podman`) unless
+ * an explicit `runtime` option is provided.
+ */
+declare const compose: {
+    /**
+     * Ensure a compose-file is present at `<projectDirectory>/compose.yml`.
+     *
+     * Provide either `src` (a local file path to upload) or `content` (a string
+     * to write). The check phase compares the remote file content with the
+     * desired content and skips the apply if they match.
+     *
+     * @param options - Configuration for the compose file.
+     * @param options.projectDirectory - The project directory on the remote host.
+     * @param options.src - Local file path to upload as `compose.yml`.
+     * @param options.content - String content to write as `compose.yml`.
+     * @param options.runtime - Explicit container runtime override.
+     * @returns A Module that ensures the compose file is present and valid.
+     */
+    config(options: {
+        content?: string;
+        projectDirectory: string;
+        runtime?: ComposeRuntime;
+        src?: string;
+    }): Module;
+    /**
+     * Tear down all containers in the compose stack. Optionally remove volumes.
+     *
+     * @param options - Configuration for the down operation.
+     * @param options.projectDirectory - The project directory on the remote host.
+     * @param options.volumes - When `true`, also remove named volumes.
+     * @param options.runtime - Explicit container runtime override.
+     * @returns A Module that ensures all containers are stopped and removed.
+     */
+    down(options: {
+        projectDirectory: string;
+        runtime?: ComposeRuntime;
+        volumes?: boolean;
+    }): Module;
+    /**
+     * Pull the latest images for all services in the compose stack.
+     * Signal-style: always applies since an efficient up-to-date check is not
+     * feasible.
+     *
+     * @param options - Configuration for the pull operation.
+     * @param options.projectDirectory - The project directory on the remote host.
+     * @param options.runtime - Explicit container runtime override.
+     * @returns A Module that pulls the latest images.
+     */
+    pull(options: {
+        projectDirectory: string;
+        runtime?: ComposeRuntime;
+    }): Module;
+    /**
+     * Restart all containers by running `down` followed by `up -d`.
+     * Signal-style: always applies.
+     *
+     * @param options - Configuration for the restart operation.
+     * @param options.projectDirectory - The project directory on the remote host.
+     * @param options.runtime - Explicit container runtime override.
+     * @returns A Module that restarts the compose stack.
+     */
+    restart(options: {
+        projectDirectory: string;
+        runtime?: ComposeRuntime;
+    }): Module;
+    /**
+     * Generate and write a systemd service unit that manages the compose stack
+     * via `ExecStart` / `ExecStop`.
+     *
+     * The service name defaults to `compose-<basename(projectDirectory)>` when not
+     * explicitly provided.
+     *
+     * @param options - Configuration for the systemd unit.
+     * @param options.detached - When true, use `compose up -d`; otherwise start attached.
+     * @param options.projectDirectory - The project directory on the remote host.
+     * @param options.name - Optional service name (without `.service` suffix).
+     * @param options.runtime - Explicit container runtime override.
+     * @returns A Module that ensures the systemd unit file is present and up-to-date.
+     */
+    systemd(options: {
+        detached?: boolean;
+        name?: string;
+        projectDirectory: string;
+        runtime?: ComposeRuntime;
+    }): Module;
+    /**
+     * Ensure all services in the compose stack are running.
+     *
+     * The check phase inspects each container's state via `ps --format json`
+     * and only skips when every service reports `"running"`.
+     *
+     * @param options - Configuration for the up operation.
+     * @param options.projectDirectory - The project directory on the remote host.
+     * @param options.services - Optional list of specific services to start.
+     * @param options.runtime - Explicit container runtime override.
+     * @returns A Module that ensures the compose stack is up.
+     */
+    up(options: {
+        projectDirectory: string;
+        runtime?: ComposeRuntime;
+        services?: string[];
+    }): Module;
+};
+
+/** Options for `cron.job`. */
+type CronJobOptions = {
+    /** The crontab line to manage (e.g. `"0 * * * * /usr/bin/backup"`). */
+    job: string;
+    /** Whether the job should be `"present"` or `"absent"`. Defaults to `"present"`. */
+    state?: "absent" | "present";
+};
+/**
+ * Modules for managing cron jobs in user crontabs.
+ *
+ * Each managed entry is identified by a `# paratix: <name>` marker comment
+ * written on the line directly above the job line, making all changes
+ * idempotent and safely repeatable.
+ */
+declare const cron: {
+    /**
+     * Ensure a cron job is present in (or absent from) a user's crontab.
+     *
+     * Each managed entry is tracked via a `# paratix: <name>` marker comment
+     * placed on the line directly above the job line. When the marker already
+     * exists, the job line is updated in place. When `state` is `"absent"`,
+     * both the marker and the job line are removed.
+     *
+     * @param user - The target user whose crontab is managed.
+     * @param name - Unique identifier for this cron job, used in the marker line.
+     * @param options - Job content and desired state.
+     * @param options.job - The crontab line to manage (e.g. `"0 * * * * /usr/bin/backup"`).
+     * @param options.state - Whether the job should be `"present"` or `"absent"`. Defaults to `"present"`.
+     * @returns A Module that manages the cron job entry.
+     */
+    job(user: string, name: string, options: CronJobOptions): Module;
+};
+
+/**
+ * Options shared by all download methods.
+ */
+type BaseDownloadOptions = {
+    /** Allow unencrypted `http://` downloads explicitly. */
+    allowInsecureHttp?: boolean;
+    /** Explicitly opt out of integrity verification for trusted sources. */
+    allowUnverifiedDownload?: boolean;
+    /** Group owner to set on the downloaded file via `chown`. */
+    group?: string;
+    /** File mode to set via `chmod` (e.g. `"0755"`). */
+    mode?: string;
+    /** User owner to set on the downloaded file via `chown`. */
+    owner?: string;
+    /** Expected SHA-256 hex digest for integrity verification. */
+    sha256?: string;
+};
+/**
+ * Modules for downloading files to remote servers via `curl`.
+ */
+declare const download: {
+    /**
+     * Download a release asset from a GitHub repository.
+     *
+     * Builds the download URL from the repository, tag, and asset name. For
+     * private repositories, provide a `token` which is sent as an
+     * `Authorization` header.
+     *
+     * Idempotency follows the same rules as {@link download.url}: SHA-256
+     * comparison when a digest is given, otherwise file-existence check.
+     *
+     * @param destination - Absolute path on the remote server where the asset is saved.
+     * @param options - Repository coordinates and optional download settings.
+     * @param options.repo - GitHub repository in `owner/repo` format (e.g. `"hashicorp/terraform"`).
+     * @param options.tag - Release tag (e.g. `"v1.5.0"`).
+     * @param options.asset - GitHub release asset filename (e.g. `"terraform_1.5.0_linux_amd64.zip"`).
+     * @param options.token - GitHub Personal Access Token for private repositories.
+     * @param options.sha256 - Expected SHA-256 hex digest for integrity verification.
+     * @param options.allowUnverifiedDownload - Explicitly opt out of integrity verification.
+     * @param options.mode - File mode to set via `chmod` (e.g. `"0755"`).
+     * @param options.owner - User owner to set on the downloaded file via `chown`.
+     * @param options.group - Group owner to set on the downloaded file via `chown`.
+     * @returns A Module that manages the GitHub release download.
+     */
+    github(destination: string, options: {
+        /** GitHub release asset filename (e.g. `"terraform_1.5.0_linux_amd64.zip"`). */
+        asset: string;
+        /** GitHub repository in `owner/repo` format (e.g. `"hashicorp/terraform"`). */
+        repo: string;
+        /** Release tag (e.g. `"v1.5.0"`). */
+        tag: string;
+        /** GitHub Personal Access Token for private repositories. */
+        token?: string;
+    } & BaseDownloadOptions): Module;
+    /**
+     * Download a large file that should only be fetched once.
+     *
+     * Tracks whether the download has been performed by writing a flag file
+     * under `/var/lib/paratix/flags/`. The flag name is derived from a SHA-256
+     * hash of the URL. When `sha256` is provided, the check additionally verifies
+     * the remote file's digest, and the downloaded file is verified after transfer.
+     *
+     * @param destination - Absolute path on the remote server where the file is saved.
+     * @param url - The URL to download from.
+     * @param options - Optional settings for ownership, permissions, and headers.
+     * @param options.allowInsecureHttp - Allow unencrypted `http://` downloads explicitly.
+     * @param options.group - Group owner to set on the downloaded file via `chown`.
+     * @param options.mode - File mode to set via `chmod` (e.g. `"0755"`).
+     * @param options.owner - User owner to set on the downloaded file via `chown`.
+     * @param options.sha256 - Expected SHA-256 hex digest for integrity verification.
+     * @param options.allowUnverifiedDownload - Explicitly opt out of integrity verification.
+     * @param options.headers - Additional HTTP headers sent with the curl request.
+     * @returns A Module that manages the large file download.
+     */
+    large(destination: string, url: string, options?: {
+        /** Allow unencrypted `http://` downloads explicitly. */
+        allowInsecureHttp?: boolean;
+        /** Explicitly opt out of integrity verification for trusted sources. */
+        allowUnverifiedDownload?: boolean;
+        /** Group owner to set on the downloaded file via `chown`. */
+        group?: string;
+        /** Additional HTTP headers sent with the curl request. */
+        headers?: Record<string, string>;
+        /** File mode to set via `chmod` (e.g. `"0755"`). */
+        mode?: string;
+        /** User owner to set on the downloaded file via `chown`. */
+        owner?: string;
+        /** Expected SHA-256 hex digest for integrity verification. */
+        sha256?: string;
+    }): Module;
+    /**
+     * Download a file from a URL to the remote server via `curl -fsSL`.
+     *
+     * Idempotency is determined by SHA-256 comparison (when `sha256` is
+     * provided), file existence (when no digest is given), or skipped entirely
+     * when `force` is `true`.
+     *
+     * @param destination - Absolute path on the remote server where the file is saved.
+     * @param url - The URL to download from.
+     * @param options - Optional settings for integrity, ownership, and headers.
+     * @param options.allowUnverifiedDownload - Explicitly opt out of integrity verification.
+     * @returns A Module that manages the file download.
+     */
+    url(destination: string, url: string, options?: {
+        /** Allow unencrypted `http://` downloads explicitly. */
+        allowInsecureHttp?: boolean;
+        /** Explicitly opt out of integrity verification for trusted sources. */
+        allowUnverifiedDownload?: boolean;
+        /** Force re-download even if the file already exists. */
+        force?: boolean;
+        /** Additional HTTP headers sent with the curl request. */
+        headers?: Record<string, string>;
+    } & BaseDownloadOptions): Module;
+};
+
+/** Options for the {@link block} module. */
+type BlockOptions = {
+    /** The desired content between the markers. */
+    content: string;
+    /** Unique identifier for the managed block. Used in the marker comment lines. */
+    name: string;
+    /** Comment prefix for the marker lines (default `"#"`). */
+    prefix?: string;
+};
+/**
+ * Concatenate local fragment files and write the result to the remote host.
+ * The file is only transferred when the remote SHA-256 differs from the
+ * combined local fragments.
+ *
+ * @param remotePath - Destination path on the remote host.
+ * @param fragments - Array of local file paths whose contents are concatenated.
+ * @param options - Optional file attributes.
+ * @param options.mode - Optional chmod mode string (e.g. `"0644"`).
+ * @param options.owner - Optional chown owner string (e.g. `"www-data:www-data"`).
+ * @returns A Module that assembles the fragments on the remote host.
+ */
+declare function assemble(remotePath: string, fragments: string[], options?: {
+    mode?: string;
+    owner?: string;
+}): Module;
+/**
+ * Ensure a managed block of text is present in a remote file.
+ * The block is delimited by marker comments of the form
+ * `<prefix> BEGIN paratix: <name>` / `<prefix> END paratix: <name>`.
+ * If the markers are not yet present, the block is appended to the file.
+ * If the markers already exist, the content between them is replaced in place.
+ *
+ * @param remotePath - Path to the file on the remote host.
+ * @param options - Block configuration.
+ * @param options.content - The desired content between the begin and end markers.
+ * @param options.name - Unique identifier for the managed block, used in the marker lines.
+ * @param options.prefix - Comment prefix for the marker lines (default `"#"`).
+ * @returns A Module that ensures the block is present with the correct content.
+ */
+declare function block(remotePath: string, options: BlockOptions): Module;
+/**
+ * Set file or directory ownership and permissions on the remote host.
+ * Only the attributes specified in `options` are checked and applied.
+ *
+ * @param remotePath - Path to the file or directory on the remote host.
+ * @param options - Attributes to enforce.
+ * @param options.group - Optional group name.
+ * @param options.mode - Optional chmod mode string (e.g. `"0644"`).
+ * @param options.owner - Optional owner name.
+ * @returns A Module that ensures the properties match.
+ */
+declare function properties(remotePath: string, options: {
+    group?: string;
+    mode?: string;
+    owner?: string;
+}): Module;
+/**
+ * Replace all occurrences of a regex pattern in a remote file.
+ * `check` uses `grep -E` to detect whether the pattern still exists in the file.
+ * `apply` reads the file, performs the replacement in TypeScript and writes it back.
+ *
+ * @param remotePath - Path to the file on the remote host.
+ * @param pattern - Extended regex pattern to match.
+ * @param replacement - Replacement string.
+ * @returns A Module that performs the substitution.
+ */
+declare function replace(remotePath: string, pattern: string, replacement: string): Module;
+/**
+ * Read metadata about a remote file via `stat`.
+ * This is a read-only module: `check` always reports `"needs-apply"` so the runner
+ * invokes `apply`, which populates the result's `meta` map with the following keys:
+ * - `file.stat.size` — file size in bytes
+ * - `file.stat.mode` — octal permission bits (e.g. `"644"`)
+ * - `file.stat.owner` — owning user name
+ * - `file.stat.group` — owning group name
+ * - `file.stat.type` — file type string (e.g. `"regular file"`, `"directory"`)
+ * - `file.stat.mtime` — last modification time as a Unix timestamp string
+ *
+ * @param remotePath - Path to the file on the remote host.
+ * @returns A Module that reads file metadata into `result.meta`.
+ */
+declare function stat(remotePath: string): Module;
+
+/**
+ * Modules for managing remote files and directories.
+ *
+ * Idempotency is enforced via SHA-256 checksums for file content and
+ * existence checks for directories and individual lines.
+ */
+declare const file: {
+    /**
+     * Ensure a remote path does not exist, removing it recursively if present.
+     *
+     * @param remotePath - Path to remove on the remote host.
+     * @returns A Module that ensures the path is absent.
+     */
+    absent(remotePath: string): Module;
+    assemble: typeof assemble;
+    block: typeof block;
+    chmod(remotePath: string, mode: string): Module;
+    chown(remotePath: string, owner: string): Module;
+    /**
+     * Upload a local file to the remote host.
+     * The file is only transferred when the remote SHA-256 differs from the local one.
+     *
+     * @param remotePath - Destination path on the remote host.
+     * @param localPath - Source path on the local filesystem.
+     * @param options - Optional file attributes.
+     * @param options.mode - Optional chmod mode string (e.g. `"0644"`).
+     * @param options.owner - Optional chown owner string (e.g. `"www-data:www-data"`).
+     * @returns A Module that copies the file to the remote host.
+     */
+    copy(remotePath: string, localPath: string, options?: {
+        mode?: string;
+        owner?: string;
+    }): Module;
+    /**
+     * Ensure a remote directory exists, creating it recursively if needed.
+     *
+     * @param remotePath - Path of the directory to create on the remote host.
+     * @param options - Optional directory attributes.
+     * @param options.mode - Optional chmod mode string.
+     * @param options.owner - Optional chown owner string.
+     * @returns A Module that ensures the directory exists.
+     */
+    directory(remotePath: string, options?: {
+        mode?: string;
+        owner?: string;
+    }): Module;
+    /**
+     * Ensure a specific line is present in a remote file.
+     * When `options.match` is provided, the first line matching the regex is replaced
+     * with the new `line` value instead of appending.
+     *
+     * @param remotePath - Path to the file on the remote host.
+     * @param line - The exact line content to ensure is present.
+     * @param options - Optional match configuration.
+     * @param options.match - A regex pattern; when matched, the line is replaced rather than appended.
+     * @returns A Module that ensures the line is present.
+     */
+    line(remotePath: string, line: string, options?: {
+        match?: string;
+    }): Module;
+    properties: typeof properties;
+    replace: typeof replace;
+    stat: typeof stat;
+    /**
+     * Render a local template file with env values and write the result to the remote host.
+     * Uses SHA-256 comparison of the rendered output to avoid unnecessary writes.
+     *
+     * @param remotePath - Destination path on the remote host.
+     * @param templatePath - Path to the local template file containing `{{key}}` placeholders.
+     * @param options - Optional file attributes.
+     * @param options.mode - Optional chmod mode string.
+     * @param options.owner - Optional chown owner string.
+     * @param options.strict - When `true`, every template placeholder must use an explicit modifier.
+     * @returns A Module that renders and writes the template.
+     */
+    template(remotePath: string, templatePath: string, options?: {
+        mode?: string;
+        owner?: string;
+        strict?: boolean;
+    }): Module;
+};
+
+/**
+ * Modules for managing Git repositories on the remote host.
+ */
+declare const git: {
+    /**
+     * Ensure a Git repository is cloned to the given destination and optionally
+     * checked out at a specific ref (branch, tag, or commit).
+     *
+     * If the destination directory does not yet contain a `.git` folder, the
+     * repository is cloned from scratch. If it already exists, the repository is
+     * updated instead (fetch + checkout + reset). When no `ref` is specified, a
+     * plain `git pull` is performed on an existing clone.
+     *
+     * @param repo - The repository URL to clone.
+     * @param destination - The destination path on the remote host.
+     * @param options - Optional settings.
+     * @param options.ref - A branch, tag, or commit SHA to check out.
+     * @returns A Module that manages the cloned repository.
+     */
+    clone(repo: string, destination: string, options?: {
+        ref?: string;
+    }): Module;
+};
+
+/**
+ * Modules for managing Linux groups.
+ */
+declare const group: {
+    /**
+     * Ensure a group does not exist. Removes it via `groupdel` if present.
+     *
+     * @param name - The group name to remove.
+     * @returns A Module that ensures the group is absent.
+     */
+    absent(name: string): Module;
+    /**
+     * Ensure a group exists. Creates it via `groupadd` if absent.
+     *
+     * @param name - The group name.
+     * @param options - Optional group configuration.
+     * @param options.gid - Desired numeric GID.
+     * @returns A Module that ensures the group is present.
+     */
+    present(name: string, options?: {
+        gid?: number;
+    }): Module;
+};
+
+/**
+ * Modules for managing the system hostname.
+ */
+declare const hostname: {
+    /**
+     * Set the system hostname via `hostnamectl set-hostname`.
+     * Checks the current hostname first and skips the command when it already matches.
+     *
+     * @param name - The desired hostname.
+     * @returns A Module that sets the hostname.
+     */
+    set(name: string): Module;
+};
+
+/**
+ * Modules for managing filesystem mounts and `/etc/fstab` entries on a remote host.
+ */
+declare const mount: {
+    /**
+     * Ensure a mountpoint is not mounted. Optionally removes the `/etc/fstab` entry.
+     *
+     * The check phase verifies both whether the path is currently mounted and, when
+     * `persist` is `true`, whether a corresponding fstab entry exists. The apply
+     * phase always returns `"changed"` even if only one of the two conditions required
+     * action.
+     *
+     * @param options - Configuration for unmounting.
+     * @param options.path - The mountpoint to unmount.
+     * @param options.persist - When `true` (default), also remove the fstab entry.
+     * @returns A Module that ensures the mountpoint is absent.
+     */
+    absent(options: {
+        path: string;
+        persist?: boolean;
+    }): Module;
+    /**
+     * Ensure a filesystem is mounted at the given path. Creates the mountpoint
+     * directory if it does not exist. Optionally persists the mount in `/etc/fstab`.
+     *
+     * The check phase verifies that the mountpoint is active (via `findmnt`) and,
+     * when `persist` is `true`, that the fstab entry matches the desired line
+     * exactly. It does **not** compare the currently mounted source, filesystem
+     * type, or options against the desired values — a remount is only triggered
+     * when the mountpoint is absent entirely.
+     *
+     * @param options - Configuration for the mount.
+     * @param options.fstype - The filesystem type (e.g. `"ext4"`, `"tmpfs"`, `"nfs"`).
+     * @param options.opts - Mount options string (e.g. `"noexec,nosuid,nodev,size=512m"`).
+     * @param options.path - The mountpoint path.
+     * @param options.persist - When `true` (default), add or update the fstab entry.
+     * @param options.src - The device or virtual filesystem source (e.g. `"tmpfs"`, `"/dev/sdb1"`).
+     * @returns A Module that ensures the filesystem is mounted.
+     */
+    present(options: {
+        fstype: string;
+        opts: string;
+        path: string;
+        persist?: boolean;
+        src: string;
+    }): Module;
+};
+
+/** Wait-for condition and timing options. */
+type WaitForOptions = {
+    /** String that must appear in `file` for the condition to be satisfied. Requires `file`. */
+    contains?: string;
+    /** Absolute path to a file whose existence (or content) is checked. */
+    file?: string;
+    /** Host address used for port checks (default: `"127.0.0.1"`). */
+    host?: string;
+    /** Poll interval in milliseconds between condition checks (default: `2000`). */
+    interval?: number;
+    /** TCP port to probe with `nc -z`. */
+    port?: number;
+    /** Maximum time in milliseconds to wait before failing (default: `60000`). */
+    timeout?: number;
+};
+
+/** Interface configuration options shared by Netplan and networkd builders. */
+type InterfaceOptions = {
+    addresses?: string[];
+    dhcp?: boolean;
+    gateway?: string;
+    nameservers?: string[];
+};
+/**
+ * Modules for managing network configuration on the remote host.
+ */
+declare const net: {
+    /**
+     * Manage entries in /etc/hosts.
+     *
+     * @param ip - The IP address for the hosts entry.
+     * @param hostnames - One or more hostnames to associate with the IP.
+     * @param options - Optional settings.
+     * @param options.state - Whether the entry should be "present" (default) or "absent".
+     * @returns A Module that manages the hosts entry.
+     */
+    hosts(ip: string, hostnames: string[], options?: {
+        state?: "absent" | "present";
+    }): Module;
+    /**
+     * Configure a network interface via Netplan (when available) or systemd-networkd.
+     *
+     * @param name - The interface name (e.g. "eth0").
+     * @param options - Network configuration options.
+     * @returns A Module that manages the interface configuration.
+     */
+    interface(name: string, options: InterfaceOptions): Module;
+    /**
+     * Check that an HTTP endpoint returns the expected status code and/or body.
+     *
+     * @param url - The URL to request.
+     * @param options - Optional request settings.
+     * @param options.body - Expected string in the response body.
+     * @param options.headers - Additional HTTP headers.
+     * @param options.method - HTTP method (default: `"GET"`).
+     * @param options.status - Expected HTTP status code (default: `200`).
+     * @returns A Module that checks the HTTP endpoint.
+     */
+    request(url: string, options?: {
+        body?: string;
+        headers?: Record<string, string>;
+        method?: string;
+        status?: number;
+    }): Module;
+    /**
+     * Manage /etc/resolv.conf (nameservers and search domains).
+     *
+     * @param options - Resolver configuration.
+     * @param options.nameservers - List of nameserver IP addresses.
+     * @param options.search - Optional list of DNS search domains.
+     * @returns A Module that manages /etc/resolv.conf.
+     */
+    resolv(options: {
+        nameservers: string[];
+        search?: string[];
+    }): Module;
+    /**
+     * Manage persistent static routes via `ip route` and a systemd-networkd drop-in.
+     *
+     * @param destination - The route destination (e.g. "10.0.0.0/24").
+     * @param gateway - The gateway IP address.
+     * @param options - Optional settings.
+     * @param options.device - The network device to use (e.g. "eth0").
+     * @param options.state - Whether the route should be "present" (default) or "absent".
+     * @returns A Module that manages the static route.
+     */
+    route(destination: string, gateway: string, options?: {
+        device?: string;
+        state?: "absent" | "present";
+    }): Module;
+    /**
+     * Wait for a condition to become true on the remote host.
+     *
+     * @param options - Wait condition and timing options.
+     * @returns A Module that waits for the condition.
+     */
+    waitFor(options: WaitForOptions): Module;
+};
+
+/**
+ * Modules for resolving secrets from 1Password on the local controller.
+ */
+declare const op: {
+    /**
+     * Resolve 1Password secret references into environment values.
+     *
+     * Regular references are resolved in bulk via `op inject`.
+     * References ending in `/one-time-password` or `/otp` are resolved individually
+     * via `op read` and returned as lazy functions that compute a fresh TOTP code
+     * on each call.
+     *
+     * This module runs locally (`local: true`) and never touches the remote host.
+     * `check` always returns `"needs-apply"` so the runner executes `apply`
+     * unconditionally and propagates the resolved meta values.
+     * If any CLI call fails the module returns `{ status: "failed", error }`.
+     *
+     * @param references - A map of logical names to 1Password secret references
+     *   (e.g. `op://vault/item/field`). References ending in `/one-time-password`
+     *   or `/otp` are treated as TOTP sources.
+     * @returns A Module that resolves the references and emits them as meta values.
+     *
+     * @example
+     * ```ts
+     * op.resolve({
+     *   DB_PASSWORD: "op://prod/database/password",
+     *   API_TOKEN:   "op://prod/api/credential",
+     *   MFA_CODE:    "op://prod/authenticator/one-time-password",
+     * })
+     * ```
+     */
+    resolve(references: Record<string, string>): Module;
+};
+
+/**
+ * Distro-agnostic package management module.
+ *
+ * Automatically detects the system package manager (apt, dnf, yum, apk)
+ * and delegates to the appropriate commands. All methods are idempotent.
+ *
+ * For Debian/Ubuntu-specific configuration (debconf pre-seeding, GPG keys,
+ * apt repositories) use the `apt` module instead.
+ *
+ * @example
+ * // Install packages
+ * pkg.installed("git", "curl")
+ *
+ * @example
+ * // Refresh package lists and upgrade all packages on a specific date
+ * pkg.update("2024-01-15")
+ * pkg.upgrade("2024-01-15")
+ */
+declare const pkg: {
+    /**
+     * Ensure the given packages are not installed.
+     *
+     * The check phase queries the package database for each package individually;
+     * the remove command is only executed when at least one package is present.
+     *
+     * @param packages - One or more package names to remove.
+     * @returns A Module that removes the packages if any are present.
+     *
+     * @example
+     * pkg.absent("vim", "nano")
+     */
+    absent(...packages: string[]): Module;
+    /**
+     * Ensure the given packages are installed.
+     *
+     * The check phase queries the package database for each package individually;
+     * the install command is only executed when at least one package is missing.
+     *
+     * @param packages - One or more package names to install.
+     * @returns A Module that installs missing packages.
+     *
+     * @example
+     * pkg.installed("git", "curl", "unzip")
+     */
+    installed(...packages: string[]): Module;
+    /**
+     * Refresh the package manager's package lists once per dated flag.
+     *
+     * A flag file at `${FLAGS_DIRECTORY}/package-update-<date>` is created after
+     * a successful run. On the next run the flag is detected and the module
+     * reports `"ok"` without running the update again. Changing `date` to a new
+     * value invalidates all previous flags for this operation.
+     *
+     * @param date - A date string used as the idempotency key (e.g. `"2024-01-15"`).
+     * @returns A Module that refreshes package lists.
+     *
+     * @example
+     * pkg.update("2024-01-15")
+     */
+    update(date: string): Module;
+    /**
+     * Upgrade all installed packages once per dated flag.
+     *
+     * A flag file at `${FLAGS_DIRECTORY}/package-upgrade-<date>` is created after
+     * a successful run. On the next run the flag is detected and the module
+     * reports `"ok"` without running the upgrade again. Changing `date` to a new
+     * value invalidates all previous flags for this operation.
+     *
+     * On apt systems this runs `apt-get update && apt-get upgrade -y` (not
+     * `dist-upgrade`); use `apt.distUpgrade` for full dependency resolution.
+     *
+     * @param date - A date string used as the idempotency key (e.g. `"2024-01-15"`).
+     * @returns A Module that upgrades all packages.
+     *
+     * @example
+     * pkg.upgrade("2024-01-15")
+     *
+     * @see apt.distUpgrade
+     */
+    upgrade(date: string): Module;
+};
+
+type QuadletAutoUpdate = "local" | "registry";
+type QuadletRestartPolicy = "always" | "no" | "on-abnormal" | "on-abort" | "on-failure" | "on-success" | "on-watchdog";
+type QuadletContainerOptions = {
+    autoUpdate?: QuadletAutoUpdate;
+    containerName?: string;
+    description?: string;
+    environment?: Record<string, string>;
+    exec?: string[];
+    image: string;
+    name: string;
+    networks?: string[];
+    podmanArgs?: string[];
+    publishPorts?: string[];
+    restart?: QuadletRestartPolicy;
+    volumes?: string[];
+    wantedBy?: string;
+};
+/**
+ * Modules for managing Podman Quadlet definitions.
+ *
+ * The first V1 method writes `.container` files under `/etc/containers/systemd`
+ * and reloads systemd when content changes. Resulting services can be managed
+ * via the regular `service.*(...)` modules.
+ */
+declare const quadlet: {
+    /**
+     * Write a Podman Quadlet `.container` definition and reload systemd when it changes.
+     *
+     * The resulting generated service can be controlled with `service.enabled(name)`
+     * and `service.running(name)`.
+     *
+     * @param options - Configuration for the Quadlet container definition.
+     * @param options.name - Quadlet base name without `.container`.
+     * @param options.image - Container image reference.
+     * @param options.description - Optional systemd unit description.
+     * @param options.containerName - Optional explicit Podman container name.
+     * @param options.autoUpdate - Optional Podman auto-update policy.
+     * @param options.environment - Optional environment variables.
+     * @param options.exec - Optional command and arguments for `Exec=`.
+     * @param options.networks - Optional `Network=` entries.
+     * @param options.podmanArgs - Optional `PodmanArgs=` entries.
+     * @param options.publishPorts - Optional `PublishPort=` entries.
+     * @param options.restart - Optional `Restart=` policy in the `[Container]` section.
+     * @param options.volumes - Optional `Volume=` entries.
+     * @param options.wantedBy - Optional install target. Defaults to `multi-user.target`.
+     * @returns A Module that ensures the Quadlet file is present and up to date.
+     */
+    container(options: QuadletContainerOptions): Module;
+};
+
+/**
+ * Options for the {@link releaseUpgrade.upgrade} module.
+ */
+type ReleaseUpgradeOptions = {
+    /**
+     * When `true`, only check whether an upgrade is available without applying
+     * any changes. The module returns `"ok"` regardless of what is found.
+     */
+    dryRun?: boolean;
+    /**
+     * Optional async function to resolve the new host address after the
+     * post-upgrade reboot. Useful when the server's IP address may change
+     * (e.g. DHCP or cloud environments). The resolved value is emitted as
+     * `system.host` meta so the runner can reconnect to the correct address.
+     */
+    resolveHost?: () => Promise<string>;
+};
+/**
+ * Modules for upgrading the operating system to the next major release.
+ *
+ * Supports Ubuntu (via `do-release-upgrade`) and Debian (via sources.list
+ * rewrite + `apt-get full-upgrade`). After a successful upgrade the module
+ * signals the runner to reboot and optionally reconnect to a new host address
+ * via the `system.reboot` / `system.host` meta keys.
+ */
+declare const releaseUpgrade: {
+    /**
+     * Upgrade the remote host to the next major OS release.
+     *
+     * The distribution is auto-detected from `/etc/os-release`. Ubuntu hosts
+     * are upgraded with `do-release-upgrade`; Debian hosts are upgraded by
+     * rewriting apt sources to the current stable suite and running
+     * `apt-get full-upgrade`.
+     *
+     * The `check` phase returns `"needs-apply"` when an upgrade is available
+     * (Ubuntu: `do-release-upgrade -c` exits 0; Debian: current codename differs
+     * from stable codename) and `"ok"` when the host is already up to date.
+     *
+     * @param options - Optional settings.
+     * @param options.dryRun - When `true`, only inspect whether an upgrade is
+     *   available without modifying the system.
+     * @param options.resolveHost - Async callback invoked after the upgrade to
+     *   determine the new host address before the runner reconnects.
+     * @returns A Module that performs the OS release upgrade.
+     *
+     * @example
+     * // Simple upgrade — auto-detect distro and apply
+     * releaseUpgrade.upgrade()
+     *
+     * @example
+     * // Dry-run: check availability without making changes
+     * releaseUpgrade.upgrade({ dryRun: true })
+     *
+     * @example
+     * // Resolve the new host address after reboot (e.g. dynamic DNS or DHCP)
+     * releaseUpgrade.upgrade({
+     *   resolveHost: async () => {
+     *     const ip = await myDns.resolve("my-server.example.com")
+     *     return ip
+     *   },
+     * })
+     */
+    upgrade(options?: ReleaseUpgradeOptions): Module;
+};
+
+type SyncOptions = {
+    /** Permission mode applied via `--chmod`, e.g. `"Du=rwx,go=rx,Fu=rw,go=r"`. */
+    chmod?: string;
+    /** Remove files on the remote that are absent from the source (`--delete`). */
+    delete?: boolean;
+    /** Absolute destination path on the remote host. */
+    dest: string;
+    /** Patterns passed to rsync `--exclude` in order, applied after includes. */
+    exclude?: string[];
+    /** Group name for `--chown`; defaults to `owner` when only `owner` is set. */
+    group?: string;
+    /** Patterns passed to rsync `--include` in order, applied before excludes. */
+    include?: string[];
+    /** Owner name for `--chown`. */
+    owner?: string;
+    /** Local source path (file or directory) to synchronize. */
+    src: string;
+    /**
+     * SSH `StrictHostKeyChecking` option passed to the `-o` flag.
+     *
+     * Defaults to `"yes"`. Use `"accept-new"` for explicit TOFU when first-time
+     * connections must be auto-accepted, or `"no"` to disable checking entirely
+     * (not recommended for production).
+     */
+    strictHostKeyChecking?: "accept-new" | "no" | "off" | "yes";
+};
+/**
+ * Modules for synchronizing files to a remote host using rsync.
+ */
+declare const rsync: {
+    /**
+     * Synchronize a local path to a remote destination using rsync over SSH.
+     *
+     * The `check` phase runs rsync with `--dry-run` and reports `needs-apply`
+     * when the itemized output is non-empty. The `apply` phase returns
+     * `"changed"` when rsync reports transferred items, or `"ok"` when the
+     * destination was already in sync.
+     *
+     * @param options - Sync configuration including source, destination, and optional filters.
+     * @returns A Module that manages the rsync synchronization.
+     *
+     * @example
+     * ```ts
+     * rsync.sync({
+     *   src: "./dist/",
+     *   dest: "/var/www/app",
+     *   delete: true,
+     *   exclude: ["*.map"],
+     *   owner: "www-data",
+     * })
+     * ```
+     *
+     * @example Enforce strict host-key checking for a host that is already known:
+     * ```ts
+     * rsync.sync({
+     *   src: "./dist/",
+     *   dest: "/var/www/app",
+     *   strictHostKeyChecking: "yes",
+     * })
+     * ```
+     */
+    sync(options: SyncOptions): Module;
+};
+
+/**
+ * Modules for executing scripts on the remote host.
+ */
+declare const script: {
+    /**
+     * Upload and run a local script on the remote host exactly once.
+     * Idempotency is tracked via a versioned flag file; bumping the version
+     * causes the script to run again.
+     *
+     * @param name - A unique identifier for this script execution (alphanumeric, dots, hyphens, underscores).
+     * @param localPath - Path to the script on the local filesystem.
+     * @param options - Optional settings.
+     * @param options.args - Arguments to pass to the script (each element is shell-quoted).
+     * @param options.version - Version string for the flag file (default: `"1"`).
+     * @returns A Module that manages the one-time script execution.
+     */
+    once(name: string, localPath: string, options?: {
+        args?: string[];
+        version?: string;
+    }): Module;
+};
+
+/**
+ * Modules for managing systemd services.
+ *
+ * State-checking methods (`running`, `stopped`, `enabled`, `disabled`) are
+ * idempotent. Signal-style methods (`restart`, `reload`) always apply.
+ */
+declare const service: {
+    /**
+     * Ensure a systemd service is disabled and will not start on boot.
+     * @param name - The systemd unit name.
+     * @returns A Module that ensures the service is disabled.
+     */
+    disabled(name: string): Module;
+    /**
+     * Ensure a systemd service is enabled to start on boot.
+     * @param name - The systemd unit name.
+     * @returns A Module that ensures the service is enabled.
+     */
+    enabled(name: string): Module;
+    /**
+     * Collect status information for all systemd services and expose them as
+     * meta entries. Does not change anything on the server.
+     * @returns A Module that gathers service facts into `service.<name>` meta keys.
+     */
+    facts(): Module;
+    /**
+     * Reload a systemd service. Intended as a recipe signal -- always applies.
+     * @param name - The systemd unit name.
+     * @returns A Module that reloads the service.
+     */
+    reload(name: string): Module;
+    /**
+     * Restart a systemd service. Intended as a recipe signal -- always applies.
+     * @param name - The systemd unit name.
+     * @returns A Module that restarts the service.
+     */
+    restart(name: string): Module;
+    /**
+     * Ensure a systemd service is running. Starts the service if inactive.
+     * @param name - The systemd unit name (e.g. `"nginx"`).
+     * @returns A Module that ensures the service is running.
+     */
+    running(name: string): Module;
+    /**
+     * Ensure a systemd service is stopped. Stops the service if active.
+     * @param name - The systemd unit name.
+     * @returns A Module that ensures the service is stopped.
+     */
+    stopped(name: string): Module;
+};
+
+type KnownHostsOptions = {
+    expectedFingerprint?: string;
+    port?: number;
+    publicKey?: string;
+    state?: "absent" | "present";
+};
+/**
+ * Modules for managing SSH client-side resources such as known hosts
+ * and authorized keys.
+ */
+declare const ssh: {
+    /**
+     * Ensure a public key is present in (or absent from) a user's `authorized_keys` file.
+     *
+     * When `state` is `"present"` (the default), the key is appended if missing and the
+     * `.ssh` directory and `authorized_keys` file are created with correct ownership
+     * and permissions. When `state` is `"absent"`, the matching line is removed.
+     *
+     * @param user - The target user whose `authorized_keys` file is managed.
+     * @param key - The full public key string (e.g. `"ssh-ed25519 AAAA... comment"`).
+     * @param options - Optional settings.
+     * @param options.state - Whether the key should be `"present"` or `"absent"`. Defaults to `"present"`.
+     * @returns A Module that manages the authorized key entry.
+     */
+    authorizedKeys(user: string, key: string, options?: {
+        state?: "absent" | "present";
+    }): Module;
+    /**
+     * Ensure a host is present in (or absent from) the connecting user's `~/.ssh/known_hosts`.
+     *
+     * When `state` is `"present"` (the default), the host's public keys are fetched
+     * via `ssh-keyscan` and appended to `~/.ssh/known_hosts`. When `state` is
+     * `"absent"`, the host entry is removed via `ssh-keygen -R`.
+     *
+     * @param host - The hostname or IP address to manage.
+     * @param options - Optional settings.
+     * @param options.state - Whether the host should be `"present"` or `"absent"`. Defaults to `"present"`.
+     * @returns A Module that manages the known hosts entry.
+     */
+    knownHosts(host: string, options?: KnownHostsOptions): Module;
+};
+
+/**
+ * Modules for managing the OpenSSH daemon configuration (`/etc/ssh/sshd_config`).
+ * All methods restart or reload `sshd` after applying changes.
+ */
+declare const sshd: {
+    /**
+     * Apply one or more key-value settings to `sshd_config`.
+     * Existing directives are updated in-place; missing directives are appended.
+     *
+     * @param settings - A map of sshd_config directive names to their desired values
+     *   (e.g. `{ PasswordAuthentication: "no" }`).
+     * @returns A Module that applies the sshd configuration settings.
+     */
+    config(settings: Record<string, string>): Module;
+    /**
+     * Set the SSH daemon listen port.
+     * Updates the `Port` directive in `sshd_config` and restarts `sshd`.
+     * The new port is exported as `sshd.port` in the module result meta so
+     * the runner can reconnect on the updated port.
+     *
+     * @param targetPort - The port number sshd should listen on.
+     * @returns A Module that sets the sshd listen port.
+     */
+    port(targetPort: number): Module;
+};
+
+/**
+ * Modules for managing kernel parameters via sysctl on the remote host.
+ */
+declare const sysctl: {
+    /**
+     * Set a sysctl kernel parameter and persist it across reboots.
+     *
+     * The live value is applied immediately via `sysctl -w` and a configuration
+     * file is written to `/etc/sysctl.d/99-paratix-<sanitized-key>.conf` for
+     * persistence.
+     *
+     * When `state` is `"absent"`, the persistence file is removed but the live
+     * value is not reverted (a reboot will restore the default).
+     *
+     * @param key - The sysctl key (e.g. "net.ipv4.ip_forward").
+     * @param value - The desired value (e.g. "1").
+     * @param options - Optional settings.
+     * @param options.state - Whether the parameter should be "present" (default) or "absent".
+     * @returns A Module that manages the sysctl parameter.
+     */
+    set(key: string, value: string, options?: {
+        state?: "absent" | "present";
+    }): Module;
+};
+
+/**
+ * Options for the reboot module.
+ */
+type RebootOptions = {
+    /**
+     * Optional async function to resolve the new host address after a reboot.
+     * Useful when the server's IP address may change (e.g. DHCP or cloud environments).
+     */
+    resolveHost?: () => Promise<string>;
+};
+/**
+ * Modules for managing system-level operations.
+ */
+declare const system: {
+    /**
+     * Collect system facts (OS, architecture, hostname, kernel, RAM, CPU, IPs, disk).
+     * Always applies because it is informational and should always report.
+     *
+     * All gathered values are emitted as `system.*` meta keys.
+     *
+     * @returns A Module that collects system facts.
+     */
+    facts(): Module;
+    /**
+     * Reboot the remote system via `shutdown -r now`.
+     * Always applies because a reboot is an imperative action.
+     *
+     * When `resolveHost` is provided, the resolved address is emitted as
+     * `system.host` meta so the runner can update the SSH connection.
+     * The `system.reboot` meta signal is always set to `"true"`.
+     *
+     * @param options - Optional settings including a host resolver.
+     * @returns A Module that reboots the system.
+     */
+    reboot(options?: RebootOptions): Module;
+    /**
+     * Read the system uptime in seconds from `/proc/uptime`.
+     * Always applies because it is informational and should always report.
+     *
+     * The uptime value is emitted as `system.uptime` meta.
+     *
+     * @returns A Module that reads the system uptime.
+     */
+    uptime(): Module;
+};
+
+/**
+ * Modules for managing systemd unit files and unit masking.
+ *
+ * The `unit` method writes unit files with idempotent checks and triggers a daemon-reload
+ * on change. `masked` and `unmasked` control unit masking state.
+ * `daemonReload` is a signal-style method that always applies.
+ */
+declare const systemd: {
+    /**
+     * Reload the systemd manager configuration. Intended as a recipe signal --
+     * always applies.
+     * @returns A Module that runs `systemctl daemon-reload`.
+     */
+    daemonReload(): Module;
+    /**
+     * Ensure a systemd unit is masked and cannot be started.
+     * @param name - The systemd unit name (e.g. `"apt-daily.timer"`).
+     * @returns A Module that ensures the unit is masked.
+     */
+    masked(name: string): Module;
+    /**
+     * Write a systemd unit file to `/etc/systemd/system/` and reload the
+     * daemon configuration when the content changes.
+     *
+     * The check phase compares the remote file content with the desired
+     * content string. Apply writes the file and runs `systemctl daemon-reload`.
+     *
+     * @param name - Unit file name (e.g. `"my-app.service"` or `"backup.timer"`).
+     * @param content - The full unit file content.
+     * @returns A Module that ensures the unit file is present with the given content.
+     */
+    unit(name: string, content: string): Module;
+    /**
+     * Ensure a systemd unit is unmasked and can be started normally.
+     * @param name - The systemd unit name (e.g. `"apt-daily.timer"`).
+     * @returns A Module that ensures the unit is unmasked.
+     */
+    unmasked(name: string): Module;
+};
+
+/**
+ * Modules for managing the UFW (Uncomplicated Firewall) on Debian/Ubuntu hosts.
+ */
+declare const ufw: {
+    /**
+     * Ensure UFW is inactive. If UFW is not installed, this is treated as already satisfied.
+     *
+     * @returns A Module that ensures UFW is disabled.
+     */
+    disabled(): Module;
+    /**
+     * Ensure UFW is active. Enables the firewall non-interactively if not already running.
+     *
+     * @returns A Module that ensures UFW is enabled.
+     */
+    enabled(): Module;
+    /**
+     * Add an allow or deny rule for one or more ports.
+     * The check phase reads `ufw status` and verifies the expected rule is present.
+     *
+     * @param action - Whether to `"allow"` or `"deny"` traffic on the given ports.
+     * @param ports - A single port number or an array of port numbers.
+     * @returns A Module that manages UFW rules.
+     */
+    rule(action: "allow" | "deny", ports: number | number[]): Module;
+};
+
+type UserOptions = {
+    groups?: string[];
+    home?: string;
+    password?: string;
+    shell?: string;
+    uid?: number;
+};
+/**
+ * Modules for managing Linux user accounts.
+ */
+declare const user: {
+    /**
+     * Ensure a user account does not exist. Removes the account via `userdel`.
+     *
+     * @param name - The username to remove.
+     * @param options - Optional removal configuration.
+     * @param options.removeHome - When `true`, also delete the user's home directory.
+     * @returns A Module that ensures the user account is absent.
+     */
+    absent(name: string, options?: {
+        removeHome?: boolean;
+    }): Module;
+    /**
+     * Ensure a user account exists. Creates the account if absent, or runs
+     * `usermod` to update attributes if the user already exists.
+     *
+     * @param name - The username.
+     * @param options - Optional user account configuration.
+     * @param options.uid - Desired numeric UID.
+     * @param options.shell - Login shell path (e.g. `"/bin/bash"`).
+     * @param options.home - Home directory path.
+     * @param options.groups - Supplementary groups to add the user to.
+     * @param options.password - Pre-hashed password (e.g. SHA-512 `$6$...`) set via `chpasswd -e`.
+     * @returns A Module that ensures the user account is present.
+     */
+    present(name: string, options?: UserOptions): Module;
+};
+
+export { apt as a, archive as b, command as c, compose as d, cron as e, download as f, file as g, git as h, group as i, hostname as j, rsync as k, service as l, mount as m, net as n, op as o, pkg as p, quadlet as q, releaseUpgrade as r, script as s, ssh as t, sshd as u, sysctl as v, system as w, systemd as x, ufw as y, user as z };