openclacky 1.3.6 → 1.3.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45a64960de249e34ee18e67f0ce38888b510a886988d545c58aca558d942bbdb
-  data.tar.gz: '008d7b7bec8fd7edf43cb9848949637d23783d2ad3a8a2b6199010f9b8ed660d'
+  metadata.gz: 48e94ccf83645b5e18be8d5d33582dc128b06824ab226dd314540658b9cc7e4a
+  data.tar.gz: 1112ed443505eca99e745838377ebbf4b6f1e96a7c7f83c7bf1cff844b5ddea9
 SHA512:
-  metadata.gz: 2f0e9c3fb21691cf9bbfdd6820faaaed86086bebb820278b6104356f92fec4c0e53584a8c3ca40bfd42fb7f82e1f3a484ed404c2b693a47467e9c43d517ed9e8
-  data.tar.gz: 83cb1fa9ac5a3ae4834bf5c02c344da9db09a5863a4970857f2d233656c66d9b20fde131f0af4b04d23e204a09a978968ae7d2310ae1c3c3ceb8bcb6d721e3c2
+  metadata.gz: b0e4b2664bb7990ec91dd7c5598cfb561ce6f931b1f006a962b6cbf5516ee424b3a6f605fd70c3996ad4d0e0bf1a20dfd626d6466020393cc8cf18832008a68a
+  data.tar.gz: 2b74eea0a552e5d26545779da2f0a2b1f88812063398ffbf15be913e396d6efe7131d8205bff766939ef252c4ca3b8075ce8e86c855de59774226e3e03bdbfde

data/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.7] - 2026-07-06
+
+### Added
+- Extension ecosystem: install, manage, and publish extensions with Creator Studio
+- Brand extension and brand badge support for extension agents
+- Hook/profile extension type for intercepting and customizing agent behavior
+- Extension upload CLI for publishing extensions from the command line
+- New session page with improved layout and discoverability
+- Session auto-cleanup hint, skeleton loading, and type filter in trash panel
+- Renew button on brand warning bar for expiring subscriptions
+- i18n tooltips for header theme toggle and trash toolbar buttons
+- Refresh button in header to reload sessions
+- xhigh reasoning effort level for supported models
+- i18n file upload error messages
+
+### Improved
+- Merge Creator Center into ext-studio as a unified extension hub
+- Extension developer experience: scaffold template improvements, badge and author metadata support
+- Share modal UI polish — theme dots on hover, close button hover effect, layout refinement
+- Unify Clacky.* JS namespace and single-segment extension architecture
+- Migrate default agents to default extensions with unified panel visibility
+
+### Fixed
+- Ctrl+C now works properly in TUI auto-answer mode
+- Show-system-skills toggle persists correctly and uses theme accent color
+- Cron display handles every-N-hours with weekdays pattern correctly
+- New-session dropdown arrow button responds to both click and keyboard
+- New cron virtual entry inserts at the correct position relative to pinned sessions
+- File upload error messages use i18n consistently
+
 ## [1.3.6] - 2026-06-30
 
 ### Added

data/lib/clacky/agent.rb

@@ -51,7 +51,7 @@ module Clacky
     attr_accessor :pinned
     attr_accessor :channel_info
 
-    REASONING_EFFORTS = %w[low medium high].freeze
+    REASONING_EFFORTS = %w[low medium high xhigh].freeze
 
     def permission_mode
       @config&.permission_mode&.to_s || ""
@@ -136,6 +136,8 @@ module Clacky
       # Free-mode counterpart: branded but not activated → fetch unencrypted skills
       # via the public endpoint so users get a working install with no serial number.
       @brand_config.sync_free_skills_async!
+      # Brand extensions bundled into the activated license's distribution.
+      @brand_config.sync_brand_extensions_async!
 
       # Initialize Time Machine
       init_time_machine
@@ -146,6 +148,11 @@ module Clacky
       # Load declarative shell hooks from ~/.clacky/hooks.yml
       ShellHookLoader.load_into(@hooks)
 
+      # Copy ext.yml-contributed hook callbacks (contributes.hooks) onto this
+      # agent's hook manager. The callbacks were registered process-wide at
+      # boot via ExtensionHookLoader.
+      ExtensionHookRegistry.apply_to(@hooks)
+
       # Ensure user-space parsers are in place (~/.clacky/parsers/)
       Utils::ParserManager.setup!
 

data/lib/clacky/agent_profile.rb

@@ -6,107 +6,175 @@ module Clacky
   # Loads and represents an agent profile (system prompt + skill whitelist).
   #
   # Lookup order for a profile named "coding":
