shipeasy-sdk 1.7.0 → 2.1.0

data/lib/shipeasy/config.rb

@@ -1,7 +1,7 @@
 # Single configuration object for the Shipeasy gem.
 #
 # Covers both subsystems:
-#   - SDK / experimentation (api_key, base_url) — drives FlagsClient
+#   - SDK / experimentation (api_key, base_url) — drives Engine
 #   - i18n / string manager (public_key, profile, cdn_base_url, ...) — drives
 #     the Rails view helpers and label fetcher
 #
@@ -14,7 +14,7 @@
 #   end
 #
 # Anything not set falls back to the defaults below. The same Shipeasy.config
-# is read by FlagsClient and the Rails helpers, so there is one place to
+# is read by Engine and the Rails helpers, so there is one place to
 # point environment variables at.
 
 module Shipeasy
@@ -22,6 +22,39 @@ module Shipeasy
     # ---- experimentation / SDK ----
     attr_accessor :api_key, :base_url
 
+    # Advanced `configure` options — threaded into the global Engine `configure`
+    # builds, so callers never construct an Engine themselves:
+    #   - env (default "prod"): deployment tag on see() events + usage telemetry.
+    #   - disable_telemetry (default false): opt out of per-eval usage telemetry.
+    #   - telemetry_url: override the telemetry endpoint (rarely needed).
+    #   - private_attributes: attribute keys stripped from every outbound event
+    #     before it leaves the process (they still drive targeting locally).
+    #   - sticky_store: pin a user's experiment group across re-buckets.
+    attr_accessor :env, :disable_telemetry, :telemetry_url,
+                  :private_attributes, :sticky_store
+
+    # Fetch lifecycle for the global engine `configure` builds:
+    #   - init (default true): fire a one-shot fetch fire-and-forget so the first
+    #     `Shipeasy::Client.new(user).get_flag(...)` resolves against real rules
+    #     (ideal for serverless / short-lived processes).
+    #   - poll (default false): start the background poll (initial fetch +
+    #     periodic refresh) for a long-running server, so flags stay fresh
+    #     without a redeploy. Configuration owns the lifecycle — you never call
+    #     `engine.init` yourself.
+    attr_accessor :init, :poll
+
+    # Optional transform from YOUR user object (any shape) to the Shipeasy
+    # attribute hash every flag/experiment evaluation uses. A callable
+    # (lambda/proc or anything responding to #call). Default = identity (the
+    # user object is assumed to already BE the attribute hash). Runs once, in
+    # the Shipeasy::Client constructor.
+    #
+    #   Shipeasy.configure do |c|
+    #     c.api_key    = ENV["SHIPEASY_SERVER_KEY"]
+    #     c.attributes = ->(u) { { "user_id" => u.id, "plan" => u.plan } }
+    #   end
+    attr_accessor :attributes
+
     # ---- i18n / string manager ----
     attr_accessor :public_key, :profile, :default_chunk,
                   :cdn_base_url, :loader_url,
@@ -29,6 +62,14 @@ module Shipeasy
 
     def initialize
       @base_url             = "https://edge.shipeasy.dev"
+      @attributes           = nil
+      @init                 = true
+      @poll                 = false
+      @env                  = "prod"
+      @disable_telemetry    = false
+      @telemetry_url        = nil
+      @private_attributes   = nil
+      @sticky_store         = nil
 
       @profile              = "default"
       @default_chunk        = "index"
@@ -45,8 +86,225 @@ module Shipeasy
       @config ||= Configuration.new
     end
 
+    # Configure the gem once at boot. In addition to populating the shared
+    # Configuration, this builds and registers the ONE global Shipeasy::Engine
+    # (first-config-wins) from the api_key/base_url and kicks off its one-shot
+    # fetch (fire-and-forget) so `Shipeasy::Client.new(user).get_flag(...)`
+    # resolves against real rules with no explicit init call.
+    #
+    #   Shipeasy.configure do |c|
+    #     c.api_key    = ENV["SHIPEASY_SERVER_KEY"]
+    #     c.attributes = ->(u) { { "user_id" => u.id, "plan" => u.plan } }
+    #   end
+    #
+    #   Shipeasy::Client.new(current_user).get_flag("new_checkout")
+    #
+    # Long-running servers that also want the background poll can call
+    # `Shipeasy.engine.init` after configure.
     def configure
       yield config
