browserctl 0.10.0 → 0.12.0

data/lib/browserctl/state.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+require_relative "constants"
+require_relative "errors"
+require_relative "version"
+require_relative "state/bundle"
+require_relative "state/transport"
+require_relative "state/transports/file"
+require_relative "state/transports/s3"
+require_relative "state/transports/one_password"
+
+module Browserctl
+  # Top-level state store: a single .bctl bundle per name under
+  # ~/.browserctl/state/<name>.bctl. Wraps the Bundle codec with on-disk
+  # naming, validation, and a small inventory API used by `state list/info`.
+  #
+  # Data shape inside a bundle:
+  #
+  #   manifest = {
+  #     name:        String,
+  #     version:     1,                       # bundle schema version
+  #     producer:    "browserctl/<gem-ver>",
+  #     created_at:  ISO-8601,
+  #     origins:     [String, ...],
+  #     flow:        String | nil,            # bound flow name, for `state rotate`
+  #     flow_version: String | nil,
+  #     expires_at:  ISO-8601 | nil,          # earliest cookie expiry
+  #     encrypted:   Boolean
+  #   }
+  #
+  #   payload = {
+  #     cookies:         [Hash, ...],
+  #     local_storage:   { origin => { key => value } },
+  #     session_storage: { origin => { key => value } }
+  #   }
+  module State
+    BASE_DIR  = File.join(BROWSERCTL_DIR, "state")
+    SAFE_NAME = /\A[a-zA-Z0-9_-]{1,64}\z/
+    EXTENSION = ".bctl"
+    MANIFEST_VERSION = 1
+
+    def self.path(name) = File.join(BASE_DIR, "#{name}#{EXTENSION}")
+    def self.exist?(name) = File.exist?(path(name))
+
+    def self.validate_name!(name)
+      return if SAFE_NAME.match?(name.to_s)
+
+      raise ArgumentError, "invalid state name #{name.inspect} — use letters, digits, _ or - (max 64 chars)"
+    end
+
+    # Persist a bundle. `payload` is { cookies:, local_storage:, session_storage: }.
+    # `manifest_extras` may carry origins (override), flow, flow_version.
+    def self.save(name, payload:, origins: nil, flow: nil, flow_version: nil, passphrase: nil) # rubocop:disable Metrics/ParameterLists
+      validate_name!(name)
+      FileUtils.mkdir_p(BASE_DIR)
+
+      manifest = build_manifest(
+        name: name,
+        origins: origins || derive_origins(payload),
+        flow: flow,
+        flow_version: flow_version,
+        cookies: payload[:cookies] || payload["cookies"] || [],
+        encrypted: !passphrase.nil?
+      )
+
+      blob = Bundle.encode(manifest: manifest, payload: payload, passphrase: passphrase)
+      File.open(path(name), "wb", 0o600) { |f| f.write(blob) }
+      manifest
+    end
+
+    # Load and decode a bundle. Returns { manifest:, payload:, encrypted: }.
+    def self.load(name, passphrase: nil)
+      validate_name!(name)
+      raise Browserctl::Error, "state '#{name}' not found" unless exist?(name)
+
+      Bundle.decode(File.binread(path(name)), passphrase: passphrase)
+    end
+
+    def self.delete(name)
+      validate_name!(name)
+      FileUtils.rm_f(path(name))
+    end
+
+    # Copies the on-disk .bctl bundle to a transport-addressable destination
+    # (file path, s3://bucket/key, op://Vault/Item, or any registered scheme).
+    # Bundle bytes are written verbatim — no re-encoding — so the receiving
+    # side can verify the manifest/payload exactly as produced.
+    def self.export(name, destination)
+      validate_name!(name)
+      raise Browserctl::Error, "state '#{name}' not found" unless exist?(name)
+
+      transport, parsed = Transport.for(destination)
+      blob = ::File.binread(path(name))
+      transport.write(parsed, blob)
+      { name: name, destination: destination, bytes: blob.bytesize }
+    end
+
+    # Pulls a bundle from a transport-addressable source and stores it as a
+    # local state. Validates the magic header before persisting so we never
+    # leave a corrupt bundle in the state directory. `name` defaults to the
+    # source's basename without `.bctl`.
+    def self.import(source, name: nil)
+      transport, parsed = Transport.for(source)
+      blob = transport.read(parsed)
+      raise Bundle::BundleError, "imported blob is not a .bctl bundle" unless blob.start_with?(Bundle::MAGIC)
+
+      manifest = Bundle.peek_manifest(blob)
+      target_name = name || derive_name(source) || manifest[:name]
+      validate_name!(target_name)
+
+      FileUtils.mkdir_p(BASE_DIR)
+      ::File.open(path(target_name), "wb", 0o600) { |f| f.write(blob) }
+      { name: target_name, source: source, bytes: blob.bytesize, encrypted: manifest[:encrypted] }
+    end
+
+    def self.derive_name(uri)
+      base = ::File.basename(uri.to_s.split("?").first.to_s, EXTENSION)
+      return nil if base.empty?
+
+      base
+    end
+    private_class_method :derive_name
+
+    # Read manifests for all stored bundles. Errors on a single file are
+    # surfaced via { error: "...", path: "..." } rather than aborting the list.
+    def self.all
+      return [] unless Dir.exist?(BASE_DIR)
+
+      Dir[File.join(BASE_DIR, "*#{EXTENSION}")].map do |file|
+        info_for(file)
+      end
+    end
+
+    # Inspect a single bundle without decrypting the payload.
+    def self.info(name)
+      validate_name!(name)
+      raise Browserctl::Error, "state '#{name}' not found" unless exist?(name)
+
+      info_for(path(name))
+    end
+
+    def self.info_for(file)
+      blob     = File.binread(file)
+      manifest = Bundle.peek_manifest(blob)
+      manifest.merge(
+        path: file,
+        size: blob.bytesize
+      )
+    rescue Bundle::BundleError => e
+      { name: File.basename(file, EXTENSION), path: file, error: e.message }
+    end
+    private_class_method :info_for
+
+    def self.build_manifest(name:, origins:, flow:, flow_version:, cookies:, encrypted:) # rubocop:disable Metrics/ParameterLists
+      {
+        name: name,
+        version: MANIFEST_VERSION,
+        producer: "browserctl/#{Browserctl::VERSION}",
+        created_at: Time.now.utc.iso8601,
+        origins: Array(origins).compact.uniq,
+        flow: flow,
+        flow_version: flow_version,
+        expires_at: earliest_expiry(cookies),
+        encrypted: encrypted
+      }
+    end
+    private_class_method :build_manifest
+
+    # Origins captured from the payload itself when not overridden. Pulls from
+    # cookie domains and storage keys to cover both navigation-tracked and
+    # cookie-only auth.
+    def self.derive_origins(payload)
+      cookies = fetch_either(payload, :cookies, "cookies", default: [])
+      ls      = fetch_either(payload, :local_storage, "local_storage", default: {})
+      ss      = fetch_either(payload, :session_storage, "session_storage", default: {})
+
+      (origins_from_cookies(cookies) + ls.keys.map(&:to_s) + ss.keys.map(&:to_s)).uniq
+    end
+    private_class_method :derive_origins
+
+    def self.origins_from_cookies(cookies)
+      cookies.filter_map do |c|
+        domain = (c[:domain] || c["domain"]).to_s
+        next if domain.empty?
+
+        domain.start_with?(".") ? "https://#{domain[1..]}" : "https://#{domain}"
+      end
+    end
+    private_class_method :origins_from_cookies
+
+    def self.fetch_either(hash, sym_key, str_key, default:)
+      hash[sym_key] || hash[str_key] || default
+    end
+    private_class_method :fetch_either
+
+    def self.earliest_expiry(cookies)
+      times = cookies.filter_map do |c|
+        v = c[:expires] || c["expires"] || c[:expiresAt] || c["expiresAt"]
+        v&.to_f&.positive? ? Time.at(v.to_f).utc.iso8601 : nil
+      end
+      times.min
+    end
+    private_class_method :earliest_expiry
+  end
+end

