@catapultjs/deploy 0.8.0 → 0.10.0

package/build/src/task/store.js

@@ -27,12 +27,18 @@ export class TaskStore {
     getDescription(name) {
         return this.#descriptions.get(name) ?? '';
     }
-    async run(name, deployCtx, host) {
+    async run(name, deployCtx, host, options = {}) {
         const fn = this.#registry.get(name);
         if (!fn)
             throw new Error(`Task not found: "${name}"`);
         const paths = getPaths(host.deployPath, deployCtx.release);
-        const ctx = { host, paths, config: deployCtx.config, release: deployCtx.release, logger };
+        const ctx = {
+            host,
+            paths,
+            config: deployCtx.config,
+            release: deployCtx.release,
+            logger: options.logger ?? logger,
+        };
         this.#runner.set(ctx);
         try {
             const result = fn(ctx);

package/build/src/task/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/task/store.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAErC,MAAM,OAAO,SAAS;IACpB,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAA;IACrC,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAA;IACzC,mBAAmB,GAAkB,IAAI,CAAA;IACzC,OAAO,CAAY;IAEnB,YAAY,MAAkB;QAC5B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACvB,CAAC;IAED,QAAQ,CAAC,WAAmB;QAC1B,IAAI,CAAC,mBAAmB,GAAG,WAAW,CAAA;IACxC,CAAC;IAED,QAAQ,CAAC,IAAc,EAAE,EAAU;QACjC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QAC5B,IAAI,IAAI,CAAC,mBAAmB,KAAK,IAAI,EAAE,CAAC;YACtC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAA;YACtD,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAA;QACjC,CAAC;IACH,CAAC;IAED,GAAG,CAAC,IAAc;QAChB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACjC,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAA;IACnC,CAAC;IAED,cAAc,CAAC,IAAc;QAC3B,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;IAC3C,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAc,EAAE,SAAwB,EAAE,IAAU;QAC5D,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACnC,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,GAAG,CAAC,CAAA;QAErD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;QAC1D,MAAM,GAAG,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,CAAA;QACzF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAErB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,EAAE,CAAC,GAAG,CAAC,CAAA;YACtB,IAAI,MAAM,YAAY,OAAO;gBAAE,MAAM,MAAM,CAAA;YAC3C,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QAC5B,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QACtB,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/task/store.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,OAAO,EAAE,MAAM,EAAuB,MAAM,cAAc,CAAA;AAE1D,MAAM,OAAO,SAAS;IACpB,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAA;IACrC,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAA;IACzC,mBAAmB,GAAkB,IAAI,CAAA;IACzC,OAAO,CAAY;IAEnB,YAAY,MAAkB;QAC5B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACvB,CAAC;IAED,QAAQ,CAAC,WAAmB;QAC1B,IAAI,CAAC,mBAAmB,GAAG,WAAW,CAAA;IACxC,CAAC;IAED,QAAQ,CAAC,IAAc,EAAE,EAAU;QACjC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QAC5B,IAAI,IAAI,CAAC,mBAAmB,KAAK,IAAI,EAAE,CAAC;YACtC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,mBAAmB,CAAC,CAAA;YACtD,IAAI,CAAC,mBAAmB,GAAG,IAAI,CAAA;QACjC,CAAC;IACH,CAAC;IAED,GAAG,CAAC,IAAc;QAChB,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACjC,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAA;IACnC,CAAC;IAED,cAAc,CAAC,IAAc;QAC3B,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;IAC3C,CAAC;IAED,KAAK,CAAC,GAAG,CACP,IAAc,EACd,SAAwB,EACxB,IAAU,EACV,UAAuC,EAAE;QAEzC,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACnC,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,GAAG,CAAC,CAAA;QAErD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;QAC1D,MAAM,GAAG,GAAG;YACV,IAAI;YACJ,KAAK;YACL,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,MAAM;SACjC,CAAA;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAErB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,EAAE,CAAC,GAAG,CAAC,CAAA;YACtB,IAAI,MAAM,YAAY,OAAO;gBAAE,MAAM,MAAM,CAAA;YAC3C,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QAC5B,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;QACtB,CAAC;IACH,CAAC;CACF"}

package/build/src/task.d.ts

@@ -1,4 +1,5 @@
 import type { Host, DeployContext, TaskName } from './types.ts';
+import type { CatapultLogger } from './logger.ts';
 import { type TaskFn } from './task/runner.ts';
 import type { Verbose } from './enums.ts';
 export type { TaskContext } from './task/runner.ts';
@@ -7,7 +8,9 @@ export declare function task(name: TaskName, fn: TaskFn): void;
 export declare function hasTask(name: TaskName): boolean;
 export declare function getTasks(): string[];
 export declare function getTaskDescription(name: TaskName): string;
-export declare function runTask(name: TaskName, deployCtx: DeployContext, host: Host): Promise<void>;
+export declare function runTask(name: TaskName, deployCtx: DeployContext, host: Host, options?: {
+    logger?: CatapultLogger;
+}): Promise<void>;
 export declare function cd(path: string): void;
 export declare function run(command: string): void;
 export declare function bin(name: string): string;

package/build/src/task.js

@@ -18,8 +18,8 @@ export function getTasks() {
 export function getTaskDescription(name) {
     return store.getDescription(name);
 }
-export async function runTask(name, deployCtx, host) {
-    return store.run(name, deployCtx, host);
+export async function runTask(name, deployCtx, host, options = {}) {
+    return store.run(name, deployCtx, host, options);
 }
 export function cd(path) {
     runner.push(`cd ${q(runner.resolve(path))}`);

package/build/src/task.js.map

@@ -1 +1 @@
-{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/task.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,OAAO,EAAE,CAAC,EAAE,MAAM,YAAY,CAAA;AAI9B,MAAM,MAAM,GAAG,IAAI,UAAU,EAAE,CAAA;AAC/B,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,CAAA;AAEnC,MAAM,UAAU,IAAI,CAAC,WAAmB;IACtC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;AAC7B,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAc,EAAE,EAAU;IAC7C,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;AAC1B,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,IAAc;IACpC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACxB,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,OAAO,KAAK,CAAC,IAAI,EAAE,CAAA;AACrB,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC/C,OAAO,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,CAAA;AACnC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,IAAc,EAAE,SAAwB,EAAE,IAAU;IAChF,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,CAAA;AACzC,CAAC;AAMD,MAAM,UAAU,EAAE,CAAC,IAAY;IAC7B,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAA;AAC9C,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,OAAe;IACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;AACtC,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,IAAY;IAC9B,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;AAChC,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,UAA4B,EAAE;IACnE,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AACvC,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,SAAiB,EAAE,UAAkB;IAC1D,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAA;AAC7C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,UAAkB,EAAE,SAAiB;IAC5D,OAAO,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;AAC/C,CAAC"}
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/task.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,OAAO,EAAE,CAAC,EAAE,MAAM,YAAY,CAAA;AAI9B,MAAM,MAAM,GAAG,IAAI,UAAU,EAAE,CAAA;AAC/B,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,CAAA;AAEnC,MAAM,UAAU,IAAI,CAAC,WAAmB;IACtC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;AAC7B,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAc,EAAE,EAAU;IAC7C,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;AAC1B,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,IAAc;IACpC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACxB,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,OAAO,KAAK,CAAC,IAAI,EAAE,CAAA;AACrB,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAc;IAC/C,OAAO,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,CAAA;AACnC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,IAAc,EACd,SAAwB,EACxB,IAAU,EACV,UAAuC,EAAE;IAEzC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;AAClD,CAAC;AAMD,MAAM,UAAU,EAAE,CAAC,IAAY;IAC7B,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAA;AAC9C,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,OAAe;IACjC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;AACtC,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,IAAY;IAC9B,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;AAChC,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,UAA4B,EAAE;IACnE,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AACvC,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,SAAiB,EAAE,UAAkB;IAC1D,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAA;AAC7C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,UAAkB,EAAE,SAAiB;IAC5D,OAAO,MAAM,CAAC,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;AAC/C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catapultjs/deploy",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "main": "build/index.js",
   "bin": {
@@ -14,6 +14,7 @@
   },
   "files": [
     "build",
+    "skills",
     "!build/bin/test.js",
     "!build/bin/test.d.ts",
     "!build/bin/test.js.map",
@@ -64,21 +65,25 @@
       "types": "./build/src/utils.d.ts",
       "import": "./build/src/utils.js"
     },
+    "./api": {
+      "types": "./build/src/api.d.ts",
+      "import": "./build/src/api.js"
+    },
     "./recipes/*": {
       "types": "./build/recipes/*.d.ts",
       "import": "./build/recipes/*.js"
     }
   },
   "devDependencies": {
-    "@adonisjs/eslint-config": "^3.0.0",
-    "@adonisjs/prettier-config": "^1.4.5",
+    "@adonisjs/eslint-config": "^3.1.0",
+    "@adonisjs/prettier-config": "^1.5.0",
     "@adonisjs/tsconfig": "^2.0.0",
     "@japa/assert": "^4.2.0",
     "@japa/runner": "^5.3.0",
-    "@types/node": "^25.5.2",
-    "eslint": "^10.2.0",
-    "prettier": "^3.8.1",
-    "typescript": "^6.0.2",
+    "@types/node": "^25.9.3",
+    "eslint": "^10.4.1",
+    "prettier": "^3.8.4",
+    "typescript": "^6.0.3",
     "vitepress": "^2.0.0-alpha.17"
   },
   "dependencies": {

package/skills/catapultjs/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: catapultjs
+description: Work with Catapult (@catapultjs/deploy), the SSH deployment tool for Node.js. Use when creating or updating a deploy.ts config, writing recipes or deployment tasks, customizing the deploy pipeline, or scripting deployments with the programmatic API (Catapult class).
+---
+
+# Catapult (@catapultjs/deploy)
+
+Capistrano-style SSH deployment for Node.js: versioned releases under `releases/`, an atomic `current` symlink, shared directories, a composable task pipeline, automatic rollback. The CLI is `cata`. Docs: https://catapultjs.com
+
+## Critical rule
+
+`defineConfig()` does not impose a deployment mode: exactly one recipe (or a custom task) must provide the `deploy:update_code` pipeline task. Providers: `recipes/git`, `recipes/rsync`, `recipes/adonisjs_local`, `recipes/astro`, `recipes/vitepress`, or your own `task('deploy:update_code', …)`. A config without one fails at deploy time.
+
+## References
+
+Read the file matching the task before writing code:
+
+| Task | Read |
+| --- | --- |
+| Create or update `deploy.ts`: hosts, recipe selection, healthchecks, lifecycle hooks, pipeline tuning, `setPipeline()` | [references/config.md](references/config.md) |
+| Write or modify a recipe or deployment task: task DSL, `onSetup`/`onStatus` hooks, store options, `TaskRegistry` | [references/recipe.md](references/recipe.md) |
+| Use an official recipe (git, rsync, astro, vitepress, adonisjs, nuxt, directus, pm2, redis): tasks added, store keys, monorepo patterns | [references/recipes.md](references/recipes.md) |
+| Script deployments from Node.js (scripts, CI, bots, dashboards) with the `Catapult` class | [references/api.md](references/api.md) |
+| Set up a GitHub Actions workflow with `catapultjs/deploy-action`: inputs, SSH secrets, env vars | [references/github-actions.md](references/github-actions.md) |
+| Use the `cata` CLI: deploy, rollback, task, status, run, ssh, list commands and their options | [references/cli.md](references/cli.md) |
+
+When a change spans several areas (e.g. a config plus a custom recipe), read every matching reference.

package/skills/catapultjs/references/api.md

@@ -0,0 +1,70 @@
+# Using the Catapult programmatic API
+
+The `Catapult` class exposes the same operations as the `cata` CLI, without any interactive prompt. Full docs: https://catapultjs.com/guide/programmatic
+
+```typescript
+import { Catapult } from '@catapultjs/deploy'
+import '@catapultjs/deploy/recipes/git'
+import '@catapultjs/deploy/recipes/pm2'
+
+const catapult = new Catapult({
+  hosts: [{ name: 'production', ssh: 'deploy@example.com', deployPath: '/home/deploy/myapp' }],
+})
+
+await catapult.deploy()
+```
+
+Rules that differ from a `deploy.ts`:
+
+- Import recipes **before** constructing, exactly like in a config file.
+- The constructor takes the same object as `defineConfig()`: `hosts`, `keepReleases`, `repository`, `packageManager`, `hooks`, `verbose`.
+- One `Catapult` instance per process. The deploy context is global; a second instance with a different config is not supported.
+- No prompts: methods either act or throw. Catch errors instead of expecting confirmation flows.
+
+## Methods
+
+All server-targeting methods accept `{ hosts?: string[] }` (default: all configured hosts; unknown names throw before anything runs).
+
+| Method | Returns | CLI equivalent |
+| --- | --- | --- |
+| `setup(options?)` | `void` | `cata deploy:setup` |
+| `deploy(options?)` | `void` | `cata deploy` |
+| `rollback({ hosts?, release? })` | `void` | `cata rollback` |
+| `task(name, options?)` | `TaskOutput[]` (`{ host, output }`) | `cata task <name>` |
+| `status(options?)` | `HostStatus[]` | `cata status --json` |
+| `listReleases(options?)` | `{ name, current, releases }[]` | `cata list:releases --json` |
+| `listRevisions({ hosts?, limit? })` | `{ name, revisions }[]` | `cata list:revisions --json` |
+| `listTasks()` | `{ pipeline, extra }` of `{ name, description }` | `cata list:tasks --json` |
+| `pipeline()` | `string[]` | `cata pipeline --json` |
+
+Behavior notes:
+
+- `deploy()` generates a fresh release name on every call, runs the full pipeline, applies the CLI's auto-rollback on failure, then rethrows. Hosts must be initialized first (`setup()`), otherwise it throws.
+- `task()` runs against the **currently deployed release** and returns what the task wrote through its `logger`, one entry per host. Display tasks (`pm2:logs`, `pm2:list`, …) report their result this way; output may contain ANSI codes. Tasks built from queued `run()` commands return an empty `output`.
+- `status()` never throws on SSH failure; the affected host entry gets an `error` field instead. Data returned by recipes' `onStatus` hooks is merged into each host entry.
+
+## Events
+
+`Catapult` is an `EventEmitter`. `deploy()` and `task()` emit:
+
+- `task:start`, `task:done` — `{ host, task }`
+- `task:error` — `{ host, task, error }`
+- `host:done` — `{ host, release }` (deploy only)
+
+```typescript
+catapult.on('host:done', ({ host, release }) => notify(`${host} → ${release}`))
+```
+
+## Silent mode
+
+By default Catapult logs progress to stdout like the CLI. For programs that rely on events and return values only:
+
+```typescript
+import { Verbose } from '@catapultjs/deploy/enums'
+
+const catapult = new Catapult({ verbose: Verbose.SILENT, hosts: […] })
+```
+
+## Lower-level functions
+
+When the class is too coarse, the primitives are exported from `@catapultjs/deploy` and take an explicit `DeployContext` + `Host`: `deployHost()`, `rollbackHost()`, `initializeHost()`, `isHostSetup()`, `getCurrentRelease()`, `getReleaseNames()`, `getRevisions()`, `collectHostStatus()`, `runTask(name, ctx, host, { logger? })`.

package/skills/catapultjs/references/cli.md

@@ -0,0 +1,160 @@
+# Catapult CLI reference
+
+The CLI is `cata`, invoked via `npx cata <command>`. Full docs: https://catapultjs.com/guide/cli
+
+## Config loading
+
+`version` and `init` work without a config file. All other commands load `deploy.ts`, `deploy.config.ts`, `deploy.js`, or `deploy.config.js` from the current directory, or use `--config <path>` / `-c <path>` to specify another file.
+
+## Global options
+
+| Option | Description |
+| --- | --- |
+| `--config <path>`, `-c <path>` | Load a specific deploy config file |
+| `--host <name>`, `-H <name>` | Target a specific host (available on all host-aware commands) |
+| `--help` | Show help for the current command |
+
+## Commands
+
+### `deploy:setup` (alias: `setup`)
+
+Creates the remote directory structure and runs recipe setup hooks. Must be run once before the first deploy.
+
+```bash
+npx cata deploy:setup
+npx cata setup --host production
+npx cata setup -H staging
+```
+
+### `deploy` (alias: `dep`)
+
+Runs the full deployment pipeline. Prompts to run `deploy:setup` if the host is not initialized.
+
+| Option | Description |
+| --- | --- |
+| `--branch <name>`, `-b <name>` | Override the branch for this deployment |
+| `-v`, `-vv`, `-vvv` | Increase verbosity |
+
+```bash
+npx cata deploy
+npx cata deploy --host production
+npx cata deploy --branch feature/my-feature
+npx cata dep -H staging -b develop
+npx cata deploy --config deploy.staging.ts
+```
+
+### `rollback`
+
+Restores the previous release. With `--interactive`, prompts to choose the target release. Automatic rollback also triggers after a failure past `deploy:publish`.
+
+| Option | Description |
+| --- | --- |
+| `--interactive`, `-i` | Choose the target release interactively |
+
+```bash
+npx cata rollback
+npx cata rollback --interactive
+npx cata rollback -i -H production
+```
+
+### `status`
+
+Shows current release, healthcheck, runtime versions, revision metadata, and lock state. With `--json`, targets all hosts by default and writes aggregated JSON to stdout (errors to stderr).
+
+| Option | Description |
+| --- | --- |
+| `--json` | Output result as JSON |
+
+```bash
+npx cata status
+npx cata status --host production
+npx cata status --json
+```
+
+### `task <task-name>`
+
+Runs a registered task against the current release. Requires an existing release on each target host. Use `list:tasks` first to see available task names.
+
+| Option | Description |
+| --- | --- |
+| `-v`, `-vv`, `-vvv` | Increase verbosity |
+
+```bash
+npx cata list:tasks
+npx cata task deploy:build
+npx cata task deploy:unlock
+npx cata task deploy:restart -H production
+npx cata task deploy:healthcheck -vv
+```
+
+### `run "<command>"`
+
+Executes a shell command on the selected hosts over SSH. Quote the command string.
+
+```bash
+npx cata run "pm2 list"
+npx cata run "pm2 reload all" --host production
+npx cata run "ls -lah current" -H staging
+```
+
+### `ssh`
+
+Opens an interactive SSH session in `deployPath` on the selected host. Prompts to choose when several hosts are configured and `--host` is omitted.
+
+```bash
+npx cata ssh
+npx cata ssh --host production
+```
+
+### `list:releases`
+
+Lists all releases on the target hosts, marking the current one.
+
+```bash
+npx cata list:releases
+npx cata list:releases --host production
+npx cata list:releases --json
+```
+
+### `list:revisions`
+
+Shows the last 10 logged revisions from `.catapult/revisions.log`.
+
+```bash
+npx cata list:revisions
+npx cata list:revisions --host production
+npx cata list:revisions --json
+```
+
+### `list:tasks`
+
+Lists all pipeline tasks and extra registered tasks from the loaded config.
+
+```bash
+npx cata list:tasks
+```
+
+### `pipeline`
+
+Shows the current deployment pipeline task order.
+
+```bash
+npx cata pipeline
+npx cata pipeline --json
+```
+
+### `init`
+
+Generates a starter `deploy.ts` in the current directory. No config required.
+
+```bash
+npx cata init
+```
+
+### `version`
+
+Prints the installed `@catapultjs/deploy` version. No config required.
+
+```bash
+npx cata version
+```

package/skills/catapultjs/references/config.md

@@ -0,0 +1,166 @@
+# Writing a Catapult deploy config
+
+The config file is auto-detected as `deploy.ts`, `deploy.js`, `deploy.config.ts` or `deploy.config.js` at the project root (override with `cata --config <path>`). It must default-export `defineConfig()`. Full reference: https://catapultjs.com/guide/api
+
+```typescript
+import { defineConfig } from '@catapultjs/deploy'
+import '@catapultjs/deploy/recipes/git'
+import '@catapultjs/deploy/recipes/pm2'
+
+export default defineConfig({
+  hosts: [
+    {
+      name: 'production',
+      ssh: 'deploy@example.com',
+      deployPath: '/home/deploy/myapp',
+      branch: 'main',
+    },
+  ],
+})
+```
+
+## Critical rule: code delivery
+
+`defineConfig()` does not impose a deployment mode. The pipeline task `deploy:update_code` MUST be provided by exactly one recipe (or a custom task), otherwise the deploy fails. Pick one:
+
+| Recipe | Delivery | Use for |
+| --- | --- | --- |
+| `recipes/git` | Clones the repo on the server (bare mirror in `.catapult/repo`) | Server can reach the repo, build on server |
+| `recipes/rsync` | Pushes a local directory into the release | Local builds, no repo access from server |
+| `recipes/adonisjs_local` | Builds AdonisJS locally, uploads the artifact | AdonisJS without building on the server |
+| `recipes/astro` / `recipes/vitepress` | Builds locally, uploads the static output | Static sites |
+| custom `task('deploy:update_code', …)` | Whatever you implement | Anything else |
+
+## Picking recipes by stack
+
+Inspect the project (`package.json`, lock file, config files) before choosing:
+
+- **AdonisJS**: `adonisjs` (installs and builds on the server, exposes `ace:*` migration tasks) or `adonisjs_local` (build locally, upload). Both need a delivery recipe only in the `adonisjs` case (pair it with `git`).
+- **Nuxt**: `nuxt` (exposes `deploy:build` and `nuxt:generate`), pair with `git`.
+- **Astro / VitePress**: `astro` / `vitepress` alone (they handle delivery).
+- **Process manager**: add `pm2` if the app runs under PM2 (`ecosystem.config.cjs` expected in the project). It wires restart after publish and adds `pm2:*` tasks plus a status report.
+- **Extras**: `directus` (DB migrations and schema snapshots), `redis` (`redis:db:flush*` tasks, configure with `set('redis_db', n)`).
+
+Recipes register their tasks at import time: imports must appear before or inside the config file, never lazily.
+
+## Config options
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `hosts` | `Host[]` | Required |
+| `keepReleases?` | `number` | Default `5` |
+| `repository?` | `string` | Auto-detected from git origin |
+| `packageManager?` | `PackageManager` | Auto-detected from lock file |
+| `hooks?` | `Hooks` | See below |
+| `verbose?` | `Verbose` | From `@catapultjs/deploy/enums`: `SILENT`, `NORMAL`, `TRACE` (default), `DEBUG` |
+
+## Host options
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `name` | `string` | Identifier used by `--host` / `hosts:` selectors |
+| `ssh` | `string \| SshConfig` | `'user@host'` or `{ user, host, port? }` |
+| `deployPath` | `string` | Absolute path on the server |
+| `branch?` | `string \| { name, ask }` | `ask: true` prompts at deploy time (CLI only) |
+| `healthcheck?` | `{ url?, retries?, delayMs? }` | Curl check after publish; the `deploy:healthcheck` task is removed automatically when no host defines a `url` |
+| `bin?` | `Record<string, string>` | Per-host binary paths, e.g. `{ node: '/home/deploy/.nvm/versions/node/v24.0.0/bin/node' }`. Needed when binaries are not on the non-interactive SSH PATH (nvm setups) |
+
+Multiple environments are just multiple hosts (`production`, `staging`); target one with `cata deploy -H staging`.
+
+## Lifecycle hooks
+
+All optional, all `(ctx: { host?, hosts?, error? }) => Promise<void>`:
+
+```typescript
+export default defineConfig({
+  hosts: […],
+  hooks: {
+    beforeDeploy: async ({ hosts }) => {},      // once, before all hosts
+    beforeHostDeploy: async ({ host }) => {},   // per host
+    afterHostDeploy: async ({ host }) => {},    // per host, even on failure
+    afterFailure: async ({ hosts, error }) => {}, // on error, before rethrow
+    afterDeploy: async ({ hosts }) => {},       // once, after success
+  },
+})
+```
+
+## Pipeline customisation
+
+The config file is a regular module: pipeline and store calls work alongside `defineConfig()`.
+
+Default pipeline order: `deploy:lock` → `deploy:release` → `deploy:update_code` → `deploy:shared` → `deploy:publish` → `deploy:log_revision` → `deploy:healthcheck` → `deploy:unlock` → `deploy:cleanup`. Inspect with `cata pipeline`. Reference: https://catapultjs.com/guide/pipeline
+
+Three built-in tasks are registered but NOT inserted by default. Insert them instead of writing custom install/build/test tasks:
+
+```typescript
+import { after } from '@catapultjs/deploy'
+
+after('deploy:update_code', 'deploy:install') // package manager install
+after('deploy:install', 'deploy:build')      // pm run build
+after('deploy:build', 'deploy:test')         // pm run test
+```
+
+Pipeline functions: `after(existing, task)`, `before(existing, task)`, `remove(name)`, `inPipeline(name)` to place a task relative to optional steps, `setPipeline([…])` to replace the whole sequence. Insertion deduplicates: re-adding a task moves it, the last position wins.
+
+```typescript
+import { set, after, inPipeline, remove, task, run, cd } from '@catapultjs/deploy'
+
+set('writable_dirs', ['logs', 'tmp/uploads'])  // created under shared/ at setup
+set('shared_files', ['.env'])                   // touched under shared/ at setup
+set('rsync_source_path', './dist')              // rsync recipe option
+
+task('app:warmup', () => {
+  cd('{{current_path}}')
+  run('curl -s localhost:3333/health')
+})
+
+// healthcheck is removed automatically when no host defines one
+if (inPipeline('deploy:healthcheck')) {
+  after('deploy:healthcheck', 'app:warmup')
+} else {
+  after('deploy:publish', 'app:warmup')
+}
+```
+
+Custom tasks can also be async functions receiving the `TaskContext` (e.g. `fetch` a Slack webhook with the `release` name). Run any registered task manually with `cata task <name>`.
+
+### Rewriting the whole pipeline
+
+`setPipeline()` replaces the sequence entirely, for full control over the order:
+
+```typescript
+import { defineConfig, setPipeline } from '@catapultjs/deploy'
+import '@catapultjs/deploy/recipes/git'
+import '@catapultjs/deploy/recipes/pm2'
+
+setPipeline([
+  'deploy:lock',
+  'deploy:release',
+  'deploy:update_code',
+  'deploy:install',
+  'deploy:build',
+  'deploy:shared',
+  'deploy:publish',
+  'pm2:startOrReload',
+  'deploy:unlock',
+  'deploy:cleanup',
+])
+
+export default defineConfig({ hosts: […] })
+```
+
+Rules:
+
+- Call it AFTER the recipe imports: recipes run their own `after()`/`before()` insertions at import time, and `setPipeline()` must have the last word.
+- Every name must be a registered task (built-in or from an imported recipe), otherwise the deploy fails at that step with "Task not found".
+- Keep `deploy:lock`/`deploy:unlock` unless concurrent deploys are acceptable, and `deploy:log_revision` if `list:revisions` and revision metadata matter.
+- Omitting `deploy:cleanup` disables release pruning (`keepReleases` has no effect then).
+
+## Checklist
+
+1. `defineConfig()` is the default export.
+2. Exactly one provider for `deploy:update_code` is imported (or defined).
+3. Recipe store options (`set(…)`) match the imported recipes.
+4. Healthcheck URLs point to an endpoint reachable from the server itself.
+5. Pin the package version in `package.json` (the API is still in beta).
+6. Verify with `cata pipeline` (task order) and `cata list:tasks` (registered tasks), then `cata deploy:setup` before the first deploy.

package/skills/catapultjs/references/github-actions.md

@@ -0,0 +1,99 @@
+# GitHub Actions with Catapult
+
+Use the official `catapultjs/deploy-action` to run Catapult inside GitHub Actions. The action handles SSH setup, detects the package manager from the lockfile, installs dependencies, and runs the requested Catapult command.
+
+Full docs: https://catapultjs.com/guide/ci-cd
+
+## Minimal workflow
+
+```yaml
+name: Deploy
+
+on:
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: catapultjs/deploy-action@v0.5.0
+        with:
+          command: deploy
+          config: deploy.ts
+          private-key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
+          known-hosts: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
+          version: latest
+```
+
+## Workflow with a custom runtime
+
+Add `actions/setup-node` (or pnpm/bun setup) before the action when the project needs a specific Node version.
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: 24
+    cache: npm
+
+- uses: catapultjs/deploy-action@v0.5.0
+  with:
+    command: deploy
+    config: deploy.ts
+    private-key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
+    known-hosts: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
+    version: latest
+    working-directory: .
+```
+
+## Action inputs
+
+| Name | Default | Description |
+| --- | --- | --- |
+| `command` | `deploy` | Catapult command to run (`deploy`, `rollback`, `task <name>`, etc.) |
+| `config` | — | Path to the deploy config file |
+| `args` | — | Extra CLI args, one per line |
+| `package-manager` | auto-detected | `npm`, `pnpm`, `yarn`, or `bun` |
+| `version` | `latest` | Version of `@catapultjs/deploy` to install |
+| `working-directory` | `.` | Working directory relative to the repository root |
+
+## SSH inputs
+
+| Input | Required | Description |
+| --- | --- | --- |
+| `private-key` | Yes | SSH private key added to `ssh-agent` |
+| `known-hosts` | Recommended | Content written to `~/.ssh/known_hosts` |
+| `ssh-config` | No | Content written to `~/.ssh/config` |
+| `insecure-ignore-host-key` | No | Disables strict host key checking |
+
+## Reading sensitive config from environment variables
+
+Keep SSH host and path out of `deploy.ts` by reading them from env vars, then passing them from the workflow:
+
+```ts
+// deploy.ts
+const ssh = process.env.DEPLOY_SSH
+const deployPath = process.env.DEPLOY_PATH
+if (!ssh) throw new Error('Missing DEPLOY_SSH')
+if (!deployPath) throw new Error('Missing DEPLOY_PATH')
+
+export default defineConfig({
+  hosts: [{ name: 'production', ssh, deployPath, branch: process.env.DEPLOY_BRANCH || 'main' }],
+})
+```
+
+```yaml
+- uses: catapultjs/deploy-action@v0.5.0
+  with:
+    command: deploy
+    private-key: ${{ secrets.DEPLOY_SSH_PRIVATE_KEY }}
+    known-hosts: ${{ secrets.DEPLOY_KNOWN_HOSTS }}
+  env:
+    DEPLOY_SSH: ${{ secrets.DEPLOY_SSH }}
+    DEPLOY_PATH: ${{ vars.DEPLOY_PATH }}
+    DEPLOY_BRANCH: main
+    DEPLOY_USER: ${{ github.actor }}
+```
+
+Use GitHub **Secrets** for sensitive values (SSH key, host string) and **Variables** for non-sensitive ones (deploy path). `DEPLOY_USER` is picked up by `deploy:log_revision` when `git config user.name` is unavailable on the runner.