hostctl 0.1.32

package/README.md

@@ -0,0 +1,1027 @@
+# hostctl
+
+`hostctl` is a modern, lightweight alternative to tools like Ansible, designed with simplicity and ease of use at its core. The primary goal of `hostctl` is to provide a straightforward and consistent way to execute scripts on both local and remote hosts. It aims for portability across all POSIX-style systems.
+
+For detailed information on Hostctl's architecture and design, please see the [ARCHITECTURE.md](ARCHITECTURE.md) document.
+For notes on developing and contributing to Hostctl, refer to the [CONTRIBUTING.md](CONTRIBUTING.md) document.
+
+## Quick start
+
+### Install age
+
+```
+❯ brew install age
+
+```
+
+### Generate keys
+
+```
+~
+❯ mkdir -p ~/.hostctl/age
+
+~
+❯ cd .hostctl
+
+~/.hostctl
+❯ age-keygen -o age/johndoe.priv
+Public key: age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
+
+~/.hostctl
+❯ age-keygen -y age/johndoe.priv
+age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
+
+~/.hostctl
+❯ age-keygen -y age/johndoe.priv > age/johndoe.pub
+
+~/.hostctl
+❯ cat age/johndoe.priv
+# created: 2025-05-24T14:24:12-05:00
+# public key: age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
+AGE-SECRET-KEY-1G403WGS9Z599V2NMK923LWCUFJGRR6LXZ72A3UT95U7AMM5SADESZH7M7P
+
+~/.hostctl
+❯ cat age/johndoe.pub
+age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
+
+~/.hostctl
+❯ age-keygen -o age/janedoe.priv
+Public key: age1qdqv054hmfmnxk56dkjm3cq8qz4lxfl7tvqfp0rqdl0nyygjlccqw0ly40
+
+~/.hostctl
+❯ age-keygen -y age/janedoe.priv > age/janedoe.pub
+
+~/.hostctl
+❯ cat age/janedoe.priv
+# created: 2025-05-24T14:26:36-05:00
+# public key: age1qdqv054hmfmnxk56dkjm3cq8qz4lxfl7tvqfp0rqdl0nyygjlccqw0ly40
+AGE-SECRET-KEY-1M4P4NQY8HEUGRJMWSPQ35J5W2SMUR7VLQULYX7HQ639C6XX8NGPQQ8Z5M7
+
+~/.hostctl
+❯ cat age/janedoe.pub
+age1qdqv054hmfmnxk56dkjm3cq8qz4lxfl7tvqfp0rqdl0nyygjlccqw0ly40
+```
+
+### Create hostctl config file
+
+```
+~
+❯ mkdir -p ~/.hostctl/age
+
+~
+❯ cd .hostctl
+
+~/.hostctl
+❯ cat <<EOF > hostctl.yaml
+hosts:
+  debian-vm:
+    hostname: 192.168.56.11
+    user: vagrant
+    password: !secret vagrant-password
+    tags: [debian, testvm]
+
+  ubuntu-vm:
+    hostname: 192.168.56.15
+    user: vagrant
+    password: !secret vagrant-password
+    tags: [ubuntu, testvm]
+
+secrets:
+  vagrant-password:
+    ids: johndoe, janedoe
+    value: vagrant
+
+ids:
+  johndoe: age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
+  janedoe: age1qdqv054hmfmnxk56dkjm3cq8qz4lxfl7tvqfp0rqdl0nyygjlccqw0ly40
+EOF
+
+~/.hostctl
+❯ tree
+.
+├── age
+│   ├── janedoe.priv
+│   ├── janedoe.pub
+│   ├── johndoe.priv
+│   └── johndoe.pub
+└── hostctl.yaml
+
+2 directories, 5 files
+```
+
+#### Host Configuration Details
+
+When defining hosts in your `hostctl.yaml`:
+
+- The **key** for each entry under the `hosts:` map **is** the network identifier (hostname or IP address) for that host. This key is directly used as the `hostname` for connection and identification purposes.
+
+For example:
+
+```yaml
+hosts:
+  # The key '192.168.56.11' is the hostname.
+  192.168.56.11:
+    alias: debian1 # An optional alias for convenience
+    user: vagrant
+    # Any 'hostname: some.other.address' field here would be ignored for connection.
+
+  # The key 'my-web-server' is treated as the hostname.
+  # Ensure 'my-web-server' is resolvable if it's not an IP.
+  my-web-server:
+    user: admin
+```
+
+The `Host` object within `hostctl` stores this key as its `hostname` property. When the configuration is saved (e.g., after decryption or other modifications), this `hostname` (which was the original key) will be written to an explicit `hostname` field in the YAML output for that host entry. This ensures that even if the key was, for example, an IP address, it's preserved and clearly identifiable in the output YAML.
+
+### Run a task
+
+The `hostctl run <script_path> [params...]` command executes the specified script on your local machine. Within the script, you can use the `context.ssh(...)` method to connect to remote hosts defined in your inventory and perform operations on them.
+
+export AGE_IDS="~/.hostctl/age/johndoe.priv ~/.hostctl/age/janedoe.priv"
+
+hostctl on  HEAD (dd3d7ff) [?] is 📦 v0.1.31 via 🥟 v1.2.10 via 🦕 via  v23.11.0 took 13s
+❯ hostctl run example/reachable.ts
+run: /home/david/sync/projects/monopod/hostctl/example/reachable.ts {}
+✔ Enter your password
+=== Evaluation ===
+✓ Reachable
+✓ echo foo,bar,baz
+✓ echo foo,bar,baz
+✓ os
+✓ echo 1,1,1
+✓ echo 2,2,2
+✓ echo 3,3,4
+=== Result ===
+{ value: 'foo' }
+
+hostctl on  HEAD (dd3d7ff) [?] is 📦 v0.1.31 via 🥟 v1.2.10 via 🦕 via  v23.11.0 took 17s
+❯ hostctl run example/echo.ts args:foo,bar
+run: /home/david/sync/projects/monopod/hostctl/example/echo.ts { args: [ 'foo', 'bar' ] }
+=== Evaluation ===
+✓ echo foo,bar
+=== Result ===
+undefined
+
+```
+
+### Encrypt and decrypt inventory
+
+
+```
+
+hostctl on  main [!] is 📦 v0.1.31 via 🥟 v1.2.10 via  v23.11.0
+❯ hostctl inventory -c example/hostctl.yaml encrypt
+Encrypting inventory file: example/hostctl.yaml
+
+hostctl on  main [!] is 📦 v0.1.31 via 🥟 v1.2.10 via  v23.11.0
+❯ cat example/hostctl.yaml
+hosts:
+debian-vm:
+user: vagrant
+password: !secret vagrant-password
+tags: - debian - test - example - debian-vm
+ubuntu-vm:
+user: vagrant
+password: !secret vagrant-password
+tags: - ubuntu - test - example - ubuntu-vm
+secrets:
+vagrant-password:
+ids: - johndoe - janedoe
+value: |
+-----BEGIN AGE ENCRYPTED FILE-----
+YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBRc0NING5YRlpJdFFoQjJS
+MGdzdVIzWElkMDBPM2RkNVE2ZUpucDhGVVN3CnpsdlpxQzJWaTRwSXl0WmxUT2tJ
+bER5SEk5Wm9IWmhTVXkrNFRpL3BsbzAKLT4gWDI1NTE5IFZ2OU94aThZQXJQNjl5
+ZEk1eWg0QWE5T2pKQVA2a1dvOC9FeXAvL3Q2RFEKbHpGUzJiU1dMNEV4OHFkd0pt
+dS9TSVEwRlU2ZW9mUnhNdk9JdmEwVGU1RQotLS0gdkM3VmwvYzNEejE4OUU2blJI
+d3NzVzZsREJ6Q3NjbEh2ai9qc3JxMGVOVQrgAqyjMEvOF2ifd02P/fr/AJzVKGdO
+qjcfnTSO6aztc8oLxqvvb+w=
+-----END AGE ENCRYPTED FILE-----
+ids:
+johndoe: - age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
+janedoe: - age1qdqv054hmfmnxk56dkjm3cq8qz4lxfl7tvqfp0rqdl0nyygjlccqw0ly40
+
+hostctl on  main [!] is 📦 v0.1.31 via 🥟 v1.2.10 via  v23.11.0
+❯ AGE_IDS="example/sample-age-ids/*.priv" hostctl inventory -c example/hostctl.yaml decrypt -v
+Decrypting inventory file: example/hostctl.yaml
+Decrypted with one or more of the following private keys:
+example/sample-age-ids/johndoe.priv
+example/sample-age-ids/janedoe.priv
+
+hostctl on  main [!] is 📦 v0.1.31 via 🥟 v1.2.10 via  v23.11.0
+❯ cat example/hostctl.yaml
+hosts:
+debian-vm:
+user: vagrant
+password: !secret vagrant-password
+tags: - debian - test - example - debian-vm
+ubuntu-vm:
+user: vagrant
+password: !secret vagrant-password
+tags: - ubuntu - test - example - ubuntu-vm
+secrets:
+vagrant-password:
+ids: - johndoe - janedoe
+value: vagrant
+ids:
+johndoe: - age1jx3ec0y5hctkfwfut4p8cj08ulcezqex8r8slwlwgwy8k2plx5ksdzy8ll
+janedoe: - age1qdqv054hmfmnxk56dkjm3cq8qz4lxfl7tvqfp0rqdl0nyygjlccqw0ly40
+
+```
+
+## Vision
+
+The vision for `hostctl` is to be an Ansible replacement that is significantly easier to use, with simple and intuitive semantics. It empowers users to manage and interact with hosts efficiently, whether for development, operations, or personal use.
+
+## Key Features
+
+*   **Simplified Host Interaction:** Run scripts seamlessly on local or remote machines.
+*   **Cross-Platform Portability:** Designed to work consistently across POSIX-compliant systems.
+*   **Flexible Scripting:** Write `hostctl` scripts in JavaScript or TypeScript.
+
+## Core Tasks
+
+`hostctl` includes a library of core tasks that can be used within your scripts to perform common system administration operations. These tasks are designed to be idempotent and portable across POSIX-compliant systems.
+
+### File and Directory Management
+- **`core.dir.copy`**: Recursively copies a directory.
+- **`core.dir.create`**: Creates a directory.
+- **`core.dir.exists`**: Checks if a directory exists.
+- **`core.file.chgrp`**: Changes the group of a file.
+- **`core.file.chmod`**: Changes the mode of a file.
+- **`core.file.chown`**: Changes the owner of a file.
+- **`core.file.copy`**: Copies a file.
+- **`core.file.delete`**: Deletes a file.
+- **`core.file.edit`**: Edits a file in place.
+- **`core.file.exists`**: Checks if a file exists.
+- **`core.file.grep`**: Searches for a pattern in a file.
+- **`core.file.link`**: Creates a symbolic link.
+- **`core.file.touch`**: Creates an empty file.
+
+### System and Host Management
+- **`core.host.hostname`**: Get or set the hostname.
+- **`core.host.info`**: Gathers information about the host (OS, architecture, etc.).
+- **`core.host.os`**: Provides OS-specific information.
+- **`core.hosts_file.add_entry`**: Adds an entry to `/etc/hosts`.
+- **`core.system.reboot`**: Reboots the system.
+- **`core.system.reboot_if_needed`**: Reboots the system if a reboot is required.
+- **`core.system.reboot_needed`**: Checks if a reboot is required.
+- **`core.system.shutdown`**: Shuts down the system.
+
+### User and Group Management
+- **`core.group.create`**: Creates a user group.
+- **`core.group.delete`**: Deletes a user group.
+- **`core.group.exists`**: Checks if a user group exists.
+- **`core.group.list`**: Lists user groups.
+- **`core.group.modify`**: Modifies a user group.
+- **`core.user.add_groups`**: Adds a user to groups.
+- **`core.user.create`**: Creates a user.
+- **`core.user.delete`**: Deletes a user.
+- **`core.user.exists`**: Checks if a user exists.
+- **`core.user.get_gid`**: Gets the group ID of a user.
+- **`core.user.get_groups`**: Gets the groups a user belongs to.
+- **`core.user.get_uid`**: Gets the user ID of a user.
+- **`core.user.get_username`**: Gets the username of the current user.
+- **`core.user.home_dir`**: Gets the home directory of a user.
+- **`core.user.set_groups`**: Sets the groups for a user.
+- **`core.user.set_shell`**: Sets the login shell for a user.
+- **`core.whoami`**: Gets the current user's username.
+
+### Package Management
+- **`core.pkg.info`**: Gathers information about a package.
+- **`core.pkg.install`**: Installs a package.
+- **`core.pkg.is_installed`**: Checks if a package is installed.
+- **`core.pkg.remove`**: Removes a package.
+- **`core.pkg.update`**: Updates a package.
+
+### Service and Process Management
+- **`core.systemd.disable`**: Disables a systemd service.
+- **`core.systemd.enable`**: Enables a systemd service.
+- **`core.systemd.reload`**: Reloads a systemd service.
+- **`core.systemd.restart`**: Restarts a systemd service.
+- **`core.systemd.start`**: Starts a systemd service.
+- **`core.systemd.status`**: Gets the status of a systemd service.
+- **`core.systemd.stop`**: Stops a systemd service.
+
+### Version Control
+- **`core.git.checkout`**: Checks out a git branch or commit.
+- **`core.git.clone`**: Clones a git repository.
+- **`core.git.pull`**: Pulls changes from a git repository.
+
+### Networking and Firewall
+- **`core.ufw.deny`**: Denies traffic with UFW.
+- **`core.ufw.disable`**: Disables UFW.
+- **`core.ufw.enable`**: Enables UFW.
+- **`core.ufw.install`**: Installs UFW.
+- **`core.ufw.reload`**: Reloads UFW rules.
+
+### Miscellaneous
+- **`core.echo`**: Prints a message.
+- **`core.remote.runAllRemote`**: Runs a task on all remote hosts.
+- **`core.ssh.copy_id`**: Copies an SSH key to a remote host.
+- **`core.sudoers.check`**: Checks the sudoers file for a user.
+- **`core.sudoers.grant-nopasswd`**: Grants passwordless sudo to a user.
+- **`core.template.write`**: Writes a file from a template.
+- **`core.k3s.k3sup-install`**: Installs k3s using k3sup.
+
+## CLI Usage
+
+The `hostctl` command-line interface (CLI) is the primary way to interact with the tool.
+
+### Global Options
+
+These options can be applied to most `hostctl` commands:
+
+*   `-q, --quiet`: Reduces the verbosity of output. Can be specified multiple times (e.g., `-qq`) for even less output.
+*   `-v, --verbose`: Increases the verbosity of output. Can be specified multiple times (e.g., `-vv`, `-vvv`) for more detailed logs. The default level typically shows warnings and errors.
+*   `-c, --config <path>`: Specifies the path to the configuration file (e.g., `my-config.yaml`) or an HTTP/HTTPS URL for a remote configuration. Defaults to `./hostctl.yaml`.
+*   `-o, --output <style>`: Sets the output style. Supported styles are `plain` (default, human-readable) and `json` (machine-readable).
+*   `--json`: A convenient shortcut for `-o json`.
+*   `--api`: Enables API mode, which implies JSON output and may include more structured data suitable for programmatic consumption.
+*   `-p, --password`: If set, `hostctl` will prompt the user for a password (e.g., for `sudo` access on hosts) if a task requires it.
+*   `-t, --tag <tags...>`: Filters the target hosts based on tags defined in the inventory. Only hosts matching all specified tags will be selected. For example, `-t webapp backend` or `-t region:europe`.
+
+### Commands
+
+#### `run` (alias: `r`)
+
+This is the **default command**. It executes a `hostctl` script.
+
+**Usage:**
+
+```bash
+hostctl run [package_or_bundle] [script] [script_arguments...]
+````
+
+- **`package_or_bundle`** (optional):
+  - A path to a local directory containing the script or package (e.g., `./scripts`, `/opt/myproject`).
+  - A URL to a Git repository (e.g., `https://github.com/yourorg/hostctl-scripts.git`). `hostctl` will clone it temporarily.
+  - A path to a local `.zip` file (a "bundle") created by the `bundle` command.
+- **`script`** (optional, especially if `package_or_bundle` is a bundle with a default script):
+  - The name or path of the script file to execute (e.g., `main.ts`, `deploy.js`).
+  - If `package_or_bundle` is provided, this is relative to the package root.
+  - If `package_or_bundle` is omitted, this is treated as a path relative to the current working directory.
+- **`script_arguments...`** (optional):
+  - Any additional arguments passed directly to the script being executed. These can be simple values or key-value pairs.
+
+**Options:**
+
+- `-f, --file <path>`: Loads script parameters from a specified JSON file. The file should contain a single JSON object.
+- `--params "<json_string>"`: Supplies script parameters as a JSON string directly on the command line (e.g., `--params '{"target_env":"production","retries":3}'`).
+- `-r, --remote`: Executes the script on remote hosts (as defined in the inventory and filtered by tags) instead of on the local machine. Defaults to `false` (local execution).
+
+**Examples:**
+
+```bash
+# Run a local script
+hostctl run deploy.ts
+
+# Run a script from a local directory, passing arguments
+hostctl run ./my-scripts provision.js server_name=app01 zone=us-west
+
+# Run a script from a Git repository with parameters from a file
+hostctl run https://github.com/user/hostctl-scripts.git setup-db.ts -f params.json --remote
+
+# Run a script on remote hosts tagged 'database'
+hostctl run -t database -r check-replication.ts
+```
+
+**Task Script Return Value**
+
+When a task script is executed using `hostctl run`, the value returned by the main task function (typically the default export of your script) is considered the primary result of the task.
+
+- **Standard Output:** By default, `hostctl` will display this result along with other evaluation details.
+- **JSON Output (`--json` or `-o json`):** If the `--json` flag (or its equivalent `-o json`) is specified, `hostctl` will output a JSON-serialized representation of the script's return value. When in JSON mode, this serialized result is the _only_ value rendered to standard output, suppressing other logs and evaluation details to ensure clean, machine-readable output. This is particularly useful for programmatic consumption of task results.
+
+#### `exec` (alias: `e`)
+
+Executes an ad-hoc shell command on the selected hosts.
+
+**Usage:**
+
+```bash
+hostctl exec "<command_string>"
+```
+
+- **`<command_string>`**: The shell command to execute. Enclose in quotes if it contains spaces or special characters.
+
+**Examples:**
+
+```bash
+# Check disk space on all targeted hosts
+hostctl exec "df -h"
+
+# Restart a service on hosts tagged 'webserver'
+hostctl exec -t webserver "sudo systemctl restart nginx"
+```
+
+#### `bundle` (alias: `b`)
+
+Packages a directory (typically a project with scripts and a `package.json`) into a deployable `.zip` bundle.
+
+**Usage:**
+
+```bash
+hostctl bundle [path]
+```
+
+- **`[path]`** (optional): The path to the directory to bundle. Defaults to the current directory (`.`).
+
+**Examples:**
+
+```bash
+# Bundle the project in the current directory
+hostctl bundle
+
+# Bundle a project in a specific directory
+hostctl bundle ./my-hostctl-project
+```
+
+#### `inventory` (alias: `i`)
+
+Manages and displays information about the host inventory.
+
+**Usage:**
+
+```bash
+hostctl inventory [subcommand]
+```
+
+Running `hostctl inventory` without a subcommand prints a report of the current inventory.
+
+**Subcommands:**
+
+- **`encrypt`** (alias: `e`)
+  - Encrypts the inventory file (determined by the global `--config` option).
+  - **Usage:** `hostctl inventory encrypt`
+- **`decrypt`** (alias: `d`)
+  - Decrypts the inventory file.
+
+#### `runtime` (alias: `rt`)
+
+Manages the `hostctl` runtime environment, particularly for Node.js scripts.
+
+**Usage:**
+
+```bash
+hostctl runtime [subcommand]
+```
+
+Running `hostctl runtime` without a subcommand prints a report about the detected/configured runtime environment.
+
+**Subcommands:**
+
+- **`install`** (alias: `i`)
+  - Installs or verifies a temporary Node.js runtime environment on the local host if `hostctl` determines one is needed (e.g., if a global Node.js is not found or a specific version is required).
+  - **Usage:** `hostctl runtime install`
+
+## Inventory File Structure
+
+`hostctl` uses a YAML file (defaulting to `hostctl.yaml`) to define its inventory of hosts, manage secrets, and specify encryption recipients. The file can contain three top-level keys: `hosts`, `secrets`, and `ids`.
+
+### `hosts` Section
+
+This section defines the machines `hostctl` can interact with.
+
+```yaml
+hosts:
+  server1.example.com:
+    user: deploy_user
+    ssh-key: !secret server1_ssh_key # References a secret
+    tags: [webserver, production, dc1]
+
+  192.168.1.100:
+    alias: db_server_primary
+    user: admin
+    password: !secret db_admin_password
+    tags: [database, primary, dc1]
+
+  localhost:
+    user: mylocaluser
+    tags: [local, dev]
+
+  another.server.com:
+    # Minimal configuration, will use global defaults or prompt if needed
+    tags: [staging]
+```
+
+- Each key under `hosts` (e.g., `server1.example.com`, `192.168.1.100`) is the hostname or IP address.
+- **Properties for each host:**
+  - `alias` (optional): A friendly name for the host.
+  - `user` (optional): The username for SSH connections.
+  - `password` (optional): The password for SSH. Can be a plain string or a `!secret` reference (e.g., `!secret my_password_name`).
+  - `ssh-key` (optional): Path to an SSH private key file or the private key content itself. Can also be a `!secret` reference.
+  - `tags` (optional): A list of strings for categorizing and selecting hosts.
+
+### `secrets` Section
+
+This section stores sensitive data, typically encrypted using AGE encryption.
+
+```yaml
+secrets:
+  server1_ssh_key:
+    ids: [age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx, admin_keys_group] # AGE public key or id group ref
+    value: |
+      -----BEGIN AGE ENCRYPTED FILE-----
+      xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+      -----END AGE ENCRYPTED FILE-----
+
+  db_admin_password:
+    ids: db_admins_group # Reference to an 'ids' group
+    value: 'plaintextpasswordbeforeencryption' # This will be encrypted by 'hostct inventory encrypt'
+```
+
+- Each key under `secrets` (e.g., `server1_ssh_key`) is a unique name for the secret.
+- **Properties for each secret:**
+  - `ids`: A single string or a list of strings specifying the AGE public keys or named recipient groups (from the `ids` section) that can decrypt this secret.
+  - `value`: The secret content. If `hostctl inventory encrypt` has been run, this will be an AGE encrypted block.
+
+### `ids` Section
+
+This section defines named groups of AGE public keys, simplifying secret management.
+
+```yaml
+ids:
+  admin_keys_group:
+    - age1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # Alice's public key
+    - age1yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy # Bob's public key
+
+  db_admins_group:
+    - admin_keys_group # Nested group reference
+    - age1zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz # CI server's public key
+
+  single_key_user: age1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq
+```
+
+- Each key under `ids` (e.g., `admin_keys_group`) is a unique name for a group of recipients.
+- The value can be a single AGE public key string, a list of AGE public key strings, or a list containing references to other `ids` group names.
+
+This structure allows for a flexible and secure way to manage host information and sensitive credentials. The `hostct inventory encrypt` and `hostct inventory decrypt` commands interact with the `secrets` and `ids` sections to manage encryption.
+
+### Inventory Decryption Behavior
+
+When working with the inventory decryption functionality, it's important to understand these key behaviors:
+
+1. **Hostname Storage**: In the YAML configuration, hostnames are stored as the keys in the `hosts` map, not as properties inside each host object. When a host is serialized to YAML via `Host.toYAML()`, the `hostname` field is not included because it's represented by the map key.
+
+2. **Verbosity and Logging**: The inventory decryption process follows the general verbosity rules of hostctl:
+
+   - By default, only ERROR level messages are shown
+   - INFO level messages (like "No encrypted secrets found to decrypt. Inventory is already decrypted.") require the `-v` flag to be visible
+   - For idempotent operations like decrypting an already-decrypted inventory, you need to use the `-v` flag to see confirmation messages
+
+3. **Idempotent Operations**: The `inventory decrypt` command is designed to be idempotent - running it on an already decrypted inventory will not cause errors, but will only show a message if the `-v` flag is used.
+
+## Writing Tasks
+
+A `hostctl` task is a TypeScript file that exports a default function created by the `task()` factory. This function receives a `context` object, which provides APIs for interacting with the system, hosts, and the user.
+
+### Task Structure
+
+Here is a basic example of a task that echoes a message:
+
+```typescript
+// src/core/echo.ts
+import { task, type TaskContext, Verbosity } from '../runtime';
+
+export interface EchoParams {
+  message: string;
+}
+
+export interface EchoResult {
+  echo: string;
+}
+
+async function run(context: TaskContext<EchoParams>): Promise<EchoResult> {
+  const { params, log } = context;
+  const { message } = params;
+  log(Verbosity.INFO, `Echoing message: ${message}`);
+  return { echo: message };
+}
+
+export default task(run, {
+  description: 'Echoes a message back to the caller.',
+});
+```
+
+### The `TaskContext` API
+
+The `context` object passed to your task's `run` function contains several helpful properties and methods for task execution:
+
+- `params`: An object containing the parameters passed to the task.
+- `id`: A unique identifier for the current task invocation.
+- `host`: The `Host` object the task is currently running against. This is only available in a remote context (e.g., inside `context.ssh`).
+- `config`: The resolved application configuration (`AppConfig`).
+- `log(level, ...message)`: A function to log messages with a specific verbosity level. Levels are available from `Verbosity` (`ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`).
+- `info(...)`, `debug(...)`, `warn(...)`, `error(...)`: Shortcuts for `log()` with the corresponding verbosity level.
+- `exec(command, options)`: Executes a shell command on the target host. The `command` can be a string or an array of strings. It returns a `Promise<CommandResult>`, which contains `stdout`, `stderr`, `exitCode`, and boolean `success`/`failure` properties.
+- `run(taskFn)`: Executes another `hostctl` task as a sub-task. This is the preferred way to compose tasks and reuse logic. For example: `await context.run(someOtherTask({ param: 'value' }))`.
+- `ssh(tags, remoteTaskFn)`: Executes a function on a set of remote hosts matching the given tags, enabling parallel remote execution.
+- `file`: An object providing a file system API (`read`, `write`, `exists`, `mkdir`, `rm`) that is contextualized to the target host (local or remote).
+- `inventory(tags)`: Returns a list of `Host` objects from the inventory that match the given tags.
+- `getPassword()`: Prompts the user for a password interactively.
+- `getSecret(name)`: Retrieves a decrypted secret value from the configuration by its name.
+- `exit(exitCode, message)`: Immediately terminates the `hostctl` application with a given exit code and optional message.
+
+This API provides the core building blocks for creating powerful and flexible automation tasks with `hostctl`.
+
+## Writing hostctl Scripts
+
+`hostctl` scripts are powerful tools for automating tasks on local and remote machines. They are written in TypeScript or JavaScript and follow a simple, consistent structure. This guide covers everything you need to know to write your own `hostctl` scripts.
+
+### The Basic Structure
+
+A `hostctl` script is a module that exports a default `task` object. This object is created using the `task()` factory function, which takes your main logic function and an optional description.
+
+```typescript
+// src/tasks/my-task.ts
+import { task, type TaskContext, Verbosity } from 'hostctl';
+
+// Define the parameters your task accepts
+export interface MyTaskParams {
+  targetSystem: string;
+  enableFeature: boolean;
+}
+
+// Define the structure of the value your task returns
+export interface MyTaskResult {
+  status: string;
+  rebootRequired: boolean;
+}
+
+// The core logic of your task
+async function run(context: TaskContext<MyTaskParams>): Promise<MyTaskResult> {
+  const { params, log, exec } = context;
+
+  log(Verbosity.INFO, `Configuring ${params.targetSystem}...`);
+
+  if (params.enableFeature) {
+    await exec('echo "Feature enabled" >> /etc/config.conf');
+  }
+
+  const result = await exec('check-reboot-status');
+
+  return {
+    status: 'Configuration applied successfully.',
+    rebootRequired: result.stdout.includes('reboot required'),
+  };
+}
+
+// Export the task with a description that can use Handlebars templating
+export default task(run, 'Configures {{targetSystem}} with feature: {{enableFeature}}');
+```
+
+### The `task()` Factory
+
+The `task()` function is the entry point for defining your script.
+
+`task(runFunction, description?)`
+
+- `runFunction`: An `async` function that contains the core logic of your task. It receives a `TaskContext` object.
+- `description` (optional): A string describing the task. It supports [Handlebars](https://handlebarsjs.com/) templating to dynamically insert parameter values, e.g., `"Deploying version {{version}} to {{environment}}"`.
+
+### The `TaskContext` Object
+
+The `TaskContext` is the heart of the scripting API. It's passed to your `run` function and provides all the necessary tools to interact with the system.
+
+- `params: TParams`: A strongly-typed object containing the parameters passed to your script from the command line or a params file.
+- `log(level: LogLevel, ...message)`: A logging function for structured output.
+  - **Levels**: Use the `Verbosity` enum for log levels: `Verbosity.DEBUG`, `Verbosity.INFO`, `Verbosity.WARN`, `Verbosity.ERROR`, `Verbosity.TRACE`.
+  - **Usage**: `context.log(Verbosity.INFO as LogLevel, "This is an info message");`
+- `info(...message)`: A convenience function that calls `log(Verbosity.INFO, ...message)`
+- `error(...message)`: A convenience function that calls `log(Verbosity.ERROR, ...message)`
+- `warn(...message)`: A convenience function that calls `log(Verbosity.WARN, ...message)`
+- `debug(...message)`: A convenience function that calls `log(Verbosity.DEBUG, ...message)`
+- `trace(...message)`: A convenience function that calls `log(Verbosity.TRACE, ...message)`
+- `exec(command: string, options?: ExecOptions): Promise<CommandResult>`: Executes a shell command on the target host.
+  - **`options`**:
+    - `cwd`: The working directory for the command.
+    - `sudo`: If `true`, runs the command with `sudo`.
+    - `stdin`: A string or Buffer to pass to the command's standard input when it starts.
+    - `input`: An object where keys are regular expression strings (to match command output) and values are the corresponding strings to send to the command's standard input. Used for automating interactive prompts.
+    - `pty`: If `true`, allocates a pseudo-terminal, useful for interactive commands.
+    - `env`: An object of environment variables.
+  - **`CommandResult`**: The promise resolves to an object containing `stdout`, `stderr`, `exitCode`, and `signal`.
+- `ssh(hostSelector, taskDefinition, params?): Promise<TRemoteReturn[] | Error>`: Executes another `hostctl` task on one or more remote hosts.
+  - **`hostSelector`**: A string, an array of strings, a `Host` object, or an array of `Host` objects to specify the target hosts from your inventory.
+  - **`taskDefinition`**: The task to execute on the remote host(s).
+  - **`params`**: The parameters to pass to the remote task.
+- `file: FileOperations`: An object for performing file operations on the target host.
+  - `read(path)`: Reads the content of a file.
+  - `write(path, content)`: Writes content to a file.
+  - `exists(path)`: Checks if a file or directory exists.
+  - `mkdir(path)`: Creates a directory.
+  - `rm(path)`: Removes a file or directory.
+- `cwd: Path`: The current working directory of the task.
+- `app: App`: A reference to the main `App` instance, giving you access to global configuration, the full host inventory, and secret management (`context.app.getSecretValue()`).
+- `host?: Host`: If the task is running on a specific host (e.g., via `ssh`), this object contains details about that host.
+
+### Handling Interactive Commands
+
+For commands that require user input (e.g., password prompts, confirmation dialogs), `hostctl` provides a straightforward way to automate these interactions through the `input` option in `context.exec()`.
+
+You don't need to create an `InteractionHandler` instance directly in your task script. Instead, you provide an object to the `input` option where:
+
+- Each **key** is a string representing a regular expression. `hostctl` will monitor the command's standard output for lines matching this regex.
+- Each **value** is the string that `hostctl` will send to the command's standard input when the corresponding key's regex is matched.
+
+```typescript
+import { task, type TaskContext } from 'hostctl';
+
+async function run(context: TaskContext): Promise<void> {
+  const { exec, log } = context;
+
+  log(Verbosity.INFO as LogLevel, 'Attempting an operation that requires interactive confirmation...');
+
+  const result = await exec('your-interactive-command --with-prompt', {
+    pty: true, // A PTY is usually required for interactive commands
+    input: {
+      // When the command outputs "Enter your password:", respond with "mysecretpassword"
+      'Enter your password:': 'mysecretpassword',
+      // When the command outputs something like "Are you sure you want to continue (yes/no)?", respond with "yes"
+      'Are you sure you want to continue \\(yes\\/no\\)\\?': 'yes',
+    },
+  });
+
+  if (result.exitCode === 0) {
+    log(Verbosity.INFO as LogLevel, 'Interactive command completed successfully.');
+  } else {
+    log(
+      Verbosity.ERROR as LogLevel,
+      `Interactive command failed with exit code ${result.exitCode}. Stderr: ${result.stderr}`,
+    );
+  }
+}
+
+export default task(run, 'Demonstrate handling of an interactive command');
+```
+
+**Important Considerations:**
+
+- **PTY Allocation**: Interactive commands usually require a pseudo-terminal (PTY) to behave correctly. Always set `pty: true` in the `ExecOptions` when using the `input` map for interactions.
+- **Regex Specificity**: Make your regular expressions specific enough to avoid unintended matches. Test them thoroughly.
+- **Order of Interactions**: If a command has multiple prompts, `hostctl` will respond to them as they appear in the output and match the keys in your `input` object.
+
+#### Using the `withSudo` Helper
+
+Since running commands with `sudo` is a very common pattern, `hostctl` provides a convenient helper function, `withSudo`, to simplify this process. It automatically creates the correct input mapping for the `sudo` password prompt.
+
+```typescript
+import { task, type TaskContext, withSudo } from 'hostctl';
+
+async function run(context: TaskContext): Promise<void> {
+  const { exec, log, getPassword } = context;
+
+  const sudoPassword = await getPassword(); // Prompts user if not already provided
+  if (!sudoPassword) {
+    throw new Error('Sudo password is required but was not provided.');
+  }
+
+  // Use the helper to build the input map
+  const input = withSudo(sudoPassword);
+
+  log(Verbosity.INFO as LogLevel, 'Running a command with sudo...');
+
+  // Pass the generated input map to the exec options
+  const result = await exec('sudo apt-get update', { pty: true, input });
+
+  if (result.exitCode === 0) {
+    log(Verbosity.INFO as LogLevel, "'apt-get update' completed successfully.");
+  } else {
+    log(Verbosity.ERROR as LogLevel, "'apt-get update' failed.");
+  }
+}
+
+export default task(run, 'Demonstrate using the withSudo helper');
+```
+
+The `withSudo` helper can also be combined with other interactions:
+
+`const input = withSudo(password, { "Do you want to continue?": "yes" });`
+
+### A Complete Example: Installing a Package
+
+Here is a realistic example of a task that installs a package on a Debian-based system.
+
+```typescript
+// src/tasks/install-nginx.ts
+import { task, type TaskContext, Verbosity, type LogLevel } from 'hostctl';
+
+export interface InstallNginxParams {
+  updateCache?: boolean;
+}
+
+async function run(context: TaskContext<InstallNginxParams>): Promise<void> {
+  const { params, log, exec } = context;
+
+  log(Verbosity.INFO as LogLevel, 'Starting Nginx installation...');
+
+  if (params.updateCache) {
+    log(Verbosity.DEBUG as LogLevel, 'Updating package cache...');
+    await exec('sudo apt-get update');
+  }
+
+  log(Verbosity.INFO as LogLevel, 'Installing nginx package...');
+  const installResult = await exec('sudo apt-get install -y nginx');
+
+  if (installResult.exitCode !== 0) {
+    log(Verbosity.ERROR as LogLevel, 'Failed to install Nginx.');
+    throw new Error(`apt-get failed with exit code ${installResult.exitCode}`);
+  }
+
+  log(Verbosity.INFO as LogLevel, 'Nginx installed successfully.');
+}
+
+export default task(run, 'Install Nginx on a Debian-based system');
+```
+
+## Roadmap: Expanding Capabilities
+
+To further enhance `hostctl` and position it as a comprehensive Ansible alternative, the following task primitives are planned for future development. These aim to provide built-in support for common system administration and automation workflows:
+
+1. **File Management:**
+   - `file.replace` (regex substitution)
+   - `file.fetch` (remote → local)
+
+2. **Package Management:**
+   - `pkg.purge`
+   - `pkg.autoremove`
+
+3. **User & Group Management:**
+   - `user.password` (change password)
+
+4. **System Operations:**
+   - `system.timezone`
+   - `system.mount`
+
+5. **Archive Management:**
+   - `archive.compress`
+   - `archive.extract`
+   - `archive.unarchive` (auto-detect format)
+
+6. **Networking & Firewall:**
+   - `firewall.status`
+   - `firewall.add_rule`
+   - `firewall.remove_rule`
+   - `network.interfaces`
+   - `network.get_facts`
+
+7. **Templating & Control Flow:**
+   - Enhanced templating (diff mode, variables, idempotent)
+   - `retry`
+   - `until` (wait for condition)
+   - `include_tasks` (run another script)
+   - `wait_for`
+   - `assert`
+   - Improved looping & retry helpers
+
+This roadmap will evolve, and contributions are welcome!
+
+3.  **Define ResultTypes** (optional but recommended): Specify the structure of the result your task will return (e.g., `MyTaskResult`).
+4.  **Implement the `run` function**: This is the core logic of your task.
+5.  **Export the task**: Use `export default task(runFunction, {description: "Optional description"});`.
+
+Here's a template:
+
+```typescript
+// my-task.ts
+import { task, type TaskContext, type IInvocation, type LogLevel } from 'hostctl'; // Adjust path if developing hostctl itself
+// For users of the hostctl package, it would typically be:
+// import { task, type TaskContext, type IInvocation, type LogLevel, Verbosity } from "hostctl";
+
+// (If developing hostctl, Verbosity might be imported from a relative path like "../app")
+import { Verbosity } from '../app'; // Example for internal development path
+
+// 1. Define the structure of parameters your task expects
+export type MyTaskParams = {
+  targetSystem: string;
+  enableFeature?: boolean;
+};
+
+// 2. Define the structure of the result your task will return
+export interface MyTaskResult {
+  success: boolean;
+  details?: string;
+}
+
+// 3. Implement the core task logic in a 'run' function
+async function run(
+  context: TaskContext<MyTaskParams>, // First argument is the TaskContext
+): Promise<MyTaskResult> {
+  // Access parameters passed to the script via context.params
+  const { targetSystem, enableFeature = false } = context.params;
+
+  // Use 'this' for invocation-specific operations
+  this.log(Verbosity.INFO as LogLevel, `Configuring ${targetSystem}...`);
+
+  try {
+    // Use context for runtime utilities like 'exec' or 'file' operations
+    const { stdout } = await context.exec(
+      `configure-system --target ${targetSystem} ${enableFeature ? '--enable' : ''}`,
+    );
+    this.log(Verbosity.DEBUG as LogLevel, `Configuration output: ${stdout}`);
+
+    // Example of using this.sh (often a shorthand for context.exec for simple commands)
+    // const { stdout: diskSpace } = await this.sh("df -h /");
+    // this.log(Verbosity.INFO as LogLevel, `Disk space: ${diskSpace}`);
+
+    return { success: true, details: 'System configured successfully.' };
+  } catch (error: any) {
+    this.log(Verbosity.ERROR as LogLevel, `Error during configuration: ${error.message}`);
+    return { success: false, details: error.message };
+  }
+}
+
+// 4. Export the task, optionally with a dynamic description
+// The '{{ args?.join(" ") }}' uses Handlebars templating.
+// 'args' needs to be available in the template context for this to work.
+export default task(run, 'Configures {{ targetSystem }} with feature: {{ enableFeature }}');
+```
+
+### The `run` Function Signature
+
+The `run` function is where your task's main logic resides. It must conform to the following signature:
+
+`async function run(context: TaskContext<TParams>): Promise<TResult>`
+
+- **`context: TaskContext<TParams>`**: This is the **first and only argument** passed to your `run` function. It's a crucial object providing access to:
+
+  - `context.params: TParams`: An object containing the parameters passed to your script from the command line (e.g., `args:key,value` or via `--params <json_string>`). `TParams` is a type interface you define to structure these expected parameters.
+  - `context.log`, `context.exec`: The same logging and command execution functions available via `this`.
+  - `context.file: FileSystemOperations`: An object with methods for file system operations (`read`, `write`, `exists`, `mkdir`, `rm`) that work on the target host (local or remote).
+  - `context.host?: Host`: If the task is executing on a remote host, this object provides details about that host.
+  - `context.cwd: string`: The current working directory of the task.
+
+- **`Promise<TResult>`**: Your `run` function must be `async` and should return a `Promise`. The value this promise resolves to is considered the result of your task. `TResult` is a type interface you define for structuring this result.
+
+### Defining Parameters (`TParams`) and Results (`TResult`)
+
+It's highly recommended to define TypeScript interfaces or types for your task's parameters (`TParams`) and its return value (`TResult`). This greatly improves code clarity, maintainability, and enables type checking.
+
+```typescript
+// For parameters
+export type MyScriptParams = {
+  inputFile: string;
+  outputDir?: string;
+  forceOverwrite: boolean;
+};
+
+// For results
+export interface MyScriptResult {
+  filesProcessed: number;
+  errorsEncountered: number;
+  outputLocation?: string;
+}
+```
+
+### Example: The `echo` Task (from `src/core/echo.ts`)
+
+This task demonstrates the core concepts:
+
+```typescript
+import { task, type TaskContext, type IInvocation, type LogLevel } from 'hostctl';
+import { Verbosity } from 'hostctl/app'; // Path for user-facing package
+
+// 1. Define Parameters
+export type EchoParams = {
+  args: string[]; // Expects an array of strings named 'args'
+};
+
+// 2. Define Result
+export interface EchoResult {
+  stdout: string; // The echoed output
+}
+
+// 3. Implement the 'run' function
+async function run(context: TaskContext<EchoParams>): Promise<EchoResult> {
+  const { params, exec, log } = context;
+  // Provide a default for args in case it's not passed from the CLI
+  const { args = [] } = params;
+
+  log(Verbosity.DEBUG as LogLevel, `Echoing arguments: ${args.join(' ')}`);
+
+  // Use context.exec with an array of command and arguments
+  // This is generally safer than manually joining strings for shell execution.
+  const commandArray = ['echo', ...args];
+  const { stdout } = await exec(commandArray);
+
+  return {
+    stdout, // Return the standard output of the echo command
+  };
+}
+
+// 4. Export the task with a dynamic description
+// The '{{ args?.join(" ") }}' uses Handlebars templating.
+// 'args' needs to be available in the template context for this to work.
+export default task(run, "Echoes the provided arguments: {{ args?.join(' ') }}");
+```
+
+To run this echo task:
+`hostctl run path/to/echo.ts args:hello,world`
+Inside the `run` function, `context.params` would be `{ args: ["hello", "world"] }`.
+
+## TODO
+
+- [ ] Further refine the script execution interface.
+- [ ] Expand documentation for script development.
+- [ ] Add more examples for common use cases.