browserctl 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f20046bbdcf3ff57a52790137144c5f1197b6d3f8651f250bf6feb1cc9988f7
-  data.tar.gz: 1d928edc69e4691cc720b9bb7f32ea4001d1fd5df636a4af7fc59341f7714174
+  metadata.gz: 2a7eb052c2bbfc4e1f5afc24ba08c5b2b0d471a85d2acf6ea61a7f160cbe201b
+  data.tar.gz: 2d4259da9b4a13a50ad80e68d404f11eda89b6249e5315c58247c8d80514d21f
 SHA512:
-  metadata.gz: 87be1521e16f71d8f77c699712fb03c7a339b2421102e6ad0d4bc9c1a0e860ff29882c81d0e5819a802b3364962922594bd9a08d80cdf5521e50ea09659dac98
-  data.tar.gz: 29256e3d109bdfa651e8bea5fb82eef18fcb2b299c648db937015cebbfddd0d947e3e042b848adf32b61006f99d69150aaf38acf2a1356946c1584e2dc7a00b6
+  metadata.gz: ca34ca3125de0686417b06919a8cb0eaf3311eaedd7ebe6538c1f159941d737ca549f3d0c3d8a10da73146bd23602cb145ed010539a48de97c3d8552d4f317c9
+  data.tar.gz: 61c89f8a4b2e61076ddd5fa603710e226ebfe1e176914ffb37f47a79ee35a2161b3700406a35c878d6fdc6cb129f051f00943d080b636076f6d1452b6ee290b3

data/CHANGELOG.md