-  #   1. ~/.clacky/agents/coding/          (user override)
-  #   2. <gem>/lib/clacky/default_agents/coding/  (built-in default)
+  #   1. ~/.clacky/agents/coding/                (user override, physical dir)
+  #   2. extension agent unit with id == "coding" (ext.yml contributes.agents)
   #
-  # Each profile directory must contain:
+  # Each user profile directory (opt-in override) contains:
   #   - profile.yml       — name, description, skills whitelist
   #   - system_prompt.md  — agent-specific system prompt content
   #
-  # Global files (shared across all agents), also with user-override support:
-  #   - SOUL.md   — agent personality/values
-  #   - USER.md   — user profile information
-  #   - base_prompt.md — universal behavioral rules (todo manager, tool usage, etc.)
+  # Global files (shared across all agents) are user-only overrides:
+  #   - ~/.clacky/agents/SOUL.md   — agent personality/values (else DEFAULT_SOUL)
+  #   - ~/.clacky/agents/USER.md   — user profile info        (else DEFAULT_USER)
+  # The universal behavioural rules (todo manager, tool usage, response style,
+  # etc.) live in a bundled resource file at lib/clacky/prompts/base.md.
   class AgentProfile
-    DEFAULT_AGENTS_DIR = File.expand_path("../default_agents", __FILE__).freeze
     USER_AGENTS_DIR = File.expand_path("~/.clacky/agents").freeze
+    BASE_PROMPT_PATH = File.expand_path("../prompts/base.md", __FILE__).freeze
+
+    DEFAULT_SOUL = <<~MD.freeze
+      You are calm, precise, and helpful. You communicate clearly and concisely.
+      You are honest about uncertainty and ask for clarification when needed.
+      You take initiative but respect the user's preferences and decisions.
+    MD
+
+    DEFAULT_USER = "(No user profile configured yet. To personalize, create ~/.clacky/agents/USER.md)"
 
     attr_reader :name, :description
 
     def initialize(name)
       @name = name.to_s
+      result = ExtensionLoader.last_result
+      @ext_unit = result&.agents&.find { |u| u.id == @name }
+      if @ext_unit.nil?
+        result = ExtensionLoader.load_all(force: true)
+        @ext_unit = result&.agents&.find { |u| u.id == @name }
+      end
       profile_data = load_profile_yml
       @description = profile_data["description"] || ""
       @system_prompt_content = load_agent_file("system_prompt.md")
     end
 
-    # Load a named profile. Raises ArgumentError if profile directory not found.
     # @param name [String, Symbol] profile name (e.g. "coding", "general")
     # @return [AgentProfile]
     def self.load(name)
       new(name)
     end
 
+    # List all available agent profiles across user + extension layers.
+    # Precedence on id collision: user override → extension unit.
+    # @return [Array<Hash>] each: { id:, title:, title_zh:, description:, description_zh:, source:, order:, layer:, author: }
+    def self.all
+      out = {}
+
+      add = lambda do |id, title, title_zh, description, description_zh, source, order, layer, author|
+        next if id.nil? || id.empty?
+        out[id] = {
+          id: id,
+          title: title,
+          title_zh: title_zh,
+          description: description,
+          description_zh: description_zh,
+          source: source,
+          order: order,
+          layer: layer,
+          author: author,
+        }
+      end
+
+      ext_result = ExtensionLoader.last_result || ExtensionLoader.load_all
+      ext_result&.agents&.each do |unit|
+        spec = unit.spec || {}
+        title = spec["title"].to_s
+        title = unit.id if title.empty?
+        add.call(
+          unit.id, title, spec["title_zh"].to_s,
+          spec["description"].to_s, spec["description_zh"].to_s,
+          "extension", spec["order"], unit.layer.to_s,
+          spec["author"].to_s
+        )
+      end
+
+      Dir.glob(File.join(USER_AGENTS_DIR, "*")).sort.each do |path|
+        next unless File.directory?(path)
+        id = File.basename(path)
+        next if id.start_with?("_")
+        next unless File.file?(File.join(path, "profile.yml"))
+        meta = read_profile_yml(File.join(path, "profile.yml"))
+        add.call(
+          id, meta["title"] || meta["name"] || id, meta["title_zh"].to_s,
+          meta["description"].to_s, meta["description_zh"].to_s,
+          "user", meta["order"], "user",
+          meta["author"].to_s.empty? ? "You" : meta["author"].to_s
+        )
+      end
+
+      source_rank = { "user" => 0, "extension" => 1 }
+      out.values.sort_by { |a| [source_rank[a[:source]] || 9, a[:order] || 999, a[:id]] }
+    end
+
+    private_class_method def self.read_profile_yml(path)
+      return {} unless File.file?(path)
+      YAML.safe_load(File.read(path)) || {}
+    rescue StandardError
+      {}
+    end
+
     # @return [String] agent-specific system prompt content
     def system_prompt
       @system_prompt_content
     end
 
