smily_cli 0.1.0

data/lib/smily_cli/base_command.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "thor"
+require "json"
+
+module SmilyCli
+  # Common behavior shared by every Thor command class in the CLI: building the
+  # {Context}/{Client} from resolved options, rendering {Result}s in the chosen
+  # format, reading `--data` payloads, and printing status/errors on the right
+  # stream (data on stdout, everything else on stderr).
+  class BaseCommand < Thor
+    # Make Thor exit non-zero on its own argument errors.
+    def self.exit_on_failure?
+      true
+    end
+
+    no_commands do
+      # @return [Context] settings resolved from flags/env/profile
+      def context
+        @context ||= Context.from(options)
+      end
+
+      # @return [Client] API client for the current context
+      def client
+        @client ||= context.client
+      end
+
+      # Render a {Result} to stdout in the effective (or overridden) format.
+      #
+      # @param result [Result]
+      # @param format [String, nil] override the context format
+      # @param fields [Array<String>, nil] override the context fields
+      # @return [void]
+      def render_result(result, format: nil, fields: nil)
+        fmt = format || context.output_format
+        output = Formatters.render(result, format: fmt, fields: fields || context.fields)
+        emit(output)
+        warn_rate_limit(result)
+      end
+
+      # Print data to stdout (kept free of decoration so it stays pipeable).
+      #
+      # @param string [String]
+      # @return [void]
+      def emit(string)
+        return if string.nil? || string.empty?
+
+        $stdout.puts(string)
+      end
+
+      # Print an informational line to stderr unless `--quiet`.
+      #
+      # @param message [String]
+      # @return [void]
+      def notice(message)
+        warn(message) unless context.quiet?
+      end
+
+      # Print a green success line to stderr.
+      #
+      # @param message [String]
+      # @return [void]
+      def success(message)
+        notice(Color.green(message))
+      end
+
+      # Read and JSON-parse the `--data` option, which may be inline JSON,
+      # `@path` to read a file, or `-` to read stdin. Raises when absent.
+      #
+      # @return [Hash, Array]
+      def require_data
+        raw = options["data"]
+        if raw.nil? || raw.to_s.empty?
+          raise UsageError,
+                "This command needs a JSON body: pass --data '<json>', --data @file.json, or --data - for stdin."
+        end
+
+        parse_data(raw)
+      end
+
+      # @param raw [String]
+      # @return [Object] parsed JSON
+      def parse_data(raw)
+        content =
+          if raw == "-"
+            $stdin.read
+          elsif raw.start_with?("@")
+            read_data_file(raw[1..])
+          else
+            raw
+          end
+        JSON.parse(content)
+      rescue JSON::ParserError => e
+        raise UsageError, "Invalid JSON in --data: #{e.message}"
+      end
+
+      # @param path [String]
+      # @return [String]
+      def read_data_file(path)
+        File.read(File.expand_path(path))
+      rescue SystemCallError => e
+        raise UsageError, "Could not read --data file #{path.inspect}: #{e.message}"
+      end
+
+      # Guard a destructive action behind confirmation unless `--yes` is set.
+      # In a non-interactive context, refuses rather than blocking.
+      #
+      # @param message [String]
+      # @return [void]
+      def confirm!(message)
+        return if options["yes"]
+
+        unless $stdin.respond_to?(:tty?) && $stdin.tty?
+          raise UsageError, "#{message} Refusing without confirmation; pass --yes to proceed."
+        end
+
+        $stderr.print("#{message} [y/N] ")
+        answer = $stdin.gets&.strip&.downcase
+        raise Error, "Aborted." unless %w[y yes].include?(answer)
+      end
+
+      # In verbose mode, surface the remaining rate-limit budget.
+      #
+      # @param result [Result]
+      # @return [void]
+      def warn_rate_limit(result)
+        return unless context.verbose?
+
+        remaining = result.rate_limit_remaining
+        notice(Color.dim("rate limit remaining: #{remaining}")) if remaining
+      end
+    end
+  end
+end

