RubyGems - shipeasy-sdk - Versions diffs - 2.0.0 → 2.3.0 - Mend

shipeasy-sdk 2.0.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (177) hide show

data/lib/generators/shipeasy/install/install_generator.rb ADDED Viewed

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+require "rails/generators/base"
+module Shipeasy
+  module Generators
+    # `rails generate shipeasy:install`
+    #
+    # Scaffolds Shipeasy into a Rails app the Rails way:
+    #
+    #   - writes config/initializers/shipeasy.rb (the single Shipeasy.configure call)
+    #   - with --i18n, sets the public client key in that initializer AND injects
+    #     `<%= i18n_head_tags %>` into the application layout's <head>
+    #   - prints the keys / credentials next steps
+    #
+    # The gem's Railties already auto-mount the anon-id Rack middleware and the
+    # i18n view helpers, so this generator never touches middleware wiring — it
+    # only creates the things an app must own: the initializer, the layout tag,
+    # and your keys.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Create config/initializers/shipeasy.rb (and, with --i18n, wire the i18n view helpers)."
+      class_option :i18n, type: :boolean, default: false,
+        desc: "Also enable i18n: set the public client key and inject i18n_head_tags into the app layout"
+      class_option :poll, type: :boolean, default: true,
+        desc: "Use the background poll (long-running server). Pass --no-poll for a serverless one-shot fetch"
+      APP_LAYOUT = "app/views/layouts/application.html.erb"
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/shipeasy.rb"
+      end
+      def inject_layout_helpers
+        return unless options[:i18n]
+        unless layout_exists?
+          say_status :skip, "#{APP_LAYOUT} not found — add <%= i18n_head_tags %> to your <head> by hand", :yellow
+          return
+        end
+        if layout_already_wired?
+          say_status :identical, "#{APP_LAYOUT} already has i18n_head_tags", :blue
+          return
+        end
+        # Insert just before the closing </head>, picking up its indentation.
+        inject_into_file APP_LAYOUT, "<%= i18n_head_tags %>\n  ", before: "</head>"
+      end
+      def print_next_steps
+        say ""
+        say "  Shipeasy installed → config/initializers/shipeasy.rb", :green
+        say ""
+        say "  Next steps:"
+        say "    1. Mint your keys: https://app.shipeasy.ai → Settings → SDK keys"
+        say "    2. Provide them (pick one):"
+        say "         • ENV — set SHIPEASY_SERVER_KEY#{options[:i18n] ? " and SHIPEASY_CLIENT_KEY" : ""}"
+        say "         • Rails credentials — bin/rails credentials:edit, then read"
+        say "           them from Rails.application.credentials in the initializer"
+        if options[:i18n]
+          say "    3. i18n_head_tags is wired into your layout — run the Shipeasy"
+          say "       i18n install to create your en:prod profile, then translate."
+        end
+        say ""
+        say "  Read a flag anywhere per request:"
+        say "    Shipeasy::Client.new(current_user).get_flag(\"new_checkout\")"
+        say ""
+        say "  Docs: https://docs.shipeasy.ai", :cyan
+        say ""
+      end
+      private
+      def layout_exists?
+        File.exist?(File.join(destination_root, APP_LAYOUT))
+      end
+      def layout_already_wired?
+        File.read(File.join(destination_root, APP_LAYOUT)).include?("i18n_head_tags")
+      end
+    end
+  end
+end

data/lib/generators/shipeasy/install/templates/initializer.rb.tt ADDED Viewed

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+# Shipeasy — feature flags, dynamic configs, kill switches, A/B experiments,
+# metrics and (optional) i18n. Generated by `rails generate shipeasy:install`.
+#
+# Configure the SDK ONCE here at boot, then construct a cheap, user-bound
+# `Shipeasy::Client.new(current_user)` per request — every read takes no user
+# argument because the user is bound at construction:
+#
+#   flags = Shipeasy::Client.new(current_user)
+#   flags.get_flag("new_checkout")        # NO user arg — bound at construction
+#
+# Docs: https://docs.shipeasy.ai
+Shipeasy.configure do |c|
+  # Required — your Shipeasy SERVER key. A server-side secret; never embed it in
+  # the browser. Read it from the environment, or from Rails credentials:
+  #   c.api_key = Rails.application.credentials.dig(:shipeasy, :server_key)
+  c.api_key = ENV.fetch("SHIPEASY_SERVER_KEY", nil)
+<% if options[:poll] -%>
+  # Long-running server (Puma): keep flags fresh with the background poll
+  # (initial fetch + periodic refresh). Set to false for serverless /
+  # short-lived processes — they get a one-shot fetch and no background thread.
+  c.poll = true
+<% else -%>
+  # Serverless / short-lived process: one-shot fetch, no background thread.
+  c.poll = false
+<% end -%>
+  # Optional — map YOUR user object to the Shipeasy attribute hash that
+  # targeting evaluates against. Runs once, in the Shipeasy::Client constructor.
+  # Delete this line to pass the object through unchanged (identity default).
+  c.attributes = ->(user) { { "user_id" => user.id } }
+<% if options[:i18n] -%>
+  # i18n view helpers (i18n_head_tags / i18n_t) — the PUBLIC client key. Safe to
+  # expose to the browser via the loader tag these helpers emit.
+  c.public_key = ENV.fetch("SHIPEASY_CLIENT_KEY", nil)
+  c.profile    = "en:prod"
+<% end -%>
+end

