browserctl 0.11.0 → 0.13.0

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)
@@ -283,33 +283,6 @@ module Browserctl
     # @return [Hash] `{ ok: true }` or `{ error: }`
     def dialog_dismiss(name)           = call("dialog_dismiss", name: name)
 
-    # Saves the current browser state (cookies, localStorage, open pages) to a named session.
-    # @param session_name [String] name for the saved session
-    # @return [Hash] `{ ok: true, path:, pages: N, cookies: N }` or `{ error: }`
-    def session_save(session_name, encrypt: false)
-      call("session_save", session_name: session_name, encrypt: encrypt)
-    end
-
-    # Restores a previously saved session into the running daemon.
-    # @param session_name [String] name of the session to load
-    # @return [Hash] `{ ok: true, cookies: N, pages: N, local_storage_keys: N }` or `{ error: }`
-    def session_load(session_name)
-      call("session_load", session_name: session_name)
-    end
-
-    # Lists all saved sessions.
-    # @return [Hash] `{ ok: true, sessions: [Hash] }` or `{ error: }`
-    def session_list
-      call("session_list")
-    end
-
-    # Permanently deletes a named session.
-    # @param session_name [String] name of the session to delete
-    # @return [Hash] `{ ok: true }` or `{ error: }`
-    def session_delete(session_name)
-      call("session_delete", session_name: session_name)
-    end
-
     # Saves browser state (cookies + storage) into a single .bctl bundle.
     # @return [Hash] `{ ok:, path:, origins:, cookies:, encrypted: }` or `{ error: }`
     def state_save(name, origins: nil, flow: nil, flow_version: nil, passphrase: nil)
@@ -371,10 +344,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,19 +1,37 @@
 # frozen_string_literal: true
 
+require "json"
 require_relative "../errors"
+require_relative "../error/suggested_actions"
+require_relative "output_format"
 
 module Browserctl
   module Commands
     module CliOutput
       AUTH_REQUIRED_EXIT_CODE = Browserctl::AuthRequiredError::AUTH_REQUIRED_EXIT_CODE
 
-      def print_result(res)
+      # Print the JSON-RPC daemon response, routed through the active
+      # `OutputFormat`. The historical default behaviour was `puts res.to_json`
+      # — keeping that as the `text` branch preserves byte-identical output
+      # for existing callers and golden files. `json` mode emits the same
+      # JSON explicitly. `silent` suppresses stdout entirely; errors still
+      # write the structured payload to stderr because errors are the
+      # result, not cosmetic output.
+      #
+      # `text_block` (optional) overrides the JSON dump in `text` mode for
+      # commands that have a distinct human-readable form (e.g. `init`).
+      def print_result(res, text_block = nil)
+        fmt = OutputFormat.current
+
         if res.is_a?(Hash) && (res[:error] || res["error"])
-          warn "Error: #{res[:error] || res['error']}"
-          puts res.to_json
+          message = res[:error] || res["error"]
+          warn "Error: #{message}"
+          warn structured_error_line(res, message)
+          puts res.to_json unless fmt.silent?
           exit exit_code_for(res)
         end
-        puts res.to_json
+
+        fmt.emit(res, text_block)
       end
 
       # Maps a daemon error response onto a process exit code. Defaults to 1;
@@ -23,6 +41,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/daemon.rb

@@ -3,6 +3,7 @@
 require "json"
 require "optimist"
 require_relative "cli_output"
+require_relative "output_format"
 
 module Browserctl
   module Commands
@@ -18,7 +19,8 @@ module Browserctl
           begin
             print_result(client.ping)
           rescue Browserctl::DaemonUnavailableError => e
-            puts JSON.generate({ ok: false, daemon: "offline", error: e.message })
+            payload = { ok: false, daemon: "offline", error: e.message }
+            OutputFormat.current.emit(payload)
             exit 1
           end
         when "status" then run_status(client)
@@ -36,14 +38,16 @@ module Browserctl
           url_res = client.url(name)
           { name: name, url: url_res[:url] || url_res[:error] }
         end