-    # @return [String] base prompt shared by all agents
+    # @return [String] base prompt shared by all agents (bundled resource)
     def base_prompt
-      load_global_file("base_prompt.md")
+      return "" unless File.file?(BASE_PROMPT_PATH)
+      File.read(BASE_PROMPT_PATH).strip
     end
 
-    # @return [String] soul content (user override → built-in default)
+    # @return [String] soul content (user override, else default)
     def soul
-      load_global_file("SOUL.md")
+      user_path = File.join(USER_AGENTS_DIR, "SOUL.md")
+      if File.exist?(user_path) && !File.zero?(user_path)
+        File.read(user_path).strip
+      else
+        DEFAULT_SOUL.strip
+      end
     end
 
-    # @return [String] user profile content (user override → built-in default)
+    # @return [String] user profile content (user override, else default)
     def user_profile
-      load_global_file("USER.md")
+      user_path = File.join(USER_AGENTS_DIR, "USER.md")
+      if File.exist?(user_path) && !File.zero?(user_path)
+        File.read(user_path).strip
+      else
+        DEFAULT_USER
+      end
     end
 
     private def load_profile_yml
-      path = find_agent_file("profile.yml")
-      raise ArgumentError, "Agent profile '#{@name}' not found. " \
-        "Looked in #{user_agent_dir} and #{default_agent_dir}" unless path
-
-      YAML.safe_load(File.read(path)) || {}
-    end
-
-    # Load a file from the agent-specific directory (user override → built-in)
-    private def load_agent_file(filename)
-      path = find_agent_file(filename)
-      return "" unless path
-
-      File.read(path).strip
-    end
-
-    # Load a global file shared across all agents (user override → built-in)
-    private def load_global_file(filename)
-      user_path = File.join(USER_AGENTS_DIR, filename)
-      default_path = File.join(DEFAULT_AGENTS_DIR, filename)
-
-      path = if File.exist?(user_path) && !File.zero?(user_path)
-               user_path
-             elsif File.exist?(default_path)
-               default_path
-             end
+      user_yml = File.join(user_agent_dir, "profile.yml")
+      if File.file?(user_yml)
+        return YAML.safe_load(File.read(user_yml)) || {}
+      end
 
-      return "" unless path
+      if @ext_unit
+        return {
+          "name"        => @name,
+          "description" => @ext_unit.spec["description"],
+          "panels"      => @ext_unit.spec["panels"],
+          "skills"      => @ext_unit.spec["skills"],
+        }
+      end
 
-      File.read(path).strip
+      raise ArgumentError, "Agent profile '#{@name}' not found. " \
+        "Looked in #{user_agent_dir} and extension registry."
     end
 
-    # Find a file in user override dir first, then built-in default dir
-    private def find_agent_file(filename)
+    # Agent-specific file lookup: user override → extension prompt (system_prompt.md only).
+    private def load_agent_file(filename)
       user_path = File.join(user_agent_dir, filename)
-      default_path = File.join(default_agent_dir, filename)
+      return File.read(user_path).strip if File.exist?(user_path) && !File.zero?(user_path)
 
-      if File.exist?(user_path) && !File.zero?(user_path)
-        user_path
-      elsif File.exist?(default_path)
-        default_path
+      if @ext_unit && filename == "system_prompt.md"
+        prompt_abs = @ext_unit.spec["prompt_abs"]
+        return File.read(prompt_abs).strip if prompt_abs && File.file?(prompt_abs)
       end
+
+      ""
     end
 
     private def user_agent_dir
       File.join(USER_AGENTS_DIR, @name)
     end
-
-    private def default_agent_dir
-      File.join(DEFAULT_AGENTS_DIR, @name)
-    end
   end
 end

data/lib/clacky/brand_config.rb

@@ -583,13 +583,279 @@ module Clacky
       { success: false, error: "Network error: #{e.message}" }
     end
 