data/lib/shipeasy/admin.rb ADDED Viewed

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+# Optional Admin API client for the Shipeasy Ruby SDK.
+#
+# This subpackage is OFF by default: the main `shipeasy-sdk` entrypoint never
+# requires it, and its HTTP dependency (`faraday`) is an optional development
+# dependency — so `require "shipeasy-sdk"` never pulls it in. Require it
+# explicitly when you want to *administer* resources (create gates, start
+# experiments, …) from server code:
+#
+#   require "faraday"
+#   require "shipeasy/admin"
+#
+#   admin = Shipeasy::Admin::Client.new(
+#     api_key: ENV.fetch("SHIPEASY_ADMIN_KEY"),
+#     project_id: ENV.fetch("SHIPEASY_PROJECT_ID"),
+#   )
+#   admin.gates.list_gates
+#
+# Everything under `Shipeasy::Admin::Generated` (lib/shipeasy_admin*) is produced
+# by scripts/gen_admin.sh from the OpenAPI spec and must not be edited by hand.
+# `Client` is a thin auth/scoping wrapper; it does NOT add name->id resolution or
+# percent->basis-point conversion (that facade lives in the Shipeasy CLI/MCP). The
+# surface here is the raw, 1:1-with-the-spec REST API.
+# Define the namespace BEFORE loading the generated client: its files use the
+# compact `module Shipeasy::Admin::Generated` form, which requires Shipeasy::Admin
+# to already exist (and `require "shipeasy/admin"` may run without the main SDK).
+module Shipeasy
+  module Admin
+  end
+end
+require "shipeasy_admin" # the generated client (loads faraday transitively)
+module Shipeasy
+  module Admin
+    # Programmatic client for the Shipeasy Admin REST API. Each resource group is
+    # a lazily-constructed, memoized reader whose methods map 1:1 to the OpenAPI
+    # operations: #gates, #configs, #killswitches, #experiments, #universes,
+    # #metrics, #events, #alert_rules, #attributes, #projects, #ops, #i18n.
+    class Client
+      # Friendly reader name => generated Api class.
+      APIS = {
+        gates: Generated::GatesApi,
+        configs: Generated::ConfigsApi,
+        killswitches: Generated::KillswitchesApi,
+        experiments: Generated::ExperimentsApi,
+        universes: Generated::UniversesApi,
+        metrics: Generated::MetricsApi,
+        events: Generated::EventsApi,
+        alert_rules: Generated::AlertRulesApi,
+        attributes: Generated::AttributesApi,
+        projects: Generated::ProjectsApi,
+        ops: Generated::OpsApi,
+        i18n: Generated::I18nApi,
+      }.freeze
+      # @param api_key [String] admin SDK key, sent as `Authorization: Bearer <api_key>`.
+      # @param project_id [String, nil] optional project id sent as the `X-Project-Id`
+      #   header on every request. Operations also accept an explicit `x_project_id:`
+      #   argument to override per call.
+      # @param base_url [String] API base URL. Defaults to https://shipeasy.ai
+      #   (the spec's production server); use http://localhost:3000 for local dev.
+      def initialize(api_key:, project_id: nil, base_url: "https://shipeasy.ai")
+        config = Generated::Configuration.new
+        config.access_token = api_key
+        scheme, _, host = base_url.rpartition("://")
+        config.scheme = scheme unless scheme.empty?
+        config.host = host.empty? ? base_url : host
+        @api_client = Generated::ApiClient.new(config)
+        @api_client.default_headers["X-Project-Id"] = project_id if project_id
+        @apis = {}
+      end
+      # The underlying generated ApiClient (advanced/escape hatch).
+      attr_reader :api_client
+      APIS.each_key do |name|
+        define_method(name) { @apis[name] ||= APIS.fetch(name).new(@api_client) }
+      end
+    end
+  end
+end

data/lib/shipeasy/client.rb CHANGED Viewed

@@ -55,6 +55,15 @@ module Shipeasy
     def get_killswitch(name, switch_key = nil)
       @engine.get_killswitch(name, switch_key)
     end
+    def track(event_name, props = {})
+      id = @attributes["user_id"] || @attributes["anonymous_id"]
+      @engine.track(id, event_name, props)
+    end
+    def log_exposure(experiment_name)
+      @engine.log_exposure(@attributes, experiment_name)
+    end
   end
   # Raised by Shipeasy::Client when constructed before Shipeasy.configure.

data/lib/shipeasy/config.rb CHANGED Viewed

@@ -22,6 +22,27 @@ 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
@@ -42,6 +63,13 @@ 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"
@@ -105,23 +133,180 @@ module Shipeasy
       @engine
     end
-    # Build + register the one global engine (first-config-wins). Fires the
-    # one-shot fetch fire-and-forget. Idempotent within a process.
+    # 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)
+      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).
-      Thread.new do
-        engine.init_once
-      rescue => e
-        warn "[shipeasy] configure() one-shot fetch failed: #{e.message}"
+      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.
     def reset_config!
       @config = nil

data/lib/shipeasy/engine.rb CHANGED Viewed

@@ -90,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
@@ -300,17 +304,21 @@ module Shipeasy
       # 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 per-key switch is on. Unknown
-      # killswitches / switches return false. Not user-scoped.
+      # 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
-        if switch_key.nil?
-          Eval.enabled?(ks["killed"])
-        else
-          Eval.enabled?(ks.dig("switches", switch_key.to_s))
+        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

data/lib/shipeasy/sdk/openfeature.rb CHANGED Viewed

@@ -11,11 +11,10 @@
 #   require "open_feature/sdk"
 #   require "shipeasy/sdk/openfeature"
 #
-#   client = Shipeasy::Engine.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
@@ -38,6 +37,8 @@ rescue LoadError => e
 end
 require_relative "../engine"
+require_relative "../config"
+require_relative "../client"
 module Shipeasy
   module OpenFeature
@@ -66,7 +67,17 @@ module Shipeasy
       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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -1,5 +1,5 @@
 module Shipeasy
   module SDK
-    VERSION = "2.0.0"
+    VERSION = "2.3.0"
   end
 end