@catapultjs/deploy 0.12.0 → 0.13.0

package/schema/deploy.schema.json

@@ -0,0 +1,287 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://catapultjs.com/schema/deploy.schema.json",
+  "title": "Catapult deploy JSON configuration",
+  "description": "Declarative deployment configuration for @catapultjs/deploy.",
+  "type": "object",
+  "required": ["version", "config"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "recipes": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "adonisjs",
+          "adonisjs_local",
+          "astro",
+          "astro_static",
+          "caddy",
+          "directus",
+          "git",
+          "nestjs",
+          "nextjs",
+          "nextjs_static",
+          "nuxt",
+          "nuxt_static",
+          "pm2",
+          "redis",
+          "rsync",
+          "systemd",
+          "tanstack",
+          "vitepress"
+        ]
+      },
+      "uniqueItems": true
+    },
+    "config": { "$ref": "#/definitions/config" },
+    "store": { "$ref": "#/definitions/store" },
+    "tasks": {
+      "type": "object",
+      "propertyNames": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
+      "additionalProperties": { "$ref": "#/definitions/taskDefinition" }
+    },
+    "pipeline": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "before": {
+      "type": "object",
+      "propertyNames": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
+      "additionalProperties": {
+        "oneOf": [
+          { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
+          {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
+            "minItems": 1,
+            "uniqueItems": true
+          }
+        ]
+      }
+    },
+    "after": {
+      "type": "object",
+      "propertyNames": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
+      "additionalProperties": {
+        "oneOf": [
+          { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
+          {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
+            "minItems": 1,
+            "uniqueItems": true
+          }
+        ]
+      }
+    },
+    "remove": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1, "pattern": "^\\S+$" },
+      "uniqueItems": true
+    }
+  },
+  "definitions": {
+    "store": {
+      "type": "object",
+      "properties": {
+        "shared_dirs": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "shared_files": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "writable_dirs": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "source_path": { "type": "string" },
+        "adonisjs_path": { "type": "string" },
+        "astro_mode": {
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "object",
+              "minProperties": 1,
+              "propertyNames": { "type": "string", "minLength": 1 },
+              "additionalProperties": { "type": "string", "minLength": 1 }
+            }
+          ]
+        },
+        "astro_path": { "type": "string" },
+        "caddy_config_path": { "type": "string", "minLength": 1 },
+        "caddy_local_config_path": { "type": "string", "minLength": 1 },
+        "caddy_use_sudo": { "type": "boolean" },
+        "caddy_validate_before_reload": { "type": "boolean" },
+        "caddy_reload_after_publish": { "type": "boolean" },
+        "directus_path": { "type": "string" },
+        "directus_snapshot_path": { "type": "string", "minLength": 1 },
+        "nextjs_path": { "type": "string" },
+        "nextjs_out_path": { "type": "string", "minLength": 1 },
+        "nuxt_path": { "type": "string" },
+        "redis_db": {
+          "oneOf": [
+            { "type": "integer", "minimum": 0 },
+            {
+              "type": "array",
+              "items": { "type": "integer", "minimum": 0 },
+              "minItems": 1,
+              "uniqueItems": true
+            }
+          ]
+        },
+        "rsync_source_path": { "type": "string", "minLength": 1 },
+        "rsync_excludes": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "systemd_service": { "type": "string", "minLength": 1 },
+        "systemd_use_sudo": { "type": "boolean" },
+        "systemd_logs_lines": { "type": "number", "exclusiveMinimum": 0 },
+        "vitepress_path": { "type": "string" }
+      },
+      "required": [],
+      "additionalProperties": false
+    },
+    "config": {
+      "type": "object",
+      "properties": {
+        "keepReleases": { "type": "integer", "minimum": 1 },
+        "repository": { "type": "string", "minLength": 1 },
+        "packageManager": { "enum": ["npm", "pnpm", "yarn", "bun"] },
+        "hosts": { "type": "array", "items": { "$ref": "#/definitions/host" }, "minItems": 1 },
+        "verbose": { "enum": [0, 1, 2, 3] }
+      },
+      "required": ["hosts"],
+      "additionalProperties": false
+    },
+    "host": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "ssh": {
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "object",
+              "properties": {
+                "user": { "type": "string", "minLength": 1 },
+                "host": { "type": "string", "minLength": 1 },
+                "port": { "type": "integer", "minimum": 1, "maximum": 65535 }
+              },
+              "required": ["user", "host"],
+              "additionalProperties": false
+            }
+          ]
+        },
+        "deployPath": { "type": "string", "minLength": 1, "pattern": "^/" },
+        "branch": {
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "object",
+              "properties": {
+                "name": { "type": "string", "minLength": 1 },
+                "ask": { "type": "boolean" }
+              },
+              "required": ["name", "ask"],
+              "additionalProperties": false
+            }
+          ]
+        },
+        "healthcheck": {
+          "type": "object",
+          "properties": {
+            "url": { "type": "string", "minLength": 1 },
+            "retries": { "type": "integer", "minimum": 1 },
+            "delayMs": { "type": "integer", "minimum": 0 }
+          },
+          "required": [],
+          "additionalProperties": false
+        },
+        "bin": {
+          "type": "object",
+          "propertyNames": { "type": "string", "minLength": 1 },
+          "additionalProperties": { "type": "string", "minLength": 1 }
+        }
+      },
+      "required": ["name", "ssh", "deployPath"],
+      "additionalProperties": false
+    },
+    "taskStep": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": { "cd": { "type": "string", "minLength": 1 } },
+          "required": ["cd"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": { "run": { "type": "string", "minLength": 1 } },
+          "required": ["run"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "local": {
+              "type": "object",
+              "properties": {
+                "command": { "type": "string", "minLength": 1 },
+                "cwd": { "type": "string", "minLength": 1 }
+              },
+              "required": ["command"],
+              "additionalProperties": false
+            }
+          },
+          "required": ["local"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "upload": {
+              "type": "object",
+              "properties": {
+                "local": { "type": "string", "minLength": 1 },
+                "remote": { "type": "string", "minLength": 1 }
+              },
+              "required": ["local", "remote"],
+              "additionalProperties": false
+            }
+          },
+          "required": ["upload"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "download": {
+              "type": "object",
+              "properties": {
+                "remote": { "type": "string", "minLength": 1 },
+                "local": { "type": "string", "minLength": 1 }
+              },
+              "required": ["remote", "local"],
+              "additionalProperties": false
+            }
+          },
+          "required": ["download"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "taskDefinition": {
+      "oneOf": [
+        { "type": "array", "items": { "$ref": "#/definitions/taskStep" }, "minItems": 1 },
+        {
+          "type": "object",
+          "properties": {
+            "description": { "type": "string", "minLength": 1 },
+            "steps": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/taskStep" },
+              "minItems": 1
+            }
+          },
+          "required": ["steps"],
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}

package/skills/catapultjs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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).
+description: Work with Catapult (@catapultjs/deploy), the SSH deployment tool for Node.js. Use when creating or updating TypeScript, JavaScript or JSON deploy configs, writing recipes or deployment tasks, customizing the deploy pipeline, or scripting deployments with the programmatic API (Catapult class).
 ---
 
 # Catapult (@catapultjs/deploy)
@@ -9,33 +9,36 @@ Capistrano-style SSH deployment for Node.js: versioned releases under `releases/
 
 ## Critical rule
 
-`deploy:update_code` uploads `source_path` by SCP by default. Import `recipes/git` or `recipes/rsync` only when you want to replace that delivery behavior. Do not combine delivery providers such as `git` and `rsync` unless the user explicitly defines the pipeline.
+`deploy:update_code` uploads `source_path` by SCP by default. Import `recipes/git` or `recipes/rsync`, or list `git`/`rsync` under JSON `recipes`, only when you want to replace that delivery behavior. Do not combine delivery providers such as `git` and `rsync` unless the user explicitly defines the pipeline.
 
 ## 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, nextjs, nuxt, astro, tanstack, nestjs, adonisjs, vitepress, directus, pm2, redis, caddy, systemd): 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) |
+| Task                                                                                                                                                                              | Read                                                         |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Create or update a deploy config: choose TS/JS or JSON, configure hosts and recipes, add tasks, store values, healthchecks or pipeline controls                                   | [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, nextjs, nuxt, astro, tanstack, nestjs, adonisjs, vitepress, directus, pm2, redis, caddy, systemd): 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.
 
 ## Interactive config workflow
 
-When the user asks to create, initialize, or configure a Catapult deployment and the required facts are not already present in the repo or prompt, ask focused questions before writing `deploy.ts`.
+When the user asks to create, initialize, or configure a Catapult deployment and the required facts are not already present in the repo or prompt, ask focused questions before writing the config.
 
 Do not invent production values. At minimum, determine:
 
 - app stack/recipe (`nextjs`, `nextjs_static`, `nuxt`, `astro`, `nestjs`, `tanstack`, `adonisjs`, etc.)
+- config format: strict declarative JSON, or TypeScript/JavaScript when executable behavior is required
 - code delivery mode (default SCP via `source_path`, `git`, `rsync`, local-build/static recipe, or custom)
 - host name, SSH target, deploy path, and branch if using `git`
 - process manager (`pm2` or none) and whether an `ecosystem.config.cjs` should be created
 - `.env`/shared paths and optional healthcheck URL
 
 Prefer one compact question group over a long interview. If the project files already answer some items, state the inferred values and ask only for the missing or ambiguous ones. After the user answers, generate the config and include the setup/deploy commands.
+
+Use `deploy.config.json` for data-only deployments with built-in recipes, serializable store values, declarative task steps and direct `pipeline`, `remove`, `before`, and `after` controls. Include `"$schema": "https://catapultjs.com/schema/deploy.schema.json"` and `"version": 1`. Static `hosts[].bin` overrides are supported. Use `cata config:validate` to validate a config explicitly in CI or before deployment; add `--json` for machine-readable output. Use TypeScript or JavaScript for callbacks/hooks, external recipes, dynamic `bin()` calls inside custom tasks, conditional pipeline changes or arbitrary task code.

package/skills/catapultjs/references/cli.md

@@ -4,7 +4,7 @@ The CLI is `cata`, invoked via `npx cata <command>`. Full docs: https://catapult
 
 ## 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.
+`version` and `init` work without a config file. All other commands auto-detect `deploy.ts`, `deploy.config.ts`, `deploy.js`, `deploy.config.js`, `deploy.config.json` or `deploy.json` from the current directory, or use `--config <path>` / `-c <path>` to specify another file. JSON configs are schema-validated before command execution.
 
 ## Global options
 
@@ -145,12 +145,21 @@ npx cata pipeline --json
 
 ### `init`
 
-Generates a starter `deploy.ts` in the current directory. No config required.
+Prompts for TypeScript, JavaScript or JSON and generates `deploy.config.ts`, `deploy.config.js` or `deploy.config.json` in the current directory. The JSON template includes `version: 1` and `"$schema": "https://catapultjs.com/schema/deploy.schema.json"`. No config required.
 
 ```bash
 npx cata init
 ```
 
+### `config:validate`
+
+Loads the deploy config and exits without running deployment tasks or connecting to hosts. Supports `--config <path>` / `-c <path>` and `--json`. JSON output is `{ "valid": true, "file": "..." }` on success and `{ "valid": false, "file": "...", "error": "..." }` on validation failure.
+
+```bash
+npx cata config:validate
+npx cata config:validate --json
+```
+
 ### `version`
 
 Prints the installed `@catapultjs/deploy` version. No config required.

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