@catapultjs/deploy 0.8.0 → 0.10.0

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.

package/skills/catapultjs/references/recipes.md

@@ -0,0 +1,316 @@
+# Official Catapult recipes
+
+Recipes are imported as side effects and register tasks into the pipeline automatically. Import order matters: `set()` calls that configure a recipe must appear **before** the recipe import.
+
+Full docs: https://catapultjs.com/guide/recipes
+
+## Choosing a recipe
+
+| Recipe | Delivers `deploy:update_code`? | Use when |
+| --- | --- | --- |
+| `recipes/git` | Yes | Server can reach the repo; build runs on the server |
+| `recipes/rsync` | Yes | Local build, push artifacts via rsync |
+| `recipes/astro` | Yes | Astro site, build locally, upload dist |
+| `recipes/vitepress` | Yes | VitePress site, build locally, upload dist |
+| `recipes/adonisjs_local` | Yes | AdonisJS, build locally, upload artifact |
+| `recipes/adonisjs` | No (pair with `git` or `rsync`) | AdonisJS, build on the server |
+| `recipes/nuxt` | No (pair with `git` or `rsync`) | Nuxt, build on the server |
+| `recipes/directus` | No (pair with `git` or `rsync`) | Directus, migrations and schema snapshots |
+| `recipes/pm2` | No | Process management (add to any stack) |
+| `recipes/redis` | No | Redis cache flush (add to any stack) |
+
+---
+
+## `recipes/git`
+
+```typescript
+import '@catapultjs/deploy/recipes/git'
+```
+
+Requires `branch` on each host. `repository` is auto-detected from `git remote get-url origin`.
+
+| Task | Inserted | Description |
+| --- | --- | --- |
+| `git:check` | after `deploy:lock` | Verifies the branch exists on the remote |
+| `git:update` | before `deploy:update_code` | Clones a bare mirror into `.catapult/repo`, or fetches it |
+| `deploy:update_code` | — | Clones or resets the branch from the local mirror into the release |
+
+No store keys.
+
+---
+
+## `recipes/rsync`
+
+```typescript
+import '@catapultjs/deploy/recipes/rsync'
+```
+
+Always uses `--delete`. Trailing slash on the source is added automatically.
+
+| Task | Inserted | Description |
+| --- | --- | --- |
+| `deploy:update_code` | — | Syncs a local directory into `releases/<release>/` via rsync |
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `rsync_source_path` | `string` | `./` | Local source directory |
+| `source_path` | `string` | — | Fallback if `rsync_source_path` is not set |
+| `rsync_excludes` | `string[]` | `[]` | Patterns passed to `--exclude` |
+
+```typescript
+set('rsync_source_path', './dist')
+set('rsync_excludes', ['.env'])
+import '@catapultjs/deploy/recipes/rsync'
+```
+
+---
+
+## `recipes/astro`
+
+```typescript
+import '@catapultjs/deploy/recipes/astro'
+```
+
+Builds locally before the lock step, then uploads the output via SCP. Does not run `astro build` on the server.
+
+| Task | Inserted | Description |
+| --- | --- | --- |
+| `deploy:build` | before `deploy:lock` | Runs `astro build --mode <astro_mode>` locally |
+| `deploy:update_code` | — | Uploads the generated directory to `releases/<release>` via SCP |
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `astro_mode` | `string \| Record<string, string>` | `'production'` | Build mode. String = same for all hosts; object = per host name |
+| `source_path` | `string` | `'./dist/.'` | Local directory uploaded after the build |
+
+```typescript
+// Per-host modes
+set('astro_mode', { production: 'production', staging: 'staging' })
+import '@catapultjs/deploy/recipes/astro'
+```
+
+To use rsync instead of SCP for the upload, import both `astro` and `rsync` — `astro` provides `deploy:build`, `rsync` overrides `deploy:update_code`. Do not combine with `git`.
+
+---
+
+## `recipes/vitepress`
+
+```typescript
+import '@catapultjs/deploy/recipes/vitepress'
+```
+
+| Task | Inserted | Description |
+| --- | --- | --- |
+| `deploy:build` | before `deploy:lock` | Runs `vitepress build <vitepress_path>` locally |
+| `deploy:update_code` | — | Uploads `<vitepress_path>.vitepress/dist` to `releases/<release>` via SCP |
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `vitepress_path` | `string` | `''` | Path passed to `vitepress build`; output read from `<path>.vitepress/dist` |
+| `source_path` | `string` | `''` | Used as default for `vitepress_path` |
+
+```typescript
+set('vitepress_path', 'docs/')
+import '@catapultjs/deploy/recipes/vitepress'
+```
+
+---
+
+## `recipes/adonisjs`
+
+```typescript
+import '@catapultjs/deploy/recipes/adonisjs'
+```
+
+Remote build. Does not override `deploy:update_code` — pair with `git` or `rsync`.
+
+| Task | Inserted | Description |
+| --- | --- | --- |
+| `deploy:install` | after `deploy:update_code` | Installs dependencies in the release |
+| `deploy:build` | after `deploy:shared` | Runs `node ace build`, copies `package.json` + lockfile into `build/`, creates `build/tmp` |
+| `ace:migration:run` | before `deploy:publish` | Runs `node ace migration:run --force` |
+| `ace:migration:rollback` | manual | Runs `node ace migration:rollback` |
+| `ace:migration:status` | manual | Runs `node ace migration:status` |
+| `ace:list:routes` | manual | Runs `node ace list:routes` |
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `writable_dirs` | `string[]` | `['storage', 'logs', 'tmp']` | Created in `shared/` at setup |
+| `shared_dirs` | `string[]` | `['storage', 'logs']` | Symlinked into each release |
+| `shared_files` | `string[]` | `['.env']` | Symlinked into each release |
+| `adonisjs_path` | `string` | `''` | Sub-path to the app within the repo (monorepo) |
+
+```typescript
+set('adonisjs_path', 'apps/api')
+set('shared_files', ['.env', '.env.production'])
+import '@catapultjs/deploy/recipes/adonisjs'
+```
+
+---
+
+## `recipes/adonisjs_local`
+
+```typescript
+import '@catapultjs/deploy/recipes/adonisjs_local'
+```
+
+Local build + artifact upload. Same `ace:*` tasks as `adonisjs`. Copies `package.json`, lockfile, and optionally `pnpm-workspace.yaml`, `.npmrc`, `ecosystem.config.cjs` into the local `build/` before uploading.
+
+| Task | Inserted | Description |
+| --- | --- | --- |
+| `deploy:build` | before `deploy:lock` | Runs `node ace build` locally |
+| `deploy:update_code` | — | Uploads local build output to `releases/<release>` via SCP |
+| `deploy:install` | after `deploy:shared` | Installs prod dependencies in the release |
+| `ace:migration:run` | before `deploy:publish` | Runs `node ace migration:run --force` |
+| `ace:migration:rollback` | manual | Runs `node ace migration:rollback` |
+| `ace:migration:status` | manual | Runs `node ace migration:status` |
+| `ace:list:routes` | manual | Runs `node ace list:routes` |
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `writable_dirs` | `string[]` | `['storage', 'logs', 'tmp']` | Created in `shared/` at setup |
+| `shared_dirs` | `string[]` | `['storage', 'logs']` | Symlinked into each release |
+| `shared_files` | `string[]` | `['.env']` | Symlinked into each release |
+| `adonisjs_path` | `string` | `''` | Sub-path to the app (monorepo) |
+| `source_path` | `string` | `<adonisjs_path>/build/.` | Local build directory to upload |
+
+---
+
+## `recipes/nuxt`
+
+```typescript
+import '@catapultjs/deploy/recipes/nuxt'
+```
+
+Remote build. Does not override `deploy:update_code` — pair with `git` or `rsync`.
+
+| Task | Inserted | Description |
+| --- | --- | --- |
+| `deploy:build` | — | Overrides the built-in build task, runs `nuxt build` |
+| `nuxt:generate` | — | Runs `nuxt generate` (manual) |
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `shared_files` | `string[]` | `['.env']` | Symlinked into each release |
+| `nuxt_path` | `string` | `''` | Sub-path to the Nuxt app (monorepo) |
+| `source_path` | `string` | `''` | Used as default for `nuxt_path` |
+
+```typescript
+set('nuxt_path', 'apps/web')
+import '@catapultjs/deploy/recipes/nuxt'
+```
+
+---
+
+## `recipes/directus`
+
+```typescript
+import '@catapultjs/deploy/recipes/directus'
+```
+
+DB migrations and schema snapshots. Does not override `deploy:update_code` — pair with `git` or `rsync`. All tasks are manual (not inserted automatically).
+
+| Task | Inserted | Description |
+| --- | --- | --- |
+| `directus:database:migrate` | manual | Runs `directus database migrate:latest` |
+| `directus:snapshot:create` | manual | Runs `directus schema snapshot <directus_snapshot_path>` |
+| `directus:snapshot:apply` | manual | Runs `directus schema apply -y <directus_snapshot_path>` |
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `writable_dirs` | `string[]` | `['uploads']` | Created in `shared/` at setup |
+| `shared_dirs` | `string[]` | `['uploads']` | Symlinked into each release |
+| `shared_files` | `string[]` | `['.env']` | Symlinked into each release |
+| `directus_path` | `string` | `''` | Sub-path to the Directus app (monorepo) |
+| `directus_snapshot_path` | `string` | `'./snapshot.yaml'` | Snapshot file path used by schema tasks |
+
+```typescript
+set('directus_path', 'apps/cms')
+set('directus_snapshot_path', './database/snapshot.yaml')
+import '@catapultjs/deploy/recipes/directus'
+```
+
+---
+
+## `recipes/pm2`
+
+```typescript
+import '@catapultjs/deploy/recipes/pm2'
+```
+
+Requires an `ecosystem.config.cjs` at the release root. Use absolute paths inside that file resolving through `current/` to avoid stale release references after a new deploy.
+
+| Task | Inserted | Description |
+| --- | --- | --- |
+| `pm2:startOrReload` | after `deploy:publish` | Starts or reloads via `startOrReload --update-env` |
+| `pm2:save` | after `pm2:startOrReload` | Persists the PM2 process list |
+| `pm2:start` | manual | Starts PM2 processes |
+| `pm2:reload` | manual | Zero-downtime reload |
+| `pm2:restart` | manual | Hard restart |
+| `pm2:stop` | manual | Stops all processes |
+| `pm2:delete` | manual | Deletes all processes from PM2 |
+| `pm2:logs` | manual | Displays the last 50 lines of logs |
+| `pm2:list` | manual | Lists PM2 processes |
+| `pm2:show` | manual | Shows detailed info for each app in `ecosystem.config.cjs` |
+
+No store keys. `onStatus` displays the PM2 version in `cata status`.
+
+```bash
+npx cata task pm2:reload
+npx cata task pm2:logs --host staging
+```
+
+---
+
+## `recipes/redis`
+
+```typescript
+import '@catapultjs/deploy/recipes/redis'
+```
+
+All tasks are manual (not inserted automatically).
+
+| Task | Inserted | Description |
+| --- | --- | --- |
+| `redis:db:flush` | manual | Flushes the configured Redis DB(s) |
+| `redis:db:flush_all` | manual | Runs `redis-cli FLUSHALL` |
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `redis_db` | `number \| number[]` | `1` | DB index(es) flushed by `redis:db:flush` |
+
+```typescript
+set('redis_db', [0, 1, 2])
+import '@catapultjs/deploy/recipes/redis'
+
+// Insert before publish:
+before('deploy:publish', 'redis:db:flush')
+```
+
+---
+
+## Monorepo pattern
+
+Keep the transfer recipe (`git` or `rsync`) and override `deploy:install`/`deploy:build` paths via `set()`:
+
+```typescript
+import { defineConfig, set, before } from '@catapultjs/deploy'
+import '@catapultjs/deploy/recipes/git'
+import '@catapultjs/deploy/recipes/nuxt'
+import '@catapultjs/deploy/recipes/directus'
+import '@catapultjs/deploy/recipes/pm2'
+import '@catapultjs/deploy/recipes/redis'
+
+set('nuxt_path', 'apps/web')
+set('directus_path', 'apps/cms')
+set('directus_snapshot_path', './database/snapshot.yaml')
+set('redis_db', 2)
+
+before('deploy:publish', 'redis:db:flush')
+
+export default defineConfig({
+  hosts: [{ name: 'production', ssh: 'deploy@example.com', deployPath: '/home/deploy/acme', branch: 'main' }],
+})
+```
+
+`deploy:install` (inserted by `nuxt`/`directus`) runs at the workspace root `{{release_path}}` by default — no override needed for standard monorepos.