-        puts JSON.pretty_generate(
+        payload = {
           daemon: "online",
           pid: ping[:pid],
           protocol_version: ping[:protocol_version],
           pages: page_info
-        )
+        }
+        OutputFormat.current.emit(payload, JSON.pretty_generate(payload))
       rescue Browserctl::DaemonUnavailableError => e
-        puts JSON.pretty_generate(daemon: "offline", error: e.message)
+        payload = { daemon: "offline", error: e.message }
+        OutputFormat.current.emit(payload, JSON.pretty_generate(payload))
         exit 1
       end
 
@@ -57,7 +61,7 @@ module Browserctl
         flags += ["--name", opts[:name]] if opts[:name]
         pid = Process.spawn("browserd", *flags, out: File::NULL, err: File::NULL)
         Process.detach(pid)
-        puts "browserd started (pid #{pid})"
+        OutputFormat.current.emit({ ok: true, pid: pid }) { "browserd started (pid #{pid})" }
       end
 
       def self.run_list
@@ -74,7 +78,7 @@ module Browserctl
         rescue Browserctl::DaemonUnavailableError, RuntimeError
           nil
         end.compact
-        puts({ daemons: rows }.to_json)
+        OutputFormat.current.emit({ daemons: rows })
       end
     end
   end

data/lib/browserctl/commands/flow.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require_relative "cli_output"
+require_relative "output_format"
 require_relative "../flow_registry"
 require_relative "../runner"
 
@@ -31,22 +32,22 @@ module Browserctl
         page_proxy = page_name ? Browserctl::PageProxy.new(page_name, client) : nil
 
         result = flow.run(page: page_proxy, client: client, **params)
-        puts JSON.generate(ok: true, flow: flow.name, result: serialisable(result))
+        OutputFormat.current.emit({ ok: true, flow: flow.name, result: serialisable(result) })
       rescue Browserctl::FlowError => e
         warn "Error: #{e.message}"
-        puts JSON.generate(ok: false, code: e.code, error: e.message)
+        OutputFormat.current.emit({ ok: false, code: e.code, error: e.message }) unless OutputFormat.current.silent?
         exit 1
       end
 
       def self.run_list
         entries = Browserctl::FlowRegistry.list
-        puts JSON.generate(flows: entries)
+        OutputFormat.current.emit({ flows: entries })
       end
 
       def self.run_describe(args)
         name = args.shift or abort "usage: browserctl flow describe <name>"
         flow = resolve(name)
-        puts JSON.pretty_generate(
+        payload = {
           name: flow.name,
           desc: flow.description,
           version: flow.version_string,
@@ -56,7 +57,8 @@ module Browserctl
           steps: flow.steps.map(&:label),
           postconditions: flow.postconditions.map(&:label),
           produces_state: !flow.produces_state_block.nil?
-        )
+        }
+        OutputFormat.current.emit(payload, JSON.pretty_generate(payload))
       end
 
       def self.resolve(name_or_path)

data/lib/browserctl/commands/init.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require_relative "output_format"
 
 module Browserctl
   module Commands
@@ -14,15 +15,15 @@ module Browserctl
       YAML
 
       GITIGNORE_CONTENT = <<~GITIGNORE
-        # Cookie session exports — contain credentials, never commit
-        sessions/
+        # State bundles — contain credentials, never commit
+        state/
       GITIGNORE
 
       def self.run(_args)
         FileUtils.mkdir_p(".browserctl/workflows")
         FileUtils.touch(".browserctl/workflows/.keep")
 
-        FileUtils.mkdir_p(".browserctl/sessions")
+        FileUtils.mkdir_p(".browserctl/state")
 
         gitignore_path = ".browserctl/.gitignore"
         File.write(gitignore_path, GITIGNORE_CONTENT) unless File.exist?(gitignore_path)
@@ -30,10 +31,22 @@ module Browserctl
         config_path = ".browserctl/config.yml"
         File.write(config_path, CONFIG_TEMPLATE) unless File.exist?(config_path)
 