+      register_engine!(config) if config.api_key
+      config
+    end
+
+    # The resolved attributes transform (callable). Default = identity, so a
+    # user object that is already the attribute hash is used verbatim.
+    def attributes_transform
+      transform = config.attributes
+      if transform.nil?
+        ->(user) { user }
+      elsif transform.respond_to?(:call)
+        transform
+      else
+        raise Error, "Shipeasy.configure { |c| c.attributes = … } must be a callable (e.g. a lambda)"
+      end
+    end
+
+    # The single global engine registered by configure, or nil if configure has
+    # not run (or ran without an api_key). Shipeasy::Client reads this.
+    def engine
+      pid = Process.pid
+      if @engine && @engine_pid != pid
+        # Post-fork: the parent's poll thread didn't survive. Rebuild lazily
+        # from the stored config in this child process.
+        @engine = nil
+        register_engine!(config) if config.api_key
+      end
+      @engine
+    end
+
+    # Build + register the one global engine (first-config-wins). Kicks off the
+    # configured fetch lifecycle (one-shot by default; the background poll when
+    # `c.poll = true`) fire-and-forget. Idempotent within a process.
+    def register_engine!(cfg)
+      return @engine if @engine && @engine_pid == Process.pid
+      @engine_pid = Process.pid
+      engine = Engine.new(
+        api_key:            cfg.api_key,
+        base_url:           cfg.base_url,
+        env:                cfg.env,
+        disable_telemetry:  cfg.disable_telemetry,
+        telemetry_url:      cfg.telemetry_url,
+        private_attributes: cfg.private_attributes,
+        sticky_store:       cfg.sticky_store,
+      )
+      @engine = engine
+      # Capture +engine+ in the closure (not the @engine ivar, which a concurrent
+      # reset/reconfigure could nil out before the thread runs).
+      if cfg.poll
+        Thread.new do
+          engine.init   # initial fetch + background poll thread
+        rescue => e
+          warn "[shipeasy] configure(poll) background poll failed: #{e.message}"
+        end
+      elsif cfg.init
+        Thread.new do
+          engine.init_once
+        rescue => e
+          warn "[shipeasy] configure() one-shot fetch failed: #{e.message}"
+        end
+      end
+      engine
+    end
+
+    # ---- configure() test/offline siblings -----------------------------------
+    #
+    # Drop-in siblings of `Shipeasy.configure` for tests and offline evaluation.
+    # Unlike `configure` (first-config-wins), these REPLACE the registered global
+    # engine, so a suite can reconfigure between cases. After either, you read the
+    # same way: `Shipeasy::Client.new(user)`.
+
+    # Configure Shipeasy in TEST MODE — no api key, zero network, ever. Seed the
+    # values your code under test should see via the override args, then read
+    # through the ordinary `Shipeasy::Client.new(user)`:
+    #
+    #   Shipeasy.configure_for_testing(flags: { "new_checkout" => true })
+    #   Shipeasy::Client.new({ "user_id" => "u_1" }).get_flag("new_checkout") # => true
+    #
+    #   flags:       { name => bool }              forced get_flag results
+    #   configs:     { name => value }             forced get_config results
+    #   experiments: { name => [group, params] }   forced enrolments
+    #   attributes:  same transform as configure (default identity)
+    def configure_for_testing(flags: nil, configs: nil, experiments: nil, attributes: nil)
+      engine = Engine.for_testing
+      apply_overrides(engine, flags, configs, experiments)
+      install_global_engine(engine, attributes)
+    end
+
+    # Configure Shipeasy OFFLINE — evaluate the REAL rules from an in-memory
+    # snapshot or a JSON file, with no network. Provide exactly one source:
+    #
+    #   snapshot: { "flags" => <body of /sdk/flags>, "experiments" => <body of /sdk/experiments> }
+    #   path:     "snapshot.json"   (a JSON file of the same shape)
+    #
+    # Optional flags/configs/experiments overrides layer on top (same shapes as
+    # configure_for_testing). Replaces any previously-configured engine.
+    def configure_for_offline(snapshot: nil, path: nil, flags: nil, configs: nil, experiments: nil, attributes: nil)
+      engine =
+        if path
+          Engine.from_file(path)
+        elsif snapshot
+          s = snapshot.transform_keys(&:to_s)
+          Engine.from_snapshot(flags: s["flags"], experiments: s["experiments"])
+        else
+          raise Error, "Shipeasy.configure_for_offline requires snapshot: or path:"
+        end
+      apply_overrides(engine, flags, configs, experiments)
+      install_global_engine(engine, attributes)
+    end
+
+    # ---- package-level helpers (so callers never name the Engine) -------------
+
+    # On-the-spot overrides layered on top of whatever configure_for_testing /
+    # configure_for_offline (or a live configure) set up — they win over the blob
+    # until clear_overrides. Require a prior configure* call.
+    def override_flag(name, value)
+      require_engine("override_flag").override_flag(name, value)
+      nil
+    end
+
+    def override_config(name, value)
+      require_engine("override_config").override_config(name, value)
+      nil
+    end
+
+    def override_experiment(name, group, params)
+      require_engine("override_experiment").override_experiment(name, group, params)
+      nil
+    end
+
+    # Drop EVERY override — including the seed from configure_for_testing (test
+    # mode has no blob beneath); under configure_for_offline it reverts to the
+    # snapshot.
+    def clear_overrides
+      require_engine("clear_overrides").clear_overrides
+      nil
+    end
+
+    # Register a poll listener fired after a background poll fetches NEW data
+    # (HTTP 200, not 304). Requires configure(poll: true). Returns an unsubscribe
+    # proc. Accepts a block or any callable.
+    def on_change(callable = nil, &block)
+      require_engine("on_change").on_change(callable, &block)
+    end
+
+    # SSR tag helpers — delegate to the configured global engine, so you never
+    # touch it. i18n_script_tag carries the PUBLIC client key (not the server
+    # key); bootstrap_script_tag embeds no key.
+    def i18n_script_tag(client_key, profile: "en:prod", base_url: nil)
+      require_engine("i18n_script_tag").i18n_script_tag(client_key, profile: profile, base_url: base_url)
+    end
+
+    def bootstrap_script_tag(user, anon_id: nil, i18n_profile: "en:prod", base_url: nil)
+      require_engine("bootstrap_script_tag").bootstrap_script_tag(
+        user, anon_id: anon_id, i18n_profile: i18n_profile, base_url: base_url
+      )
+    end
+
+    # see() structured error reporting — package-level, dispatched through the
+    # last-constructed default client (the engine configure built). Never raises
+    # into caller code; a call before any client exists warns and no-ops.
+    def see(problem)
+      Shipeasy::SDK.see(problem)
+    end
+
+    def see_violation(name)
+      Shipeasy::SDK.see_violation(name)
+    end
+
+    def control_flow_exception(err)
+      Shipeasy::SDK.control_flow_exception(err)
+    end
+
+    # Replace the registered global engine + attributes transform (used by the
+    # configure_for_* siblings — unlike configure, they replace so a test suite
+    # can reconfigure between cases). Returns the engine.
+    def install_global_engine(engine, attributes)
+      config.attributes = attributes
+      @engine = engine
+      @engine_pid = Process.pid
+      engine
+    end
+
+    # Apply the configure_for_* override args onto an engine.
+    def apply_overrides(engine, flags, configs, experiments)
+      (flags || {}).each { |name, value| engine.override_flag(name, value) }
+      (configs || {}).each { |name, value| engine.override_config(name, value) }
+      (experiments || {}).each do |name, spec|
+        group, params = spec   # spec is [group, params]
+        engine.override_experiment(name, group, params)
+      end
+    end
+
+    # The global engine, or raise a helpful error naming the package-level fn the
+    # caller used before any configure*.
+    def require_engine(fn_name)
+      e = engine
+      return e unless e.nil?
+
+      raise Error, "Shipeasy.#{fn_name} called before Shipeasy.configure " \
+                   "{ |c| c.api_key = … } (or configure_for_testing / " \
+                   "configure_for_offline). Call one once at app boot."
     end
 
     # Reset the config back to defaults — primarily for tests.
