@catapultjs/deploy 0.11.0 → 0.13.0

package/skills/catapultjs/references/config.md

@@ -1,6 +1,17 @@
 # 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
+Config files are auto-detected at the project root (override with `cata <command> --config <path>`):
+
+- TypeScript/JavaScript: `deploy.ts`, `deploy.config.ts`, `deploy.js`, `deploy.config.js`
+- JSON: `deploy.config.json`, `deploy.json`
+
+TypeScript and JavaScript must default-export `defineConfig()`. JSON is validated as a strict declarative document. Full references: https://catapultjs.com/guide/api and https://catapultjs.com/guide/json-configuration
+
+## Choosing a format
+
+Use JSON for a data-only deployment made from built-in recipes, serializable store values, declarative task steps and direct pipeline controls. Prefer `deploy.config.json`, include the public schema URL, and set `version` to `1`.
+
+Use TypeScript or JavaScript when the deployment needs callbacks/hooks, external or project-local recipes, dynamic `bin()` calls inside custom tasks, conditions such as `inPipeline()`, or custom task code with branching, loops, API calls or arbitrary async behavior. Static per-host `bin` overrides are supported in JSON. Do not try to encode executable behavior as JSON strings.
 
 ## Before creating a config
 
@@ -21,7 +32,7 @@ Ask a compact set of questions for missing values:
 4. Should PM2 be configured? If yes, confirm app name, start entry, port, and whether to create `ecosystem.config.cjs`.
 5. Is there a healthcheck URL and any extra shared files or directories?
 
-When the user answers, generate `deploy.ts` with the selected recipes and put `set(...)` calls before the recipe imports they configure.
+When the user answers, generate the requested format. For TypeScript/JavaScript, put `set(...)` calls before the recipe imports they configure. For JSON, put those values under `store` and recipe names under `recipes`.
 
 ```typescript
 import { defineConfig } from '@catapultjs/deploy'
@@ -40,18 +51,106 @@ export default defineConfig({
 })
 ```
 
+## JSON configuration
+
+Use strict JSON: double-quoted keys and strings, with no comments or trailing commas. The schema rejects unknown properties and validates the whole document before Catapult connects to a host.
+
+```json
+{
+  "$schema": "https://catapultjs.com/schema/deploy.schema.json",
+  "version": 1,
+  "recipes": ["git"],
+  "config": {
+    "keepReleases": 2,
+    "hosts": [
+      {
+        "name": "production",
+        "ssh": "deploy@example.com",
+        "deployPath": "/home/deploy/myapp",
+        "branch": "main"
+      }
+    ]
+  },
+  "store": {
+    "shared_files": [".env"],
+    "shared_dirs": ["storage", "logs"]
+  },
+  "tasks": {
+    "app:build": {
+      "description": "Install dependencies and build the application",
+      "steps": [{ "cd": "{{release_path}}" }, { "run": "npm ci" }, { "run": "npm run build" }]
+    }
+  },
+  "after": {
+    "deploy:shared": "app:build"
+  }
+}
+```
+
+Top-level contract:
+
+| Field      | Rule                                                                                                |
+| ---------- | --------------------------------------------------------------------------------------------------- |
+| `$schema`  | Recommended: `https://catapultjs.com/schema/deploy.schema.json`                                      |
+| `version`  | Required and exactly `1`                                                                            |
+| `recipes`  | Optional closed list of built-in recipe names                                                       |
+| `config`   | Required serializable `Config` values, excluding function-valued `hooks`                            |
+| `store`    | Optional typed values for documented core and built-in recipe keys, equivalent to `set(key, value)` |
+| `tasks`    | Optional object of declarative task definitions                                                     |
+| `pipeline` | Optional complete task array, equivalent to `setPipeline()`                                         |
+| `remove`   | Optional task array, equivalent to repeated `remove()` calls                                        |
+| `before`   | Optional target-to-task mapping, equivalent to `before()`                                           |
+| `after`    | Optional target-to-task mapping, equivalent to `after()`                                            |
+
+Built-in recipe names accepted by JSON: `adonisjs`, `adonisjs_local`, `astro`, `astro_static`, `caddy`, `directus`, `git`, `nestjs`, `nextjs`, `nextjs_static`, `nuxt`, `nuxt_static`, `pm2`, `redis`, `rsync`, `systemd`, `tanstack`, `vitepress`. Do not use module paths such as `recipes/git`.
+
+The schema validates known `store` key types and rejects unknown keys. Use TypeScript or JavaScript when a custom recipe needs its own store contract.
+
+`config` accepts `hosts`, `keepReleases`, `repository`, `packageManager` and `verbose`. Host data accepts `name`, `ssh`, `deployPath`, `branch`, `healthcheck` and static `bin` path overrides. Host names must be unique. Built-in recipes can resolve `hosts[].bin`; declarative custom task steps cannot invoke the dynamic `bin()` helper.
+
+A task is either an array of steps or `{ "description": "...", "steps": [...] }`. Supported steps:
+
+- `{ "cd": "..." }` and `{ "run": "..." }` execute remotely.
+- `{ "local": { "command": "...", "cwd": "..." } }` executes locally; `cwd` is optional.
+- `{ "upload": { "local": "...", "remote": "..." } }` uploads with SCP.
+- `{ "download": { "remote": "...", "local": "..." } }` downloads with SCP.
+
+Local, upload and download steps flush the current remote command batch. Repeat `{ "cd": "..." }` before later remote `{ "run": "..." }` steps when a task mixes remote commands with local or transfer steps.
+
+Remote commands and paths support Catapult placeholders such as `{{release_path}}`, `{{current_path}}` and `{{shared_path}}`. Declaring a task registers it but does not insert it into the deploy pipeline.
+
+Pipeline controls are applied after recipes and tasks are registered, in a fixed order independent of top-level JSON property order:
+
+1. `pipeline` replaces the complete task sequence when present.
+2. `remove` removes each listed task.
+3. `before` inserts a task or ordered task array before each target.
+4. `after` inserts a task or ordered task array after each target.
+
+```json
+{
+  "pipeline": ["deploy:lock", "deploy:release", "deploy:publish", "deploy:unlock"],
+  "remove": ["deploy:release"],
+  "before": { "deploy:publish": "app:verify" },
+  "after": { "deploy:lock": ["app:install", "app:build"] }
+}
+```
+
+Every pipeline and placement task must be registered. Each `before`/`after` target must exist when placement is applied, and the final pipeline must contain at least one task. A task can be placed only once across `before` and `after`; it cannot also be a placement target or appear under `remove`. Use an array under one target for an ordered task sequence. When `pipeline` is present it replaces recipe insertions too; recipes still register their tasks, but the array must describe the complete intended sequence.
+
+Catapult already unlocks failed deployments automatically; do not invent a `deploy:failed` hook mapping. `ace:migration:run` only exists when `adonisjs` is listed in `recipes`, so import that recipe before trying to remove the migration task.
+
 ## Code delivery
 
 Catapult registers a default `deploy:update_code` task that uploads `source_path` via SCP. Recipes can override that task when a different delivery mechanism is needed. Pick one delivery mode:
 
