browserctl 0.10.0 → 0.12.0

data/lib/browserctl/commands/flow.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "cli_output"
+require_relative "../flow_registry"
+require_relative "../runner"
+
+module Browserctl
+  module Commands
+    module Flow
+      extend CliOutput
+
+      USAGE = "Usage: browserctl flow <run|list|describe> [args]"
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+        case sub
+        when "run"      then run_flow(client, args)
+        when "list"     then run_list
+        when "describe" then run_describe(args)
+        else abort "unknown flow subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_flow(client, args)
+        name = args.shift or
+          abort "usage: browserctl flow run <name|file> [--page NAME] [--params FILE] [--key value ...]"
+
+        flow = resolve(name)
+        page_name, params = parse_run_args(args)
+        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))
+      rescue Browserctl::FlowError => e
+        warn "Error: #{e.message}"
+        puts JSON.generate(ok: false, code: e.code, error: e.message)
+        exit 1
+      end
+
+      def self.run_list
+        entries = Browserctl::FlowRegistry.list
+        puts JSON.generate(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(
+          name: flow.name,
+          desc: flow.description,
+          version: flow.version_string,
+          requires_browserctl: flow.min_browserctl_version,
+          params: format_params(flow),
+          preconditions: flow.preconditions.map(&:label),
+          steps: flow.steps.map(&:label),
+          postconditions: flow.postconditions.map(&:label),
+          produces_state: !flow.produces_state_block.nil?
+        )
+      end
+
+      def self.resolve(name_or_path)
+        if File.exist?(name_or_path)
+          before = Browserctl.flow_registry_snapshot.keys
+          load File.expand_path(name_or_path)
+          new_name = (Browserctl.flow_registry_snapshot.keys - before).first
+          new_name ||= File.basename(name_or_path, ".rb")
+          flow = Browserctl.lookup_flow(new_name)
+        else
+          flow = Browserctl::FlowRegistry.resolve(name_or_path)
+        end
+        flow or abort "flow '#{name_or_path}' not found"
+      end
+
+      def self.parse_run_args(args)
+        page_name = take_option(args, "--page")
+        params_path = take_option(args, "--params")
+        file_params = params_path ? load_params_file(params_path) : {}
+        cli_params = pair_args(args)
+        [page_name, file_params.merge(cli_params)]
+      end
+
+      def self.take_option(args, flag)
+        idx = args.index(flag)
+        return nil unless idx
+
+        value = args.delete_at(idx + 1)
+        args.delete_at(idx)
+        value
+      end
+
+      def self.load_params_file(path)
+        Browserctl::Runner.load_params_file(path)
+      rescue StandardError => e
+        abort "Error loading params file: #{e.message}"
+      end
+
+      def self.pair_args(args)
+        out = {}
+        args.each_slice(2) do |flag, val|
+          out[flag.sub(/\A--/, "").to_sym] = val
+        end
+        out
+      end
+
+      def self.format_params(flow)
+        flow.param_defs.transform_values do |p|
+          entry = { required: p.required, secret: p.secret, default: p.default }
+          entry[:secret_ref] = p.secret_ref if p.secret_ref
+          entry
+        end
+      end
+
+      def self.serialisable(value)
+        case value
+        when nil, true, false, Numeric, String, Hash, Array then value
+        when Symbol then value.to_s
+        else value.respond_to?(:to_h) ? value.to_h : value.to_s
+        end
+      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

data/lib/browserctl/commands/state.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "io/console"
+require "json"
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    # `browserctl state` — top-level command for portable, encrypted, origin-
+    # scoped browser state. Wraps the daemon's state_* RPCs.
+    module State
+      extend CliOutput
+
+      USAGE = "Usage: browserctl state <save|load|list|info|delete|rotate|export|import> [args]"
+
+      DAEMON_SUBCOMMANDS = {
+        "save" => :run_save, "load" => :run_load, "list" => :run_list,
+        "info" => :run_info, "delete" => :run_delete, "rotate" => :run_rotate
+      }.freeze
+
+      LOCAL_SUBCOMMANDS = { "export" => :run_export, "import" => :run_import }.freeze
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+
+        if (m = DAEMON_SUBCOMMANDS[sub])
+          sub == "list" ? send(m, client) : send(m, client, args)
+        elsif (m = LOCAL_SUBCOMMANDS[sub])
+          send(m, args)
+        else
+          abort "unknown state subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_save(client, args)
+        encrypt = args.delete("--encrypt")
+        origins = extract_value!(args, "--origins")
+        flow    = extract_value!(args, "--flow")
+        name    = args.shift or abort "usage: browserctl state save <name> [--encrypt] " \
+                                      "[--origins a,b] [--flow NAME]"
+
+        passphrase = encrypt ? prompt_passphrase(confirm: true) : nil
+        origin_list = parse_origins(origins)
+
+        print_result(client.state_save(name, origins: origin_list, flow: flow, passphrase: passphrase))
+      end
+
+      def self.parse_origins(value)
+        return nil unless value
+
+        value.split(",").map(&:strip).reject(&:empty?)
+      end
+
+      def self.run_load(client, args)
+        name = args.shift or abort "usage: browserctl state load <name>"
+        passphrase = state_needs_passphrase?(client, name) ? prompt_passphrase : nil
+        print_result(client.state_load(name, passphrase: passphrase))
+      end
+
+      def self.run_list(client)
+        print_result(client.state_list)
+      end
+
+      def self.run_info(client, args)
+        name = args.shift or abort "usage: browserctl state info <name>"
+        print_result(client.state_info(name))
+      end
+
+      def self.run_delete(client, args)
+        name = args.shift or abort "usage: browserctl state delete <name>"
+        print_result(client.state_delete(name))
+      end
+
+      # Re-runs the flow bound to <name> and re-saves the bundle. The flow is
+      # read from the manifest (set when the bundle was originally produced
+      # via `state save --flow ...`). Params come from --params or k=v pairs.
+      def self.run_rotate(client, args)
+        require "browserctl/flow_registry"
+        page_name   = extract_value!(args, "--page")
+        params_path = extract_value!(args, "--params")
+        name        = args.shift or abort "usage: browserctl state rotate <name> " \
+                                          "[--page NAME] [--params FILE] [--key value ...]"
+
+        manifest = read_manifest!(client, name)
+        flow     = resolve_bound_flow!(manifest)
+        params   = build_rotate_params(params_path, args)
+        page_proxy = page_name ? Browserctl::PageProxy.new(page_name, client) : nil
+
+        flow.run(page: page_proxy, client: client, **params)
+
+        save_result = client.state_save(name,
+                                        flow: flow.name,
+                                        flow_version: flow.version_string,
+                                        origins: manifest[:origins])
+        print_result(save_result.merge(rotated_flow: flow.name))
+      rescue Browserctl::FlowError => e
+        warn "Error: #{e.message}"
+        exit 1
+      end
+
+      def self.read_manifest!(client, name)
+        info = client.state_info(name)
+        abort "Error: #{info[:error] || info['error']}" if info[:error] || info["error"]
+
+        info[:info] || info["info"] || {}
+      end
+      private_class_method :read_manifest!
+
+      def self.resolve_bound_flow!(manifest)
+        flow_name = manifest[:flow] || manifest["flow"]
+        abort "Error: state has no bound flow — re-save with `state save --flow NAME` first" if flow_name.nil? ||
+                                                                                                flow_name.to_s.empty?
+
+        flow = Browserctl::FlowRegistry.resolve(flow_name)
+        abort "Error: flow '#{flow_name}' not found in registry" unless flow
+
+        flow
+      end
+      private_class_method :resolve_bound_flow!
+
+      def self.build_rotate_params(params_path, args)
+        require "browserctl/runner"
+        file_params = params_path ? Browserctl::Runner.load_params_file(params_path) : {}
+        cli_params  = args.each_slice(2).to_h { |flag, val| [flag.to_s.sub(/\A--/, "").to_sym, val] }
+        file_params.merge(cli_params)
+      end
+      private_class_method :build_rotate_params
+
+      def self.run_export(args)
+        name        = args.shift or abort "usage: browserctl state export <name> <destination>"
+        destination = args.shift or abort "usage: browserctl state export <name> <destination>"
+        require "browserctl/state"
+        result = Browserctl::State.export(name, destination)
+        puts result.to_json
+      rescue Browserctl::State::Transport::TransportError, Browserctl::Error, ArgumentError => e
+        warn "Error: #{e.message}"
+        exit 1
+      end
+
+      def self.run_import(args)
+        name_override = extract_value!(args, "--name")
+        source        = args.shift or abort "usage: browserctl state import <source> [--name NAME]"
+        require "browserctl/state"
+        result = Browserctl::State.import(source, name: name_override)
+        puts result.to_json
+      rescue Browserctl::State::Transport::TransportError,
+             Browserctl::State::Bundle::BundleError,
+             Browserctl::Error, ArgumentError => e
+        warn "Error: #{e.message}"
+        exit 1
+      end
+
+      private_class_method :parse_origins
+
+      def self.extract_value!(args, flag)
+        idx = args.index(flag)
+        return nil unless idx
+
+        args.delete_at(idx)
+        args.delete_at(idx) or abort "missing value for #{flag}"
+      end
+      private_class_method :extract_value!
+
+      def self.prompt_passphrase(confirm: false)
+        return ENV["BROWSERCTL_STATE_PASSPHRASE"] if ENV["BROWSERCTL_STATE_PASSPHRASE"]
+
+        $stderr.print "Passphrase: "
+        pass = $stdin.noecho(&:gets).to_s.chomp
+        $stderr.puts
+
+        if confirm
+          $stderr.print "Confirm passphrase: "
+          confirm_pass = $stdin.noecho(&:gets).to_s.chomp
+          $stderr.puts
+          abort "Passphrases do not match." unless pass == confirm_pass
+        end
+
+        pass
+      end
+      private_class_method :prompt_passphrase
+
+      # Peek at the manifest first so we only prompt for a passphrase when needed.
+      def self.state_needs_passphrase?(client, name)
+        info = client.state_info(name)
+        return false if info[:error] || info["error"]
+
+        manifest = info[:info] || info["info"] || {}
+        manifest[:encrypted] || manifest["encrypted"] || false
+      end
+      private_class_method :state_needs_passphrase?
+    end
+  end
+end

data/lib/browserctl/commands/trace.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "../logger"
+require_relative "../redactor"
+require_relative "../secret_resolver_registry"
+
+module Browserctl
+  module Commands
+    # `browserctl trace [<session>] [--no-redact]` — pretty timeline of
+    # structured log events across cli.log + daemon.log. Defaults to most
+    # recent session.
+    #
+    # Loose categorisation by inspecting common keys (event/snapshot/request/
+    # error). No schema is enforced — this command is tolerant of any JSONL
+    # produced by Browserctl::JsonlFormatter.
+    #
+    # Redaction: ON by default. Secret values are sourced from current ENV
+    # patterns (`*_TOKEN`, `*_KEY`, `*_SECRET`, `*_PASSWORD`) and any values
+    # captured by `SecretResolverRegistry` during this process. Pass
+    # `--no-redact` to disable (local debugging only). Note: when replaying
+    # historical traces from a previous process, registry-captured values are
+    # gone — only current ENV patterns apply.
+    module Trace
+      USAGE = "Usage: browserctl trace [<session>] [--no-redact]"
+      NO_REDACT_WARNING = "[browserctl] traces include unredacted secret values; " \
+                          "do not paste this output publicly."
+
+      LEVEL_COLORS = {
+        "DEBUG" => "\e[2;37m", # dim grey
+        "INFO" => "\e[36m",    # cyan
+        "WARN" => "\e[33m",    # yellow
+        "ERROR" => "\e[31m" # red
+      }.freeze
+      RESET = "\e[0m"
+
+      CATEGORY_ICONS = {
+        error: "!",
+        snapshot: "S",
+        network: "N",
+        event: "."
+      }.freeze
+
+      OMIT_KEYS = %w[ts level component event msg].freeze
+
+      def self.run(args, log_dir: Browserctl.log_dir, out: $stdout, err: $stderr)
+        abort USAGE if args.include?("-h") || args.include?("--help")
+        args = args.dup
+        redact = !args.delete("--no-redact")
+        session_filter = args.shift
+
+        if redact
+          redactor = build_redactor
+        else
+          redactor = nil
+          warn_no_redact(err)
+        end
+
+        records = load_records(log_dir)
+        if records.empty?
+          out.puts "No log entries found in #{log_dir}"
+          return
+        end
+
+        records = filter_session(records, session_filter)
+        if records.empty?
+          out.puts "No entries match session=#{session_filter}"
+          return
+        end
+
+        render(records, out: out, redactor: redactor)
+      end
+
+      def self.build_redactor
+        extra = if defined?(Browserctl::SecretResolverRegistry)
+                  Browserctl::SecretResolverRegistry.resolved_values
+                else
+                  []
+                end
+        Browserctl::Redactor.from_env(extra: extra)
+      rescue StandardError
+        Browserctl::Redactor.new(secrets: [])
+      end
+
+      def self.warn_no_redact(err)
+        err&.puts NO_REDACT_WARNING
+      end
+
+      def self.load_records(log_dir)
+        paths = Dir.glob(File.join(log_dir, "{cli,daemon}.log"))
+        records = paths.flat_map do |path|
+          File.foreach(path).filter_map { |line| parse_line(line) }
+        end
+        records.sort_by { |r| r["ts"].to_s }
+      end
+
+      def self.parse_line(line)
+        line = line.strip
+        return nil if line.empty?
+
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Session resolution. When session_id is stamped on records (future PR),
+      # filter/select by it. Otherwise, treat the entire merged stream as one
+      # session — caller can scope by tailing/rotating logs.
+      # TODO: stamp session_id on every log line so this scopes correctly.
+      def self.filter_session(records, session_filter)
+        if session_filter
+          records.select { |r| r["session_id"].to_s == session_filter }
+        else
+          ids = records.map { |r| r["session_id"] }.compact.uniq
+          if ids.empty?
+            records
+          else
+            recent = ids.last
+            records.select { |r| r["session_id"] == recent }
+          end
+        end
+      end
+
+      def self.render(records, out:, redactor: nil)
+        tty = out.respond_to?(:tty?) && out.tty?
+        records.each { |r| out.puts(format_line(r, tty: tty, redactor: redactor)) }
+      end
+
+      def self.format_line(record, tty:, redactor: nil)
+        level = (record["level"] || "INFO").to_s
+        line  = format("%-12<ts>s %<icon>s %-5<level>s %-7<comp>s %-22<label>s %<ctx>s",
+                       ts: format_ts(record["ts"]),
+                       icon: CATEGORY_ICONS.fetch(categorise(record), "."),
+                       level: level,
+                       comp: (record["component"] || "?").to_s,
+                       label: event_label(record),
+                       ctx: context_snippet(record)).rstrip
+
+        line = redactor.redact(line) if redactor
+        tty ? colourise(line, level) : line
+      end
+
+      def self.format_ts(timestamp)
+        Time.iso8601(timestamp.to_s).strftime("%H:%M:%S.%L")
+      rescue ArgumentError, TypeError
+        "??:??:??.???"
+      end
+
+      def self.categorise(record)
+        return :error    if record["level"] == "ERROR" || record["error"]
+        return :snapshot if record["snapshot"]
+        return :network  if record["request"] || record["response"] || record["url"]
+
+        :event
+      end
+
+      def self.event_label(record)
+        (record["event"] || record["snapshot"] || record["request"] ||
+          record["msg"] || "-").to_s.slice(0, 22)
+      end
+
+      # Compact "k=v k=v" snippet of remaining structured keys, capped to keep
+      # the timeline scannable. Skips fields already shown in fixed columns.
+      def self.context_snippet(record)
+        pairs = record.except(*OMIT_KEYS)
+        return "" if pairs.empty?
+
+        pairs.map { |k, v| "#{k}=#{format_value(v)}" }.join(" ").slice(0, 120)
+      end
+
+      def self.format_value(value)
+        case value
+        when String  then value.length > 40 ? "#{value[0, 37]}..." : value
+        when Array   then "[#{value.length}]"
+        when Hash    then "{#{value.keys.length}}"
+        else value.to_s
+        end
+      end
+
+      def self.colourise(line, level)
+        colour = LEVEL_COLORS[level] || ""
+        "#{colour}#{line}#{RESET}"
+      end
+    end
+  end
+end