@@ -55,9 +313,12 @@ module Shipeasy
       @flags_pid = nil
       @flags&.destroy
       @flags = nil
+      @engine&.destroy
+      @engine = nil
+      @engine_pid = nil
     end
 
-    # Lazy, fork-safe singleton FlagsClient. The first call from each
+    # Lazy, fork-safe singleton Engine. The first call from each
     # process spawns a fresh client + poll thread — including post-fork
     # workers under Puma's preload_app!. Callers can `Shipeasy.flags.get_flag(...)`
     # straight from a controller without holding a constant or worrying
@@ -70,7 +331,12 @@ module Shipeasy
     #
     # The first request that touches `Shipeasy.flags.*` triggers init().
     # For serverless / Lambda where you want a single fetch with no thread,
-    # build the client explicitly: `Shipeasy::SDK::FlagsClient.new(...).init_once`.
+    # build the engine explicitly: `Shipeasy::Engine.new(...).init_once`.
+    #
+    # NOTE: this remains a separate, polling engine from the one configure()
+    # registers (Shipeasy.engine). New code should prefer the
+    # Shipeasy.configure + Shipeasy::Client.new(user) front door; `Shipeasy.flags`
+    # is retained for the legacy `Shipeasy.flags.get_flag(name, user)` style.
     def flags
       pid = Process.pid
       if @flags && @flags_pid != pid