-    # Fetch the public store skills list from the OpenClacky Cloud API.
-    # Requires an activated license for HMAC authentication.
-    # Passes scope: "store" to retrieve platform-wide published public skills
-    # (not filtered by the authenticated user's own skills).
-    # Returns { success: bool, skills: [], error: }.
+    # ── Extension marketplace (creator publishing via device token) ──
+    # Extensions authenticate with the device token stored in identity.yml,
+    # which binds this device to a platform account. This is independent of any
+    # license — publishing only requires the owning user to be a contributor.
+    # See platform Api::V1::Client::ExtensionsController.
+
+    # Upload (publish) a packed extension ZIP to the platform.
+    # ext_id:   extension slug (matches ext.yml id)
+    # zip_data: binary ZIP content produced by `clacky ext pack`
+    # force:    when true, PATCH an existing extension (new version) instead of POST
+    #
+    # Returns { success: true, extension: {...} } or
+    #         { success: false, error: "...", already_exists: Boolean }.
+    def upload_extension!(ext_id, zip_data, force: false, status: nil, changelog: nil)
+      identity = Clacky::Identity.load
+      return { success: false, error: "Device not bound to a platform account" } unless identity.bound?
+
+      path = if force
+               "/api/v1/client/extensions/#{URI.encode_www_form_component(ext_id)}"
+             else
+               "/api/v1/client/extensions"
+             end
+
+      fields = { "device_token" => identity.device_token }
+      fields["status"]    = status.to_s    if status
+      fields["changelog"] = changelog.to_s if changelog
+
+      body_bytes, boundary = build_multipart(fields, "extension_zip", "#{ext_id}.zip", zip_data)
+
+      result = if force
+                 platform_client.multipart_patch(path, body_bytes, boundary, read_timeout: 60)
+               else
+                 platform_client.multipart_post(path, body_bytes, boundary, read_timeout: 60)
+               end
+
+      if result[:success]
+        { success: true, extension: result[:data]["extension"] }
+      else
+        body   = result[:data] || {}
+        code   = body["code"] || body["error"]
+        errors = body["errors"]&.join(", ")
+        msg    = result[:error] || [code, errors].compact.join(": ")
+        msg    = "Publish failed" if msg.to_s.strip.empty?
+        already_exists = body["code"].to_s.include?("taken") ||
+                         body["code"].to_s.include?("already") ||
+                         result[:error].to_s.include?("HTTP 409")
+        { success: false, error: msg, already_exists: already_exists }
+      end
+    rescue StandardError => e
+      { success: false, error: "Network error: #{e.message}" }
+    end
+
+    # Fetch the creator's own published extensions.
+    # Uses GET /api/v1/client/extensions (HMAC-signed, system license only).
+    # Returns { success: bool, extensions: [], error: }.
+    def fetch_my_extensions!
+      identity = Clacky::Identity.load
+      return { success: false, error: "Device not bound to a platform account", extensions: [] } unless identity.bound?
+
+      response = platform_client.get(
+        "/api/v1/client/extensions",
+        headers: { "Authorization" => "Bearer #{identity.device_token}" }
+      )
+
+      if response[:success]
+        { success: true, extensions: response[:data]["extensions"] || [] }
+      else
+        { success: false, error: response[:error] || "Fetch failed", extensions: [] }
+      end
+    end
+
+    # Soft-delete (unpublish) one of the creator's extensions by id/slug.
+    # Uses DELETE /api/v1/client/extensions/:id. Returns { success:, error: }.
+    def delete_extension!(ext_id)
+      identity = Clacky::Identity.load
+      return { success: false, error: "Device not bound to a platform account" } unless identity.bound?
+
+      path     = "/api/v1/client/extensions/#{URI.encode_www_form_component(ext_id)}"
+      response = platform_client.delete(
+        path,
+        headers: { "Authorization" => "Bearer #{identity.device_token}" }
+      )
+
+      if response[:success]
+        { success: true }
+      else
+        { success: false, error: response[:error] || "Delete failed" }
+      end
+    end
+
+    # Search the public extension marketplace. Anonymous — no license required.
+    # Uses GET /api/v1/extensions. Returns { success:, extensions: [], error: }.
+    def search_extensions!(query: nil, sort: nil)
+      params = {}
+      params["q"]    = query if query && !query.to_s.strip.empty?
+      params["sort"] = sort  if sort && !sort.to_s.strip.empty?
+      qs   = params.empty? ? "" : "?#{URI.encode_www_form(params)}"
+      response = platform_client.get("/api/v1/extensions#{qs}")
+
+      if response[:success]
+        { success: true, extensions: response[:data]["extensions"] || [] }
+      else
+        { success: false, error: response[:error] || "Search failed", extensions: [] }
+      end
+    rescue StandardError => e
+      { success: false, error: "Network error: #{e.message}", extensions: [] }
+    end
+
+    # Fetch a single public marketplace extension's detail (contributes +
+    # version history). Anonymous, no license required. Returns
+    # { success:, extension:, error: }.
+    def extension_detail!(id)
+      response = platform_client.get("/api/v1/extensions/#{URI.encode_www_form_component(id.to_s)}")
+
+      if response[:success]
+        { success: true, extension: response[:data]["extension"] }
+      else
+        { success: false, error: response[:error] || "Not found" }
+      end
+    rescue StandardError => e
+      { success: false, error: "Network error: #{e.message}" }
+    end
+    # Extensions bundled into the activated license's distribution are free and
+    # unencrypted. They are fetched over the same license-HMAC scheme as brand
+    # skills and installed into the ExtensionLoader `installed` layer.
+
+    # Fetch the extensions bundled into the activated license's distribution.
+    # Requires an activated license. Returns { success:, extensions: [], error: }.
+    # Each extension carries name + latest_version.download_url so
+    # install_brand_extension! can consume it directly.
+    def fetch_brand_extensions!
+      return { success: false, error: "License not activated", extensions: [] } unless activated?
+
+      user_id   = parse_user_id_from_key(@license_key)
+      ts        = Time.now.utc.to_i.to_s
+      nonce     = SecureRandom.hex(16)
+      message   = "#{user_id}:#{@device_id}:#{ts}:#{nonce}"
+
+      payload = {
+        key_hash:  Digest::SHA256.hexdigest(@license_key),
+        user_id:   user_id.to_s,
+        device_id: @device_id,
+        timestamp: ts,
+        nonce:     nonce,
+        signature: OpenSSL::HMAC.hexdigest("SHA256", @license_key, message)
+      }
+
+      response = api_post("/api/v1/licenses/extensions", payload)
+
+      if response[:success]
+        body       = response[:data]
+        installed  = installed_brand_extensions
+        extensions = (body["extensions"] || []).map do |ext|
+          slug       = ext["name"].to_s
+          local      = installed[slug]
+          latest_ver = (ext["latest_version"] || {})["version"] || ext["version"]
+          ext.merge(
+            "installed_version" => local ? local["version"] : nil,
+            "needs_update"      => local ? version_older?(local["version"], latest_ver) : true
+          )
+        end
+        { success: true, extensions: extensions, expires_at: body["expires_at"] }
+      else
+        { success: false, error: response[:error] || "Failed to fetch extensions", extensions: [] }
+      end
+    end
+
+    # Install (or update) a single brand extension by downloading its zip into
+    # the ExtensionLoader `installed` layer.
+    # ext_info: a hash from fetch_brand_extensions! with at least
+    #           name + latest_version.download_url + version.
+    def install_brand_extension!(ext_info)
+      slug    = ext_info["name"].to_s.strip
+      version = (ext_info["latest_version"] || {})["version"] || ext_info["version"]
+      url     = (ext_info["latest_version"] || {})["download_url"]
+
+      return { success: false, error: "Missing extension name" } if slug.empty?
+      return { success: false, error: "No download URL" } if url.nil? || url.strip.empty?
+
+      Clacky::ExtensionPackager.install(url, force: true)
+      record_installed_extension(slug, version)
+      { success: true, name: slug, version: version }
+    rescue StandardError => e
+      { success: false, error: e.message }
+    end
+
+    # Synchronise brand extensions in the background for activated installs.
+    # Mirrors sync_brand_skills_async! but installs into the extension layer.
+    # Unlike brand skills, new extensions are auto-installed because a bundled
+    # extension is chosen by the brand administrator, not the end user.
     #