data/lib/smily_cli/cli.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "thor"
+require "json"
+require "bookingsync/api" # for the `version` command's BookingSync::API::VERSION
+
+module SmilyCli
+  # The top-level `smily` command. It wires the reusable resource CRUD commands
+  # (one registered subcommand per {Registry} entry), the `auth`/`config`
+  # subcommand groups, and a handful of core commands (`api`, `resources`,
+  # `whoami`, `completion`, `version`). Business logic lives in the library
+  # classes; this class only parses input and dispatches.
+  class CLI < BaseCommand
+    CLIOptions.connection(self)
+    CLIOptions.output(self)
+
+    package_name "smily"
+
+    # Single-value global flags that are safe to move past the subcommand.
+    HOISTABLE_VALUE_FLAGS = %w[
+      --profile --token --base-url --account-id --max-pages --retry
+      -o --output --mcp-token --mcp-url
+    ].freeze
+    # Value-less global flags.
+    HOISTABLE_BOOL_FLAGS = %w[-v --verbose -q --quiet --no-color].freeze
+
+    # Every top-level command word, so normalization can tell a real flag value
+    # from a subcommand the user meant to run.
+    #
+    # @return [Array<String>]
+    def self.command_names
+      @command_names ||= (
+        Registry.commands + %w[api auth config mcp resources whoami completion version help]
+      ).freeze
+    end
+
+    # Thor's registered subcommands can't see class options that appear *before*
+    # the subcommand word, so `smily -o json rentals list` would drop `-o`. We
+    # normalize by moving any leading global flags to the end of the args, where
+    # every command re-declares them. (Array-valued flags like `--fields` are
+    # left alone and must follow the subcommand.)
+    #
+    # A leading value flag with no attached `=value` whose next token is missing
+    # or is itself a command word is a forgotten value (`smily --token rentals
+    # list`). We fail with a clear {UsageError} rather than swallow the
+    # subcommand into the flag — which otherwise yields a baffling "command not
+    # found" or a request fired with a bogus value. Use `--flag=value` when a
+    # value legitimately collides with a command name (e.g. a profile named like
+    # a resource).
+    #
+    # @param argv [Array<String>]
+    # @return [Array<String>]
+    # @raise [UsageError] when a leading value flag is missing its value
+    def self.normalize_argv(argv)
+      leading = []
+      rest = argv.dup
+      until rest.empty?
+        token = rest.first
+        break if token == "--"
+
+        name = token.split("=", 2).first
+        if HOISTABLE_VALUE_FLAGS.include?(name)
+          leading << rest.shift
+          next if token.include?("=") # value already attached
+
+          value = rest.first
+          unless takes_value?(value)
+            raise UsageError,
+                  "Missing value for #{name}. Pass it as `#{name} <VALUE>`, or as " \
+                  "`#{name}=<VALUE>` if the value is also a command name."
+          end
+          leading << rest.shift
+        elsif HOISTABLE_BOOL_FLAGS.include?(token)
+          leading << rest.shift
+        else
+          break
+        end
+      end
+      leading.empty? || rest.empty? ? argv : rest + leading
+    end
+
+    # A token is a flag's value only when it's present and not a command word
+    # the user more likely meant to run (a forgotten flag value).
+    #
+    # @param token [String, nil]
+    # @return [Boolean]
+    def self.takes_value?(token)
+      !token.nil? && !command_names.include?(token)
+    end
+
+    def self.start(given_args = ARGV, config = {})
+      super(normalize_argv(Array(given_args)), config)
+    end
+
+    # Register every known resource as a subcommand with list/get/create/... .
+    Registry.all.each do |resource|
+      verbs = resource.writable? ? "list|get|create|update|delete" : "list|get"
+      register(
+        ResourceCommand.bind(resource),
+        resource.command,
+        "#{resource.command} <#{verbs}>",
+        resource.description
+      )
+    end
+
+    register(Commands::AuthCommand, "auth", "auth <SUBCOMMAND>",
+             "Obtain, refresh and inspect OAuth tokens")
+    register(Commands::ConfigCommand, "config", "config <SUBCOMMAND>",
+             "Manage config profiles and settings")
+    register(Commands::McpCommand, "mcp", "mcp <SUBCOMMAND>",
+             "Talk to a BookingSync MCP server (Model Context Protocol)")
+
+    desc "api METHOD PATH", "Make a raw request to any API v3 endpoint"
+    long_desc <<~DESC
+      Escape hatch for endpoints (or verbs) the resource commands don't cover.
+      The body is sent verbatim — no envelope wrapping.
+
+        smily api get rentals --query per_page=5
+        smily api get bookings/123
+        smily api post rentals/42/bookings --data @booking.json
+        smily api get rentals --paginate -o ndjson
+
+      By default the raw JSON response is printed. With --paginate, every page
+      is fetched and the combined records are printed as a JSON array.
+    DESC
+    method_option :query, type: :array, banner: "k=v", desc: "Query params (key=value)"
+    method_option :data, type: :string, aliases: "-d", banner: "JSON|@file|-", desc: "Request body"
+    method_option :paginate, type: :boolean, desc: "Follow pagination and combine records"
+    def api(method, path)
+      verb = method.to_s.downcase
+      unless %w[get post put patch delete head].include?(verb)
+        raise UsageError, "Unknown HTTP method #{method.inspect}. Use get, post, put, patch or delete."
+      end
+
+      query = QueryOptions.build(fields: context.fields, query: options["query"] || [])
+
+      if options["paginate"]
+        result = client.list(path, query: query, all: true)
+        render_api(result, records: true)
+      else
+        body = options["data"] ? parse_data(options["data"]) : nil
+        result = client.request(verb, path, query: query, body: body)
+        render_api(result, records: false)
+      end
+    end
+
+    desc "resources [FILTER]", "List the API v3 resources this CLI knows about"
+    def resources(filter = nil)
+      selected = Registry.all.select { |r| filter.nil? || r.command.include?(filter) }
+
+      if context.output_format == "table"
+        render_resources_table(selected)
+      else
+        payload = selected.map do |r|
+          { "command" => r.command, "path" => r.path, "group" => r.group,
+            "description" => r.description, "readonly" => r.readonly }
+        end
+        render_result(Result.new(records: payload, single: false))
+      end
+    end
+
+    desc "whoami", "Show the current application and account (/me)"
+    def whoami
+      render_result(client.me)
+    end
+
+    desc "completion SHELL", "Print a completion script (bash, zsh or fish)"
+    def completion(shell)
+      emit(Completion.script(shell))
+    end
+
+    desc "version", "Show version information"
+    def version
+      emit("smily #{SmilyCli::VERSION} (ruby #{RUBY_VERSION}, bookingsync-api #{BookingSync::API::VERSION})")
+    end
+    map %w[--version] => :version
+
+    no_commands do
+      # Render an `api` result: honor an explicit non-json format, otherwise
+      # print raw JSON (records array when paginating, else the full envelope).
+      def render_api(result, records:)
+        fmt = context.requested_output_format
+        # render_result already surfaces the rate-limit note, so return early to
+        # avoid warning about it twice.
+        return render_result(result, format: fmt) if fmt && fmt != "json"
+
+        emit(JSON.pretty_generate(records ? result.records : (result.envelope || {})))
+        warn_rate_limit(result)
+      end
+
+      # The grouped, human-readable resource listing (table output).
+      def render_resources_table(selected)
+        selected.group_by(&:group).each do |group, list|
+          emit(Color.bold(group))
+          width = list.map { |r| r.command.length }.max
+          list.each do |r|
+            flag = r.readonly ? Color.dim(" (read-only)") : ""
+            emit("  #{r.command.ljust(width)}  #{Color.dim(r.description)}#{flag}")
+          end
+          emit("")
+        end
+      end
+    end
+  end
+end