-| Recipe | Delivery | Use for |
-| --- | --- | --- |
-| default `deploy:update_code` | Uploads `source_path` via SCP | Simple local upload, static recipes that set `source_path` |
-| `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/vitepress` | Builds locally, uploads the static output | VitePress static sites |
-| custom `task('deploy:update_code', …)` | Whatever you implement | Anything else |
+| Recipe                                 | Delivery                                                        | Use for                                                    |
+| -------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------- |
+| default `deploy:update_code`           | Uploads `source_path` via SCP                                   | Simple local upload, static recipes that set `source_path` |
+| `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/vitepress`                    | Builds locally, uploads the static output                       | VitePress static sites                                     |
+| custom `task('deploy:update_code', …)` | Whatever you implement                                          | Anything else                                              |
 
 Avoid combining providers that override `deploy:update_code` (`git`, `rsync`, `adonisjs_local`, `vitepress`, custom) unless intentionally replacing task behavior.
 
@@ -69,35 +168,35 @@ Inspect the project (`package.json`, lock file, config files) before choosing:
 - **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.
+Recipes register their tasks at import time. In TypeScript/JavaScript, imports must appear before or inside the config file, never lazily. In JSON, list built-in names under `recipes`; external recipes require TypeScript or JavaScript.
 
 ## 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` |
