portage-cli 0.7.4 → 0.8.0

data/lib/portage/cli.rb

@@ -1,18 +1,27 @@
 require "optparse"
 require "json"
+require "uri"
 
 require_relative "cli/version"
 require_relative "cli/user_agent"
 require_relative "cli/shipping_profile"
 require_relative "cli/buyer_context"
 require_relative "cli/catalog_products"
+require_relative "cli/agent_profile_url"
+require_relative "cli/offer_sources"
+require_relative "cli/index"
+require_relative "cli/browser_import"
+require_relative "cli/browser_profile"
 require_relative "cli/buy"
 require_relative "cli/find"
 require_relative "cli/compare"
 require_relative "cli/history"
 require_relative "cli/payment_methods"
 require_relative "cli/proxy_settings"
+require_relative "cli/handoff_only"
+require_relative "cli/handoff_target"
 require_relative "cli/doctor"
+require_relative "cli/setup_wizard"
 require_relative "cli/handoff_reconciler"
 require_relative "cli/handoff_waiter"
 require_relative "cli/reconcile_notifier"
@@ -30,6 +39,7 @@ module Portage
       usage: portage buy <url> --query "..." [--qty N] [--payment-token TOKEN]
                                 [--product-id ID] [--yes] [--dry-run]
                                 [--auto-open|--no-auto-open] [--notify-webhook URL]
+                                [--handoff-target default|print|profile|agent:NAME]
                                 [--decision-backend jev|laya] [--min-confidence N] [--json]
                                 [--wait [--wait-timeout DURATION|off]]
              portage buy --query "..." [--store URL] [--max-price N] [--limit N] ...
@@ -51,9 +61,20 @@ module Portage
                                  [--velocity-count N --velocity-window-seconds N]
                                  [--allow HOST ...] [--clear-allowlist]
              portage orders reconcile [--checkout ID] [--json]
+             portage index build [--sources a,b] [--queries FILE] [--dry-run] [--export DIR] [--json]
+             portage index refresh [--sources a,b] [--queries FILE] [--dry-run] [--export DIR] [--json]
+             portage index show [--stores|--products] [--json]
+             portage index add <url> [--json]
+             portage index remove <host> [--json]
+             portage index sources [--json]
+             portage browser import [--browser chrome|edge|brave|arc|firefox|safari] [--profile-root DIR]
+                                    [--history-days 90] [--include-product-pages] [--max-probes 200]
+                                    [--exclude HOST,HOST] [--dry-run] [--yes] [--json]
+             portage browser profile init|open|status [--browser chrome|edge|brave|arc] [--port N]
+                                    [--url URL (open only)] [--json]
              portage doctor [--require FILE] [--adapter CLASS_NAME] [--json]
              portage configure [--require FILE] [--adapter CLASS_NAME] [--json]  (alias for doctor)
-             portage setup [--require FILE] [--adapter CLASS_NAME] [--json]      (alias for doctor)
+             portage setup [--json]  (interactive wizard on a TTY; --json/no TTY: today's doctor report)
              portage generate adapter NAME [--dir DIR]
              portage generate agent-profile [--out FILE] [--key-out FILE] [--rotate]
              portage --version
@@ -66,8 +87,9 @@ module Portage
 
     COMMANDS = { "buy" => :run_buy, "find" => :run_find, "compare" => :run_compare,
                  "history" => :run_history, "payment" => :run_payment, "policy" => :run_policy,
-                 "orders" => :run_orders, "doctor" => :run_doctor, "configure" => :run_doctor,
-                 "setup" => :run_doctor, "generate" => :run_generate }.freeze
+                 "orders" => :run_orders, "index" => :run_index, "browser" => :run_browser,
+                 "doctor" => :run_doctor,
+                 "configure" => :run_doctor, "setup" => :run_setup, "generate" => :run_generate }.freeze
 
     VERSION_FLAGS = %w[--version -v version].freeze
 