data/lib/smily_cli/cli_options.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SmilyCli
+  # Declares the reusable Thor option groups so every command exposes the same
+  # connection and output flags with identical wording. Because Thor does not
+  # forward a parent command's `class_option`s to `register`ed subcommands, each
+  # command class opts in by calling these helpers in its body.
+  module CLIOptions
+    module_function
+
+    # Connection / global behavior flags (token, profile, base URL, verbosity).
+    #
+    # @param thor [Class<Thor>]
+    # @return [void]
+    def connection(thor)
+      thor.class_option :profile, type: :string, banner: "NAME",
+                                  desc: "Config profile to use (env: SMILY_PROFILE)"
+      thor.class_option :token, type: :string, banner: "TOKEN",
+                                desc: "OAuth access token (env: SMILY_TOKEN)"
+      thor.class_option :base_url, type: :string, banner: "URL",
+                                   desc: "API base URL (default: https://www.bookingsync.com)"
+      thor.class_option :account_id, type: :string, banner: "ID",
+                                     desc: "Scope requests to an account (for client-credentials tokens)"
+      thor.class_option :max_pages, type: :numeric, banner: "N",
+                                    desc: "Cap auto-pagination at N pages (default 1000)"
+      thor.class_option :retry, type: :numeric, banner: "N",
+                                desc: "Retry 429s up to N times, honoring rate-limit reset"
+      thor.class_option :verbose, type: :boolean, aliases: "-v",
+                                  desc: "Log HTTP requests/responses to stderr"
+      thor.class_option :quiet, type: :boolean, aliases: "-q",
+                                desc: "Suppress status messages"
+      thor.class_option :no_color, type: :boolean,
+                                   desc: "Disable ANSI color"
+    end
+
+    # MCP-mode connection flags. Shares profile/base-url/account/verbosity with
+    # {connection} but swaps the REST token for the dedicated MCP credential.
+    #
+    # @param thor [Class<Thor>]
+    # @return [void]
+    def mcp(thor)
+      thor.class_option :profile, type: :string, banner: "NAME",
+                                  desc: "Config profile to use (env: SMILY_PROFILE)"
+      thor.class_option :mcp_token, type: :string, banner: "TOKEN",
+                                    desc: "MCP access token (env: SMILY_MCP_TOKEN)"
+      thor.class_option :mcp_url, type: :string, banner: "URL",
+                                  desc: "MCP server endpoint (default: <base-url>/mcp)"
+      thor.class_option :base_url, type: :string, banner: "URL",
+                                   desc: "Base URL used to derive the default MCP endpoint"
+      thor.class_option :account_id, type: :string, banner: "ID",
+                                     desc: "Scope tool calls to an account"
+      thor.class_option :verbose, type: :boolean, aliases: "-v",
+                                  desc: "Log MCP traffic to stderr"
+      thor.class_option :quiet, type: :boolean, aliases: "-q",
+                                desc: "Suppress status messages"
+      thor.class_option :no_color, type: :boolean, desc: "Disable ANSI color"
+    end
+
+    # Output-shaping flags (format and field selection).
+    #
+    # @param thor [Class<Thor>]
+    # @return [void]
+    def output(thor)
+      thor.class_option :output, type: :string, aliases: "-o", banner: "FORMAT",
+                                 desc: "Output: table, json, yaml, csv, ndjson (default: table on a TTY, else json)"
+      thor.class_option :fields, type: :array, banner: "a b c",
+                                 desc: "Limit fields/columns (sparse fieldset)"
+    end
+  end
+end