-    # Fetch the creator's own published skills from the platform API.
+    # @return [Thread, nil]
+    def sync_brand_extensions_async!(on_complete: nil)
+      return nil unless activated?
+      return nil if ENV["CLACKY_TEST"] == "1"
+
+      Thread.new do
+        Thread.current.abort_on_exception = false
+
+        begin
+          result = fetch_brand_extensions!
+          next unless result[:success]
+
+          remote_names = result[:extensions].map { |e| e["name"] }
+          installed_brand_extensions.each_key do |local_name|
+            delete_brand_extension!(local_name) unless remote_names.include?(local_name)
+          end
+
+          to_install = result[:extensions].select { |e| e["needs_update"] }
+          results    = to_install.map { |ext_info| install_brand_extension!(ext_info) }
+
+          Clacky::ExtensionLoader.invalidate_cache! unless results.empty?
+          on_complete&.call(results)
+        rescue StandardError
+          # Background sync failures are intentionally swallowed.
+        end
+      end
+    end
+
+    # Path to the JSON registry tracking installed brand extension versions.
+    def brand_extensions_registry_path
+      File.join(File.expand_path(Clacky::ExtensionLoader::INSTALLED_DIR), "brand_extensions.json")
+    end
+
+    # Installed brand extensions keyed by ext_id => { "version" => "..." }.
+    # Entries whose on-disk container no longer exists are pruned.
+    def installed_brand_extensions
+      path = brand_extensions_registry_path
+      return {} unless File.exist?(path)
+
+      raw     = JSON.parse(File.read(path))
+      valid   = {}
+      changed = false
+      raw.each do |name, meta|
+        if Dir.exist?(File.join(File.dirname(path), name))
+          valid[name] = meta
+        else
+          changed = true
+        end
+      end
+      File.write(path, JSON.generate(valid)) if changed
+      valid
+    rescue StandardError
+      {}
+    end
+
+    # Remove a single installed brand extension by id (files + registry entry).
+    def delete_brand_extension!(ext_id)
+      ext_dir = File.join(File.expand_path(Clacky::ExtensionLoader::INSTALLED_DIR), ext_id)
+      FileUtils.rm_rf(ext_dir) if Dir.exist?(ext_dir)
+
+      path = brand_extensions_registry_path
+      if File.exist?(path)
+        registry = JSON.parse(File.read(path))
+        registry.delete(ext_id)
+        File.write(path, JSON.generate(registry))
+      end
+      Clacky::ExtensionLoader.invalidate_cache!
+    rescue StandardError
+      # Deletion errors are non-fatal.
+    end
+
+    private def record_installed_extension(ext_id, version)
+      path = brand_extensions_registry_path
+      FileUtils.mkdir_p(File.dirname(path))
+      registry = File.exist?(path) ? (JSON.parse(File.read(path)) rescue {}) : {}
+      registry[ext_id] = { "version" => version.to_s }
+      File.write(path, JSON.generate(registry))
+    end
+
+    public
+
+    # Fetch the public store skills list from the OpenClacky Cloud API.
     # Uses GET /api/v1/client/skills (HMAC-signed, system license only).
     # Returns { success: bool, skills: [], error: }.
     def fetch_my_skills!