-        puts "Initialised browserctl project:"
-        puts "  .browserctl/workflows/   (place workflow .rb files here)"
-        puts "  .browserctl/sessions/    (cookie exports — git-ignored)"
-        puts "  .browserctl/config.yml   (project settings)"
+        payload = {
+          ok: true,
+          paths: {
+            workflows: ".browserctl/workflows",
+            state: ".browserctl/state",
+            config: ".browserctl/config.yml"
+          }
+        }
+        OutputFormat.current.emit(payload) do
+          <<~TEXT.chomp
+            Initialised browserctl project:
+              .browserctl/workflows/   (place workflow .rb files here)
+              .browserctl/state/       (state bundles — git-ignored)
+              .browserctl/config.yml   (project settings)
+          TEXT
+        end
       end
     end
   end

data/lib/browserctl/commands/migrate.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative "../migrations"
+require_relative "../errors"
+require_relative "../error/codes"
+require_relative "../error/exit_codes"
+require_relative "output_format"
+
+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 = detect_format!(path, err: err)
+        current = Browserctl::Migrations.detect_version(path, format)
+        emit_detected(format, current, path, out)
+
+        return plan_dry_run(format, current, target_version, out) if dry_run
+
+        result = Browserctl::Migrations.run(path, target_version: target_version)
+        emit_applied(format, current, result, out)
+      end
+
+      def self.detect_format!(path, err:)
+        format = Browserctl::Migrations.detect_format(path)
+        return format if format
+
+        err.puts "Error: could not detect format for #{path} (expected .bctl, .jsonl, or .rb)"
+        exit Browserctl::Error::ExitCodes::PROTOCOL_MISMATCH
+      end
+      private_class_method :detect_format!
+
+      def self.emit_detected(format, current, path, out)
+        return unless OutputFormat.current.text?
+
+        out.puts "Detected: format=#{format} version=#{current.inspect} path=#{path}"
+      end
+      private_class_method :emit_detected
+
+      def self.emit_applied(format, current, result, out)
+        fmt = OutputFormat.current
+        if fmt.json?
+          fmt.emit({ ok: true, format: format, from: result.from, to: result.to,
+                     applied: result.applied.map { |m| { from: m.from_version, to: m.to_version } } },
+                   io: out)
+          return
+        end
+        return if fmt.silent?
+
+        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
+      private_class_method :emit_applied
+
+      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)
+        emit_plan(format, current, target, chain, out)
+      end
+
+      def self.emit_plan(format, current, target, chain, out)
+        fmt = OutputFormat.current
+        if fmt.json?
+          fmt.emit(plan_payload(format, current, target, chain), io: out)
+          return
+        end
+        return if fmt.silent?
+
+        emit_plan_text(format, current, target, chain, out)
+      end
+      private_class_method :emit_plan
+
+      def self.plan_payload(format, current, target, chain)
+        {
+          format: format, from: current, to: target, dry_run: true,
+          plan: chain&.map { |m| { from: m.from_version, to: m.to_version } },
+          registered: registered_for(format)
+        }
+      end
+      private_class_method :plan_payload
+
+      def self.emit_plan_text(format, current, target, chain, out)
+        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
+      private_class_method :emit_plan_text
+
+      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