data/lib/smily_cli/client.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "logger"
+require "bookingsync/api"
+
+module SmilyCli
+  # A thin, generic wrapper over the official {BookingSync::API::Client}. It
+  # reuses that client's connection handling, JSON:API serialization, `Link`
+  # header pagination and typed errors, and adds exactly what a CLI needs:
+  # path-based (rather than method-per-resource) access, cross-page collection,
+  # write-body wrapping, and translation of gem errors into {ApiError}.
+  #
+  # Everything is driven by a resource *path*, so any v3 endpoint is reachable —
+  # including ones the {Registry} doesn't list.
+  class Client
+    # @param token [String] OAuth access token
+    # @param base_url [String] site base URL (the client appends `/api/v3`)
+    # @param account_id [String, Integer, nil] scope requests to one account.
+    #   Sent as the `account_id` query parameter on every request, which is how
+    #   a Client-Credentials-flow token (spanning many accounts) is pinned to a
+    #   single account. Harmless for single-account (Authorization Code) tokens.
+    # @param max_pages [Integer] hard backstop on auto-pagination: stop after
+    #   this many pages even if the server keeps advertising a `next` link.
+    # @param retries [Integer] how many times to retry a `429 Too Many Requests`,
+    #   waiting for the rate-limit window before each retry.
+    # @param max_retry_wait [Integer] cap (seconds) on any single retry wait.
+    # @param sleeper [#call] injectable sleep, for tests. Defaults to Kernel#sleep.
+    # @param verbose [Boolean] log HTTP traffic to stderr
+    def initialize(token:, base_url: Context::DEFAULT_BASE_URL, account_id: nil,
+                   max_pages: Context::DEFAULT_MAX_PAGES, retries: 0,
+                   max_retry_wait: 60, sleeper: nil, verbose: false)
+      @account_id = account_id
+      @max_pages = max_pages
+      @retries = retries
+      @max_retry_wait = max_retry_wait
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @api = BookingSync::API.new(token, base_url: base_url, logger: build_logger(verbose))
+    end
+
+    # List a collection, transparently following pagination as requested.
+    #
+    # @param path [String] collection path, e.g. "rentals"
+    # @param query [Hash] query parameters (filters, include, fields, ...)
+    # @param limit [Integer, nil] stop after this many records (follows pages)
+    # @param page [Integer, nil] fetch one specific page (disables following)
+    # @param per_page [Integer, nil] page size hint
+    # @param all [Boolean] fetch every page
+    # @return [Result]
+    def list(path, query: {}, limit: nil, page: nil, per_page: nil, all: false)
+      q = stringify(query)
+      q["per_page"] = per_page if per_page
+      # With a limit but no explicit page size, request exactly what we need
+      # (capped at the API max of 100) instead of paging at the default 25.
+      q["per_page"] = [limit, 100].min if per_page.nil? && limit && page.nil?
+      q["page"] = page if page
+
+      response = call(:get, path, query: q)
+      first = Result.from_response(response)
+      records = first.records.dup
+      last = first
+
+      last = follow_pages(response, records, limit: limit) if all || (limit && page.nil?)
+
+      records = records.first(limit) if limit
+      Result.new(
+        records: records, single: false,
+        envelope: last.envelope, key: last.key,
+        status: last.status, headers: last.headers
+      )
+    end
+
+    # Fetch a single member.
+    #
+    # @param path [String] collection path
+    # @param id [String, Integer]
+    # @param query [Hash]
+    # @return [Result]
+    def get(path, id, query: {})
+      response = call(:get, member_path(path, id), query: stringify(query))
+      Result.from_response(response, single: true)
+    end
+
+    # Create a member. Wraps attributes into the `{ key: [attrs] }` envelope v3
+    # expects, unless the caller already supplied that envelope.
+    #
+    # @param path [String] collection path
+    # @param resource_key [String] JSON:API key (usually the last path segment)
+    # @param attributes [Hash, Array] attributes or a ready envelope
+    # @param query [Hash]
+    # @return [Result]
+    def create(path, resource_key, attributes, query: {})
+      response = call(:post, path, query: stringify(query), body: wrap_body(resource_key, attributes))
+      Result.from_response(response, single: true)
+    end
+
+    # Update a member (HTTP PUT, matching the v3 reference).
+    #
+    # @return [Result]
+    def update(path, resource_key, id, attributes, query: {})
+      response = call(:put, member_path(path, id), query: stringify(query), body: wrap_body(resource_key, attributes))
+      Result.from_response(response, single: true)
+    end
+
+    # Delete/cancel a member. Returns an empty {Result} on 204.
+    #
+    # @return [Result]
+    def delete(path, id, body: nil, query: {})
+      response = call(:delete, member_path(path, id), query: stringify(query), body: body)
+      Result.from_response(response, single: true)
+    end
+
+    # Escape hatch: issue an arbitrary request against any path. The body is
+    # sent verbatim (no envelope wrapping) so callers stay in full control.
+    #
+    # @param method [Symbol, String] :get/:post/:put/:patch/:delete
+    # @param path [String] path or full URL (base + `/api/v3` are stripped)
+    # @param query [Hash]
+    # @param body [Hash, String, nil]
+    # @return [Result]
+    def request(method, path, query: {}, body: nil)
+      response = call(method.to_sym, path, query: stringify(query), body: body)
+      Result.from_response(response)
+    end
+
+    # Fetch `/me` (current application + account).
+    #
+    # @return [Result]
+    def me
+      Result.from_response(call(:get, "me", query: {}), single: true)
+    end
+
+    private
+
+    # Perform one HTTP call through the underlying gem, mapping its typed errors
+    # into {ApiError}. Returns the raw {BookingSync::API::Response} (or nil on
+    # 204) so pagination can read `Link` relations.
+    def call(method, path, query: {}, body: nil)
+      with_error_handling do
+        m = method.to_sym
+        normalized = normalize_path(path)
+        q = with_account_scope(query)
+        if %i[get head].include?(m)
+          @api.call(m, normalized, query: q)
+        else
+          @api.call(m, normalized, body, query: q)
+        end
+      end
+    end
+
+    # Fetch the next page from a `Link`-header relation, through the same error
+    # handling / retry as a normal call (the relation otherwise bypasses it).
+    def fetch_next(relation)
+      with_error_handling { relation.call({}, method: :get) }
+    end
+
+    # Run a request block, mapping gem errors to {ApiError} and retrying on 429
+    # (up to @retries times) after waiting for the rate-limit window.
+    def with_error_handling
+      attempt = 0
+      begin
+        yield
+      rescue BookingSync::API::RateLimitExceeded => e
+        raise ApiError.from_api(e) unless attempt < @retries
+
+        attempt += 1
+        @sleeper.call(retry_delay(e.headers))
+        retry
+      rescue BookingSync::API::Error => e
+        raise ApiError.from_api(e)
+      rescue Faraday::Error => e
+        raise ApiError, "Network error talking to the API: #{e.message}"
+      end
+    end
+
+    # Seconds to wait before a retry: prefer `Retry-After`, then the time until
+    # `X-RateLimit-Reset`, clamped to [1, @max_retry_wait].
+    def retry_delay(headers)
+      retry_after = header(headers, "Retry-After").to_i
+      return clamp_delay(retry_after) if retry_after.positive?
+
+      reset = header(headers, "X-RateLimit-Reset").to_i
+      return clamp_delay(reset - Time.now.to_i) if reset.positive?
+
+      1
+    end
+
+    def clamp_delay(seconds)
+      seconds.clamp(1, @max_retry_wait)
+    end
+
+    def header(headers, name)
+      return nil unless headers
+
+      headers[name] || headers[name.downcase]
+    end
+
+    # Walk `next` links, appending records to `records` in place, until the
+    # limit is reached, there is no next page, a page comes back empty, or the
+    # max-pages backstop trips. Returns the {Result} of the last page fetched.
+    def follow_pages(response, records, limit:)
+      current = response
+      last = Result.from_response(response)
+      pages = 1
+
+      loop do
+        break if limit && records.length >= limit
+
+        nxt = current&.relations&.[](:next)
+        break unless nxt
+
+        # We have another page to fetch but have hit the backstop — warn only
+        # here (i.e. when data is genuinely being left behind), never when the
+        # page count merely equals @max_pages on a fully-fetched collection.
+        if pages >= @max_pages
+          warn_truncated(pages)
+          break
+        end
+
+        current = fetch_next(nxt)
+        pages += 1
+        page_result = Result.from_response(current)
+        break if page_result.records.empty?
+
+        records.concat(page_result.records)
+        last = page_result
+      end
+
+      last
+    end
+
+    def member_path(path, id)
+      "#{path}/#{id}"
+    end
+
+    def warn_truncated(pages)
+      warn("warning: stopped after #{pages} pages (max-pages #{@max_pages}); " \
+           "results may be truncated — raise --max-pages to fetch more")
+    end
+
+    # Add the configured account_id to a query unless the caller set one.
+    def with_account_scope(query)
+      return query if @account_id.nil? || @account_id.to_s.empty?
+      return query if query.key?("account_id") || query.key?(:account_id)
+
+      query.merge("account_id" => @account_id)
+    end
+
+    def wrap_body(resource_key, attributes)
+      case attributes
+      when Array
+        { resource_key => attributes }
+      when Hash
+        return attributes if attributes.key?(resource_key) || attributes.key?(resource_key.to_sym)
+
+        { resource_key => [attributes] }
+      else
+        raise UsageError, "Request body must be a JSON object or array of objects."
+      end
+    end
+
+    def stringify(query)
+      (query || {}).each_with_object({}) do |(k, v), acc|
+        next if v.nil?
+
+        acc[k.to_s] = v
+      end
+    end
+
+    # Accept full URLs, `/api/v3/...`, or bare paths and return a bare path.
+    def normalize_path(path)
+      p = path.to_s.strip
+      p = p.sub(%r{\Ahttps?://[^/]+}, "")
+      p = p.sub(%r{\A/}, "")
+      p.sub(%r{\Aapi/v3/}, "")
+    end
+
+    def build_logger(verbose)
+      return nil unless verbose
+
+      logger = Logger.new($stderr)
+      logger.level = Logger::DEBUG
+      # The API gem's logger middleware dumps request/response headers verbatim,
+      # which includes `Authorization: Bearer <token>` — scrub before writing.
+      logger.formatter = lambda do |severity, _time, prog, msg|
+        label = prog ? "#{prog}: " : ""
+        "[smily #{severity.downcase}] #{label}#{Redaction.scrub(msg)}\n"
+      end
+      logger
+    end
+  end
+end