@@ -1267,6 +1533,43 @@ module Clacky
       false
     end
 
+    # Build the shared HMAC-signed field set for client API calls (skills,
+    # extensions). Proves creator identity via the system user license.
+    private def client_signed_fields
+      user_id   = @license_user_id.to_s
+      ts        = Time.now.utc.to_i.to_s
+      nonce     = SecureRandom.hex(16)
+      message   = "#{user_id}:#{@device_id}:#{ts}:#{nonce}"
+      {
+        "key_hash"  => Digest::SHA256.hexdigest(@license_key),
+        "user_id"   => user_id,
+        "device_id" => @device_id,
+        "timestamp" => ts,
+        "nonce"     => nonce,
+        "signature" => OpenSSL::HMAC.hexdigest("SHA256", @license_key, message)
+      }
+    end
+
+    # Assemble a binary multipart/form-data body: text fields + one file part.
+    # Kept binary-safe so null bytes in the ZIP survive. Returns [body, boundary].
+    private def build_multipart(fields, file_field, filename, file_bytes)
+      boundary = "----ClackyMultipart#{SecureRandom.hex(8)}"
+      crlf     = "\r\n"
+      parts    = []
+      fields.each do |field, value|
+        parts << "--#{boundary}#{crlf}"
+        parts << "Content-Disposition: form-data; name=\"#{field}\"#{crlf}#{crlf}"
+        parts << value.to_s
+        parts << crlf
+      end
+      parts << "--#{boundary}#{crlf}"
+      parts << "Content-Disposition: form-data; name=\"#{file_field}\"; filename=\"#{filename}\"#{crlf}"
+      parts << "Content-Type: application/zip#{crlf}#{crlf}"
+      parts << file_bytes.b
+      parts << "#{crlf}--#{boundary}--#{crlf}"
+      [parts.map(&:b).join, boundary]
+    end
+
     # Instance-level delegate so fetch_brand_skills! can call version_older? directly.
     private def version_older?(installed, latest)
       self.class.version_older?(installed, latest)