@catapultjs/deploy 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catapultjs/deploy",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "main": "build/index.js",
   "bin": {
@@ -14,10 +14,12 @@
   },
   "files": [
     "build",
+    "schema",
     "skills",
     "!build/bin/test.js",
     "!build/bin/test.d.ts",
     "!build/bin/test.js.map",
+    "!build/scripts",
     "!build/docs",
     "!build/examples",
     "!build/tests"
@@ -25,9 +27,10 @@
   "scripts": {
     "lint": "eslint .",
     "format": "prettier --write .",
+    "schema:generate": "node scripts/generate_json_schema.ts",
     "typecheck": "tsc --noEmit",
     "build": "tsc",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm run schema:generate && npm run build",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
@@ -73,6 +76,7 @@
       "types": "./build/src/api.d.ts",
       "import": "./build/src/api.js"
     },
+    "./schema/deploy.schema.json": "./schema/deploy.schema.json",
     "./recipes/*": {
       "types": "./build/recipes/*.d.ts",
       "import": "./build/recipes/*.js"
@@ -84,14 +88,15 @@
     "@adonisjs/tsconfig": "^2.0.0",
     "@japa/assert": "^4.2.0",
     "@japa/runner": "^5.3.0",
-    "@types/node": "^25.9.3",
-    "eslint": "^10.4.1",
-    "prettier": "^3.8.4",
+    "@types/node": "^25.9.5",
+    "eslint": "^10.7.0",
+    "prettier": "^3.9.5",
     "typescript": "^6.0.3",
-    "vitepress": "^2.0.0-alpha.17"
+    "vitepress": "^2.0.0-alpha.18"
   },
   "dependencies": {
     "@adonisjs/ace": "^14.1.0",
+    "ajv": "^8.20.0",
     "execa": "^9.6.1"
   },
   "eslintConfig": {

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): 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.