data/lib/browserctl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Browserctl
-  VERSION = "0.10.0"
+  VERSION = "0.12.0"
 end

data/lib/browserctl/workflow/flow_wrapper.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../constants"
+
+module Browserctl
+  module Workflow
+    # Renders a `Browserctl.flow` definition that wraps a promoted workflow.
+    # The flow becomes a globally-registered, parameterised handle that runs
+    # the underlying workflow via `Runner#run_workflow`. Params are inferred
+    # from the workflow's `param_defs` so callers see the same surface area
+    # they would on the workflow itself.
+    #
+    # Wrapping (rather than translating step-by-step) keeps the workflow as
+    # the single source of truth: edits to the workflow file flow through
+    # to the wrapper without regeneration.
+    module FlowWrapper
+      module_function
+
+      def target_dir
+        File.join(Browserctl::BROWSERCTL_DIR, "flows")
+      end
+
+      def target_path(name)
+        File.join(target_dir, "#{name}.rb")
+      end
+
+      # @param defn [Browserctl::WorkflowDefinition]
+      # @return [String] Ruby source for a flow file
+      def render(defn)
+        params = defn.param_defs.values.map { |p| render_param(p) }.join("\n")
+        desc   = defn.description || "Promoted from workflow '#{defn.name}'"
+        <<~RUBY
+          # frozen_string_literal: true
+
+          require "browserctl/flow"
+          require "browserctl/runner"
+
+          # Auto-generated flow wrapper for workflow '#{defn.name}'.
+          # Edit the underlying workflow file rather than this wrapper.
+          Browserctl.flow(#{defn.name.inspect}) do
+            version "1.0.0"
+            requires_browserctl "0.11.0"
+            desc #{desc.inspect}
+
+          #{params.gsub(/^/, '  ') unless params.empty?}
+
+            step("run workflow #{defn.name}") do
+              Browserctl::Runner.new.run_workflow(#{defn.name.inspect}, **params)
+            end
+          end
+        RUBY
+      end
+
+      # @param defn [Browserctl::WorkflowDefinition]
+      # @param overwrite [Boolean]
+      # @param dir [String, nil] override target dir (testing)
+      # @return [String] path written
+      def write(defn, overwrite: true, dir: nil)
+        path = dir ? File.join(dir, "#{defn.name}.rb") : target_path(defn.name)
+        if File.exist?(path) && !overwrite
+          raise Browserctl::WorkflowError, "flow wrapper already exists at #{path} (pass overwrite: true to replace)"
+        end
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, render(defn))
+        path
+      end
+
+      def render_param(param)
+        opts = []
+        opts << "required: true" if param.required
+        opts << "secret: true"   if param.secret && !param.secret_ref
+        opts << "secret_ref: #{param.secret_ref.inspect}" if param.secret_ref
+        opts << "default: #{param.default.inspect}" unless param.default.nil?
+        suffix = opts.empty? ? "" : ", #{opts.join(', ')}"
+        "param :#{param.name}#{suffix}"
+      end
+    end
+  end
+end

data/lib/browserctl/workflow/promoter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../constants"
+require_relative "promotion_ledger"
+require_relative "flow_wrapper"
+
+module Browserctl
+  module Workflow
+    # Promotes a workflow file from the project-local `.browserctl/workflows/`
+    # directory to the user-global `~/.browserctl/workflows/` directory, where
+    # it is invocable from any project.
+    #
+    # Promotion is gated by `PromotionLedger.clean_streak`: a workflow must
+    # have at least `threshold` consecutive clean `--check` runs before it
+    # can be promoted. `--force` overrides the gate.
+    module Promoter
+      class IneligibleError < StandardError
+        attr_reader :streak, :threshold
+
+        def initialize(workflow:, streak:, threshold:)
+          @streak = streak
+          @threshold = threshold
+          super(
+            "workflow '#{workflow}' has #{streak} clean --check run(s); " \
+            "needs #{threshold}. Run `browserctl workflow run #{workflow} --check` " \
+            "until clean, or pass --force to override."
+          )
+        end
+      end
+
+      class NotFoundError < StandardError; end
+
+      module_function
+
+      DEFAULT_SOURCE_DIR = ".browserctl/workflows"
+
+      def target_dir
+        File.join(Browserctl::BROWSERCTL_DIR, "workflows")
+      end
+
+      def source_path(workflow, source_dir: DEFAULT_SOURCE_DIR)
+        File.join(source_dir, "#{workflow}.rb")
+      end
+
+      def target_path(workflow)
+        File.join(target_dir, "#{workflow}.rb")
+      end
+
+      # @param workflow [String]
+      # @param force [Boolean]
+      # @param threshold [Integer]
+      # @param source_dir [String] override the source directory (testing)
+      # @param ledger_path [String] override the ledger path (testing)
+      # @return [Hash] `{ workflow:, source:, target:, streak:, threshold:, forced: }`
+      def promote(workflow:, force: false, threshold: PromotionLedger::DEFAULT_THRESHOLD, # rubocop:disable Metrics/ParameterLists
+                  as_flow: false, source_dir: DEFAULT_SOURCE_DIR,
+                  ledger_path: PromotionLedger.ledger_path, flow_dir: nil)
+        src = source_path(workflow, source_dir: source_dir)
+        raise NotFoundError, "workflow file not found: #{src}" unless File.exist?(src)
+
+        streak = PromotionLedger.clean_streak(workflow: workflow, path: ledger_path)
+        unless force || streak >= threshold
+          raise IneligibleError.new(workflow: workflow, streak: streak, threshold: threshold)
+        end
+
+        dst = target_path(workflow)
+        FileUtils.mkdir_p(File.dirname(dst))
+        FileUtils.cp(src, dst)
+
+        result = {
+          workflow: workflow,
+          source: src,
+          target: dst,
+          streak: streak,
+          threshold: threshold,
+          forced: force && streak < threshold
+        }
+
+        result[:flow] = wrap_as_flow(workflow, dst, flow_dir) if as_flow
+        result
+      end
+
+      # Loads the just-promoted workflow file, infers params from its
+      # WorkflowDefinition, and writes a flow wrapper at `flow_dir`
+      # (defaults to `~/.browserctl/flows/<name>.rb`).
+      def wrap_as_flow(workflow, workflow_path, flow_dir)
+        load workflow_path
+        defn = Browserctl.lookup_workflow(workflow.to_s) or
+          raise NotFoundError, "workflow '#{workflow}' did not register after load"
+
+        FlowWrapper.write(defn, overwrite: true, dir: flow_dir)
+      end
+    end
+  end
+end

data/lib/browserctl/workflow/promotion_ledger.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "time"
+require_relative "../constants"
+
+module Browserctl
+  module Workflow
+    # Append-only JSONL ledger of `workflow run --check` outcomes per workflow.
+    # Used as the gate for `workflow promote`: only workflows with a sufficient
+    # streak of clean runs are eligible for promotion to `~/.browserctl/workflows/`.
+    #
+    # Record schema (one JSONL line):
+    #   { "ts": "2026-05-10T12:00:00Z", "workflow": "name", "verdict": "clean" }
+    module PromotionLedger
+      LEDGER_BASENAME = "check_ledger.jsonl"
+      DEFAULT_THRESHOLD = 3
+      VALID_VERDICTS = %i[clean drift fail].freeze
+
+      module_function
+
+      def ledger_path
+        File.join(Browserctl::BROWSERCTL_DIR, LEDGER_BASENAME)
+      end
+
+      # Append a verdict for a workflow run.
+      # @param workflow [String]
+      # @param verdict [Symbol] :clean, :drift, or :fail
+      # @param path [String] override (testing)
+      def record(workflow:, verdict:, path: ledger_path, at: Time.now.utc)
+        return unless VALID_VERDICTS.include?(verdict)
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.open(path, "a") do |f|
+          f.puts JSON.generate(
+            ts: at.iso8601,
+            workflow: workflow.to_s,
+            verdict: verdict.to_s
+          )
+        end
+      end
+
+      # Count the trailing streak of :clean verdicts for a workflow.
+      # A non-clean verdict resets the streak. Drift and fail both break it
+      # — the gate is intentionally strict; users can override with --force.
+      # @return [Integer]
+      def clean_streak(workflow:, path: ledger_path)
+        return 0 unless File.exist?(path)
+
+        streak = 0
+        File.foreach(path) do |line|
+          entry = parse(line) or next
+          next unless entry["workflow"] == workflow.to_s
+
+          if entry["verdict"] == "clean"
+            streak += 1
+          else
+            streak = 0
+          end
+        end
+        streak
+      end
+
+      def parse(line)
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end