+| 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`          | TypeScript/JavaScript only; 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) |
+| 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>`       | Supported in all formats. Per-host binary paths, e.g. `{ node: '/home/deploy/.nvm/versions/node/v24.0.0/bin/node' }`. Built-in recipes resolve these paths; calling `bin()` inside a custom task requires TypeScript/JavaScript. |
 
 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/JavaScript only. All optional, all `(ctx: { host?, hosts?, error? }) => Promise<void>`:
 
 ```typescript
 export default defineConfig({
@@ -124,8 +223,8 @@ Three built-in tasks are registered but NOT inserted by default. Insert them ins
 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
+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.
@@ -133,9 +232,9 @@ Pipeline functions: `after(existing, task)`, `before(existing, task)`, `remove(n
 ```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
+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}}')
@@ -186,7 +285,7 @@ Rules:
 
 ## Checklist
 
-1. `defineConfig()` is the default export.
+1. TypeScript/JavaScript default-exports `defineConfig()`; JSON uses strict syntax, the public `$schema` URL and `version: 1`.
 2. Delivery mode is intentional: default SCP, or one overriding provider such as `git`, `rsync`, `adonisjs_local`, `vitepress`, or a custom `deploy:update_code`.
 3. Recipe store options (`set(…)`) match the imported recipes.
 4. Healthcheck URLs point to an endpoint reachable from the server itself.

package/skills/catapultjs/references/recipe.md

@@ -104,7 +104,7 @@ task('my-recipe:sync', () => {
 })
 ```
 
-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/`).
+Users set values in `deploy.ts` with `set('my_recipe_excludes', […])`. Values read inside task functions can be set before or after a static import. Values read while the recipe module is loaded, especially options that change pipeline wiring, require `set(...)` followed by `await import(...)` because static ESM imports run before the module body. 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
 

package/skills/catapultjs/references/recipes.md

@@ -21,8 +21,10 @@ Full docs: https://catapultjs.com/guide/recipes
 | `recipes/nuxt` | No (pair with `git` or `rsync`) | Nuxt, build on the server |
 | `recipes/nuxt_static` | Uses default SCP; `rsync` optional | Static Nuxt site, generate locally |
 | `recipes/directus` | No (pair with `git` or `rsync`) | Directus, migrations and schema snapshots |
+| `recipes/caddy` | No | Caddy validation, reload, and config upload |
 | `recipes/pm2` | No | Process management (add to any stack) |
 | `recipes/redis` | No | Redis cache flush (add to any stack) |
+| `recipes/systemd` | No | systemd service management (add when the host uses systemd) |
 | `recipes/tanstack` | No (pair with `git` or `rsync`) | TanStack Start, build on the server |
 
 ---
@@ -512,6 +514,72 @@ import '@catapultjs/deploy/recipes/directus'
 
 ---
 
+## `recipes/caddy`
+
+```typescript
+import '@catapultjs/deploy/recipes/caddy'
+```
+
+Manages Caddy configuration. Does not deliver application code and does not reload Caddy by default unless `caddy_reload_after_publish` is set before loading the recipe. Service management is intentionally separate; combine with `recipes/systemd` and set `systemd_service` to `caddy` when Caddy is managed by systemd.
+
+> [!WARNING]
+> Caddy must be able to traverse every parent directory of the configured web root and read the published files. Deploying under a private home directory such as `/home/deploy/...` may require extra permissions or ACLs. Prefer a web root under `/var/www/<app>` or `/srv/www/<app>` for static sites. On the server, use `namei -l /path/to/current/index.html` to inspect which directory blocks access.
+
+| Task | Inserted | Description |
+| --- | --- | --- |
+| `caddy:reload` | after `deploy:publish` when `caddy_reload_after_publish` is true | Validates and reloads Caddy |
+| `caddy:validate` | manual | Runs `caddy validate` |
+| `caddy:fmt` | manual | Formats the configured Caddyfile |
+| `caddy:config:show` | manual | Displays the configured Caddyfile |
+| `caddy:config:upload` | manual | Uploads a local Caddyfile, installs it, and validates it |
+
+`onStatus` displays the Caddy version in `cata status`.
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `caddy_config_path` | `string` | `'/etc/caddy/Caddyfile'` | Remote Caddyfile path |
+| `caddy_local_config_path` | `string` | `'./Caddyfile'` | Local Caddyfile for upload |
+| `caddy_use_sudo` | `boolean` | `true` | Prefix privileged commands with `sudo` |
+| `caddy_validate_before_reload` | `boolean` | `true` | Validate before reload |
+| `caddy_reload_after_publish` | `boolean` | `false` | Add reload after publish |
+
+```typescript
+set('caddy_reload_after_publish', true)
+await import('@catapultjs/deploy/recipes/caddy')
+```
+
+Use a dynamic import when a recipe option changes pipeline wiring. Static ESM imports run before `set()` calls in the module body.
+
+---
+
+## `recipes/systemd`
+
+```typescript
+import '@catapultjs/deploy/recipes/systemd'
+```
+
+Generic systemd service management. Import only when the target host uses systemd.
+
+| Task | Inserted | Description |
+| --- | --- | --- |
+| `systemd:restart` | manual | Restarts the configured service |
+| `systemd:reload` | manual | Reloads the configured service |
+| `systemd:status` | manual | Shows `systemctl status` for the service |
+| `systemd:logs` | manual | Shows recent `journalctl` lines for the service |
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `systemd_service` | `string` | `'app'` | systemd service name |
+| `systemd_use_sudo` | `boolean` | `true` | Prefix privileged commands with `sudo` |
+| `systemd_logs_lines` | `number` | `100` | Number of journal lines shown by `systemd:logs` |
+
+```typescript
+set('systemd_service', 'caddy')
+import '@catapultjs/deploy/recipes/systemd'
+```
+
+---
+
 ## `recipes/pm2`
 
 ```typescript