openclacky 1.3.6 → 1.3.7

data/lib/clacky/extension/packager.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "tmpdir"
+require "open-uri"
+require "zip"
+
+module Clacky
+  # Packs a local extension container into a distributable zip, and installs a
+  # zip (local path or URL) into the `installed` layer.
+  #
+  # These are the local halves of the publish/marketplace flow: `pack` produces
+  # the artifact that later gets uploaded, `install` is what a download performs.
+  # Both are pure filesystem operations with no network dependency beyond the
+  # optional URL fetch in `install`.
+  module ExtensionPackager
+    MANIFEST     = "ext.yml"
+    MAX_ZIP_SIZE = 50 * 1024 * 1024
+
+    Result = Struct.new(:ext_id, :path, :units, keyword_init: true)
+
+    class Error < StandardError; end
+
+    class << self
+      # Zip up a single container from the local layer into `out_dir`.
+      # Runs verify first (blocking on errors) and refuses protected/encrypted
+      # units — those are produced by the platform's encryption pipeline, not
+      # hand-packed. Returns a Result with the produced zip path.
+      def pack(ext_id, source_dir: Clacky::ExtensionLoader::LOCAL_DIR, out_dir: Dir.pwd)
+        slug = ext_id.to_s.strip
+        raise Error, "invalid extension id: #{ext_id.inspect}" if slug.empty?
+
+        container_dir = File.join(source_dir, slug)
+        unless File.directory?(container_dir) && File.file?(File.join(container_dir, MANIFEST))
+          raise Error, "no container found at #{container_dir} (expected #{MANIFEST})"
+        end
+
+        verify_container!(slug, container_dir)
+        refuse_protected!(slug, container_dir)
+
+        FileUtils.mkdir_p(out_dir)
+        zip_path = File.join(out_dir, "#{slug}.zip")
+        File.delete(zip_path) if File.exist?(zip_path)
+
+        write_zip(container_dir, zip_path)
+
+        Result.new(ext_id: slug, path: zip_path, units: nil)
+      end
+
+      # Install a packed container into the `installed` layer. `source` is a
+      # local zip path or an http(s) URL. Validates the archive (single top
+      # container with an ext.yml, no path traversal), extracts it, then runs
+      # verify on the resolved installed layer.
+      def install(source, installed_dir: Clacky::ExtensionLoader::INSTALLED_DIR, force: false)
+        Dir.mktmpdir("clacky-ext-install") do |tmp|
+          zip_path = local_zip_for(source, tmp)
+          extract_root = File.join(tmp, "unpacked")
+          FileUtils.mkdir_p(extract_root)
+
+          extract_zip(zip_path, extract_root)
+
+          ext_id, container_src = locate_container(extract_root)
+
+          target = File.join(installed_dir, ext_id)
+          if Dir.exist?(target) && !force
+            raise Error, "extension #{ext_id.inspect} already installed at #{target} (pass force: true to overwrite)"
+          end
+
+          FileUtils.mkdir_p(installed_dir)
+          FileUtils.rm_rf(target) if Dir.exist?(target)
+          FileUtils.cp_r(container_src, target)
+
+          Clacky::ExtensionLoader.invalidate_cache!
+          units = verify_installed(ext_id, installed_dir)
+
+          Result.new(ext_id: ext_id, path: target, units: units)
+        end
+      end
+
+      # Verify only the target container in isolation: symlink it into a temp
+      # root so sibling containers in the real local dir don't pollute the run.
+      private def verify_container!(slug, container_dir)
+        Dir.mktmpdir("clacky-ext-verify") do |root|
+          FileUtils.ln_s(File.expand_path(container_dir), File.join(root, slug))
+          result = Clacky::ExtensionLoader.load_all(layers: { local: root }, force: true)
+          issues = Clacky::ExtensionVerifier.verify(result)
+          errors = issues.select { |i| i.level == :error && i.ext == slug }
+          next if errors.empty?
+
+          detail = errors.map { |e| "  - #{e.code}: #{e.message}" }.join("\n")
+          raise Error, "cannot pack #{slug}: verify found errors:\n#{detail}"
+        end
+      ensure
+        Clacky::ExtensionLoader.invalidate_cache!
+      end
+
+      # Packing is for authored (open) containers. Anything already protected or
+      # carrying encrypted skills is produced by the platform pipeline; refuse
+      # to re-pack it so we never smuggle marketplace artifacts out of band.
+      private def refuse_protected!(slug, container_dir)
+        manifest = YAML.safe_load(File.read(File.join(container_dir, MANIFEST)), permitted_classes: [Symbol]) || {}
+        origin = (manifest["origin"] || "self").to_s
+        if origin == "marketplace"
+          raise Error, "refusing to pack #{slug}: origin=marketplace is produced by the platform, not hand-packed"
+        end
+
+        enc = Dir.glob(File.join(container_dir, "**", "SKILL.md.enc"))
+        return if enc.empty?
+
+        raise Error, "refusing to pack #{slug}: contains encrypted skill(s): #{enc.map { |p| relative(container_dir, p) }.join(', ')}"
+      end
+
+      private def write_zip(container_dir, zip_path)
+        Zip::File.open(zip_path, create: true) do |zip|
+          files = Dir.glob(File.join(container_dir, "**", "*"), File::FNM_DOTMATCH)
+          files.each do |abs|
+            base = File.basename(abs)
+            next if base == "." || base == ".."
+
+            rel = relative(container_dir, abs)
+            entry = File.join(File.basename(container_dir), rel)
+            if File.directory?(abs)
+              zip.mkdir(entry) unless zip.find_entry(entry)
+            else
+              zip.add(entry, abs)
+            end
+          end
+        end
+      end
+
+      private def local_zip_for(source, tmp)
+        src = source.to_s
+        if src.match?(%r{\Ahttps?://})
+          dest = File.join(tmp, "download.zip")
+          download(src, dest)
+          dest
+        else
+          path = File.expand_path(src)
+          raise Error, "zip not found: #{path}" unless File.file?(path)
+          path
+        end
+      end
+
+      private def download(url, dest)
+        total = 0
+        URI.open(url, "rb") do |io| # rubocop:disable Security/Open
+          File.open(dest, "wb") do |out|
+            while (chunk = io.read(64 * 1024))
+              total += chunk.bytesize
+              raise Error, "download exceeds #{MAX_ZIP_SIZE} bytes" if total > MAX_ZIP_SIZE
+              out.write(chunk)
+            end
+          end
+        end
+      rescue OpenURI::HTTPError, SocketError => e
+        raise Error, "failed to download #{url}: #{e.message}"
+      end
+
+      private def extract_zip(zip_path, dest_root)
+        total = 0
+        Zip::File.open(zip_path) do |zip|
+          zip.each do |entry|
+            safe = safe_join(dest_root, entry.name)
+            total += entry.size.to_i
+            raise Error, "archive expands beyond #{MAX_ZIP_SIZE} bytes" if total > MAX_ZIP_SIZE
+
+            if entry.directory?
+              FileUtils.mkdir_p(safe)
+            else
+              FileUtils.mkdir_p(File.dirname(safe))
+              File.binwrite(safe, entry.get_input_stream.read)
+            end
+          end
+        end
+      end
+
+      # Reject zip-slip: the resolved path must stay inside dest_root.
+      private def safe_join(dest_root, name)
+        path = File.expand_path(File.join(dest_root, name))
+        root = File.expand_path(dest_root)
+        unless path == root || path.start_with?("#{root}#{File::SEPARATOR}")
+          raise Error, "unsafe path in archive: #{name.inspect}"
+        end
+        path
+      end
+
+      # A valid archive holds exactly one top-level directory that is the
+      # container (has ext.yml). Returns [ext_id, absolute_container_dir].
+      private def locate_container(root)
+        children = Dir.children(root).reject { |c| c.start_with?(".") }
+        dirs = children.select { |c| File.directory?(File.join(root, c)) }
+
+        if File.file?(File.join(root, MANIFEST))
+          return [File.basename(File.expand_path(root)), root]
+        end
+
+        if dirs.size == 1 && File.file?(File.join(root, dirs.first, MANIFEST))
+          return [dirs.first, File.join(root, dirs.first)]
+        end
+
+        raise Error, "archive does not contain a single container with #{MANIFEST}"
+      end
+
+      private def verify_installed(ext_id, installed_dir)
+        layers =
+          if installed_dir == Clacky::ExtensionLoader::INSTALLED_DIR
+            Clacky::ExtensionLoader.default_layers
+          else
+            { installed: installed_dir }
+          end
+        result = Clacky::ExtensionLoader.load_all(layers: layers, force: true)
+        issues = Clacky::ExtensionVerifier.verify(result)
+        errors = issues.select { |i| i.level == :error && i.ext == ext_id }
+        unless errors.empty?
+          detail = errors.map { |e| "  - #{e.code}: #{e.message}" }.join("\n")
+          raise Error, "installed #{ext_id} but verify found errors:\n#{detail}"
+        end
+        result.units.select { |u| u.ext_id == ext_id }
+      end
+
+      private def relative(base, abs)
+        Pathname.new(abs).relative_path_from(Pathname.new(base)).to_s
+      end
+    end
+  end
+end

data/lib/clacky/{patch_loader.rb → extension/patch_loader.rb}

@@ -53,10 +53,55 @@ module Clacky
             apply_one(patch_dir, meta_path, result)
           end
         end
+        load_extension_patches(result)
         @last_result = result
         result
       end
 
+      # Apply patches contributed by ext.yml containers (contributes.patches).
+      # ext.yml-driven patches use a flat shape (target + file [+ fingerprint])
+      # rather than the per-dir meta.yml + patch.rb layout, since the container
+      # author already owns the upgrade lifecycle. If `fingerprint` is given in
+      # ext.yml we still verify it; if absent we trust the author and require
+      # the file directly. Errors are isolated to that single patch.
+      def load_extension_patches(result)
+        units = Array(Clacky::ExtensionLoader.last_result&.patches)
+        units.each do |unit|
+          target   = unit.spec["target"]
+          file_abs = unit.spec["file_abs"]
+          recorded = unit.spec["fingerprint"].to_s
+          id       = "#{unit.ext_id}/#{File.basename(unit.spec['file'], '.rb')}"
+
+          if recorded.empty?
+            require file_abs
+            result.applied << id
+            log(:info, id, "applied → #{target} (no fingerprint, trusted)")
+            next
+          end
+
+          current = fingerprint(target)
+          if current != recorded
+            reason = "fingerprint mismatch — upstream code for #{target} changed"
+            if unit.spec["on_mismatch"] == "warn"
+              result.skipped << [id, "#{reason} (kept, not applied)"]
+              log(:warn, id, result.skipped.last[1])
+            else
+              result.skipped << [id, "#{reason} — disabled"]
+              log(:warn, id, result.skipped.last[1])
+            end
+            next
+          end
+
+          require file_abs
+          result.applied << id
+          log(:info, id, "applied → #{target}")
+        rescue StandardError, ScriptError => e
+          fallback_id = "#{unit&.ext_id}/#{File.basename(unit&.spec&.[]('file').to_s, '.rb')}"
+          result.skipped << [fallback_id, e.message]
+          log(:warn, fallback_id, e.message)
+        end
+      end
+
       def last_result
         @last_result || load_all
       end

data/lib/clacky/extension/scaffold/template_renderer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "erb"
+require "fileutils"
+require "ostruct"
+
+module Clacky
+  module ExtensionScaffold
+    # Copy a template directory into `target`, rendering `.erb` files with
+    # ERB and substituting `__key__` placeholders in path segments. Non-erb
+    # files are copied byte-for-byte.
+    #
+    # Placeholders in filenames use the `__slug__` form (double underscores
+    # around the key) — any locals key can be referenced this way.
+    class TemplateRenderer
+      PATH_PLACEHOLDER = /__([a-z_][a-z0-9_]*)__/.freeze
+
+      def self.render(template_dir:, target:, locals: {})
+        new(template_dir, target, locals).render
+      end
+
+      def initialize(template_dir, target, locals)
+        @template_dir = File.expand_path(template_dir)
+        @target       = target
+        @locals       = locals
+        @binding      = OpenStruct.new(locals).instance_eval { binding }
+      end
+
+      def render
+        raise ArgumentError, "template dir not found: #{@template_dir}" unless Dir.exist?(@template_dir)
+
+        Dir.glob(File.join(@template_dir, "**", "{*,.[!.]*}"), File::FNM_DOTMATCH).sort.each do |src|
+          next if [".", ".."].include?(File.basename(src))
+
+          rel  = src.sub(/\A#{Regexp.escape(@template_dir)}\/?/, "")
+          next if rel.empty?
+
+          dest = File.join(@target, substitute_path(rel))
+
+          if File.directory?(src)
+            FileUtils.mkdir_p(dest)
+          elsif File.extname(src) == ".erb"
+            FileUtils.mkdir_p(File.dirname(dest))
+            File.write(dest.sub(/\.erb\z/, ""), ERB.new(File.read(src), trim_mode: "-").result(@binding))
+          else
+            FileUtils.mkdir_p(File.dirname(dest))
+            FileUtils.cp(src, dest)
+          end
+        end
+
+        @target
+      end
+
+      private def substitute_path(rel)
+        rel.gsub(PATH_PLACEHOLDER) do
+          key = Regexp.last_match(1).to_sym
+          raise ArgumentError, "unknown path placeholder: __#{key}__" unless @locals.key?(key)
+
+          @locals[key].to_s
+        end
+      end
+    end
+  end
+end

data/lib/clacky/extension/scaffold/templates/full/README.md.erb

@@ -0,0 +1,48 @@
+# <%= slug %>
+
+Kitchen-sink reference extension generated by `clacky ext new --full`.
+It exercises every `contributes` type at once so you can copy-paste
+the parts you actually need into a real extension.
+
+## Contents
+
+- `panels/dashboard/view.js` — WebUI panel. Also demonstrates every UI hook at once:
+  a full-page workspace opened from three sidebar slots
+  (`sidebar.nav.top` above Sessions, `sidebar.nav` between
+  Sessions and Config, `sidebar.nav.bottom` at the end of the
+  rail — hash `#ext/<%= slug %>`), plus `session.banner`,
+  `session.aside`, and `session.composer` (quick-action
+  buttons that submit slash commands).
+- `api/handler.rb`    — HTTP backend mounted at `/api/ext/<%= slug %>/`
+                        (routes `/dashboard`, `/stats`)
+- `skills/<%= slug %>-skill/SKILL.md` — a skill contributed to the agent
+- `agents/designer.md` — a custom agent (`--agent designer`) that owns the panel + skill
+- `channels/noop.rb`  — a no-op IM channel adapter (`:<%= slug %>_noop`)
+- `patches/audit.rb`  — a monkey-patch on `Clacky::Tools::Terminal#execute`
+- `hooks/audit.rb`    — a `before_tool_use` hook callback
+
+## Verify
+
+```bash
+clacky ext verify       # schema + reference integrity check
+clacky ext list         # see all 7 units listed under <%= slug %>
+```
+
+## Try it
+
+- Reload the WebUI page → three sidebar entries appear:
+  **<%= slug %> console** at the top, **<%= slug %> menu (middle)** between
+  Sessions and Config, **<%= slug %> footer link** at the very bottom
+  (all global; every agent sees them)
+- Click any of them → main area switches to the full-page workspace at `#ext/<%= slug %>` (Load stats works)
+- Switch to the `designer` agent → see the **<%= slug %>** tab in the aside, plus a banner and quick-action buttons above the input
+- Click a quick-action button → it fills `#user-input` with `/<%= slug %>-skill …` and submits
+- `clacky --agent designer "say hi"` — uses the contributed skill
+- Run any tool from chat → see `[ext-hook] before_tool_use` in the log
+- Run a shell tool → see `[ext-audit] terminal.execute` from the patch
+
+## Trim it down
+
+When you know which contributes types you actually want, delete the
+others (and remove their entries from `ext.yml`). `clacky ext verify`
+will tell you if anything is left dangling.

data/lib/clacky/extension/scaffold/templates/full/agents/designer.md

@@ -0,0 +1,5 @@
+You are **Designer**, a demo agent shipped by this extension.
+
+Your job is to help the user iterate on visual design. You have a
+dashboard panel mounted in the WebUI session aside. Use it to surface
+information rather than dumping it into chat.

data/lib/clacky/extension/scaffold/templates/full/api/handler.rb.erb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# API backend for "<%= slug %>". Mounted at /api/ext/<%= slug %>/.
+# Group routes by feature (panel, standalone endpoint, webhook, ...) —
+# the mount point is shared, but paths keep them cleanly separated.
+class <%= const_prefix %>Ext < Clacky::ApiExtension
+  # ── Dashboard panel backend — /api/ext/<%= slug %>/dashboard/*
+  get "/dashboard" do
+    json(panel: "dashboard", at: Time.now.utc.iso8601)
+  end
+
+  # ── Standalone stats endpoint — /api/ext/<%= slug %>/stats
+  get "/stats" do
+    json(uptime: Process.clock_gettime(Process::CLOCK_MONOTONIC).round(2))
+  end
+end

data/lib/clacky/extension/scaffold/templates/full/channels/noop.rb.erb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Demo channel adapter for `:<%= slug %>_noop`. It doesn't actually
+# connect anywhere — it exists to show the wiring. Real adapters
+# (see the built-in Feishu / WeCom / Telegram / Discord ones) open
+# a long-poll or webhook and translate messages both ways.
+module Clacky
+  module Channel
+    module Adapters
+      class <%= const_prefix %>NoopAdapter < Base
+        def self.platform_id
+          :<%= slug %>_noop
+        end
+
+        def self.platform_config(_data)
+          {}
+        end
+
+        def initialize(config)
+          @config = config
+        end
+
+        def start(&_on_message)
+          # TODO: connect to your platform and yield events.
+        end
+
+        def stop
+          # TODO: tear down connections.
+        end
+
+        def send_text(_chat_id, text, reply_to: nil)
+          Clacky::Logger.info("[<%= slug %>_noop] would send: #{text}")
+          { message_id: "noop-#{Time.now.to_i}" }
+        end
+      end
+
+      register(<%= const_prefix %>NoopAdapter.platform_id, <%= const_prefix %>NoopAdapter)
+    end
+  end
+end

data/lib/clacky/extension/scaffold/templates/full/ext.yml.erb

@@ -0,0 +1,41 @@
+id: <%= slug %>
+name: <%= slug %>
+description: Kitchen-sink reference container — exercises all 7 contributes types.
+version: "0.1.0"
+author: (your name)               # shown as the credit on the New Session card
+origin: self
+contributes:
+  api: api/handler.rb              # single mount at /api/ext/<%= slug %>/
+  panels:
+    - id: dashboard
+      title: Dashboard
+      view: panels/dashboard/view.js
+      # No `attach:` — visibility is driven by the `designer` agent below,
+      # which references it via `panels: [dashboard]`. Set
+      # `attach: [<agent-id>]` (or `["*"]`) if you want the panel author to
+      # suggest a default mount without requiring agent-side references.
+  skills:
+    - id: <%= slug %>-skill        # SKILL.md under skills/<%= slug %>-skill/
+  agents:
+    - id: designer
+      title: Designer
+      title_zh: 设计师
+      description: A demo agent that owns the dashboard panel and the <%= slug %>-skill skill.
+      description_zh: 这是一个演示 agent，绑定 dashboard 面板和 <%= slug %>-skill 技能。
+      prompt: agents/designer.md
+      panels: [dashboard]
+      skills: [<%= slug %>-skill]
+  channels:
+    - id: noop
+      adapter: channels/noop.rb
+  patches:
+    # Patches monkey-patch real classes. The example target is a
+    # real, live method — Terminal#execute is called for every
+    # shell tool invocation. Omit `fingerprint:` to trust the patch
+    # (loader will require the file directly); provide one to have
+    # the loader disable/warn if upstream source drifts.
+    - target: "Clacky::Tools::Terminal#execute"
+      file: patches/audit.rb
+  hooks:
+    - event: before_tool_use
+      file: hooks/audit.rb

data/lib/clacky/extension/scaffold/templates/full/hooks/audit.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Hook callbacks contributed by this extension. The block is copied
+# onto each agent's HookManager at agent init time. The event name
+# comes from ext.yml — no need to repeat it here.
+Clacky::ExtensionHookRegistry.add do |tool_name, args|
+  Clacky::Logger.debug("[ext-hook] before_tool_use", tool: tool_name)
+  { action: :allow }
+end