@@ -10,6 +10,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.12.0](https://github.com/patrick204nqh/browserctl/compare/v0.11.0...v0.12.0) (2026-05-10)
+
+
+### ⚠ BREAKING CHANGES
+
+* Scripts that hard-coded `exit 7 = AUTH_REQUIRED` must update — AUTH_REQUIRED is now exit 3, and 7 is STATE_EXPIRED. Scripts treating any non-zero status as a generic failure are unaffected. Prior to this change the CLI exited 1 for everything except AUTH_REQUIRED (which already used 7); typed errors now surface their dedicated codes.
+
+### Features
+
+* benchmark harness + bundle_codec target ([#154](https://github.com/patrick204nqh/browserctl/issues/154)) ([f4b815a](https://github.com/patrick204nqh/browserctl/commit/f4b815a617d4a7d22473e6028ce2a0f90467fa87))
+* bundle format version ([#132](https://github.com/patrick204nqh/browserctl/issues/132)) ([b52d325](https://github.com/patrick204nqh/browserctl/commit/b52d32546d1b9ec3915fac014fecd8f929161ddb))
+* crash reports ([#135](https://github.com/patrick204nqh/browserctl/issues/135)) ([b02adf4](https://github.com/patrick204nqh/browserctl/commit/b02adf4d41295dbe547d2965d838168d48efb8bf))
+* error code enum ([#128](https://github.com/patrick204nqh/browserctl/issues/128)) ([feb0522](https://github.com/patrick204nqh/browserctl/commit/feb0522887935737fd96ad8a8b47d1407a5f585e))
+* exit code map ([#140](https://github.com/patrick204nqh/browserctl/issues/140)) ([1a1d2b2](https://github.com/patrick204nqh/browserctl/commit/1a1d2b2f50693863cb508b5354e5546f340a2771))
+* format version header convention ([#129](https://github.com/patrick204nqh/browserctl/issues/129)) ([405774d](https://github.com/patrick204nqh/browserctl/commit/405774dd6c99cc96f62f0c092010b30e7e710d41))
+* migration helpers ([#143](https://github.com/patrick204nqh/browserctl/issues/143)) ([1c1762e](https://github.com/patrick204nqh/browserctl/commit/1c1762e755f83445c7cdd0df75fc5324a820fa19))
+* recording format version ([#136](https://github.com/patrick204nqh/browserctl/issues/136)) ([4f1bc46](https://github.com/patrick204nqh/browserctl/commit/4f1bc467e653ecc1f508a85b3c329adf048b783d))
+* structured error payload ([#137](https://github.com/patrick204nqh/browserctl/issues/137)) ([f028410](https://github.com/patrick204nqh/browserctl/commit/f02841069f68de749a76ba9a98a38b0c20836d76))
+* structured JSONL logs ([#131](https://github.com/patrick204nqh/browserctl/issues/131)) ([c6daff4](https://github.com/patrick204nqh/browserctl/commit/c6daff488460606659c0641dd8cee6c23561be05))
+* trace --redact ([#139](https://github.com/patrick204nqh/browserctl/issues/139)) ([19b4cec](https://github.com/patrick204nqh/browserctl/commit/19b4cec37daf95a06b0513780d991d0522069593))
+* trace command ([#133](https://github.com/patrick204nqh/browserctl/issues/133)) ([156f304](https://github.com/patrick204nqh/browserctl/commit/156f304246d24fa6c3e06f8d941ac971629ea77c))
+* workflow format version ([#138](https://github.com/patrick204nqh/browserctl/issues/138)) ([963776b](https://github.com/patrick204nqh/browserctl/commit/963776be785583fc3a3b0c04c97510e16c73ca9a))
+
+
+### Miscellaneous Chores
+
+* target next release as 0.12.0 ([#156](https://github.com/patrick204nqh/browserctl/issues/156)) ([9797fcc](https://github.com/patrick204nqh/browserctl/commit/9797fcc0bae1a47bb72eec9cec5fda105e698406))
+
 ## [0.11.0](https://github.com/patrick204nqh/browserctl/compare/v0.10.0...v0.11.0) (2026-05-10)
 
 

data/README.md

@@ -198,6 +198,7 @@ The daemon shuts itself down after 30 minutes of inactivity.
 | [Agent Integration](docs/guides/agent-integration.md) | Call browserctl from Python, shell, or Anthropic tool-use agents |
 | [Concepts](docs/concepts/) | Sessions, snapshots, [state](docs/concepts/state.md), [flows](docs/concepts/flows.md), human-in-the-loop |
 | [Guides](docs/guides/) | Writing workflows, handling challenges, smoke testing |
+| [Debugging](docs/guides/debugging.md) | Read traces, redaction, crash reports, filing a good issue |
 | [Examples](examples/) | Runnable scripts: session reuse, Cloudflare HITL, and more |
 | [Command Reference](docs/reference/commands.md) | Every command and flag |
 | [API Stability](docs/reference/api-stability.md) | Wire protocol contract and stability zones |

data/bin/browserctl

@@ -31,14 +31,29 @@ require "browserctl/commands/workflow"
 require "browserctl/commands/flow"
 require "browserctl/commands/dialog"
 require "browserctl/commands/ask"
+require "browserctl/commands/trace"
+require "browserctl/commands/migrate"
+
+def structured_stderr_payload(res, message)
+  code    = (res[:code] || res["code"] || Browserctl::Error::Codes::GENERIC).to_s
+  context = res[:context] || res["context"] || {}
+  action  = res[:suggested_action] || res["suggested_action"] ||
+            Browserctl::Error::SuggestedActions.for(code)
+  [code, JSON.generate(code: code, message: message, context: context, suggested_action: action)]
+end
 
 def print_result(res)
-  if res.is_a?(Hash) && (res[:error] || res["error"])
-    warn "Error: #{res[:error] || res['error']}"
+  unless res.is_a?(Hash) && (res[:error] || res["error"])
     puts res.to_json
-    exit((res[:code] || res["code"]) == "AUTH_REQUIRED" ? 7 : 1)
+    return
   end
+
+  message = res[:error] || res["error"]
+  code, payload = structured_stderr_payload(res, message)
+  warn "Error: #{message}"
+  warn payload
   puts res.to_json
+  exit Browserctl::Error::ExitCodes.for(code)
 end
 
 def usage
@@ -129,6 +144,15 @@ def usage
       flow list
       flow describe <name>
 
+    Trace:
+      trace [<session>]  Pretty timeline of CLI + daemon log events.
+
+    Migrate:
+      migrate <path> [--to-version N] [--dry-run]
+        # Upgrades a persisted artifact (.bctl / .jsonl recording / workflow .rb)
+        # using registered migrations. Empty registry in v0.12 — first real
+        # migration ships post-1.0 when a format actually changes.
+
     Daemon:
       daemon start  [--headed] [--name NAME]
       daemon stop
@@ -149,6 +173,17 @@ daemon_name = if daemon_idx
                 ARGV.delete_at(daemon_idx)
               end
 
+log_level_idx = ARGV.index("--log-level") || ARGV.index("-l")
+log_level     = if log_level_idx
+                  ARGV.delete_at(log_level_idx)
+                  ARGV.delete_at(log_level_idx)
+                end || ENV["BROWSERCTL_LOG_LEVEL"] || "info"
+
+# CLI invocations write structured JSON Lines to ~/.browserctl/logs/cli.log
+# alongside the existing stderr behaviour. Stderr stays human-readable so
+# scripted callers see no change.
+Browserctl.logger = Browserctl.build_logger(log_level, component: "cli")
+
 cmd  = ARGV.shift
 args = ARGV.dup
 
@@ -156,99 +191,113 @@ usage if cmd.nil? || %w[-h --help help].include?(cmd)
 
 runner = Browserctl::Runner.new
 
-case cmd
-when "workflow" then Browserctl::Commands::Workflow.run(runner, args)
-when "record"   then Browserctl::Commands::Record.run(args)
-when "init"     then Browserctl::Commands::Init.run(args)
-when "ask"      then Browserctl::Commands::Ask.run(args)
+begin
+  case cmd
+  when "workflow" then Browserctl::Commands::Workflow.run(runner, args)
+  when "record"   then Browserctl::Commands::Record.run(args)
+  when "init"     then Browserctl::Commands::Init.run(args)
+  when "ask"      then Browserctl::Commands::Ask.run(args)
+  when "trace"    then Browserctl::Commands::Trace.run(args)
+  when "migrate"  then Browserctl::Commands::Migrate.run(args)
 
-else
-  client = Browserctl::Client.new(Browserctl.socket_path(daemon_name))
+  else
+    client = Browserctl::Client.new(Browserctl.socket_path(daemon_name))
 
-  case cmd
-  when "flow"     then Browserctl::Commands::Flow.run(client, args)
-  when "page"     then Browserctl::Commands::Page.run(client, args)
-  when "cookie"   then Browserctl::Commands::Cookie.run(client, args)
-  when "storage"  then Browserctl::Commands::Storage.run(client, args)
-  when "session"  then Browserctl::Commands::Session.run(client, args)
-  when "state"    then Browserctl::Commands::State.run(client, args)
-  when "daemon"   then Browserctl::Commands::Daemon.run(client, args)
-  when "auth-check"
-    page_name = args.shift or abort "usage: browserctl auth-check <page> [--cookies] [--state NAME] [--flow NAME]"
-    include_cookies = args.delete("--cookies") ? true : false
-    state_idx = args.index("--state")
-    state_arg = if state_idx
-                  (args.delete_at(state_idx)
-                   args.delete_at(state_idx))
-                end
-    flow_idx  = args.index("--flow")
-    flow_arg  = if flow_idx
-                  (args.delete_at(flow_idx)
-                   args.delete_at(flow_idx))
-                end
-    print_result(client.auth_check(page_name, include_cookies: include_cookies,
-                                              state: state_arg, suggested_flow: flow_arg))
-  when "navigate" then print_result(client.navigate(args[0], args[1]))
-  when "fill"     then Browserctl::Commands::Fill.run(client, args)
-  when "click"    then Browserctl::Commands::Click.run(client, args)
-  when "snapshot" then Browserctl::Commands::Snapshot.run(client, args)
-  when "screenshot" then Browserctl::Commands::Screenshot.run(client, args)
-  when "evaluate" then print_result(client.evaluate(args[0], args[1]))
-  when "url"      then print_result(client.url(args[0]))
-  when "wait"
-    opts = Optimist.options(args) do
-      opt :timeout, "Seconds to wait (default: 30)", default: 30.0, short: "-t"
-    end
-    name = args.shift
-    selector = args.shift
-    abort "usage: browserctl wait <page> <selector> [--timeout N]" unless name && selector
-    print_result(client.wait(name, selector, timeout: opts[:timeout]))
-  when "pause"
-    opts = Optimist.options(args) do
-      opt :message, "Message shown to human", type: :string, short: "-m"
+    case cmd
+    when "flow"     then Browserctl::Commands::Flow.run(client, args)
+    when "page"     then Browserctl::Commands::Page.run(client, args)
+    when "cookie"   then Browserctl::Commands::Cookie.run(client, args)
+    when "storage"  then Browserctl::Commands::Storage.run(client, args)
+    when "session"  then Browserctl::Commands::Session.run(client, args)
+    when "state"    then Browserctl::Commands::State.run(client, args)
+    when "daemon"   then Browserctl::Commands::Daemon.run(client, args)
+    when "auth-check"
+      page_name = args.shift or abort "usage: browserctl auth-check <page> [--cookies] [--state NAME] [--flow NAME]"
+      include_cookies = args.delete("--cookies") ? true : false
+      state_idx = args.index("--state")
+      state_arg = if state_idx
+                    (args.delete_at(state_idx)
+                     args.delete_at(state_idx))
+                  end
+      flow_idx  = args.index("--flow")
+      flow_arg  = if flow_idx
+                    (args.delete_at(flow_idx)
+                     args.delete_at(flow_idx))
+                  end
+      print_result(client.auth_check(page_name, include_cookies: include_cookies,
+                                                state: state_arg, suggested_flow: flow_arg))
+    when "navigate" then print_result(client.navigate(args[0], args[1]))
+    when "fill"     then Browserctl::Commands::Fill.run(client, args)
+    when "click"    then Browserctl::Commands::Click.run(client, args)
+    when "snapshot" then Browserctl::Commands::Snapshot.run(client, args)
+    when "screenshot" then Browserctl::Commands::Screenshot.run(client, args)
+    when "evaluate" then print_result(client.evaluate(args[0], args[1]))
+    when "url"      then print_result(client.url(args[0]))
+    when "wait"
+      opts = Optimist.options(args) do
+        opt :timeout, "Seconds to wait (default: 30)", default: 30.0, short: "-t"
+      end
+      name = args.shift
+      selector = args.shift
+      abort "usage: browserctl wait <page> <selector> [--timeout N]" unless name && selector
+      print_result(client.wait(name, selector, timeout: opts[:timeout]))
+    when "pause"
+      opts = Optimist.options(args) do
+        opt :message, "Message shown to human", type: :string, short: "-m"
+      end
+      name = args.shift or abort "usage: browserctl pause <page> [--message MSG]"
+      res = client.pause(name, message: opts[:message])
+      if res[:error]
+        warn "Error: #{res[:error]}"
+        exit 1
+      end
+      puts "Page '#{name}' paused. Browser is live — interact freely."
+      puts "(#{opts[:message]})" if opts[:message]
+      puts "When done: browserctl resume #{name}"
+    when "resume" then Browserctl::Commands::Resume.run(client, args)
+    when "press"
+      name = args.shift or abort "usage: browserctl press <page> <key>"
+      key  = args.shift or abort "usage: browserctl press <page> <key>"
+      print_result(client.press(name, key))
+    when "hover"
+      name     = args.shift or abort "usage: browserctl hover <page> <selector>"
+      selector = args.shift or abort "usage: browserctl hover <page> <selector>"
+      print_result(client.hover(name, selector))
+    when "upload"
+      name     = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
+      selector = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
+      path     = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
+      print_result(client.upload(name, selector, path))
+    when "select"
+      name     = args.shift or abort "usage: browserctl select <page> <selector> <value>"
+      selector = args.shift or abort "usage: browserctl select <page> <selector> <value>"
+      value    = args.shift or abort "usage: browserctl select <page> <selector> <value>"
+      print_result(client.select(name, selector, value))
+    when "dialog" then Browserctl::Commands::Dialog.run(client, args)
+    when "devtools"
+      name = args.shift or abort "usage: browserctl devtools <page>"
+      res = client.devtools(name)
+      if res[:error]
+        warn "Error: #{res[:error]}"
+        exit 1
+      end
+      url = res[:devtools_url]
+      puts "Opening DevTools for '#{name}':"
+      puts "  #{url}"
+      opener = RUBY_PLATFORM =~ /darwin/ ? "open" : "xdg-open"
+      system(opener, url)
+    else
+      abort "unknown command: #{cmd}\nRun 'browserctl --help' for usage."
     end
-    name = args.shift or abort "usage: browserctl pause <page> [--message MSG]"
-    res = client.pause(name, message: opts[:message])
-    if res[:error]
-      warn "Error: #{res[:error]}"
-      exit 1
-    end
-    puts "Page '#{name}' paused. Browser is live — interact freely."
-    puts "(#{opts[:message]})" if opts[:message]
-    puts "When done: browserctl resume #{name}"
-  when "resume" then Browserctl::Commands::Resume.run(client, args)
-  when "press"
-    name = args.shift or abort "usage: browserctl press <page> <key>"
-    key  = args.shift or abort "usage: browserctl press <page> <key>"
-    print_result(client.press(name, key))
-  when "hover"
-    name     = args.shift or abort "usage: browserctl hover <page> <selector>"
-    selector = args.shift or abort "usage: browserctl hover <page> <selector>"
-    print_result(client.hover(name, selector))
-  when "upload"
-    name     = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
-    selector = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
-    path     = args.shift or abort "usage: browserctl upload <page> <selector> <file>"
-    print_result(client.upload(name, selector, path))
-  when "select"
-    name     = args.shift or abort "usage: browserctl select <page> <selector> <value>"
-    selector = args.shift or abort "usage: browserctl select <page> <selector> <value>"
-    value    = args.shift or abort "usage: browserctl select <page> <selector> <value>"
-    print_result(client.select(name, selector, value))
-  when "dialog" then Browserctl::Commands::Dialog.run(client, args)
-  when "devtools"
-    name = args.shift or abort "usage: browserctl devtools <page>"
-    res = client.devtools(name)
-    if res[:error]
-      warn "Error: #{res[:error]}"
-      exit 1
-    end
-    url = res[:devtools_url]
-    puts "Opening DevTools for '#{name}':"
-    puts "  #{url}"
-    opener = RUBY_PLATFORM =~ /darwin/ ? "open" : "xdg-open"
-    system(opener, url)
-  else
-    abort "unknown command: #{cmd}\nRun 'browserctl --help' for usage."
   end
+rescue Browserctl::Error => e
+  payload = {
+    code: e.code,
+    message: e.message,
+    context: e.respond_to?(:context) ? (e.context || {}) : {},
+    suggested_action: Browserctl::Error::SuggestedActions.for(e.code)
+  }
+  warn "Error: #{e.message}"
+  warn JSON.generate(payload)
+  exit Browserctl::Error::ExitCodes.for(e.code)
 end

data/bin/browserd

@@ -5,6 +5,7 @@ $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
 
 require "optimist"
 require "nokogiri"
+require "browserctl/crash_report"
 require "browserctl/logger"
 require "browserctl/server"
 require "browserctl/version"
@@ -35,7 +36,9 @@ end
 
 log_path = Browserctl.log_path(assigned_name)
 warn "browserd starting — log: #{log_path}"
-Browserctl.logger = Browserctl.build_logger(opts[:log_level], log_path: log_path)
+warn "  if browserd crashes, attach the crash report from ~/.browserctl/logs/crash-*.json"
+Browserctl.logger = Browserctl.build_logger(opts[:log_level], log_path: log_path, component: "daemon")
+daemon_jsonl_log = File.join(Browserctl.log_dir, "daemon.log")
 begin
   Browserctl::Server.new(
     headless: !opts[:headed],
@@ -45,4 +48,8 @@ begin
   ).run
 rescue Browserctl::BrowserNotFound => e
   abort e.message
+rescue Exception => e # rubocop:disable Lint/RescueException
+  crash_path = Browserctl::CrashReport.write(error: e, log_path: daemon_jsonl_log)
+  warn "browserd crashed — crash report: #{crash_path}" if crash_path
+  raise
 end

data/lib/browserctl/client.rb

@@ -182,7 +182,7 @@ module Browserctl
     # @param path [String] file path to read cookies from
     # @return [Hash] `{ ok: true, count: }` or `{ error: }`
     def import_cookies(name, path)
-      raise "cookie file not found: #{path}" unless File.exist?(path)
+      raise Browserctl::Error, "cookie file not found: #{path}" unless File.exist?(path)
 
       cookies = JSON.parse(File.read(path), symbolize_names: true)
       call("import_cookies", name: name, cookies: cookies)
@@ -371,10 +371,10 @@ module Browserctl
     end
 
     def read_response(sock)
-      raise "browserd response timeout after 60s" unless sock.wait_readable(60)
+      raise DaemonUnavailableError, "browserd response timeout after 60s" unless sock.wait_readable(60)
 
       raw = sock.gets
-      raise "browserd closed connection" unless raw
+      raise DaemonUnavailableError, "browserd closed connection" unless raw
 
       JSON.parse(raw.chomp, symbolize_names: true)
     end

data/lib/browserctl/commands/cli_output.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "../errors"
+require_relative "../error/suggested_actions"
 
 module Browserctl
   module Commands
@@ -9,7 +11,9 @@ module Browserctl
 
       def print_result(res)
         if res.is_a?(Hash) && (res[:error] || res["error"])
-          warn "Error: #{res[:error] || res['error']}"
+          message = res[:error] || res["error"]
+          warn "Error: #{message}"
+          warn structured_error_line(res, message)
           puts res.to_json
           exit exit_code_for(res)
         end
@@ -23,6 +27,22 @@ module Browserctl
 
         1
       end
+
+      # Builds the single-line structured payload emitted to stderr after
+      # the human-readable line. Agents parse this JSON deterministically.
+      # Shape: { code, message, context, suggested_action }.
+      def structured_error_line(res, message)
+        code    = (res[:code] || res["code"] || Browserctl::Error::Codes::GENERIC).to_s
+        context = res[:context] || res["context"] || {}
+        action  = res[:suggested_action] || res["suggested_action"] ||
+                  Browserctl::Error::SuggestedActions.for(code)
+        JSON.generate(
+          code: code,
+          message: message,
+          context: context,
+          suggested_action: action
+        )
+      end
     end
   end
 end

data/lib/browserctl/commands/migrate.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require_relative "../migrations"
+require_relative "../errors"
+require_relative "../error/codes"
+require_relative "../error/exit_codes"
+
+module Browserctl
+  module Commands
+    # `browserctl migrate <path> [--to-version N] [--dry-run]` — operator
+    # entry point for the {Browserctl::Migrations} registry. Detects the
+    # artifact's format and version, plans a chain of registered upgraders,
+    # and applies them in order (unless `--dry-run`).
+    #
+    # The registry ships empty in v0.12; this command exists so operators
+    # have a stable invocation the moment a real migration lands. On an
+    # already-current artifact the command is a no-op and exits 0.
+    module Migrate
+      USAGE = "Usage: browserctl migrate <path> [--to-version N] [--dry-run]"
+
+      def self.run(args, out: $stdout, err: $stderr)
+        abort USAGE if args.empty? || args.include?("-h") || args.include?("--help")
+        args = args.dup
+
+        dry_run    = !args.delete("--dry-run").nil?
+        target_idx = args.index("--to-version")
+        target = if target_idx
+                   args.delete_at(target_idx)
+                   Integer(args.delete_at(target_idx))
+                 end
+        path = args.shift
+        abort USAGE unless path
+
+        unless File.exist?(path)
+          err.puts "Error: file not found: #{path}"
+          exit Browserctl::Error::ExitCodes::GENERIC
+        end
+
+        execute(path, target_version: target, dry_run: dry_run, out: out, err: err)
+      rescue Browserctl::ProtocolMismatch => e
+        err.puts "Error: #{e.message}"
+        exit Browserctl::Error::ExitCodes.for(e.code)
+      end
+
+      def self.execute(path, target_version:, dry_run:, out:, err:)
+        format = Browserctl::Migrations.detect_format(path)
+        unless format
+          err.puts "Error: could not detect format for #{path} (expected .bctl, .jsonl, or .rb)"
+          exit Browserctl::Error::ExitCodes::PROTOCOL_MISMATCH
+        end
+
+        current = Browserctl::Migrations.detect_version(path, format)
+        out.puts "Detected: format=#{format} version=#{current.inspect} path=#{path}"
+
+        if dry_run
+          plan_dry_run(format, current, target_version, out)
+          return
+        end
+
+        result = Browserctl::Migrations.run(path, target_version: target_version)
+        if result.applied.empty?
+          out.puts "No migrations registered for #{format} v#{current}; nothing to do."
+        else
+          out.puts "Applied #{result.applied.size} migration(s): #{result.from} -> #{result.to}"
+          result.applied.each { |m| out.puts "  - #{format} v#{m.from_version} -> v#{m.to_version}" }
+        end
+      end
+
+      def self.plan_dry_run(format, current, target_version, out)
+        target = target_version || latest_target(format, current)
+        chain  = Browserctl::Migrations.find_path(format: format, from: current, to: target)
+
+        if chain.nil?
+          out.puts "No migration path #{format} v#{current} -> v#{target} (registered: " \
+                   "#{registered_for(format).inspect})"
+        elsif chain.empty?
+          out.puts "Already at v#{target}; no migrations would run."
+        else
+          out.puts "Plan (#{chain.size} step(s)):"
+          chain.each { |m| out.puts "  - #{format} v#{m.from_version} -> v#{m.to_version}" }
+        end
+      end
+
+      def self.latest_target(format, current)
+        targets = registered_for(format)
+        targets.empty? ? current : targets.max
+      end
+
+      def self.registered_for(format)
+        Browserctl::Migrations.all.select { |m| m.format == format }.map(&:to_version)
+      end
+    end
+  end
+end