Convert an existing bash script into a Stagehand processor: map each command 1:1 to a step using ctx.$(), organize into logical stages, replace commands with fs/Bun APIs only when genuinely better, translate bash flags to typed Commander options, wire error handling through the typed error registry and ctx.fail(), and add compensation handlers for every side-effecting command.
Dependency note: This skill builds on define-processor (ProcessorBuilder chain, stages, steps, artifacts, finalize) and compensation-and-rollback (CompensationPolicy, effect kinds, compensate handlers, reverse-order execution). Read those skills first — this skill assumes fluency with the builder API and the compensation model.
Follow these steps in order when converting a bash script into a Stagehand processor.
Read the entire script and produce a flat list of every command that executes. Mark each command with its effect kind:
| Bash pattern | Effect kind | Needs compensation? |
|---|---|---|
cat, ls, node -v, git status | read |
| No |
mkdir -p, cp, npm ci, echo > file | create | Yes |
sed -i, git pull, npm version | update | Yes |
rm -rf, docker rm | delete | Yes |
curl -X POST, pm2 restart, ssh deploy@ | external | Yes |
Group commands into logical stages. Look for:
# --- Build ---)if [ $changed -eq 1 ]; then)Each group becomes a .stage() call.
One bash command = one Stagehand step. Never combine commands.
For each command, decide:
ctx.$() — default choice. Preserves the exact shell command.fs / Bun API — only for file existence checks, reading/writing file contents, mkdir, or simple file copies within the project.Bash case/getopts patterns become typed Commander options:
import { ScriptApp } from '../modules/classes/appScript';
import { Option } from '@commander-js/extra-typings';
// Bash: --no-git → skip git pull --build-only → skip module install
// Stagehand: