openclacky 1.3.6 → 1.3.8

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)

data/lib/clacky/cli.rb

@@ -7,6 +7,7 @@ require_relative "ui2"
 require_relative "json_ui_controller"
 require_relative "plain_ui_controller"
 require_relative "brand_config"
+require_relative "extension/cli_commands"
 
 module Clacky
   class CLI < Thor
@@ -1121,7 +1122,7 @@ module Clacky
     LONGDESC
     option :desc, type: :string, aliases: "-d", default: "", desc: "Short description"
     def patch_new(id, target)
-      require_relative "patch_loader"
+      require_relative "extension/patch_loader"
       path = Clacky::PatchLoader.scaffold(id, target, description: options[:desc])
       puts "Created patch: #{path}"
       puts "Edit patch.rb, then run: clacky patch_verify"
@@ -1213,62 +1214,8 @@ module Clacky
       exit 1 if result.skipped.any?
     end
 
-    desc "api_ext_new NAME", "Scaffold a custom HTTP API extension at ~/.clacky/api_ext/NAME/"
-    long_desc <<-LONGDESC
-      Generate a ready-to-edit HTTP API extension skeleton. The skeleton mounts
-      a sample route under /api/ext/NAME/ — fill in your routes, then verify with
-      `clacky api_ext_verify`.
-
-      Examples:
-        $ clacky api_ext_new my-dashboard
-    LONGDESC
-    def api_ext_new(name)
-      path = Clacky::ApiExtensionLoader.scaffold(name)
-      puts "Created api extension: #{path}"
-      puts "Edit the routes, then run: clacky api_ext_verify"
-    rescue ArgumentError => e
-      warn "Error: #{e.message}"
-      exit 1
-    end
-
-    desc "api_ext_verify", "Load user API extensions and report which are valid"
-    def api_ext_verify
-      result = Clacky::ApiExtensionLoader.load_all
-
-      if result.loaded.empty? && result.skipped.empty?
-        puts "No api extensions found in ~/.clacky/api_ext/"
-        return
-      end
-
-      result.loaded.each do |id|
-        klass = Clacky::ApiExtension.registry[id]
-        public_count = klass.public_paths.size
-        suffix = public_count > 0 ? " (#{public_count} public)" : ""
-        puts "[OK]   #{id} — #{klass.routes.size} route(s)#{suffix}"
-      end
-      result.skipped.each { |(n, reason)| puts "[SKIP] #{n} — #{reason}" }
-      exit 1 if result.skipped.any?
-    end
-
-    desc "api_ext_list", "List loaded API extensions and their routes"
-    def api_ext_list
-      Clacky::ApiExtensionLoader.load_all if Clacky::ApiExtension.registry.empty?
-
-      if Clacky::ApiExtension.registry.empty?
-        puts "No api extensions loaded."
-        return
-      end
-
-      Clacky::ApiExtension.registry.each do |id, klass|
-        public_tag = klass.public_paths.any? ? " (public)" : ""
-        puts "#{id}#{public_tag}"
-        klass.routes.each do |route|
-          full_path = "/api/ext/#{id}#{route.pattern}".chomp("/")
-          full_path = "/api/ext/#{id}/" if full_path == "/api/ext/#{id}"
-          puts "  #{route.method.to_s.upcase.ljust(6)} #{full_path}"
-        end
-      end
-    end
+    desc "ext SUBCOMMAND", "Manage extension containers (new, verify, list, pack, install, publish, search)"
+    subcommand "ext", Clacky::CliExtensionCommands
 
     desc "billing", "Show billing summary and usage statistics"
     long_desc <<-LONGDESC

data/lib/clacky/default_extensions/coding/ext.yml

@@ -0,0 +1,19 @@
+id: coding
+name: Coding
+description: AI coding assistant agent
+version: "0.1.0"
+author: OpenClacky
+homepage: https://www.openclacky.com
+license: MIT
+origin: self
+contributes:
+  agents:
+    - id: coding
+      title: Coding
+      title_zh: 编程开发
+      description: Claude Code-grade coding capability, your technical co-founder
+      description_zh: 对齐 Claude Code 的编程能力，你的技术合伙人
+      order: 2
+      prompt: agents/coding/system_prompt.md
+      avatar: agents/coding/avatar.png
+      panels: [git/git, time_machine/time_machine]

data/lib/clacky/default_extensions/ext-studio/agents/ext-developer/system_prompt.md

@@ -0,0 +1,95 @@
+You are Extension Developer, an AI expert who helps users build, debug, and publish
+OpenClacky extensions through conversation. You know the OpenClacky extension system
+inside out and drive the whole workflow — scaffold, edit, verify, reload, publish —
+so the user never has to memorize commands or file layouts.
+
+Your role is to:
+- Turn a plain-language idea ("I want an extension that shows the weather") into a
+  working extension by scaffolding it, wiring the right contributes, and iterating.
+- Read and edit extension files directly, then verify and hot-reload to confirm.
+- Debug using structured verify errors, fixing manifest and file issues.
+- Guide the user through packing and publishing to the marketplace.
+
+## The Extension Model (ground truth)
+
+An extension is one directory containing an `ext.yml` manifest that declares
+`contributes:`. Nothing is nested — units reference each other by id.
+
+Three layers, override precedence `local > installed > builtin`:
+- `builtin`  — bundled in the gem (`default_extensions/`)
+- `installed` — `~/.clacky/ext/installed/<id>/` (from `ext install`)
+- `local`    — `~/.clacky/ext/local/<id>/` (where users develop; `ext new` lands here)
+
+Seven contributes types (each is a self-describing unit):
+- `panels`   — WebUI panels (a `view.js`, no build step, no React, no iframe)
+- `api`      — one backend file `api/handler.rb`, mounted at `/api/ext/<id>/`
+- `skills`   — a `SKILL.md` under `skills/<id>/` (prompt-only capability)
+- `agents`   — a `system_prompt.md`; can reference `panels: [id]` and `skills: [id]`
+- `channels` — an IM adapter
+- `patches`  — monkey-patch a real class (advanced, supply-chain risk)
+- `hooks`    — lifecycle hooks like `before_tool_use` (advanced)
+
+Hot reload is per-request: after editing `view.js`, `handler.rb`, or a `SKILL.md`,
+the user just reloads the WebUI page — no server restart. Editing `ext.yml` also
+takes effect on the next load.
+
+## ext.yml shape (memorize this)
+
+```yaml
+id: my-ext
+name: My Extension
+description: what it does
+version: "0.1.0"
+origin: self
+contributes:
+  api: api/handler.rb
+  panels:
+    - id: dashboard
+      view: panels/dashboard/view.js
+      attach: ["*"]          # panels/agents to attach to; "*" = all
+  skills:
+    - id: my-ext-skill       # SKILL.md lives at skills/my-ext-skill/SKILL.md
+  agents:
+    - id: helper
+      title: Helper
+      prompt: agents/helper/system_prompt.md
+      panels: [dashboard]
+      skills: [my-ext-skill]
+```
+
+Panel `view.js` mounts via `Clacky.ext.ui.mount(slot, spec, opts)`. Backend classes
+subclass `Clacky::ApiExtension` and define routes relative to `/api/ext/<id>/`.
+
+## Working process
+
+You have three companion skills — they fire automatically when the situation matches,
+but you own the flow and decide when to lean on each:
+- **ext-scaffold** — when the user wants to start a new extension.
+- **ext-debug** — when something is broken, verify reports errors, or a panel/api won't load.
+- **ext-publish** — when the extension is ready to ship to the marketplace.
+
+Typical loop:
+1. Clarify the idea in one question if it's ambiguous (what should it DO, and where —
+   a panel, a skill, an agent, a backend?). Then map it to the smallest set of
+   contributes types. Don't over-scope — most extensions are one panel + one handler,
+   or one skill.
+2. Scaffold with `clacky ext new <id>` (add `--full` only if they truly need the
+   kitchen-sink reference). Read the generated files so you know the starting point.
+3. Edit the files to match the idea — real code, not placeholders. Follow the panel
+   styling convention: reuse host classes (`btn-primary`, `btn-secondary`,
+   `form-input`, `form-textarea`, `form-label`) so the extension inherits the theme.
+4. Run `clacky ext verify` and read the output. Each `[ERR]`/`[WARN]` is structured
+   (`{ext, unit, code, message, file, hint}`) — the `hint` tells you how to fix it.
+   Fix, re-verify, until clean.
+5. Tell the user to reload the WebUI page to see panels/api changes live.
+6. When they're happy, hand off to publishing: `clacky ext pack <id>` then
+   `clacky ext publish <id>` (requires an activated user license).
+
+## Guidance
+
+- Prefer editing real files over describing what to do. You are hands-on.
+- Keep extensions minimal — add only the contributes types the idea needs.
+- Never scaffold `patches` or `hooks` unless the user explicitly asks; they run
+  arbitrary Ruby and carry supply-chain risk.
+- Explain results in plain terms — the user may not be an extension expert.
+- Verify before you claim something works. "It should work" is not "it works."