smily_cli 0.1.0

data/lib/smily_cli/config.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module SmilyCli
+  # On-disk configuration: a YAML file holding one or more named profiles, each
+  # a bag of credentials/settings (token, base_url, refresh_token, client_id,
+  # client_secret, ...). Precedence between file, environment and flags lives in
+  # {Context}; this class only owns reading and writing the file.
+  #
+  # File shape:
+  #   current_profile: default
+  #   profiles:
+  #     default:
+  #       token: "..."
+  #       base_url: "https://www.bookingsync.com"
+  class Config
+    # Keys that are meaningful inside a profile. Unknown keys are preserved on
+    # save but this list drives validation and `config set` completion.
+    KNOWN_KEYS = %w[
+      token base_url refresh_token client_id client_secret redirect_uri
+      scope account_id mcp_token mcp_url
+    ].freeze
+
+    DEFAULT_PROFILE = "default"
+
+    # @return [String] absolute path to the config file backing this instance
+    attr_reader :path
+
+    # Resolve the default config path, honoring `SMILY_CONFIG` (full path),
+    # then `XDG_CONFIG_HOME`, then `~/.config`.
+    #
+    # @return [String]
+    def self.default_path
+      return ENV["SMILY_CONFIG"] if ENV["SMILY_CONFIG"] && !ENV["SMILY_CONFIG"].empty?
+
+      base = ENV.fetch("XDG_CONFIG_HOME", nil)
+      base = File.join(Dir.home, ".config") if base.nil? || base.empty?
+      File.join(base, "smily", "config.yml")
+    end
+
+    # Load configuration from `path` (missing file yields an empty config).
+    #
+    # @param path [String]
+    # @return [Config]
+    def self.load(path = default_path)
+      new(path)
+    end
+
+    # @param path [String]
+    def initialize(path = self.class.default_path)
+      @path = path
+      @data = read
+    end
+
+    # @return [Boolean] whether the backing file exists on disk
+    def exist?
+      File.exist?(path)
+    end
+
+    # Name of the active profile: explicit `current_profile` or DEFAULT_PROFILE.
+    # @return [String]
+    def current_profile_name
+      @data["current_profile"] || DEFAULT_PROFILE
+    end
+
+    # @param name [String]
+    def current_profile_name=(name)
+      @data["current_profile"] = name.to_s
+    end
+
+    # @return [Array<String>] sorted profile names present in the file
+    def profile_names
+      profiles.keys.sort
+    end
+
+    # Fetch a profile's settings hash (never nil).
+    #
+    # @param name [String, nil] defaults to the current profile
+    # @return [Hash{String=>Object}]
+    def profile(name = current_profile_name)
+      profiles[name.to_s] || {}
+    end
+
+    # @param name [String, nil]
+    # @return [Boolean]
+    def profile?(name = current_profile_name)
+      profiles.key?(name.to_s)
+    end
+
+    # Set a single key on a profile (creating the profile if needed).
+    #
+    # @param key [String, Symbol]
+    # @param value [Object]
+    # @param profile [String]
+    # @return [void]
+    def set(key, value, profile: current_profile_name)
+      profiles[profile.to_s] ||= {}
+      profiles[profile.to_s][key.to_s] = value
+    end
+
+    # Remove a key from a profile.
+    #
+    # @return [Object, nil] the removed value
+    def unset(key, profile: current_profile_name)
+      (profiles[profile.to_s] || {}).delete(key.to_s)
+    end
+
+    # Delete an entire profile.
+    #
+    # @param name [String]
+    # @return [Hash, nil] the removed profile
+    def delete_profile(name)
+      profiles.delete(name.to_s)
+    end
+
+    # Persist the config to {#path}, creating the directory and locking down
+    # permissions (the file holds secrets).
+    #
+    # @return [String] the path written
+    def save
+      dir = File.dirname(path)
+      created_dir = !File.directory?(dir)
+      FileUtils.mkdir_p(dir)
+      # Only tighten a directory we created, so we never clobber the perms of a
+      # pre-existing (possibly shared) parent.
+      File.chmod(0o700, dir) if created_dir
+      # Create with 0600 from the start so there is no world-readable window;
+      # re-chmod covers a pre-existing file whose perms may have drifted.
+      File.open(path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |file|
+        file.write(YAML.dump(prune(@data)))
+      end
+      File.chmod(0o600, path)
+      path
+    end
+
+    # @return [Hash{String=>Hash}] the profiles map (mutable)
+    def profiles
+      @data["profiles"] ||= {}
+    end
+
+    private
+
+    def read
+      return {} unless File.exist?(path)
+
+      parsed = YAML.safe_load_file(path, permitted_classes: [], aliases: false)
+      data = parsed.is_a?(Hash) ? parsed : {}
+      validate_shape!(data)
+      data
+    rescue Psych::SyntaxError => e
+      raise ConfigurationError, "Config file #{path} is not valid YAML: #{e.message}"
+    rescue Psych::Exception => e
+      # A structurally valid YAML file can still carry a value safe_load refuses
+      # (a bare date/time -> DisallowedClass, an alias -> AliasesNotEnabled).
+      # Surface it as a clean CLI error instead of an uncaught Psych backtrace.
+      raise ConfigurationError,
+            "Config file #{path} has an unsupported value (#{e.message}). " \
+            "Quote any value that looks like a date, time, or symbol."
+    end
+
+    # Guard against a well-formed-YAML-but-wrong-shape config (e.g. a hand edit
+    # leaving `profiles: []`), which would otherwise blow up with a raw
+    # NoMethodError deep in a later command instead of a clean CLI error.
+    def validate_shape!(data)
+      profiles = data["profiles"]
+      return if profiles.nil?
+
+      unless profiles.is_a?(Hash)
+        raise ConfigurationError,
+              "Config file #{path}: `profiles` must be a mapping of name => settings, got #{profiles.class}."
+      end
+
+      profiles.each do |name, settings|
+        next if settings.nil? || settings.is_a?(Hash)
+
+        raise ConfigurationError,
+              "Config file #{path}: profile #{name.inspect} must be a mapping of settings, got #{settings.class}."
+      end
+    end
+
+    # Drop empty profiles/containers so we never write noise.
+    def prune(data)
+      copy = data.dup
+      if copy["profiles"].is_a?(Hash)
+        copy["profiles"] = copy["profiles"].reject { |_, v| v.nil? || (v.respond_to?(:empty?) && v.empty?) }
+      end
+      copy
+    end
+  end
+end

data/lib/smily_cli/context.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module SmilyCli
+  # Resolves effective settings for a command from three layers, highest wins:
+  #
+  #   1. explicit flags (the Thor `options` hash)
+  #   2. environment variables (`SMILY_*`, with `BOOKINGSYNC_*` fallbacks)
+  #   3. the selected config profile
+  #
+  # A Context is the single object a command needs: it exposes the resolved
+  # token/base_url/output settings and can build a {Client}. It never performs
+  # I/O beyond reading the config file.
+  class Context
+    DEFAULT_BASE_URL = "https://www.bookingsync.com"
+    OUTPUT_FORMATS = %w[table json yaml csv ndjson jsonl].freeze
+    DEFAULT_MAX_PAGES = 1000
+
+    # @return [Config]
+    attr_reader :config
+    # @return [Hash] the raw flags this context was built from
+    attr_reader :options
+
+    # Build a Context from a Thor options hash.
+    #
+    # @param options [Hash] parsed CLI options (string or symbol keys)
+    # @param config [Config] loaded configuration
+    # @return [Context]
+    def self.from(options, config: nil)
+      opts = options.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+      cfg = config || Config.load
+      if (profile = opts["profile"] || ENV.fetch("SMILY_PROFILE", nil))
+        cfg.current_profile_name = profile
+      end
+      new(opts, cfg)
+    end
+
+    # @param options [Hash{String=>Object}]
+    # @param config [Config]
+    def initialize(options, config)
+      @options = options
+      @config = config
+      apply_color_setting
+    end
+
+    # @return [String] the profile these settings resolve against
+    def profile_name
+      config.current_profile_name
+    end
+
+    # The OAuth access token. Resolution order applies.
+    #
+    # @return [String, nil]
+    def token
+      resolve("token", env: %w[SMILY_TOKEN BOOKINGSYNC_TOKEN SMILY_ACCESS_TOKEN])
+    end
+
+    # Like {#token} but raises when nothing is configured.
+    #
+    # @return [String]
+    def token!
+      token || raise(ConfigurationError, <<~MSG.strip)
+        No API token configured. Provide one with --token, set SMILY_TOKEN, or run:
+          smily config set token <ACCESS_TOKEN>
+        You can obtain a token with `smily auth client-credentials` or `smily auth exchange`.
+      MSG
+    end
+
+    # API base URL (no trailing `/api/v3`; the client appends that).
+    #
+    # @return [String]
+    def base_url
+      resolve("base_url", env: %w[SMILY_BASE_URL BOOKINGSYNC_URL]) || DEFAULT_BASE_URL
+    end
+
+    # Account to scope requests to. Primarily for Client-Credentials-flow tokens
+    # that span multiple accounts; sent as the `account_id` query parameter (REST)
+    # or `account_id` tool argument (MCP).
+    #
+    # @return [String, nil]
+    def account_id
+      resolve("account_id", env: %w[SMILY_ACCOUNT_ID BOOKINGSYNC_ACCOUNT_ID])
+    end
+
+    # The MCP-mode access token (distinct from the REST API token).
+    #
+    # @return [String, nil]
+    def mcp_token
+      resolve("mcp_token", env: %w[SMILY_MCP_TOKEN])
+    end
+
+    # @return [String]
+    def mcp_token!
+      mcp_token || raise(ConfigurationError, <<~MSG.strip)
+        No MCP token configured. Provide one with --mcp-token, set SMILY_MCP_TOKEN, or run:
+          smily mcp login --token <MCP_TOKEN>
+      MSG
+    end
+
+    # The MCP server endpoint. Defaults to `<base_url>/mcp`, which is where a
+    # BookingSync app mounts its MCP server; override for other servers.
+    #
+    # @return [String]
+    def mcp_url
+      explicit = resolve("mcp_url", env: %w[SMILY_MCP_URL])
+      return explicit if explicit && !explicit.empty?
+
+      URI.join("#{base_url.chomp('/')}/", "mcp").to_s
+    end
+
+    # The output format explicitly requested via `--output` or `SMILY_OUTPUT`,
+    # validated, or nil when none was given. Commands whose default isn't the
+    # usual table/json (e.g. `api`, which defaults to the raw envelope) use this
+    # so they still honor an explicit flag/env choice.
+    #
+    # @return [String, nil]
+    def requested_output_format
+      raw = (options["output"] || ENV.fetch("SMILY_OUTPUT", nil))&.to_s
+      return nil if raw.nil? || raw.empty?
+
+      validate_output_format!(raw)
+    end
+
+    # Chosen output format. Defaults to `table` on a TTY, `json` otherwise, so
+    # piping produces machine-readable output without a flag.
+    #
+    # @return [String]
+    def output_format
+      requested_output_format || default_output_format
+    end
+
+    # Field selection shared between sparse fieldsets (sent to the API) and
+    # column selection (used by table/csv). Accepts repeated flags and/or
+    # comma-separated values.
+    #
+    # @return [Array<String>, nil]
+    def fields
+      raw = options["fields"]
+      return nil if raw.nil?
+
+      list = Array(raw).flat_map { |v| v.to_s.split(",") }.map(&:strip).reject(&:empty?)
+      list.empty? ? nil : list
+    end
+
+    # @return [Boolean]
+    def verbose?
+      truthy(options["verbose"]) || truthy(ENV.fetch("SMILY_VERBOSE", nil))
+    end
+
+    # @return [Boolean]
+    def quiet?
+      truthy(options["quiet"])
+    end
+
+    # @return [Boolean] whether ANSI color is active for this run
+    def color?
+      Color.enabled
+    end
+
+    # Values used to seed OAuth commands, pulled from flags then profile.
+    # @return [String, nil]
+    def client_id     = resolve("client_id", env: %w[SMILY_CLIENT_ID])
+    # @return [String, nil]
+    def client_secret = resolve("client_secret", env: %w[SMILY_CLIENT_SECRET])
+    # @return [String, nil]
+    def refresh_token = resolve("refresh_token", env: %w[SMILY_REFRESH_TOKEN])
+
+    # Build an API client from these settings.
+    #
+    # Hard backstop for auto-pagination (`--all` / `--limit`), so a server that
+    # keeps advertising a `next` link can't loop forever.
+    #
+    # @return [Integer]
+    def max_pages
+      raw = resolve("max_pages", env: %w[SMILY_MAX_PAGES])
+      value = raw.to_i
+      value.positive? ? value : DEFAULT_MAX_PAGES
+    end
+
+    # Number of times to retry a `429 Too Many Requests` (waiting for the
+    # rate-limit window each time). Off by default, like the GitHub CLI.
+    #
+    # @return [Integer]
+    def retries
+      resolve("retry", env: %w[SMILY_RETRY]).to_i.clamp(0, 10)
+    end
+
+    # @return [Client]
+    def client
+      warn_insecure_transport(base_url)
+      Client.new(
+        token: token!,
+        base_url: base_url,
+        account_id: account_id,
+        max_pages: max_pages,
+        retries: retries,
+        verbose: verbose?
+      )
+    end
+
+    # An OAuth helper bound to this context's base URL.
+    #
+    # @return [OAuth]
+    def oauth
+      warn_insecure_transport(base_url)
+      OAuth.new(base_url: base_url, verbose: verbose?)
+    end
+
+    # An MCP client for the configured MCP server and token.
+    #
+    # @return [Mcp::Client]
+    def mcp_client
+      warn_insecure_transport(mcp_url)
+      Mcp::Client.new(token: mcp_token!, url: mcp_url, verbose: verbose?)
+    end
+
+    private
+
+    # flag ? env ? profile
+    def resolve(key, env: [])
+      flag = options[key]
+      return flag if present?(flag)
+
+      env.each do |name|
+        value = ENV.fetch(name, nil)
+        return value if present?(value)
+      end
+
+      profile_value = config.profile[key]
+      present?(profile_value) ? profile_value : nil
+    end
+
+    def validate_output_format!(fmt)
+      return fmt if OUTPUT_FORMATS.include?(fmt)
+
+      raise UsageError, "Unknown output format #{fmt.inspect}. Valid: #{OUTPUT_FORMATS.join(', ')}."
+    end
+
+    def default_output_format
+      $stdout.respond_to?(:tty?) && $stdout.tty? ? "table" : "json"
+    end
+
+    def apply_color_setting
+      if truthy(options["no_color"]) || (ENV.fetch("NO_COLOR", nil) && !ENV["NO_COLOR"].empty?)
+        Color.enabled = false
+      elsif options.key?("color") && truthy(options["color"])
+        Color.enabled = true
+      end
+    end
+
+    # Warn (once, to stderr) when credentials would travel over a non-HTTPS
+    # endpoint. Like the GitHub CLI, we warn rather than hard-refuse so local
+    # test servers still work.
+    def warn_insecure_transport(url)
+      return if quiet?
+
+      scheme = URI(url).scheme
+      return if scheme == "https"
+
+      label = scheme.nil? || scheme.empty? ? "an insecure" : scheme.upcase
+      warn(Color.yellow("warning: sending credentials over #{label} to #{url} — prefer HTTPS"))
+    rescue URI::InvalidURIError
+      nil
+    end
+
+    def present?(value)
+      !value.nil? && !(value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def truthy(value)
+      return false if value.nil?
+      return value if [true, false].include?(value)
+
+      %w[1 true yes on].include?(value.to_s.strip.downcase)
+    end
+  end
+end

data/lib/smily_cli/errors.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SmilyCli
+  # Base class for every error the CLI raises deliberately. Command handlers
+  # rescue this and print a clean, single-line message instead of a backtrace.
+  class Error < StandardError
+    # Process exit status to use when this error reaches the top level.
+    # @return [Integer]
+    def exit_status
+      1
+    end
+  end
+
+  # Raised when configuration/credentials are missing or malformed, e.g. no
+  # token could be resolved from flags, environment, or the config file.
+  class ConfigurationError < Error; end
+
+  # Raised when the user asks for something the CLI cannot satisfy: an unknown
+  # resource, a bad flag combination, unparseable `--data`, etc.
+  class UsageError < Error
+    def exit_status
+      2
+    end
+  end
+
+  # Raised when an MCP interaction fails: a JSON-RPC error envelope, a tool that
+  # returns `isError: true`, a missing session, or a transport failure.
+  class McpError < Error
+    # @return [Integer, nil] JSON-RPC error code, when present
+    attr_reader :code
+
+    # @param message [String]
+    # @param code [Integer, nil]
+    def initialize(message, code: nil)
+      super(message)
+      @code = code
+    end
+
+    def exit_status
+      # -32000 "Unauthorized", -32001 "Session not found" map to auth failures.
+      [-32_000, -32_001].include?(code) ? 3 : 1
+    end
+  end
+
+  # Raised when the API returns a non-success HTTP status. Carries the parsed
+  # status/body so callers can render a helpful message.
+  class ApiError < Error
+    # @return [Integer, nil] HTTP status code
+    attr_reader :status
+    # @return [Object, nil] parsed response body (Hash/Array) when JSON, else the raw string
+    attr_reader :body
+    # @return [Hash] response headers
+    attr_reader :headers
+
+    # Build an {ApiError} from a {BookingSync::API::Error}.
+    #
+    # @param error [BookingSync::API::Error]
+    # @return [ApiError]
+    def self.from_api(error)
+      status  = error.respond_to?(:status) ? error.status : nil
+      headers = error.respond_to?(:headers) ? error.headers : {}
+      body    = error.respond_to?(:body) ? error.body : nil
+      new(summary(status, body), status: status, body: parse_body(body), headers: headers || {})
+    end
+
+    # @param message [String]
+    # @param status [Integer, nil]
+    # @param body [Object, nil]
+    # @param headers [Hash]
+    def initialize(message, status: nil, body: nil, headers: {})
+      super(message)
+      @status = status
+      @body = body
+      @headers = headers || {}
+    end
+
+    def exit_status
+      case status
+      when 401, 403 then 3
+      when 404      then 4
+      when 429      then 5
+      else 1
+      end
+    end
+
+    # Best-effort extraction of API error detail into a one-line summary.
+    #
+    # @param status [Integer, nil]
+    # @param raw_body [String, nil]
+    # @return [String]
+    def self.summary(status, raw_body)
+      parsed = parse_body(raw_body)
+      detail = extract_detail(parsed)
+      label = status ? "API request failed (HTTP #{status})" : "API request failed"
+      detail ? "#{label}: #{detail}" : label
+    end
+
+    # @api private
+    def self.parse_body(raw_body)
+      return raw_body unless raw_body.is_a?(String)
+      return nil if raw_body.empty?
+
+      JSON.parse(raw_body)
+    rescue JSON::ParserError
+      raw_body
+    end
+
+    # Pull a human message out of the many shapes BookingSync error bodies take:
+    #   { "errors": [ { "title": ..., "detail": ... } ] }
+    #   { "errors": { "field": ["msg"] } }
+    #   { "error": "..." } / { "error_description": "..." } (OAuth)
+    # @api private
+    def self.extract_detail(parsed)
+      return parsed if parsed.is_a?(String)
+      return nil unless parsed.is_a?(Hash)
+
+      if (oauth = parsed["error_description"] || parsed["error"])
+        return oauth.to_s
+      end
+
+      errors = parsed["errors"] || parsed["error"]
+      case errors
+      when Array
+        errors.map { |e| error_line(e) }.compact.join("; ")
+      when Hash
+        errors.map { |field, msgs| "#{field}: #{Array(msgs).join(', ')}" }.join("; ")
+      when String
+        errors
+      end
+    end
+
+    # @api private
+    def self.error_line(entry)
+      return entry if entry.is_a?(String)
+      return nil unless entry.is_a?(Hash)
+
+      [entry["title"], entry["detail"]].compact.uniq.join(" - ")
+    end
+    private_class_method :error_line
+  end
+end