@catapultjs/deploy 0.9.0 → 0.10.0

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.

package/skills/catapultjs/references/recipe.md

@@ -0,0 +1,115 @@
+# Writing a Catapult recipe
+
+A recipe is a JavaScript/TypeScript module that registers tasks and inserts them into the deployment pipeline as a side effect of being imported. Users activate it with a bare import in their `deploy.ts`:
+
+```typescript
+import './recipes/my-recipe.ts'
+```
+
+Full docs: https://catapultjs.com/guide/creating-recipes
+
+## Conventions
+
+- Namespace every task with a recipe prefix: `my-recipe:build`, not `build`.
+- Call `desc('…')` immediately before each `task()` so the task shows a description in `cata list:tasks`.
+- Tasks that queue remote commands use the DSL (`cd()`, `run()`); tasks that need command output or conditionals use `ssh()` directly with `set -e` and `q()` for quoting.
+- Resolve binaries with `bin('node')` instead of hardcoding, so users can override paths per host via `host.bin`.
+- Expose recipe options through the store (`get()`/`set()`), never through module-level mutable state.
+
+## Basic structure
+
+```typescript
+import { type TaskContext, task, desc, cd, run, after, bin } from '@catapultjs/deploy'
+import { ssh, q } from '@catapultjs/deploy/utils'
+
+// TypeScript: register task names for autocompletion
+declare module '@catapultjs/deploy' {
+  interface TaskRegistry {
+    'my-recipe:build': true
+  }
+}
+
+desc('Builds the application in the release directory')
+task('my-recipe:build', () => {
+  cd('{{release_path}}')
+  run(`${bin('node')} --run build`)
+})
+
+// Insert into the pipeline (deduplicated: re-adding moves the task)
+after('deploy:update_code', 'my-recipe:build')
+```
+
+Pipeline functions: `after(existing, newTask)`, `before(existing, newTask)`, `remove(name)`, `inPipeline(name)`, `getPipeline()`, `setPipeline(tasks)`.
+
+Default pipeline: `deploy:lock`, `deploy:release`, `deploy:update_code`, `deploy:shared`, `deploy:publish`, `deploy:log_revision`, `deploy:healthcheck`, `deploy:unlock`, `deploy:cleanup`. Recipes may override a built-in task by registering the same name (e.g. `git`/`rsync` recipes provide `deploy:update_code`).
+
+Use `inPipeline()` to attach relative to optional steps (`deploy:healthcheck` is removed when no host defines one). Insertion deduplicates: re-adding a task moves it, the last position wins.
+
+Three tasks are registered but not inserted: `deploy:install` (package manager install), `deploy:build` (`pm run build`), `deploy:test` (`pm run test`). Prefer inserting or overriding them over inventing new install/build tasks, like the `adonisjs` and `nuxt` recipes do.
+
+## Task context and raw SSH
+
+The task function receives a `TaskContext`: `{ host, paths, config, release, logger }`. Use it for output capture or host-specific logic:
+
+```typescript
+desc('Shows service logs')
+task('my-recipe:logs', async ({ host, paths, logger }: TaskContext) => {
+  const { stdout } = await ssh(host, `set -e\ncd ${q(paths.current)}\nmy-service logs --tail 50`)
+  logger.log(stdout.trim())
+})
+```
+
+Always write display output through `ctx.logger` (not `console.log`): the programmatic API captures it and returns it from `catapult.task()`.
+
+`paths` fields: `base`, `releases`, `release`, `current`, `shared`, `cataConfig`, `repo`, `builder`, `lock`.
+
+Template variables in `cd()`/`run()` strings: `{{release_path}}`, `{{current_path}}`, `{{shared_path}}`, `{{releases_path}}`, `{{base_path}}`, `{{release}}`.
+
+Other DSL helpers: `local(command, { cwd? })` runs on the local machine, `upload(localPath, remotePath)` / `download(remotePath, localPath)` transfer over SCP, `isVerbose(level)` checks verbosity.
+
+## Hooks
+
+`onSetup()` runs during `cata deploy:setup`, after base directories exist:
+
+```typescript
+import { onSetup } from '@catapultjs/deploy'
+import { ssh, q, getPaths } from '@catapultjs/deploy/utils'
+
+onSetup(async (ctx, host, logger) => {
+  const paths = getPaths(host.deployPath, ctx.release)
+  await ssh(host, `set -e\nmkdir -p ${q(paths.shared + '/storage')}`)
+  logger.step(host.name, 'storage ready')
+})
+```
+
+`onStatus()` runs during `cata status`. Return an object: each key becomes an aligned line in text mode and is merged into the host entry of `status --json` and `catapult.status()`. Output written via the `logger` argument only appears in text mode.
+
+```typescript
+import { onStatus } from '@catapultjs/deploy'
+
+onStatus(async (_ctx, host) => {
+  const { stdout } = await ssh(host, `set +e\nmy-service --version || true`)
+  return { 'my-service': stdout.trim() || 'unavailable' }
+})
+```
+
+## Configurable options
+
+```typescript
+import { task, run, get } from '@catapultjs/deploy'
+
+task('my-recipe:sync', () => {
+  const excludes = get<string[]>('my_recipe_excludes', [])
+  run(`rsync ${excludes.map((e) => `--exclude=${e}`).join(' ')} …`)
+})
+```
+
+Users set values in `deploy.ts` with `set('my_recipe_excludes', […])` before or after the import. Two store keys have built-in meaning during setup: `writable_dirs` (string[], created under `shared/`) and `shared_files` (string[], touched under `shared/`).
+
+## Checklist before shipping
+
+1. Tasks namespaced and described with `desc()`.
+2. `TaskRegistry` augmented for TypeScript users.
+3. Remote commands quoted with `q()` and prefixed with `set -e` (or `set +e` when failure is expected).
+4. Display tasks write to `ctx.logger`, status hooks return data objects.
+5. Reusable recipes can be contributed to the `contrib/` directory of https://github.com/catapultjs/deploy via pull request.