rollbackplan

rollbackplan

Rolling a release back under pressure is where ordering mistakes happen: a migration is undone before the flag that depends on it is off, or a dropped column turns out to be the one nobody can reconstruct. rollbackplan takes the release diff you already have and turns it into an ordered plan before anyone touches anything — flags first, then env, then migrations backwards.

You supply three parts of the diff: the feature flags the release touched, the environment variable changes it made, and the migrations it applied, in application order. The plan walks them in the only order that is safe to undo a release in:

• Feature flags, in input order. A flag the release enabled is disabled, one it disabled is re-enabled, one it added is removed. A flag it removed cannot simply be flipped back, so that step is flagged manual: someone has to recreate it in its pre-release state.
• Environment changes, in input order. A variable the release added is unset. For a changed or removed variable, the step restores the recorded pre-release value when there is one; when previous_value_known is false the step is flagged manual, because the old value has to be found by a person.
• Migrations, in reverse input order — the last one applied is the first one rolled back. A migration with a compensating down_id runs that migration (the down_id wins, even over reversible: false), and a reversible migration runs its own down migration. An irreversible migration with no compensating migration is flagged blocked: manual data recovery is required, and the plan's safe field is false exactly while any blocked step exists.

Every step carries its position (order, 1-based), its kind, the action to take, its target, an exact instruction (detail), and its risk — normal, manual, or blocked. The result also counts the steps overall and per kind, and counts the manual and blocked steps by risk, so a caller can gate on safe before a human starts working through the list.

The plan is advice, not action: rollbackplan executes nothing. It does not run a migration, flip a flag, or touch an environment. The computation is pure and local — no network, no configuration, no files read beyond the input you pass in.

Malformed input — a missing, empty, or non-string release, a list that is not an array, an entry that is not an object, a missing, empty, or duplicated migration id or variable / flag name, an action or change outside its enum, a wrongly typed reversible or previous_value_known, or an empty down_id — is a validation error naming the offending path (for example migrations[2].id duplicates migrations[0].id "add_orders"), and no partial plan is produced.

CLI

npx @reneturcios/rollbackplan plan --input args.json
npx @reneturcios/rollbackplan --version

args.json contains the full arguments object:

{
  "release": "v2.4.0",
  "feature_flags": [
    { "name": "checkout-v2", "change": "enabled" },
    { "name": "old-banner", "change": "removed" }
  ],
  "env_changes": [
    { "name": "TIMEOUT_MS", "action": "changed", "previous_value_known": true },
    { "name": "LEGACY_TOKEN", "action": "removed" }
  ],
  "migrations": [
    { "id": "add_orders_table" },
    { "id": "backfill_orders", "down_id": "clear_backfill" },
    { "id": "drop_legacy_table", "reversible": false }
  ]
}

migrations, env_changes, and feature_flags are each optional and default to []; reversible defaults to true per migration and previous_value_known defaults to false per env change. All three lists may be empty: the plan then has no steps and safe is true. The plan is printed as JSON:

{
  "release": "v2.4.0",
  "steps": [
    { "order": 1, "kind": "feature_flag", "action": "disable", "target": "checkout-v2", "detail": "Disable feature flag checkout-v2 (enabled by this release)", "risk": "normal" },
    { "order": 2, "kind": "feature_flag", "action": "restore", "target": "old-banner", "detail": "Feature flag old-banner was removed by this release; recreate it in its pre-release state", "risk": "manual" },
    { "order": 3, "kind": "env", "action": "set", "target": "TIMEOUT_MS", "detail": "Restore environment variable TIMEOUT_MS to its recorded pre-release value", "risk": "normal" },
    { "order": 4, "kind": "env", "action": "restore", "target": "LEGACY_TOKEN", "detail": "Environment variable LEGACY_TOKEN was removed by this release and its pre-release value is not recorded; restore it manually", "risk": "manual" },
    { "order": 5, "kind": "migration", "action": "manual", "target": "drop_legacy_table", "detail": "Migration drop_legacy_table is irreversible and has no compensating migration; manual data recovery is required", "risk": "blocked" },
    { "order": 6, "kind": "migration", "action": "run_down_migration", "target": "clear_backfill", "detail": "Run compensating migration clear_backfill to undo backfill_orders", "risk": "normal" },
    { "order": 7, "kind": "migration", "action": "run_down_migration", "target": "add_orders_table", "detail": "Run the down migration for add_orders_table", "risk": "normal" }
  ],
  "counts": { "steps": 7, "feature_flags": 2, "env_changes": 2, "migrations": 3, "manual": 2, "blocked": 1 },
  "safe": false
}

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/rollbackplan mcp

MCP client config:

{
  "mcpServers": {
    "rollbackplan": {
      "command": "npx",
      "args": ["-y", "@reneturcios/rollbackplan", "mcp"]
    }
  }
}

Tools

• plan_rollback — Plan a release rollback from its diff.

  • release (string, required, non-empty) — the release identifier or version being rolled back
  • migrations (array, optional, default []) — migrations in application order, as {id, reversible?, down_id?} objects; id is unique across the set and reversible defaults to true
  • env_changes (array, optional, default []) — changes as {name, action, previous_value_known?} objects; action is one of added, changed, removed, and previous_value_known defaults to false
  • feature_flags (array, optional, default []) — changes as {name, change} objects; change is one of enabled, disabled, added, removed

  Returns {release, steps, counts, safe}.

Docker

docker run -i ghcr.io/cloudcorprecords/rollbackplan
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/rollbackplan plan --input /w/args.json

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios