hostctl 0.1.42 → 0.1.45

package/README.md

@@ -3,11 +3,13 @@
 `hostctl` is a modern task runner for managing fleets of hosts. It executes TypeScript or JavaScript automations locally or over SSH while keeping inventories, tags, and secrets in one place.
 
 ## Why hostctl
+
 - Treat remote automation like regular code: tasks are modules with strong typing and structured logging.
 - First-class inventory and secrets management built around [AGE](https://age-encryption.org/).
 - Layered runtime cleanly separates CLI parsing, orchestration, and execution for easy extension.
 
 ## System Requirements
+
 - Node.js **24+** (CLI runs through `tsx`).
 - [`age`](https://age-encryption.org) for encrypting secrets.
 - Git (recommended) for cloning packages and publishing tasks.
@@ -23,26 +25,32 @@ age --version
 ## Install hostctl
 
 ### Clone & Develop
+
 ```bash
 git clone https://github.com/monopod/hostctl.git
 cd hostctl
 npm install
 ```
+
 Use `./hostctl` during development or `npm run build && ./dist/bin/hostctl.js ...` to test the bundled CLI.
 
 ### Global CLI
+
 ```bash
 npm install -g hostctl
 hostctl --help
 ```
 
 ### One-off Execution
+
 Run straight from npm without installing globally:
+
 ```bash
 npx hostctl run core.echo message:hello
 ```
 
 ## Bootstrap identities, inventory, and secrets
+
 1. **Generate AGE identities**
    ```bash
    mkdir -p ~/.hostctl/age
@@ -73,6 +81,7 @@ npx hostctl run core.echo message:hello
    Set `AGE_IDS="~/.hostctl/age/*.priv"` before running commands if the file is encrypted.
 
 ## Running tasks
+
 - **Local script**
   ```bash
   npm run build
@@ -82,10 +91,12 @@ npx hostctl run core.echo message:hello
   ```bash
   hostctl run ./my-package hello name:Sam
   ```
+  Local directories are executed directly and are not installable via `hostctl pkg install`.
 - **Remote orchestration**
   ```bash
   hostctl run -r -t ubuntu core.net.interfaces --json
   ```
+
   - `-r/--remote` targets hosts selected by tags via SSH.
   - `-t/--tag` is greedy; use `--` before positional args when needed.
 - **From npm or git**
@@ -106,28 +117,38 @@ npx hostctl run core.echo message:hello
   The first task streams container output back to the CLI; the detached variant returns the created container ID/name so you can manage it later.
 
 **Passing parameters**
+
 - `key:value` pairs after the task name.
 - `--params '{"key":"value"}'` for JSON blobs.
 - `--file params.json` to load structured arguments.
 
 ## Managing task packages
+
 `hostctl pkg` commands wrap the npm-only package manager:
+
 ```bash
 hostctl pkg create my-task --lang typescript
 hostctl pkg install hostctl-hello
 hostctl pkg list
 hostctl pkg remove hostctl-hello
 ```
+
 Installed packages live under `~/.hostctl/packages` and can be run offline once cached.
+Use `pkg install` for npm registry names (scoped + versioned) or git URLs. Local directories should be run directly without installing (`hostctl run ./path/to/pkg task args`); this avoids polluting the manifest with workstation paths and keeps the install story aligned with reproducible npm/git sources.
 
 ## Designing tasks
+
 Define tasks with the `task` helper and a typed `TaskContext`:
 
 ```ts
 import { task, type TaskContext } from 'hostctl';
 
-interface EchoParams { message: string }
-interface EchoResult { repeated: string }
+interface EchoParams {
+  message: string;
+}
+interface EchoResult {
+  repeated: string;
+}
 
 async function run(context: TaskContext<EchoParams>): Promise<EchoResult> {
   const { params, info } = context;
@@ -135,10 +156,13 @@ async function run(context: TaskContext<EchoParams>): Promise<EchoResult> {
   return { repeated: params.message };
 }
 
-export default task(run, { name: 'example.echo', description: 'Prints a message' });
+export default task(run, { name: 'echo', description: 'Prints a message' });
 ```
 
+Export one default task per file. Qualified task names come from a registry when present; otherwise they are derived from the task file path relative to the package root.
+
 Key `TaskContext` capabilities (see [`docs/task-api.md`](docs/task-api.md) for details):
+
 - Structured logging via `info`, `warn`, `error`, `debug`, or `log(level, ...)`.
 - Command execution with `exec(command, { sudo, env, cwd, stdin, pty })`.
 - Remote fan-out using `ssh(tags, remoteFn)`.
@@ -148,6 +172,7 @@ Key `TaskContext` capabilities (see [`docs/task-api.md`](docs/task-api.md) for d
 - File helpers: `file.read`, `file.write`, `file.exists`, `file.mkdir`, `file.rm` that respect local vs. remote runtime.
 
 ## Building & testing task packages
+
 1. Scaffold: `hostctl pkg create awesome-firewall --lang typescript`.
 2. Install deps: `cd awesome-firewall && npm install`.
 3. Build: `npm run build` (defaults to `tsc`).
@@ -155,6 +180,7 @@ Key `TaskContext` capabilities (see [`docs/task-api.md`](docs/task-api.md) for d
 5. Add unit tests with Vitest if needed, or invoke tasks directly in scripts.
 
 ## Publishing task packages
+
 1. Update `package.json` metadata (`name`, `version`, `description`, `files`).
 2. Build artifacts (`npm run build` or rely on `prepublishOnly`).
 3. Authenticate with npm (`npm login` or `NPM_TOKEN`).
@@ -167,11 +193,13 @@ Key `TaskContext` capabilities (see [`docs/task-api.md`](docs/task-api.md) for d
 6. Verify: `npm info your-package version`.
 
 ## Consuming published packages
+
 - One-off: `npx hostctl run your-package taskName param:value`.
 - Cache locally: `hostctl pkg install your-package@1.2.3` then run offline.
 - Compose in other codebases by adding the package to `dependencies` and importing its exported tasks.
 
 ## Troubleshooting
+
 - **Task not found**: confirm the package exports the task name and that `exports` exposes it.
 - **Version mismatch**: keep `package.json`, `src/version.ts`, and `jsr.json` in sync before releasing.
 - **SSH failures**: verify inventory entries (hostname, user, auth) and only pass `-r` when you intend remote execution.
@@ -179,6 +207,7 @@ Key `TaskContext` capabilities (see [`docs/task-api.md`](docs/task-api.md) for d
 - **Environment drift**: run `hostctl runtime` to inspect prerequisites or `hostctl runtime install` to bootstrap them.
 
 ## Developer workflow
+
 - Format & typing: `npm run format` (Prettier) and `npm run lint` (`tsc --noEmit`).
 - Build artifacts: `npm run build` (tsup) produces `dist/` bundles for the CLI and published package.
 - Tests:
@@ -188,7 +217,9 @@ Key `TaskContext` capabilities (see [`docs/task-api.md`](docs/task-api.md) for d
 - Releases rely on `npm run release` + `release-it`; see `NPM_MIGRATION_PLAN.md` for npm-only context.
 
 ## Documentation map
+
 - **Task API reference**: [`docs/task-api.md`](docs/task-api.md).
+- **Task package authoring**: [`docs/task-package-authoring.md`](docs/task-package-authoring.md).
 - **Operational guides**: `docs/*.md` (process, package, system management, etc.).
 - **Architecture & design**: [`ARCHITECTURE.md`](ARCHITECTURE.md) and supporting design docs.
 - **Contributor guide**: [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`AGENTS.md`](AGENTS.md).