browserctl 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f20046bbdcf3ff57a52790137144c5f1197b6d3f8651f250bf6feb1cc9988f7
-  data.tar.gz: 1d928edc69e4691cc720b9bb7f32ea4001d1fd5df636a4af7fc59341f7714174
+  metadata.gz: 41aa6c550f8a9a6403781639ebbd381c653aedb03cfa95f732b74de3ee0a931d
+  data.tar.gz: 3feea758e797eca81e1ab269ca5d9011f82778510dab1ee45e31b80b9aa38048
 SHA512:
-  metadata.gz: 87be1521e16f71d8f77c699712fb03c7a339b2421102e6ad0d4bc9c1a0e860ff29882c81d0e5819a802b3364962922594bd9a08d80cdf5521e50ea09659dac98
-  data.tar.gz: 29256e3d109bdfa651e8bea5fb82eef18fcb2b299c648db937015cebbfddd0d947e3e042b848adf32b61006f99d69150aaf38acf2a1356946c1584e2dc7a00b6
+  metadata.gz: e100a2bce4a66b7ccd1cfaebfd5e5acb3b0f9c32aafec8427efe0f8d2b613ae954d9043a8d4da536284b7739508d4b318dab5e2abe16a83113938a23fb000796
+  data.tar.gz: b2171d7d6043c5c89084a21f50a5c53bbaa0ce1e891babeb30b4beb66ede7e41e8f87e7382980bb9f9229e453121cc99bd252aa4d54c48598d01bdbc7fbdadab

data/CHANGELOG.md