@@ -220,12 +242,27 @@ module Portage
       url = parsed[:buy][:url] || parsed[:store]
       parsed[:confidence_check] = confidence_check(parsed, url)
       return 1 unless parsed[:confidence_check]
+
+      parsed[:handoff_target] = handoff_target(parsed, url)
+      return 1 unless parsed[:handoff_target]
       return execute_buy(parsed, url) if url
 
       buy_from_search(parsed)
     end
     private_class_method :run_buy
 
+    # Built and validated up front, same posture as #confidence_check — an
+    # unknown --handoff-target/PORTAGE_HANDOFF_TARGET/config.json value is a
+    # usage error, reported before a checkout is ever attempted rather than
+    # discovered mid hand-off (docs/plans/buy-skill-and-local-browser.md
+    # Phase 5).
+    def self.handoff_target(parsed, url)
+      HandoffTarget.new(override: parsed[:buy][:handoff_target])
+    rescue ArgumentError => e
+      invalid_buy_option(e.message, url: url, json: parsed[:json])
+    end
+    private_class_method :handoff_target
+
     # `portage buy` with no URL: search first, then buy from the store the
     # caller picks. `--yes` alone deliberately isn't enough to get here —
     # without a URL the merchant would have been chosen by a search ranker
@@ -260,8 +297,10 @@ module Portage
     private_class_method :prompt_for_offer
 
     def self.execute_buy(parsed, url, product_id: nil)
-      options = parsed[:buy].merge(url: url, confidence_check: parsed[:confidence_check])
+      options = parsed[:buy].merge(url: url, confidence_check: parsed[:confidence_check],
+                                   handoff_target: parsed[:handoff_target], json: !parsed[:json].nil?)
       options[:product_id] ||= product_id
+      options[:webmcp_bridge] = profile_webmcp_bridge(url) if parsed[:handoff_target].profile?
       report = Buy.new(**options).call
       record_buy(report, options[:query])
       result = parsed[:wait] ? wait_for_handoff(report, parsed) : nil
@@ -270,6 +309,64 @@ module Portage
     end
     private_class_method :execute_buy
 
