openclacky 1.3.6 → 1.3.7

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,18 @@
+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: AI coding assistant and technical co-founder
+      description_zh: AI 编程助手，你的技术合伙人
+      order: 2
+      prompt: agents/coding/system_prompt.md
+      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."

data/lib/clacky/default_extensions/ext-studio/api/handler.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "json"
+require "tmpdir"
+require "socket"
+require "digest"
+
+# Extension Studio — backend for the debug/publish panels. Mounted at
+# /api/ext/ext-studio/. Reads the resolved extension tree, runs the verifier,
+# packs and publishes local containers to the marketplace.
+class ExtStudioExt < Clacky::ApiExtension
+  timeout 60
+
+  # GET /api/ext/ext-studio/extensions
+  # List every local-layer container with a units summary and verify status,
+  # so the debug panel can populate its picker and detail view.
+  get "/extensions" do
+    result = Clacky::ExtensionLoader.load_all(force: true)
+    issues = Clacky::ExtensionVerifier.verify(result)
+
+    exts = local_containers(result).map do |ext_id, container|
+      serialize_container(ext_id, container, result, issues)
+    end
+    exts.sort_by! { |e| -e[:mtime] }
+
+    json(extensions: exts)
+  end
+
+  # POST /api/ext/ext-studio/verify
+  # body: { ext_id? }  — omit ext_id to verify the whole tree.
+  # Returns structured issues (same shape the CLI prints) plus resolved units.
+  post "/verify" do
+    ext_id = json_body["ext_id"].to_s.strip
+    result = Clacky::ExtensionLoader.load_all(force: true)
+    issues = Clacky::ExtensionVerifier.verify(result)
+
+    scoped = ext_id.empty? ? issues : issues.select { |i| i.ext == ext_id }
+    units  = result.units
+    units  = units.select { |u| u.ext_id == ext_id } unless ext_id.empty?
+
+    json(
+      ext_id: ext_id.empty? ? nil : ext_id,
+      units: units.map { |u| serialize_unit(u) },
+      issues: scoped.map { |i| serialize_issue(i) },
+      ok: scoped.none? { |i| i.level == :error }
+    )
+  end
+
+  # POST /api/ext/ext-studio/pack
+  # body: { ext_id }
+  # Packs a local container into a zip (into a temp dir) and reports its path.
+  post "/pack" do
+    ext_id = require_ext_id!
+    Dir.mktmpdir("clacky-ext-studio-pack") do |tmp|
+      res = Clacky::ExtensionPackager.pack(ext_id, out_dir: tmp)
+      json(ok: true, ext_id: res.ext_id, path: res.path)
+    end
+  rescue Clacky::ExtensionPackager::Error => e
+    error!(e.message, status: 422)
+  end
+
+  # POST /api/ext/ext-studio/publish
+  # body: { ext_id, force?, status?, changelog? }
+  # Packs then uploads to the marketplace. Requires the device to be bound to a
+  # platform account (device token). When unbound, returns a 428 with a hint so
+  # the UI can trigger the on-demand device-authorization flow.
+  post "/publish" do
+    ext_id = require_ext_id!
+
+    unless Clacky::Identity.load.bound?
+      error!("device not bound to a platform account; authorize this device to publish",
+             status: 428, needs_binding: true)
+    end
+
+    brand = Clacky::BrandConfig.load
+
+    Dir.mktmpdir("clacky-ext-studio-publish") do |tmp|
+      res      = Clacky::ExtensionPackager.pack(ext_id, out_dir: tmp)
+      zip_data = File.binread(res.path)
+
+      result = brand.upload_extension!(
+        res.ext_id, zip_data,
+        force:     json_body["force"] == true,
+        status:    presence(json_body["status"]),
+        changelog: presence(json_body["changelog"])
+      )
+
+      if result[:success]
+        ext = result[:extension] || {}
+        ver = (ext["latest_version"] || {})["version"]
+        json(ok: true, ext_id: res.ext_id, version: ver, status: ext["status"])
+      elsif result[:already_exists]
+        json(ok: false, already_exists: true,
+             error: "#{res.ext_id} already published. Publish a new version with force.")
+      else
+        error!(result[:error] || "publish failed", status: 502)
+      end
+    end
+  rescue Clacky::ExtensionPackager::Error => e
+    error!(e.message, status: 422)
+  end
+
+  # GET /api/ext/ext-studio/published
+  # List the current user's published extensions from the marketplace.
+  get "/published" do
+    brand  = Clacky::BrandConfig.load
+    result = brand.fetch_my_extensions!
+    error!(result[:error] || "failed to fetch published extensions", status: 502) unless result[:success]
+
+    exts = Array(result[:extensions]).map do |ext|
+      {
+        id: ext["name"] || ext["slug"] || ext["id"],
+        name: ext["name"],
+        version: (ext["latest_version"] || {})["version"] || ext["version"],
+        status: ext["status"],
+        units: ext["units"] || {}
+      }
+    end
+    json(extensions: exts)
+  end
+
+  # POST /api/ext/ext-studio/unpublish
+  # body: { ext_id }
+  post "/unpublish" do
+    ext_id = require_ext_id!
+    result = Clacky::BrandConfig.load.delete_extension!(ext_id)
+    error!(result[:error] || "unpublish failed", status: 502) unless result[:success]
+    json(ok: true, ext_id: ext_id)
+  end
+
+  # POST /api/ext/ext-studio/develop
+  # body: { idea? }
+  # Spawns a session bound to the ext-developer agent, optionally seeded with
+  # the user's idea as the first task — the "let AI build it for me" entry.
+  post "/develop" do
+    idea = presence(json_body["idea"])
+    name = idea ? "扩展开发: #{idea[0, 40]}" : "扩展开发"
+    sid  = create_session(name: name, prompt: idea, profile: "ext-developer", source: :setup)
+    json(ok: true, session_id: sid)
+  end
+
+  # GET /api/ext/ext-studio/binding
+  # Reports whether this device is bound to a platform account, so the publish
+  # panel can decide up-front whether to run the binding flow.
+  get "/binding" do
+    identity = Clacky::Identity.load
+    json(bound: identity.bound?, user_id: identity.user_id)
+  end
+
+  # POST /api/ext/ext-studio/binding/start
+  # Kicks off an RFC 8628 device-authorization flow against the platform and
+  # returns the verification URL the panel opens plus the device_code to poll.
+  post "/binding/start" do
+    client = Clacky::PlatformHttpClient.new
+    result = client.post("/api/v1/device/authorize", {
+      device_id:   binding_device_id,
+      device_info: { os: RUBY_PLATFORM, hostname: Socket.gethostname, app_version: Clacky::VERSION }
+    })
+
+    error!(result[:error] || "could not start authorization", status: 502) unless result[:success]
+
+    data = result[:data]
+    json(
+      ok:                        true,
+      device_code:               data["device_code"],
+      user_code:                 data["user_code"],
+      verification_uri:          data["verification_uri"],
+      verification_uri_complete: data["verification_uri_complete"],
+      interval:                  data["interval"] || 5
+    )
+  end
+
+  # POST /api/ext/ext-studio/binding/poll  { device_code }
+  # Polls the platform once. On approval, binds the issued device token to the
+  # local Identity so subsequent publishes authenticate as the platform account.
+  post "/binding/poll" do
+    device_code = presence(json_body["device_code"])
+    error!("device_code required", status: 422) unless device_code
+
+    client = Clacky::PlatformHttpClient.new
+    result = client.post("/api/v1/device/token", { device_code: device_code })
+    data   = result[:data] || {}
+    status = data["status"]
+
+    if result[:success] && status == "approved"
+      Clacky::Identity.load.bind!(
+        device_token: data["device_token"],
+        user_id:      data["user_id"]
+      ) if data["device_token"]
+      json(ok: true, status: "approved")
+    elsif status == "pending"
+      json(ok: true, status: "pending")
+    else
+      json(ok: false, status: status || "error", error: result[:error])
+    end
+  end
+
+  private def local_containers(result)
+    Array(result.containers).select { |_id, c| c[:layer] == :local }
+  end
+
+  private def serialize_container(ext_id, container, result, issues)
+    raw = container[:raw] || {}
+    ext_issues = issues.select { |i| i.ext == ext_id }
+    dir = container[:dir]
+    {
+      id: ext_id,
+      name: raw["name"] || ext_id,
+      description: raw["description"],
+      version: raw["version"],
+      origin: container[:origin],
+      layer: container[:layer].to_s,
+      dir: dir,
+      mtime: File.mtime(File.join(dir, "ext.yml")).to_i,
+      units: result.units.select { |u| u.ext_id == ext_id }.map { |u| serialize_unit(u) },
+      error_count: ext_issues.count { |i| i.level == :error },
+      warning_count: ext_issues.count { |i| i.level == :warning }
+    }
+  end
+
+  private def serialize_unit(unit)
+    { kind: unit.kind.to_s, id: unit.id, layer: unit.layer.to_s }
+  end
+
+  private def serialize_issue(issue)
+    {
+      ext: issue.ext,
+      unit: issue.unit,
+      level: issue.level.to_s,
+      code: issue.code,
+      message: issue.message,
+      file: issue.file,
+      hint: issue.hint
+    }
+  end
+
+  private def require_ext_id!
+    id = json_body["ext_id"].to_s.strip
+    error!("ext_id required", status: 422) if id.empty?
+    id
+  end
+
+  private def presence(value)
+    str = value.to_s.strip
+    str.empty? ? nil : str
+  end
+
+  # Stable per-machine id for the device-authorization flow. Matches the
+  # onboarding device_id so binding reuses the same device row on the platform.
+  private def binding_device_id
+    components = [Socket.gethostname, ENV["USER"] || ENV["USERNAME"] || "", RUBY_PLATFORM]
+    Digest::SHA256.hexdigest(components.join(":"))
+  end
+end

data/lib/clacky/default_extensions/ext-studio/ext.yml

@@ -0,0 +1,32 @@
+id: ext-studio
+name: Extension Studio
+description: AI-driven workspace for building, debugging, and publishing OpenClacky extensions
+version: "0.1.0"
+author: OpenClacky
+homepage: https://www.openclacky.com
+license: MIT
+origin: self
+contributes:
+  api: api/handler.rb
+  panels:
+    - id: studio
+      title: Extension & Creation
+      title_zh: 扩展与创作
+      description: Build, debug and publish extensions and skills
+      description_zh: 开发、调试、发布扩展与 skill
+      view: panels/studio/view.js
+      order: 210
+  agents:
+    - id: ext-developer
+      title: Extension Developer
+      title_zh: 扩展开发
+      description: AI expert that helps you build, debug, and publish OpenClacky extensions
+      description_zh: 帮你开发、调试、发布 OpenClacky 扩展的 AI 专家
+      order: 5
+      prompt: agents/ext-developer/system_prompt.md
+      panels: [studio]
+      skills: [ext-scaffold, ext-debug, ext-publish]
+  skills:
+    - id: ext-scaffold
+    - id: ext-debug
+    - id: ext-publish