data/lib/browserctl/commands/output_format.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Browserctl
+  module Commands
+    # Resolves and applies the unified `--output {json,text,silent}` flag.
+    #
+    # Resolution order: explicit flag value -> `BROWSERCTL_OUTPUT` env var ->
+    # `text` (default).
+    #
+    # Usage from a command:
+    #
+    #   fmt = OutputFormat.from(flag, ENV)
+    #   fmt.emit(payload_hash) { "human readable text" }
+    #
+    # Per the v0.13 contract:
+    #
+    #   text   - prints the human-readable block; this is byte-identical to
+    #            today's output. For most commands the human block already IS
+    #            the JSON payload (legacy CLI shape) so the two collapse.
+    #   json   - prints the JSON payload via `to_json` (no pretty printing).
+    #   silent - prints nothing on stdout. Exit codes still carry the result.
+    #
+    # The current format is also exposed as a process-wide default
+    # (`OutputFormat.current`) so that `CliOutput#print_result` and other
+    # legacy helpers can consult it without every callsite threading the
+    # value through.
+    module OutputFormat
+      VALID = %w[json text silent].freeze
+      DEFAULT = "text"
+      ENV_VAR = "BROWSERCTL_OUTPUT"
+      FLAG = "--output"
+
+      class InvalidFormat < ArgumentError; end
+
+      class Formatter
+        attr_reader :mode
+
+        def initialize(mode)
+          @mode = mode
+        end
+
+        # Print success output for a command.
+        # `payload` is a JSON-serialisable Hash (or Array). `text_block` is
+        # either a String or a block that returns a String — only evaluated
+        # when needed.
+        def emit(payload, text_block = nil, io: $stdout)
+          case @mode
+          when "silent"
+            nil
+          when "json"
+            io.puts payload.to_json
+          else # "text"
+            text = if block_given?
+                     yield
+                   elsif text_block.respond_to?(:call)
+                     text_block.call
+                   elsif text_block.nil?
+                     payload.to_json
+                   else
+                     text_block
+                   end
+            io.puts text
+          end
+        end
+
+        def silent?
+          @mode == "silent"
+        end
+
+        def json?
+          @mode == "json"
+        end
+
+        def text?
+          @mode == "text"
+        end
+      end
+
+      module_function
+
+      # Build a Formatter from an explicit flag value (or nil) and an env hash.
+      def from(flag, env = ENV)
+        raw = flag || env[ENV_VAR] || DEFAULT
+        mode = raw.to_s.strip.downcase
+        mode = DEFAULT if mode.empty?
+        unless VALID.include?(mode)
+          raise InvalidFormat,
+                "invalid --output value '#{raw}' (expected one of: #{VALID.join(', ')})"
+        end
+        Formatter.new(mode)
+      end
+
+      # Strip `--output VALUE` (or `--output=VALUE`) from `args` in place and
+      # return the extracted value (or nil). Recognises the long form only —
+      # there is intentionally no short alias.
+      def extract!(args)
+        i = 0
+        while i < args.length
+          arg = args[i]
+          if arg == FLAG
+            args.delete_at(i)
+            value = args.delete_at(i) or
+              raise InvalidFormat, "missing value for #{FLAG}"
+            return value
+          elsif arg.is_a?(String) && arg.start_with?("#{FLAG}=")
+            value = arg.split("=", 2)[1]
+            args.delete_at(i)
+            return value
+          else
+            i += 1
+          end
+        end
+        nil
+      end
+
+      # Process-wide current format. Set once by the CLI entry point after
+      # parsing the global flag; consulted by helpers that don't otherwise
+      # have a reference to a Formatter (notably `CliOutput#print_result`).
+      def current
+        @current ||= Formatter.new(DEFAULT)
+      end
+
+      def current=(formatter)
+        @current = formatter
+      end
+
+      # Convenience: parse the flag out of `args`, build a Formatter, set it
+      # as current, and return it.
+      def install!(args, env = ENV)
+        flag = extract!(args)
+        fmt  = from(flag, env)
+        self.current = fmt
+        fmt
+      end
+
+      # Reset to default — for tests.
+      def reset!
+        @current = Formatter.new(DEFAULT)
+      end
+    end
+  end
+end

data/lib/browserctl/commands/page.rb

@@ -2,21 +2,25 @@
 
 require "optimist"
 require_relative "cli_output"
+require_relative "snapshot"
+require_relative "screenshot"
 
 module Browserctl
   module Commands
     module Page
       extend CliOutput
 
-      USAGE = "Usage: browserctl page <open|close|list|focus> [args]"
+      USAGE = "Usage: browserctl page <open|close|list|focus|snapshot|screenshot> [args]"
 
       def self.run(client, args)
         sub = args.shift or abort USAGE
         case sub
