rollbackplan

rollbackplan

リリースを急いでロールバックすると、順序を間違えがちです。依存しているフラグをオフにする前にマイグレーションを元に戻してしまったり、削除したカラムが、実は誰も再構築できないものだと後から判明したりします。rollbackplan は、すでに手元にあるリリース差分を受け取り、作業に着手する前に順序付きの計画に変換します。まずフラグ、次に環境変数、最後にマイグレーションを逆順で処理します。

差分のうち、リリースが変更したフィーチャーフラグ、変更した環境変数、適用順に並べたマイグレーションの3つを指定します。計画では、リリースを安全に元に戻すための唯一の順序で処理します。

• フィーチャーフラグは入力順です。 リリースで有効にしたフラグは無効にし、無効にしたフラグは再度有効にし、追加したフラグは削除します。リリースで削除したフラグは単純に元に戻せないため、この手順は手動としてマークされます。リリース前の状態に再作成する必要があります。
• 環境変数の変更は入力順です。 リリースで追加した変数は設定を解除します。変更または削除した変数については、リリース前の値が記録されていればその値に戻します。previous_value_known が false の場合、元の値を人が調べる必要があるため、この手順は手動としてマークされます。
• マイグレーションは入力順の逆順です。最後に適用したものを最初にロールバックします。補正用の down_id があるマイグレーションでは、そのマイグレーションを実行します（reversible: false よりも down_id が優先されます）。可逆なマイグレーションでは、そのマイグレーション自身の down マイグレーションを実行します。補正用マイグレーションがない不可逆なマイグレーションはブロックとしてマークされます。手動でのデータ復旧が必要であり、ブロックされた手順が1つでもある場合に限り、計画の safe フィールドは false になります。

各手順には、位置（1始まりの order）、種類、実行するアクション、対象、具体的な指示（detail）、リスク（normal、manual、blocked）が含まれます。結果には、全手順数と種類別の手順数、リスク別の手動およびブロックされた手順数も含まれるため、呼び出し元は人が一覧に沿って作業を始める前に safe を条件として確認できます。

計画は助言を示すものであり、実行するものではありません。rollbackplan は何も実行しません。マイグレーションを実行したり、フラグを切り替えたり、環境に変更を加えたりすることはありません。処理は純粋かつローカルで行われ、ネットワークや設定は使用せず、渡された入力以外のファイルも読み込みません。

入力に不備がある場合（release がない、空である、または文字列ではない、リストが配列ではない、要素がオブジェクトではない、マイグレーションの id や変数／フラグの name がない、空、または重複している、action または change が列挙値以外である、reversible または previous_value_known の型が不正である、あるいは down_id が空である）、問題のあるパスを示すバリデーションエラーになります（例：migrations[2].id duplicates migrations[0].id "add_orders"）。計画の一部だけが生成されることはありません。

CLI

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

args.json には、引数オブジェクト全体が含まれます。

{
  "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、feature_flags はすべて省略可能で、省略時のデフォルトは [] です。各マイグレーションの reversible のデフォルトは true、各環境変数の変更における previous_value_known のデフォルトは false です。3つのリストはすべて空でもかまいません。その場合、計画には手順がなく、safe は true になります。計画は 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
}

終了コード：成功時は 0、実行時エラー時（読み取り不能または無効な入力ファイル、無効な入力を含む）は 1、使用方法のエラー時は 2 です。

MCP サーバー

npx -y @reneturcios/rollbackplan mcp

MCP クライアントの設定：

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

ツール

• plan_rollback — 差分からリリースのロールバックを計画します。

  • release（文字列、必須、空でない） — ロールバック対象のリリース識別子またはバージョン
  • migrations（配列、省略可能、デフォルトは []） — 適用順のマイグレーションを、{id, reversible?, down_id?} オブジェクトとして指定します。id はセット内で一意であり、reversible のデフォルトは true です。
  • env_changes（配列、省略可能、デフォルトは []） — 変更を {name, action, previous_value_known?} オブジェクトとして指定します。action は added、changed、 removed のいずれかで、previous_value_known のデフォルトは false です。
  • feature_flags（配列、省略可能、デフォルトは []） — 変更を {name, change} オブジェクトとして指定します。change は enabled、disabled、added、removed のいずれかです。

  {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

開発

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

ライセンス

MIT — Copyright (c) 2026 Rene Turcios