@@ -81,7 +347,7 @@ module Shipeasy
       end
       @flags ||= begin
         @flags_pid = pid
-        client = SDK::FlagsClient.new(
+        client = Engine.new(
           api_key:  config.api_key,
           base_url: config.base_url,
         )

data/lib/shipeasy/{sdk/flags_client.rb → engine.rb}

@@ -3,15 +3,31 @@ require "uri"
 require "json"
 require "thread"
 require "cgi"
-require_relative "eval"
-require_relative "telemetry"
-require_relative "anon_id"
-require_relative "sticky_store"
-require_relative "see"
+require_relative "sdk/eval"
+require_relative "sdk/telemetry"
+require_relative "sdk/anon_id"
+require_relative "sdk/sticky_store"
+require_relative "sdk/see"
 
 module Shipeasy
-  module SDK
-    class FlagsClient
+  # The heavyweight engine: owns the api key, HTTP transport, the blob cache,
+  # the background poll timer, init/init_once, local overrides, track, and
+  # see()/default-client wiring. Was `Shipeasy::SDK::FlagsClient` before 2.0;
+  # renamed to a clean top-level `Shipeasy::Engine` when the lightweight
+  # user-bound `Shipeasy::Client` became the primary front door.
+  #
+  # Most apps never construct an Engine directly — `Shipeasy.configure { … }`
+  # builds and registers the one global engine for you. Construct one explicitly
+  # only for advanced/serverless flows (multiple keys, offline snapshots).
+  class Engine
+      # Internal collaborators still live under Shipeasy::SDK; alias them so the
+      # body below can keep referring to them unqualified after the class moved
+      # out from under the SDK namespace.
+      Eval      = Shipeasy::SDK::Eval
+      Telemetry = Shipeasy::SDK::Telemetry
+      AnonId    = Shipeasy::SDK::AnonId
+      See       = Shipeasy::SDK::See
+
       DEFAULT_BASE_URL = "https://edge.shipeasy.dev"
       # CDN origin serving the static loader scripts (/sdk/bootstrap.js,
       # /sdk/i18n/loader.js) — distinct from the edge API the blobs are fetched from.
@@ -34,7 +50,7 @@ module Shipeasy
         @sticky_store = sticky_store
         # Test mode: no network, ever. init/init_once/track become no-ops and
         # evaluation answers come purely from local overrides. Built via the
-        # FlagsClient.for_testing factory; see clear_overrides / override_*.
+        # Engine.for_testing factory; see clear_overrides / override_*.
         @test_mode   = test_mode
         # Per-evaluation usage telemetry. ON by default; pass
         # disable_telemetry: true to opt out. See telemetry.rb.
@@ -74,15 +90,19 @@ module Shipeasy
 
       # Build a no-network, immediately-usable client for tests. Telemetry is
       # disabled, init/init_once/track are no-ops (never fetch), and no api_key
-      # is required. Seed it with override_flag / override_config /
+      # is required. The client is immediately READY against an empty blob (so a
+      # missing gate resolves FLAG_NOT_FOUND, not CLIENT_NOT_READY — parity with
+      # the other SDKs). Seed it with override_flag / override_config /
       # override_experiment, then call the normal getters.
       def self.for_testing(env: "prod")
-        new(
+        client = new(
           api_key: "test",
           env: env,
           disable_telemetry: true,
           test_mode: true,
         )
+        client.send(:load_snapshot, {}, {})
+        client
       end
 
       # Build an offline client from a JSON snapshot file. The file holds the
@@ -275,6 +295,32 @@ module Shipeasy
         result
       end
 
+      # Public hook for the bound Shipeasy::Client: normalise an attribute hash
+      # and apply the request-scoped anonymous_id merge ONCE, at Client
+      # construction, exactly as every per-call getter does internally.
+      def bind_attributes(user)
+        with_anon_id(user)
+      end
+
+      # Read a killswitch from the cached flags blob. Without +switch_key+,
+      # returns true when the whole killswitch is killed. With +switch_key+,
+      # returns true when that specific named per-key switch is on — and when
+      # the key isn't configured on the killswitch, FALLS BACK to the top-level
+      # value (so an unconfigured key behaves exactly like the no-key call).
+      # Unknown killswitches return false. Not user-scoped.
+      def get_killswitch(name, switch_key = nil)
+        @telemetry.emit("ks", name)
+        ks = @mutex.synchronize { @flags_blob&.dig("killswitches", name.to_s) }
+        return false unless ks
+        unless switch_key.nil?
+          switches = ks["switches"] || {}
+          key = switch_key.to_s
+          return Eval.enabled?(switches[key]) if switches.key?(key)
+          # key not configured → fall through to the top-level value
+        end
+        Eval.enabled?(ks["killed"])
+      end
+
       # Batch-evaluate every loaded gate, config and experiment for +user+ into
       # a bootstrap payload (+{ "flags" => ..., "configs" => ..., "experiments"
       # => ..., "killswitches" => ... }+) keyed to match the browser SDK's
@@ -576,6 +622,5 @@ module Shipeasy
         http.read_timeout = 10
         http.post(uri.request_uri, body, { "X-SDK-Key" => @api_key, "Content-Type" => "text/plain" })
       end
-    end
   end
 end

data/lib/shipeasy/sdk/anon_id.rb

@@ -33,7 +33,7 @@ module Shipeasy
       end
 
       # The anon id RackMiddleware resolved for the current request, or nil when
-      # no middleware ran (e.g. a background job). FlagsClient falls back to this
+      # no middleware ran (e.g. a background job). The Engine falls back to this
       # as the default anonymous_id, so evaluations need no per-call wiring.
       def current
         Thread.current[THREAD_KEY]

data/lib/shipeasy/sdk/openfeature.rb

@@ -11,18 +11,17 @@
 #   require "open_feature/sdk"
 #   require "shipeasy/sdk/openfeature"
 #
-#   client = Shipeasy::SDK::FlagsClient.new(api_key: ENV.fetch("SHIPEASY_SERVER_KEY"))
-#   client.init
+#   Shipeasy.configure { |c| c.api_key = ENV.fetch("SHIPEASY_SERVER_KEY"); c.poll = true }
 #
 #   OpenFeature::SDK.configure do |config|
-#     config.set_provider(Shipeasy::OpenFeature::Provider.new(client))
+#     config.set_provider(Shipeasy::OpenFeature::Provider.new) # uses the configured global
 #   end
 #
 #   of = OpenFeature::SDK.build_client
 #   on = of.fetch_boolean_value(flag_key: "new_checkout", default_value: false,
 #                               evaluation_context: OpenFeature::SDK::EvaluationContext.new(targeting_key: "u1"))
 #
-# Pure adapter over `FlagsClient` — no change to evaluation. Boolean values map
+# Pure adapter over `Shipeasy::Engine` — no change to evaluation. Boolean values map
 # onto gates (`get_flag_detail`); string/number/integer/float/object map onto
 # dynamic configs (`get_config`).
 
@@ -37,12 +36,14 @@ rescue LoadError => e
                    "gem \"openfeature-sdk\". (#{e.message})"
 end
 
-require_relative "flags_client"
+require_relative "../engine"
+require_relative "../config"
+require_relative "../client"
 
 module Shipeasy
   module OpenFeature
     # Shipeasy OpenFeature provider (server paradigm). Wraps a
-    # `Shipeasy::SDK::FlagsClient`; evaluation is local against the cached blob,
+    # `Shipeasy::Engine`; evaluation is local against the cached blob,
     # so resolution is effectively synchronous.
     class Provider
       OF = ::OpenFeature::SDK::Provider
@@ -56,17 +57,27 @@ module Shipeasy
       #   FLAG_NOT_FOUND   → ERROR (error_code FLAG_NOT_FOUND)
       #   CLIENT_NOT_READY → ERROR (error_code PROVIDER_NOT_READY)
       REASON_MAP = {
-        Shipeasy::SDK::FlagsClient::REASON_RULE_MATCH       => [OF::Reason::TARGETING_MATCH, nil],
-        Shipeasy::SDK::FlagsClient::REASON_DEFAULT          => [OF::Reason::DEFAULT, nil],
-        Shipeasy::SDK::FlagsClient::REASON_OFF              => [OF::Reason::DISABLED, nil],
-        Shipeasy::SDK::FlagsClient::REASON_OVERRIDE         => [OF::Reason::STATIC, nil],
-        Shipeasy::SDK::FlagsClient::REASON_FLAG_NOT_FOUND   => [OF::Reason::ERROR, OF::ErrorCode::FLAG_NOT_FOUND],
-        Shipeasy::SDK::FlagsClient::REASON_CLIENT_NOT_READY => [OF::Reason::ERROR, OF::ErrorCode::PROVIDER_NOT_READY],
+        Shipeasy::Engine::REASON_RULE_MATCH       => [OF::Reason::TARGETING_MATCH, nil],
+        Shipeasy::Engine::REASON_DEFAULT          => [OF::Reason::DEFAULT, nil],
+        Shipeasy::Engine::REASON_OFF              => [OF::Reason::DISABLED, nil],
+        Shipeasy::Engine::REASON_OVERRIDE         => [OF::Reason::STATIC, nil],
+        Shipeasy::Engine::REASON_FLAG_NOT_FOUND   => [OF::Reason::ERROR, OF::ErrorCode::FLAG_NOT_FOUND],
+        Shipeasy::Engine::REASON_CLIENT_NOT_READY => [OF::Reason::ERROR, OF::ErrorCode::PROVIDER_NOT_READY],
       }.freeze
 
       attr_reader :metadata
 
-      def initialize(client)
+      # Construct the provider. With no argument it resolves the global engine
+      # configured via `Shipeasy.configure(...)`, so callers never build an
+      # Engine themselves — construct it AFTER your `Shipeasy.configure` call.
+      # Pass an explicit engine only for advanced/multi-key setups.
+      def initialize(client = nil)
+        client ||= Shipeasy.engine
+        if client.nil?
+          raise Shipeasy::Error, "Shipeasy::OpenFeature::Provider.new needs " \
+            "Shipeasy.configure { |c| c.api_key = … } to have run first " \
+            "(or pass an explicit engine)."
+        end
         @client = client
         @metadata = OF::ProviderMetadata.new(name: "shipeasy").freeze
       end
@@ -123,12 +134,28 @@ module Shipeasy
       end
 
       # OpenFeature `track()` → Shipeasy `track()`. No-ops without a targeting key.
-      def track(tracking_event_name, evaluation_context: nil, details: {})
+      def track(tracking_event_name, evaluation_context: nil, tracking_event_details: nil)
         ctx = normalize_context(evaluation_context)
         user_id = ctx["targeting_key"] || ctx["user_id"]
         return if user_id.nil? || user_id.to_s.empty?
 
-        props = details.is_a?(Hash) ? details : {}
+        # Base props = the evaluation-context attributes (minus the identity
+        # keys), with the tracking-event details merged on top.
+        props = ctx.reject { |k, _| k == "targeting_key" || k == "user_id" }
+
+        detail_fields = if tracking_event_details.respond_to?(:fields)
+                          tracking_event_details.fields.transform_keys(&:to_s)
+                        elsif tracking_event_details.is_a?(Hash)
+                          tracking_event_details.transform_keys(&:to_s)
+                        else
+                          {}
+                        end
+        props = props.merge(detail_fields)
+
+        if tracking_event_details.respond_to?(:value) && !tracking_event_details.value.nil?
+          props["value"] = tracking_event_details.value
+        end
+
         @client.track(user_id, tracking_event_name, props)
       end
 

data/lib/shipeasy/sdk/skill.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Shipeasy
+  module SDK
+    # `shipeasy-skill` — install the bundled Shipeasy agent skill into a project.
+    #
+    # RubyGems has no safe post-install hook (gems don't run code on install;
+    # installers run non-interactively), so installing the skill is an explicit,
+    # opt-in command:
+    #
+    #     shipeasy-skill install                 # → .claude/skills/shipeasy-ruby/SKILL.md
+    #     shipeasy-skill install --dir path/     # custom destination (file or dir)
+    #     shipeasy-skill install --force         # overwrite an existing file
+    #     shipeasy-skill print                   # write the skill to stdout
+    #
+    # The skill (`docs/skill/SKILL.md`) is shipped inside the gem, so this reads
+    # it with no network — relative to this file, which works both from an
+    # installed gem and a source checkout.
+    module Skill
+      DEFAULT_DEST = ".claude/skills/shipeasy-ruby/SKILL.md"
+
+      # The bundled SKILL.md, read from docs/skill/SKILL.md (a sibling of lib/ in
+      # both the installed gem and a source checkout).
+      def self.skill_text
+        path = File.expand_path("../../../docs/skill/SKILL.md", __dir__)
+        File.read(path)
+      end
+
+      # Copy the skill to +dest+ (a file, or a directory it's written into).
+      def self.install(dest, force: false)
+        dest = File.join(dest, "SKILL.md") if File.directory?(dest) || File.extname(dest).empty?
+        if File.exist?(dest) && !force
+          warn "shipeasy-skill: refusing to overwrite #{dest} — pass --force"
+          return 1
+        end
+        FileUtils.mkdir_p(File.dirname(dest))
+        File.write(dest, skill_text)
+        puts "shipeasy-skill: installed the Shipeasy agent skill → #{dest}"
+        0
+      end
+
+      def self.main(argv)
+        cmd = argv.shift
+        case cmd
+        when "install"
+          dest  = DEFAULT_DEST
+          force = false
+          while (arg = argv.shift)
+            case arg
+            when "--dir" then dest = argv.shift
+            when "--force" then force = true
+            else
+              warn "shipeasy-skill: unknown argument #{arg}"
+              return 1
+            end
+          end
+          install(dest, force: force)
+        when "print"
+          puts skill_text
+          0
+        else
+          puts <<~USAGE
+            shipeasy-skill — install the Shipeasy Ruby agent skill into your project.
+
+            Usage:
+              shipeasy-skill install [--dir PATH] [--force]   copy SKILL.md (default: #{DEFAULT_DEST})
+              shipeasy-skill print                            print the skill to stdout
+          USAGE
+          0
+        end
+      end
+    end
+  end
+end

data/lib/shipeasy/sdk/version.rb

@@ -1,5 +1,5 @@
 module Shipeasy
   module SDK
-    VERSION = "1.7.0"
+    VERSION = "2.1.0"
   end
 end