-        when "open"  then run_open(client, args)
-        when "close" then run_close(client, args)
-        when "list"  then run_list(client)
-        when "focus" then run_focus(client, args)
+        when "open"       then run_open(client, args)
+        when "close"      then run_close(client, args)
+        when "list"       then run_list(client)
+        when "focus"      then run_focus(client, args)
+        when "snapshot"   then Browserctl::Commands::Snapshot.run(client, args)
+        when "screenshot" then Browserctl::Commands::Screenshot.run(client, args)
         else abort "unknown page subcommand '#{sub}'\n#{USAGE}"
         end
       end

data/lib/browserctl/commands/{record.rb → recording.rb}

@@ -4,11 +4,12 @@ require "fileutils"
 require "json"
 require "optimist"
 require "browserctl/recording"
+require_relative "output_format"
 
 module Browserctl
   module Commands
-    class Record
-      USAGE = "Usage: browserctl record start <name> | stop [--out PATH] | status"
+    class Recording
+      USAGE = "Usage: browserctl recording start <name> | stop [--out PATH] | status"
 
       def self.run(args)
         subcmd = args.shift
@@ -17,7 +18,7 @@ module Browserctl
         when "stop"   then run_stop(args)
         when "status" then run_status
         else
-          abort "#{USAGE}\nRun 'browserctl record <subcommand> --help' for details."
+          abort "#{USAGE}\nRun 'browserctl recording <subcommand> --help' for details."
         end
       end
 
@@ -25,29 +26,29 @@ module Browserctl
         private
 
         def run_start(args)
-          Optimist.options(args) { banner "Usage: browserctl record start <name>" }
-          name = args.shift or abort "usage: browserctl record start <name>"
+          Optimist.options(args) { banner "Usage: browserctl recording start <name>" }
+          name = args.shift or abort "usage: browserctl recording start <name>"
           abort "Invalid recording name #{name.inspect} — use only letters, digits, _ or -" \
             unless name =~ /\A[a-zA-Z0-9_-]{1,64}\z/
-          Recording.start(name)
-          puts JSON.generate({ ok: true, name: name })
+          Browserctl::Recording.start(name)
+          OutputFormat.current.emit({ ok: true, name: name })
         end
 
         def run_stop(args)
           opts = Optimist.options(args) do
-            banner "Usage: browserctl record stop [--out PATH]"
+            banner "Usage: browserctl recording stop [--out PATH]"
             opt :out, "Output path for workflow file", type: :string, short: "-o"
           end
-          name = Recording.stop
+          name = Browserctl::Recording.stop
           out  = opts[:out] || File.join(".browserctl/workflows", "#{name}.rb")
           FileUtils.mkdir_p(File.dirname(out))
-          Recording.generate_workflow(name, output_path: out)
-          puts JSON.generate({ ok: true, name: name, path: out })
+          Browserctl::Recording.generate_workflow(name, output_path: out)
+          OutputFormat.current.emit({ ok: true, name: name, path: out })
         end
 
         def run_status
-          active = Recording.active
-          puts JSON.generate({ active: active })
+          active = Browserctl::Recording.active
+          OutputFormat.current.emit({ active: active })
         end
       end
     end

data/lib/browserctl/commands/resume.rb

@@ -14,7 +14,7 @@ module Browserctl
           warn "Error: #{res[:error]}"
           exit 1
         end
-        puts "Page '#{name}' resumed."
+        print_result(res.merge(resumed: name)) { "Page '#{name}' resumed." }
       end
     end
   end

data/lib/browserctl/commands/screenshot.rb

@@ -10,11 +10,11 @@ module Browserctl
 
       def self.run(client, args)
         opts = Optimist.options(args) do
-          banner "Usage: browserctl screenshot <page> [--out PATH] [--full]"
+          banner "Usage: browserctl page screenshot <name> [--out PATH] [--full]"
           opt :out,  "Output file path",   type: :string, short: "-o"
           opt :full, "Capture full page",  default: false, short: "-f"
         end
-        name = args.shift or abort "usage: browserctl screenshot <page> [--out PATH] [--full]"
+        name = args.shift or abort "usage: browserctl page screenshot <name> [--out PATH] [--full]"
         print_result(client.screenshot(name, path: opts[:out], full: opts[:full]))
       end
     end