@@ -10,6 +10,51 @@ 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.13.0](https://github.com/patrick204nqh/browserctl/compare/v0.12.0...v0.13.0) (2026-05-10)
+
+
+### ⚠ BREAKING CHANGES
+
+* `--output` is now a reserved global flag on every browserctl command. Existing invocations are unaffected (default mode `text` preserves prior byte-for-byte output), but commands that previously consumed `--output` as a positional or sub-flag would now collide. None ship in this gem.
+* The CLI subcommands `snapshot`, `screenshot`, and `record` are removed with no aliases. Use `page snapshot`, `page screenshot`, and `recording start|stop|status` respectively.
+* The `session` CLI commands and the `session_*` JSON-RPC wire commands are removed. Users on v0.12 sessions must regenerate state via `state save` before upgrading. The workflow DSL methods `save_session`, `load_session`, and `list_sessions` are also removed; use `save_state` / `load_state` instead.
+* `store` and `fetch` wire commands are no longer part of the Fixed zone. They move to Extension and may change between minor releases with a changelog entry. The wire shape is unchanged in v0.13; the change is to the stability promise.
+
+### Features
+
+* narrow Fixed zone — store/fetch and known overlaps ([#158](https://github.com/patrick204nqh/browserctl/issues/158)) ([067cb42](https://github.com/patrick204nqh/browserctl/commit/067cb423b5966784abc8be2395808b5e4fa92ac0))
+* noun-verb CLI consistency ([#162](https://github.com/patrick204nqh/browserctl/issues/162)) ([8ceb729](https://github.com/patrick204nqh/browserctl/commit/8ceb72998008a8e6983cb4bad13ac5f286ad9ee8))
+* remove session commands and code path ([#161](https://github.com/patrick204nqh/browserctl/issues/161)) ([12d58d9](https://github.com/patrick204nqh/browserctl/commit/12d58d9aa26b2609c98e4b34ce072a6dbb8baafe))
+* unified --output {json,text,silent} on every CLI command ([#164](https://github.com/patrick204nqh/browserctl/issues/164)) ([f8947c6](https://github.com/patrick204nqh/browserctl/commit/f8947c655bc0b1f21bbf6067a059d6ab0b7d8b9e))
+
+## [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

@@ -21,7 +21,7 @@ Every browser automation tool restarts the browser when your script ends. That m
 ```bash
 browserd &                                               # start the daemon (headless)
 browserctl page open main --url https://example.com/login
-browserctl snapshot main                                 # AI-friendly JSON snapshot with ref IDs
+browserctl page snapshot main                                 # AI-friendly JSON snapshot with ref IDs
 browserctl fill main --ref e1 --value me@example.com    # interact by ref, no selectors needed
 browserctl click main --ref e2
 browserctl daemon stop
@@ -42,7 +42,7 @@ browserd &
 browserctl page open main --url https://moatazeldebsy.github.io/test-automation-practices/#/auth
 
 # 4. Snapshot — returns JSON with a ref ID per interactable element
-browserctl snapshot main
+browserctl page snapshot main
 # → [{"ref":"e1","tag":"input","attrs":{"data-test":"username-input"}}, {"ref":"e2",...}, {"ref":"e3","tag":"button","text":"Login",...}]
 
 # 5. Interact using the ref IDs from the snapshot
@@ -52,7 +52,7 @@ browserctl click main --ref e3
 
 # 6. Observe
 browserctl url main
-browserctl snapshot main --diff   # only what changed
+browserctl page snapshot main --diff       # only what changed
 
 # Session persistence: save now, pick up later
 browserctl session save my-session
@@ -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

@@ -14,31 +14,48 @@ require "json"
 require "optimist"
 require "browserctl"
 require "browserctl/commands/cli_output"
+require "browserctl/commands/output_format"
 require "browserctl/commands/fill"
 require "browserctl/commands/click"
 require "browserctl/commands/snapshot"
 require "browserctl/commands/screenshot"
-require "browserctl/commands/record"
+require "browserctl/commands/recording"
 require "browserctl/commands/resume"
 require "browserctl/commands/init"
 require "browserctl/commands/page"
 require "browserctl/commands/cookie"
 require "browserctl/commands/storage"
-require "browserctl/commands/session"
 require "browserctl/commands/state"
 require "browserctl/commands/daemon"
 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 print_result(res)
-  if res.is_a?(Hash) && (res[:error] || res["error"])
-    warn "Error: #{res[:error] || res['error']}"
-    puts res.to_json
-    exit((res[:code] || res["code"]) == "AUTH_REQUIRED" ? 7 : 1)
+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, text_block = nil)
+  fmt = Browserctl::Commands::OutputFormat.current
+
+  unless res.is_a?(Hash) && (res[:error] || res["error"])
+    fmt.emit(res, text_block)
+    return
   end
-  puts res.to_json
+
+  message = res[:error] || res["error"]
+  code, payload = structured_stderr_payload(res, message)
+  warn "Error: #{message}"
+  warn payload
+  puts res.to_json unless fmt.silent?
+  exit Browserctl::Error::ExitCodes.for(code)
 end
 
 def usage
@@ -49,10 +66,12 @@ def usage
       init
 
     Page:
-      page open <name> [--url URL]
-      page close <name>
+      page open       <name> [--url URL]
+      page close      <name>
       page list
-      page focus <name>
+      page focus      <name>
+      page snapshot   <name> [--format elements|html] [--diff]
+      page screenshot <name> [--out PATH] [--full]
 
     Interaction (page is always first arg after verb):
       navigate <page> <url>
@@ -60,8 +79,6 @@ def usage
                <page> --ref <ref> --value <value>
       click    <page> <selector>
                <page> --ref <ref>
-      snapshot <page> [--format elements|html] [--diff]
-      screenshot <page> [--out PATH] [--full]
       evaluate <page> <expression>
       url      <page>
       wait     <page> <selector> [--timeout N]
@@ -90,14 +107,6 @@ def usage
       storage import <page> <path>
       storage delete <page> [--store local|session|all]
 
-    Session:
-      session save   <name>
-      session load   <name>
-      session list
-      session delete <name>
-      session export <name> <path>
-      session import <path>
-
     Auth detection:
       auth-check <page> [--cookies] [--state NAME] [--flow NAME]
         # Exits 7 with code: AUTH_REQUIRED when the page needs login.
@@ -113,9 +122,9 @@ def usage
       state import <source> [--name NAME]
 
     Recording:
-      record start <name>
-      record stop  [--out PATH]
-      record status
+      recording start <name>
+      recording stop  [--out PATH]
+      recording status
 
     Workflow:
       workflow run      <name|file> [--check] [--params file] [--key value ...]
@@ -129,6 +138,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
@@ -138,17 +156,40 @@ def usage
 
     Global options:
       --daemon <name>    Connect to named or auto-indexed daemon (d1, d2, work, ...)
+      --output <fmt>     Output format: json | text | silent (default: text;
+                         override with BROWSERCTL_OUTPUT)
       --version, -v
   USAGE
   exit 0
 end
 
+# Resolve --output {json,text,silent} (or BROWSERCTL_OUTPUT) once, globally,
+# before per-command parsers run. Strips the flag from ARGV in place so
+# downstream Optimist/positional parsers don't see it.
+begin
+  Browserctl::Commands::OutputFormat.install!(ARGV)
+rescue Browserctl::Commands::OutputFormat::InvalidFormat => e
+  warn "Error: #{e.message}"
+  exit 2
+end
+
 daemon_idx  = ARGV.index("--daemon")
 daemon_name = if daemon_idx
                 ARGV.delete_at(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 +197,114 @@ 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 "recording" then Browserctl::Commands::Recording.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"
+    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 "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 "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
+      print_result(res.merge(paused: name, message: opts[:message])) do
+        lines = ["Page '#{name}' paused. Browser is live — interact freely."]
+        lines << "(#{opts[:message]})" if opts[:message]
+        lines << "When done: browserctl resume #{name}"
+        lines.join("\n")
+      end
+    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]
+      print_result(res) do
+        "Opening DevTools for '#{name}':\n  #{url}"
+      end
+      opener = RUBY_PLATFORM =~ /darwin/ ? "open" : "xdg-open"
+      system(opener, url)
+    else
+      abort "unknown command: #{cmd}\nRun 'browserctl --help' for usage."
     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
+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/callable_definition.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "timeout"
+require_relative "errors"
+require_relative "secret_resolvers"
+
+module Browserctl
+  # Shared base for {Flow} and {WorkflowDefinition}. Holds the duplicated
+  # DSL surface (`desc`, `param`, `step`) and the shared execution helpers
+  # for resolving params and running step blocks with retry + timeout.
+  #
+  # Subclasses provide:
+  # - their own `call`/`run` entry point and context object;
+  # - {#callable_kind} so cross-type composition can be rejected at
+  #   definition time (e.g. a flow trying to `compose` a workflow);
+  # - {#step_failure_message} for the typed error wording.
+  #
+  # The persistence DSL (`store`/`fetch`/`save_state`/`load_state`) is
+  # mixed into `WorkflowContext` via {ContextualPersistence} and is
+  # deliberately absent from `FlowContext` — flows return state, workflows
+  # share state.
+  class CallableDefinition
+    ParamDef = Struct.new(:name, :required, :secret, :default, :secret_ref, keyword_init: true)
+    StepDef  = Struct.new(:label, :block, :retry_count, :timeout, keyword_init: true)
+
+    attr_reader :name, :description, :param_defs, :steps
+
+    def initialize(name)
+      @name        = name.to_s
+      @description = nil
+      @param_defs  = {}
+      @steps       = []
+    end
+
+    def desc(text)
+      @description = text.to_s
+    end
+
+    def param(name, required: false, secret: false, default: nil, secret_ref: nil)
+      secret = true if secret_ref
+      @param_defs[name] = ParamDef.new(
+        name: name,
+        required: required,
+        secret: secret,
+        default: default,
+        secret_ref: secret_ref
+      )
+    end
+
+    def step(label, retry_count: 0, timeout: nil, &block)
+      raise ArgumentError, "#{callable_kind} step '#{label}' requires a block" unless block
+
+      @steps << StepDef.new(label: label, block: block, retry_count: retry_count, timeout: timeout)
+    end
+
+    # Subclasses override these to specialise the base behaviour.
+
+    # @return [Symbol] :flow or :workflow — used for cross-type composition checks.
+    def callable_kind
+      raise NotImplementedError
+    end
+
+    private
+
+    def resolve_params(provided)
+      @param_defs.each_with_object({}) do |(name, defn), out|
+        val = if defn.secret_ref
+                SecretResolverRegistry.resolve(defn.secret_ref)
+              elsif provided.key?(name)
+                provided[name]
+              else
+                defn.default
+              end
+
+        raise missing_param_error(name) if defn.required && val.nil?
+
+        out[name] = val
+      end
+    end
+
+    # Override for typed error wording.
+    def missing_param_error(_name)
+      raise NotImplementedError
+    end
+
+    # Runs a step block with retry + timeout. Yields the recoverable error
+    # to the caller (via the returned exception in `:error`) so subclasses
+    # can decide how to surface a failure (raise vs StepResult).
+    def execute_step_block(ctx, defn)
+      if defn.timeout
+        ::Timeout.timeout(defn.timeout) { ctx.instance_exec(&defn.block) }
+      else
+        ctx.instance_exec(&defn.block)
+      end
+    rescue ::Timeout::Error
+      raise step_timeout_error(defn)
+    end
+
+    def with_retries(defn)
+      last_error = nil
+      (defn.retry_count + 1).times do
+        return yield
+      rescue StandardError => e
+        last_error = e
+      end
+      [:error, last_error]
+    end
+
+    # Subclasses override to raise their typed timeout error.
+    def step_timeout_error(_defn)
+      raise NotImplementedError
+    end
+  end
+end