rampway 0.2.6 → 0.3.0

package/docs/config-reference.md

@@ -38,6 +38,7 @@ Each stage under `stages` supports:
 | `linkedFiles` | array | no | `[]` | Files symlinked from `shared/` into each release. See Linked files below. |
 | `linkedDirs` | array | no | `[]` | Directories symlinked from `shared/` into each release. |
 | `tasks` | object | no | `{}` | Named task groups executed in order during deploy. See Tasks below. |
+| `operationalTasks` | object | no | `{}` | Explicit standalone tasks that run against the active release. See Operational tasks below. |
 | `hooks` | object | no | `{}` | Lifecycle-phase hooks executed at specific points in the deploy pipeline. See Hooks below. |
 | `runtime` | object | no | `{type: "none"}` | Runtime adapter config. See Runtime below. |
 | `healthChecks` | array | no | `[]` | Checks run after tasks and before publish. See Health checks below. |
@@ -198,6 +199,47 @@ rampway production tasks --json
 
 Each entry shows its command plus any `cwd`, `env`, `optional`, and `onlyIfChanged` metadata. Secret-like env values and `KEY=value` assignments in commands are redacted in both the human and `--json` output.
 
+## Operational tasks
+
+`operationalTasks` is a strict namespace for reusable standalone operations. It is separate from deploy lifecycle `tasks`: an operational task runs only when its exact configured name is invoked.
+
+```js
+operationalTasks: {
+  "cache:warm": [
+    {
+      command: "npm run cache:warm",
+      cwd: "backend",
+      env: {NODE_ENV: "production"},
+      forwardEnv: ["CACHE_WARM_CREDENTIAL"]
+    }
+  ]
+}
+```
+
+Each value is a command string, one entry object, or a non-empty ordered array of strings and entry objects. Entry objects accept only:
+
+- `command` — required non-empty shell command from trusted configuration.
+- `cwd` — optional non-empty release-relative directory; absolute and escaping paths are rejected.
+- `env` — optional string-valued environment literals with safe shell names. Secret-like keys are rejected; use `forwardEnv`.
+- `forwardEnv` — optional unique allowlist of safe environment names. Every named value must exist in Rampway's invocation environment and is always treated as sensitive.
+
+Task names are 1–128 characters and match `^[A-Za-z0-9][A-Za-z0-9:_-]*$`. Selection is an exact name lookup; command text and arbitrary trailing arguments cannot come from the CLI.
+
+```bash
+CACHE_WARM_CREDENTIAL=... rampway production task cache:warm
+CACHE_WARM_CREDENTIAL=... rampway production task cache:warm --json
+```
+
+Rampway resolves all forwarded values before transport work, acquires the same exclusive lock used by deploy and rollback, then strictly resolves `current` to one existing direct child of `releases/`. Every entry is required and runs in order against that immutable release path. Missing configuration, forwarded values, lock ownership, active release, command failures, and transport failures all fail closed. There is no task `--force`.
+
+For SSH, forwarded values are sent to a fixed remote shell through stdin rather than SSH argv. Known values are redacted from streamed output, returned output, and errors even when echoed without their variable name or split across chunks. Human output identifies the application, stage, task, and release. JSON mode emits only:
+
+```json
+{"application":"demo","stage":"production","task":"cache:warm","releaseId":"20260728120000","status":"passed"}
+```
+
+Standalone task runs are not appended to the deployment report. The plural `rampway <stage> tasks` command remains a read-only inventory of deploy task groups.
+
 ## Hooks
 
 Hooks are lifecycle-phase callbacks that run commands at specific points during the deploy pipeline, outside the fixed task-group slot. Each hook phase accepts an array of task entries (strings or objects, same format as tasks).

package/docs/migration-from-capistrano.md

@@ -17,6 +17,7 @@ Rampway is a JS-native alternative to Capistrano for Node projects. This guide m
 | `SSHKit` | `transport: {type: "ssh"}` |
 | `after/before` hooks | `tasks` run in config order, or use lifecycle `hooks` for phase-specific callbacks |
 | `deploy:starting` … `deploy:finished` | task groups + runtime deploy |
+| Explicit custom task against `current` | `operationalTasks` + `rampway production task <exact-name>` |
 | `cap production deploy` | `rampway production deploy` |
 | `cap -T` / `cap production -T` | `rampway production tasks` |
 | `cap production deploy:rollback` | `rampway production rollback` |
@@ -106,7 +107,27 @@ tasks: {
 }
 ```
 
-### 5. Convert process management
+### 5. Convert standalone operational tasks
+
+Keep operations that were invoked explicitly in Capistrano out of deploy task groups. Declare each one under the strict `operationalTasks` namespace and invoke its exact configured name:
+
+```js
+operationalTasks: {
+  "cache:warm": {
+    command: "npm run cache:warm",
+    cwd: "backend",
+    forwardEnv: ["CACHE_WARM_CREDENTIAL"]
+  }
+}
+```
+
+```bash
+CACHE_WARM_CREDENTIAL=... rampway production task cache:warm
+```
+
+Rampway owns the configured transport, shared deploy lock, active-release resolution, and secret-value redaction. Replace the former caller's direct SSH with the Rampway invocation; do not retain an SSH fallback. Operational tasks are explicit and never run as part of every deploy.
+
+### 6. Convert process management
 
 Capistrano relies on SSH-based process management (puma, sidekiq, etc.) or custom tasks:
 
@@ -136,7 +157,7 @@ Rollbridge handles zero-downtime restarts, health checks, and log access. Rampwa
 
 For simple setups without a process manager, use `runtime: {type: "none"}` and handle process restarts yourself via task commands.
 
-### 6. Run the first deploy
+### 7. Run the first deploy
 
 ```bash
 # Validate
@@ -149,7 +170,7 @@ rampway production plan
 rampway production deploy
 ```
 
-### 7. Verify and cleanup
+### 8. Verify and cleanup
 
 ```bash
 rampway production status
@@ -162,6 +183,7 @@ After verifying the first deploy works, remove your old Capistrano config files.
 
 - **No Ruby dependency.** Rampway runs on Node.js, matching your JS/TS stack.
 - **Task groups replace hooks.** Order task groups instead of registering `after`/`before` callbacks. For Capistrano-style lifecycle callbacks, use `hooks` with named phases like `before_publish` and `after_cleanup`.
+- **Operational tasks replace explicitly invoked remote tasks.** Configure an exact name under `operationalTasks`; Rampway executes it against the locked active release and securely forwards allowlisted caller environment values.
 - **Runtime adapters replace process management tasks.** Rollbridge or a custom adapter handles zero-downtime handoff.
 - **ESM config.** `rampway.config.mjs` uses ES module syntax, not Ruby DSL.
 - **Health checks are built in.** Add `healthChecks` to verify deploy readiness before publishing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rampway",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "JS-native Capistrano-style release-directory deployments with Rollbridge integration.",
   "type": "module",
   "private": false,