+    # docs/plans/buy-skill-and-local-browser.md Phase 6: `--handoff-target
+    # profile` gives `portage buy` a browser of its own — the Portage
+    # profile — so it's attached here as Buy's `webmcp_bridge:`, exactly
+    # the seam Buy#initialize's own doc comment already names as "the only
+    # option from the portage buy CLI" before this phase existed. Never
+    # raises: any failure to attach (portage-ucp-webmcp not installed, the
+    # profile not running, a bad target) just means Buy runs with no
+    # bridge at all — its dead-end hand-off to "profile" then reports that
+    # the browser isn't attached (see #dispatch_to_target's "profile"
+    # case) rather than this crashing the whole buy.
+    def self.profile_webmcp_bridge(url)
+      return nil unless Webmcp.available?
+
+      profile = BrowserProfile::Profile.new
+      return nil unless profile.status[:running]
+
+      full_url = absolute_url(url)
+      target = browser_profile_target(profile, full_url)
+      ws_url = target && target["webSocketDebuggerUrl"]
+      return nil unless ws_url
+
+      socket = BrowserProfile::CdpSocket.connect(ws_url)
+      allowlist = BrowserProfile::Allowlist.new(hosts: [URI(full_url).host])
+      BrowserProfile::Bridge.new(socket: socket, allowlist: allowlist)
+    rescue StandardError
+      nil
+    end
+    private_class_method :profile_webmcp_bridge
+
+    # Same "bare host gets an https:// prefix" normalization Buy#initialize
+    # applies to the same `url` — done again here since this runs before
+    # Buy exists to do it, and a bare host like "shop.example" isn't a
+    # URI CDP's own `/json/new` or Runtime.evaluate's `window.location`
+    # comparisons can parse a host out of otherwise.
+    def self.absolute_url(url)
+      raw = url.to_s.strip
+      raw =~ %r{\Ahttps?://}i ? raw : "https://#{raw}"
+    end
+    private_class_method :absolute_url
+
+    # An existing tab already on this store's host, so a shopper who's
+    # mid-session there isn't yanked to a fresh one; otherwise a brand new
+    # tab navigated straight to `url`.
+    def self.browser_profile_target(profile, url)
+      host = URI(url).host
+      existing = BrowserProfile::Cdp.list(port: profile.port)
+                                    .find { |t| t["type"] == "page" && same_host?(t["url"], host) }
+      existing || BrowserProfile::Cdp.new_tab(port: profile.port, url: url)
+    end
+    private_class_method :browser_profile_target
+
+    def self.same_host?(url, host)
+      URI(url.to_s).host == host
+    rescue URI::InvalidURIError
+      false
+    end
+    private_class_method :same_host?
+
     # docs/plans/handoff-reconcile.md Phase 3 — `portage buy --wait`. A
     # no-op (returns nil) whenever there's nothing to wait on: --dry-run
     # never hands off at all, and a completed/browse-only/dead-end report
@@ -411,6 +508,7 @@ module Portage
       parser = buy_option_parser(buy, parsed)
       ProxySettings.add_options(parser, parsed[:proxy])
       parser.parse!(argv)
+      url = reinterpret_bare_query(url, buy, parsed)
       buy[:query] ||= ""
       return parsed if url || !buy[:query].strip.empty?
 
@@ -421,6 +519,24 @@ module Portage
     end
     private_class_method :parse_buy_options
 
+    # Bare arg is normally the store URL (`portage buy <url> --query "..."`),
+    # but `portage buy "coffee"` — no --query, and "coffee" doesn't look like
+    # a URL/domain — means the same thing as `portage buy --query "coffee"`:
+    # search first, then buy from whatever the caller picks. Only reinterpret
+    # when no --query was already given, so `portage buy shop.com --query
+    # "coffee"` keeps treating "shop.com" as the store.
+    def self.reinterpret_bare_query(url, buy, parsed)
+      return url unless url && buy[:query].to_s.strip.empty? && !url_like?(url)
+
+      buy[:url] = nil
+      parsed[:find][:query] = buy[:query] = url
+      nil
+    end
+    private_class_method :reinterpret_bare_query
+
+    def self.url_like?(text) = text.match?(%r{\A[a-z][a-z0-9+.-]*://}i) || text.include?(".")
+    private_class_method :url_like?
+
     def self.buy_option_parser(buy, parsed)
       OptionParser.new do |parser|
         parser.on("--qty N", Integer) { |v| buy[:qty] = v }
@@ -428,6 +544,7 @@ module Portage
         parser.on("--product-id ID") { |v| buy[:product_id] = v }
         parser.on("--yes") { buy[:yes] = true }
         parser.on("--dry-run") { buy[:dry_run] = true }
+        parser.on("--autofill") { buy[:autofill] = true }
         parser.on("--json") { parsed[:json] = true }
         add_handoff_options(parser, buy)
         add_wait_options(parser, parsed)
@@ -448,6 +565,7 @@ module Portage
     def self.add_handoff_options(parser, buy)
       parser.on("--[no-]auto-open") { |v| buy[:auto_open] = v }
       parser.on("--notify-webhook URL") { |v| buy[:notify_webhook] = v }
+      parser.on("--handoff-target TARGET") { |v| buy[:handoff_target] = v }
     end
     private_class_method :add_handoff_options
 
@@ -757,6 +875,9 @@ module Portage
       when "pending"
         "Timed out waiting for enrollment — finish it at #{result[:setup_url]}, then run " \
         "`portage payment enroll` again."
+      when "handoff_only"
+        "#{result[:host]} is hand-off only — there's nothing to set up here. Sign in and add a card " \
+        "on #{result[:host]} yourself."
       else "This store doesn't support payment enrollment."
       end
     end
@@ -833,6 +954,379 @@ module Portage
     end
     private_class_method :format_reconcile_result
 
+    # --- index (docs/plans/buy-skill-and-local-browser.md Phase 2b) ---
+
+    INDEX_SUBCOMMANDS = {
+      "build" => ->(argv) { run_index_build(argv, refresh: false) },
+      "refresh" => ->(argv) { run_index_build(argv, refresh: true) },
+      "show" => ->(argv) { run_index_show(argv) },
+      "add" => ->(argv) { run_index_add(argv) },
+      "remove" => ->(argv) { run_index_remove(argv) },
+      "sources" => ->(argv) { run_index_sources(argv) }
+    }.freeze
+
+    def self.run_index(argv)
+      sub = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      return INDEX_SUBCOMMANDS[sub].call(argv) if INDEX_SUBCOMMANDS.key?(sub)
+
+      warn USAGE
+      1
+    end
+    private_class_method :run_index
+
+    def self.parse_index_build_options(argv)
+      opts = { sources: nil, queries: nil, dry_run: false, json: false, export: nil }
+      OptionParser.new do |parser|
+        parser.on("--sources LIST") { |v| opts[:sources] = v.split(",").map(&:strip) }
+        parser.on("--queries FILE") { |v| opts[:queries] = v }
+        parser.on("--dry-run") { opts[:dry_run] = true }
+        parser.on("--export DIR") { |v| opts[:export] = v }
+        parser.on("--json") { opts[:json] = true }
+      end.parse!(argv)
+      opts[:queries] &&= File.readlines(opts[:queries]).map(&:strip).reject(&:empty?)
+      opts
+    end
+    private_class_method :parse_index_build_options
+
+    def self.run_index_build(argv, refresh:)
+      opts = parse_index_build_options(argv)
+      builder = Index::Builder.new(sources: index_sources(opts[:sources]), out: opts[:json] ? nil : $stdout)
+      result = if refresh
+                 builder.refresh(queries: opts[:queries], dry_run: opts[:dry_run], export: opts[:export])
+               else
+                 builder.build(queries: opts[:queries], dry_run: opts[:dry_run], export: opts[:export])
+               end
+      puts opts[:json] ? JSON.pretty_generate(result) : format_index_build(result)
+      0
+    end
+    private_class_method :run_index_build
+
+    def self.index_sources(names) = names ? Index::Sources.by_name(names) : nil
+    private_class_method :index_sources
+
+    def self.format_index_build(result)
+      lines = ["Ran #{result[:sources_run].join(', ')} — #{result[:candidates]} candidate(s)."]
+      lines << "Checked #{result[:new_origins_checked].length} new origin(s), " \
+               "#{result[:verified].length} verified UCP."
+      lines << "Hit the #{Index::Builder::MAX_NEW_PROBES}-probe cap for this run." if result[:capped]
+      lines << "#{result[:products_added]} product sighting(s) recorded." if result[:products_added]
+      if result[:exported]
+        lines << "Exported #{result[:exported][:stores]} store(s), #{result[:exported][:products]} " \
+                 "product(s) to #{result[:exported][:dir]}."
+      end
+      lines.join("\n")
+    end
+    private_class_method :format_index_build
+
+    def self.run_index_show(argv)
+      opts = { kind: nil, json: false }
+      OptionParser.new do |parser|
+        parser.on("--stores") { opts[:kind] = "stores" }
+        parser.on("--products") { opts[:kind] = "products" }
+        parser.on("--json") { opts[:json] = true }
+      end.parse!(argv)
+
+      result = { stores: opts[:kind] == "products" ? [] : Index::Store.new.all,
+                 products: opts[:kind] == "stores" ? [] : Index::ProductStore.new.all }
+      puts opts[:json] ? JSON.pretty_generate(result) : format_index_show(result)
+      0
+    end
+    private_class_method :run_index_show
+
+    def self.format_index_show(result)
+      lines = ["Stores:"]
+      result[:stores].each { |s| lines << "  #{s['origin']} (#{Array(s['sources']).join(', ')})" }
+      lines << "(none)" if result[:stores].empty?
+      lines << "Products:"
+      result[:products].each { |p| lines << "  #{p['title'] || p['key']}" }
+      lines << "(none)" if result[:products].empty?
+      lines.join("\n")
+    end
+    private_class_method :format_index_show
+
+    def self.run_index_add(argv)
+      json = argv.delete("--json") ? true : false
+      url = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      unless url
+        warn USAGE
+        return 1
+      end
+
+      result = Index::Builder.new.add(url)
+      puts json ? JSON.pretty_generate(result) : result[:message]
+      result[:added] ? 0 : 1
+    end
+    private_class_method :run_index_add
+
+    def self.run_index_remove(argv)
+      json = argv.delete("--json") ? true : false
+      host = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      unless host
+        warn USAGE
+        return 1
+      end
+
+      result = Index::Builder.new.remove(host)
+      puts json ? JSON.pretty_generate(result) : result[:message]
+      result[:removed] ? 0 : 1
+    end
+    private_class_method :run_index_remove
+
+    def self.run_index_sources(argv)
+      json = argv.delete("--json") ? true : false
+      sources = Index::Sources.all.map { |s| { name: s.name, description: s.description, path: s.source_path } }
+      puts json ? JSON.pretty_generate(sources) : format_index_sources(sources)
+      0
+    end
+    private_class_method :run_index_sources
+
+    def self.format_index_sources(sources)
+      sources.map { |s| "#{s[:name]}: #{s[:description]}#{" (#{s[:path]})" if s[:path]}" }.join("\n")
+    end
+    private_class_method :format_index_sources
+
+    # --- browser (docs/plans/buy-skill-and-local-browser.md Phase 3) ---
+
+    BROWSER_SUBCOMMANDS = { "import" => ->(argv) { run_browser_import(argv) },
+                            "profile" => ->(argv) { run_browser_profile(argv) } }.freeze
+
+    def self.run_browser(argv)
+      sub = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      return BROWSER_SUBCOMMANDS[sub].call(argv) if BROWSER_SUBCOMMANDS.key?(sub)
+
+      warn USAGE
+      1
+    end
+    private_class_method :run_browser
+
+    def self.parse_browser_import_options(argv)
+      opts = { browser: nil, root: nil, history_days: BrowserImport::Importer::DEFAULT_HISTORY_DAYS,
+               include_product_pages: false, max_probes: BrowserImport::Importer::MAX_PROBES, exclude: [],
+               dry_run: false, yes: false, json: false }
+      browser_import_option_parser(opts).parse!(argv)
+      opts
+    end
+    private_class_method :parse_browser_import_options
+
+    def self.browser_import_option_parser(opts)
+      OptionParser.new do |parser|
+        parser.on("--browser NAME", BrowserImport::Profiles::BROWSERS) { |v| opts[:browser] = v }
+        parser.on("--profile-root DIR") { |v| opts[:root] = File.expand_path(v) }
+        parser.on("--history-days N", Integer) { |v| opts[:history_days] = v }
+        parser.on("--max-probes N", Integer) { |v| opts[:max_probes] = v }
+        parser.on("--exclude HOSTS", Array) { |v| opts[:exclude] = v.map(&:strip) }
+        %i[include_product_pages dry_run yes json].each do |flag|
+          parser.on("--#{flag.to_s.tr('_', '-')}") { opts[flag] = true }
+        end
+      end
+    end
+    private_class_method :browser_import_option_parser
+
+    # Reads, reduces and probes (BrowserImport::Importer#plan), shows the
+    # list, and saves only through BrowserImport::Confirm's gate: `--yes`,
+    # or a "y" at a real TTY prompt. Under `--json`/no TTY without `--yes`
+    # nothing is written — the report says `saved: false,
+    # needs_confirmation: true` and exits 0, so an agent shows the user the
+    # list and re-runs with `--yes` only once they've approved it.
+    def self.run_browser_import(argv)
+      opts = parse_browser_import_options(argv)
+      plan = browser_importer.plan(browser_import_options(opts))
+      return report_browser_import(plan, opts, nil) if plan[:error]
+
+      puts format_browser_import(plan) unless opts[:json]
+      interactive = !opts[:json] && $stdin.tty?
+      decision = BrowserImport::Confirm.new(interactive: interactive).call(plan, yes: opts[:yes],
+                                                                                 dry_run: opts[:dry_run])
+      saved = decision == :save ? browser_importer.save(plan) : nil
+      report_browser_import(plan, opts, decision, saved)
+    rescue OptionParser::ParseError => e
+      warn "#{e.message}\n#{USAGE}"
+      1
+    end
+    private_class_method :run_browser_import
+
+    # The real HandoffOnly list (docs/plans/buy-skill-and-local-browser.md
+    # Phase 5) into Importer's own injectable `handoff_only_hosts:` seam
+    # (Phase 3 left it defaulting to `[]` for exactly this) — a history/
+    # bookmark domain on the list is kept as `handoff_only: true` and never
+    # probed.
+    def self.browser_importer
+      BrowserImport::Importer.new(handoff_only_hosts: HandoffOnly.new.hosts)
+    end
+    private_class_method :browser_importer
+
+    def self.browser_import_options(opts)
+      browser = opts[:browser] || BrowserImport::Profiles.detect || "chrome"
+      BrowserImport::Importer::Options.new(
+        browser: browser, root: opts[:root] || BrowserImport::Profiles.default_root(browser),
+        history_days: opts[:history_days], include_product_pages: opts[:include_product_pages],
+        max_probes: opts[:max_probes], exclude: opts[:exclude]
+      )
+    end
+    private_class_method :browser_import_options
+
+    BROWSER_IMPORT_MESSAGES = {
+      dry_run: "Dry run — nothing saved.",
+      nothing: "No shop domains to save.",
+      declined: "Nothing saved.",
+      needs_confirmation: "Nothing saved: there's no terminal to confirm on. Show this list to the user, then " \
+                          "re-run with --yes once they've approved it (--exclude HOST,... drops any they don't want)."
+    }.freeze
+
+    def self.report_browser_import(plan, opts, decision, saved = nil)
+      message = plan[:message] || browser_import_message(decision, saved)
+      if opts[:json]
+        puts JSON.pretty_generate(plan.merge(saved: !saved.nil?, needs_confirmation: decision == :needs_confirmation,
+                                             message: message))
+      else
+        puts message
+      end
+      plan[:error] ? 1 : 0
+    end
+    private_class_method :report_browser_import
+
+    def self.browser_import_message(decision, saved)
+      return "Saved #{saved[:stores]} store(s) and #{saved[:products]} product(s) to your local index." if saved
+
+      BROWSER_IMPORT_MESSAGES.fetch(decision, "Nothing saved.")
+    end
+    private_class_method :browser_import_message
+
+    def self.format_browser_import(plan)
+      lines = browser_import_counts(plan)
+      lines << "Shops found (#{plan[:kept].length}):"
+      plan[:kept].each { |entry| lines << "  #{browser_import_line(entry)}" }
+      lines << "  (none)" if plan[:kept].empty?
+      lines << "#{plan[:products].length} product page(s) to keep." if plan[:products].any?
+      lines.join("\n")
+    end
+    private_class_method :format_browser_import
+
+    def self.browser_import_counts(plan)
+      skipped = plan[:skipped].map { |reason, n| "#{n} #{reason}" }.join(", ")
+      lines = ["Read #{plan[:rows][:history]} history and #{plan[:rows][:bookmark]} bookmark row(s) across " \
+               "#{plan[:domains]} domain(s) from #{plan[:browser]}.",
+               "Skipped #{skipped.empty? ? 'none' : skipped}; probed #{plan[:probed]} " \
+               "(#{plan[:not_ucp]} without UCP, #{plan[:cached_miss]} already known not to)."]
+      lines << "Hit the #{plan[:probed]}-probe cap; #{plan[:unprobed]} domain(s) left unprobed." if plan[:capped]
+      lines
+    end
+    private_class_method :browser_import_counts
+
+    def self.browser_import_line(entry)
+      categories = entry[:category_names].empty? ? "uncategorised" : entry[:category_names].join(", ")
+      "#{entry[:domain]} — #{entry[:verdict]} — #{categories} " \
+        "(#{entry[:sources].join(', ')}, #{entry[:visits]} visit(s))"
+    end
+    private_class_method :browser_import_line
+
+    # --- browser profile (docs/plans/buy-skill-and-local-browser.md Phase 6) ---
+
+    BROWSER_PROFILE_SUBCOMMANDS = {
+      "init" => ->(argv) { run_browser_profile_init(argv) },
+      "open" => ->(argv) { run_browser_profile_open(argv) },
+      "status" => ->(argv) { run_browser_profile_status(argv) }
+    }.freeze
+
+    def self.run_browser_profile(argv)
+      sub = argv.first && !argv.first.start_with?("-") ? argv.shift : nil
+      return browser_profile_usage unless BROWSER_PROFILE_SUBCOMMANDS.key?(sub)
+
+      BROWSER_PROFILE_SUBCOMMANDS[sub].call(argv)
+    end
+    private_class_method :run_browser_profile
+
+    def self.browser_profile_usage
+      warn USAGE
+      1
+    end
+    private_class_method :browser_profile_usage
+
+    def self.parse_browser_profile_options(argv)
+      opts = { browser: nil, port: BrowserProfile::Profile::DEFAULT_PORT, url: nil, json: false }
+      OptionParser.new do |parser|
+        parser.on("--browser NAME", BrowserProfile::Browsers::CHROMIUM) { |v| opts[:browser] = v }
+        parser.on("--port N", Integer) { |v| opts[:port] = v }
+        parser.on("--url URL") { |v| opts[:url] = v }
+        parser.on("--json") { opts[:json] = true }
+      end.parse!(argv)
+      opts
+    end
+    private_class_method :parse_browser_profile_options
+
+    # `--browser` names the exact browser; without it, the first Chromium
+    # family browser BrowserImport::Profiles finds installed, falling back
+    # to "chrome" — same "pick something reasonable, let --browser
+    # override" posture as run_browser_import's own default.
+    def self.browser_profile_for(opts)
+      browser = opts[:browser] || BrowserProfile::Browsers.detect || "chrome"
+      BrowserProfile::Profile.new(browser: browser, port: opts[:port])
+    end
+    private_class_method :browser_profile_for
+
+    def self.run_browser_profile_init(argv)
+      opts = parse_browser_profile_options(argv)
+      result = browser_profile_for(opts).init!
+      puts opts[:json] ? JSON.pretty_generate(result) : "Profile ready at #{result[:dir]} (#{result[:browser]})."
+      0
+    rescue OptionParser::ParseError => e
+      warn "#{e.message}\n#{USAGE}"
+      1
+    end
+    private_class_method :run_browser_profile_init
+
+    # Launches the profile (if it isn't already running on its own port)
+    # and either opens a new tab at --url or attaches to the first
+    # existing one. Never touches the browser's default profile — Profile
+    # itself only ever points --user-data-dir at its own dedicated
+    # directory.
+    def self.run_browser_profile_open(argv)
+      opts = parse_browser_profile_options(argv)
+      result = browser_profile_for(opts).open!(url: opts[:url])
+      puts opts[:json] ? JSON.pretty_generate(result) : format_browser_profile_open(result)
+      0
+    rescue BrowserProfile::Error => e
+      report_browser_profile_error(e, opts[:json])
+    rescue OptionParser::ParseError => e
+      warn "#{e.message}\n#{USAGE}"
+      1
+    end
+    private_class_method :run_browser_profile_open
+
+    def self.run_browser_profile_status(argv)
+      opts = parse_browser_profile_options(argv)
+      result = browser_profile_for(opts).status
+      puts opts[:json] ? JSON.pretty_generate(result) : format_browser_profile_status(result)
+      0
+    rescue OptionParser::ParseError => e
+      warn "#{e.message}\n#{USAGE}"
+      1
+    end
+    private_class_method :run_browser_profile_status
+
+    def self.format_browser_profile_open(result)
+      tab = result.dig(:target, "url")
+      "#{result[:browser]} profile is open (port #{result[:port]}, #{result[:dir]})#{" — tab: #{tab}" if tab}."
+    end
+    private_class_method :format_browser_profile_open
+
+    def self.format_browser_profile_status(result)
+      return "#{result[:browser]} profile (#{result[:dir]}) isn't running." unless result[:running]
+
+      "#{result[:browser]} profile is running on port #{result[:port]} (#{result[:dir]})."
+    end
+    private_class_method :format_browser_profile_status
+
+    def self.report_browser_profile_error(error, json)
+      if json
+        puts JSON.pretty_generate(error: error.class.name.split("::").last, message: error.message)
+      else
+        warn error.message
+      end
+      1
+    end
+    private_class_method :report_browser_profile_error
+
     # --- doctor ---
 
     def self.parse_doctor_options(argv)
@@ -847,17 +1341,45 @@ module Portage
     end
     private_class_method :parse_doctor_options
 
-    def self.run_doctor(argv)
+    # `wizard: :force` is `portage setup`, always offering the wizard on a
+    # TTY; `:auto` is `doctor`/`configure`, which only offers it when
+    # Doctor#nothing_configured? — the read-only report is what every other
+    # run of `doctor` still gets, exactly as before this phase
+    # (docs/plans/buy-skill-and-local-browser.md Phase 4).
+    def self.run_doctor(argv, wizard: :auto)
       opts = parse_doctor_options(argv)
       require File.expand_path(opts[:require]) if opts[:require]
       adapter_class = opts[:adapter] && Object.const_get(opts[:adapter])
       proxy_settings = apply_proxy_settings(opts[:proxy])
       return 1 unless proxy_settings
 
-      report_doctor(Doctor.new(adapter_class: adapter_class, proxy_settings: proxy_settings).call, json: opts[:json])
+      doctor = Doctor.new(adapter_class: adapter_class, proxy_settings: proxy_settings,
+                          seller: !(opts[:require] || opts[:adapter]).nil?)
+      return run_setup_wizard if run_wizard?(wizard, opts, doctor)
+
+      report_doctor(doctor.call, json: opts[:json])
     end
     private_class_method :run_doctor
 
+    def self.run_setup(argv) = run_doctor(argv, wizard: :force)
+    private_class_method :run_setup
+
+    # --json or no TTY on stdin always stays today's read-only report,
+    # whichever command name was used — a piped/CI/agent run never blocks
+    # on a prompt it can't answer.
+    def self.run_wizard?(mode, opts, doctor)
+      return false if opts[:json] || !$stdin.tty?
+      return true if mode == :force
+
+      doctor.nothing_configured?
+    end
+    private_class_method :run_wizard?
+
+    def self.run_setup_wizard
+      SetupWizard.new.call
+    end
+    private_class_method :run_setup_wizard
+
     def self.report_doctor(findings, json:)
       puts json ? JSON.pretty_generate(findings.map(&:to_h)) : format_doctor(findings)
       findings.none?(&:warning?) ? 0 : 1