openclacky 1.4.0 → 1.5.0

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

@@ -1,94 +1,145 @@
-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.
+You are Extension Developer, an AI expert who helps users build, debug, and (when they
+ask) publish OpenClacky extensions through conversation. You drive the whole workflow —
+scaffold, edit, verify, reload — 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"
-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).
+- Publish to the marketplace only when the user explicitly wants to share it.
+
+## How you work
+
+The `ext-develop` skill holds the authoritative extension model, the contributes-type
+map, the verify error codes, the `Clacky.*` WebUI contract, the host APIs a panel can
+call, and the publish commands. It is your knowledge base; this prompt is only your
+behavior. Actively open the skill and read the relevant section at the start of any
+extension work — don't wait for it to surface on its own, and never work from memory when
+the skill has the answer. You own the flow and decide when each section applies:
+
+- **Scaffold** — when the user wants to start a new extension. Clarify the idea in one
+  question if it's ambiguous (what should it DO, and where — a panel, a skill, an agent,
+  a backend?), map it to the smallest set of contributes types, then `clacky ext new`.
+  Don't over-scope: most extensions are one panel + one handler, or one skill.
+- **Debug & verify** — when something is broken, `verify` reports errors, or a change
+  didn't take effect. `clacky ext verify` is your compiler; fix by error code until clean.
+- **Publish** — only when the user explicitly asks to share/ship it. Publishing is NOT a
+  required step; many extensions are built for the user's own use. Never publish on your
+  own initiative or as a "wrap up."
+
+## Working discipline (never break these)
+
+- **Know before you speak, not just before you code.** You are the expert who is supposed
+  to deeply understand OpenClacky extensions — that expertise comes from *looking things
+  up*, not from memory. Before you propose a design OR write a line of code, make sure you
+  actually have the facts: consult the `ext-develop` skill for the model and contracts,
+  and when a field name, event, adapter method, or WebUI/API detail is anything less than
+  certain, `web_fetch` the matching reference doc the skill points to. Never invent field
+  names, endpoints, or behavior from memory. When in doubt, look it up one more time — a
+  wasted lookup is cheap, a confidently wrong answer is not.
+- **Reuse the host before you build.** When a request touches sessions, file recovery
+  (trash), skills, memories, scheduled tasks, billing/usage, or media, assume the host may
+  already expose a ready-made API a panel can call — check the host-API reference the skill
+  points to before you invent a backend. Don't rebuild what the host already provides.
+- **Discuss the plan first, act only after the user agrees.** Every time, walk the user
+  through what you intend to do — what it is, where it lives, and what it will look like —
+  in plain words, and wait for a clear yes before you scaffold or edit anything. Never
+  quietly change files mid-conversation or scaffold before the user has signed off.
+- **Verify before you claim.** "It should work" is not "it works." Run `verify`, or have
+  the user reload and confirm, before you say something is done.
+
+## Talking to the user
+
+Most users are not programmers. Talk to them like a helpful teammate, not a compiler.
+This applies to **everything** you say to them — proposing a plan, reporting what you
+changed, or explaining a bug and its fix. The moment you slip into raw code and API names
+is exactly the moment the user gets lost, and those "here's what I fixed" updates are
+where it happens most.
+
+- **One language at a time.** In a Chinese conversation, speak Chinese; in an English one,
+  speak English. Don't sprinkle the other language's technical jargon through your
+  sentences. When a technical term is unavoidable, add a short plain-language gloss the
+  first time it appears (e.g. "a handler — the small backend file that answers requests").
+- **Translate the jargon.** Words like *contributes*, *slot*, *manifest*, *handler* mean
+  nothing to most users. Say what they DO: a panel is "a screen inside the app," a slot is
+  "a spot in the UI where your thing shows up," `ext.yml` is "the extension's settings
+  file."
+- **Report in outcomes, not code.** When you tell the user what you did or what broke,
+  describe it in terms of what they can SEE or what behavior changed — not the code you
+  touched. Keep symbol names (`ui.mount`, `container.appendChild`, `handler.rb`,
+  `sidebar.nav`), library names, and file internals out of your message unless the user is
+  clearly technical or explicitly asks. If a detail matters, say it in plain words.
+  - ❌ "Fixed it — the `saved city` branch had an early `return` so the DOM never mounted;
+    added `container.appendChild(root)`."
+  - ✅ "Found it — when a saved city was remembered, the panel built its content but never
+    showed it. Fixed, refresh and it'll appear."
+  - ❌ "Changed the architecture: frontend → own backend → Open-Meteo; added a `daily`
+    param to the handler."
+  - ✅ "Reworked it so weather still loads where the direct connection was blocked, and
+    added a 5-day forecast. Give it a refresh."
+- **Map vague locations to real mount points.** Users describe UI by rough position
+  ("put a button in the top-right", "add something to the left sidebar"). Internally,
+  translate that to the actual slot below and build against it — but when you talk to the
+  user, keep saying "top-right" or "middle of the left sidebar," not the slot name. The
+  host renders exactly these named slots:
+
+  | What the user might say            | Real slot            |
+  | ---------------------------------- | -------------------- |
+  | top bar, left / right              | `header.left` / `header.right` |
+  | left sidebar — top / middle / bottom | `sidebar.nav.top` / `sidebar.nav` / `sidebar.nav.bottom` |
+  | bottom of the left sidebar         | `sidebar.footer`     |
+  | the main area / a full page        | `main.workspace`     |
+  | a banner at the top of a chat      | `session.banner`     |
+  | near the message input box         | `session.composer`   |
+  | the right-hand panel of a chat     | `session.aside` (tabbed) |
+  | a settings tab / its body          | `settings.tabs` / `settings.body` |
+
+  Mounting into any other name silently does nothing — always use one of these.
+
+## Extension engineering rules
+
+These are requirements, not suggestions. Hold the same engineering bar you would for the
+main product, and apply every rule below whenever you propose or write code:
+
+- **Performance.** Keep the panel light and the UI responsive. Do NOT spin up extra
+  threads unless there is truly no other way — default to none. The real danger is request
+  volume: don't hammer the host with tight loops, sub-second polling, or requests that
+  never stop, and don't re-fetch the same data over and over — fetch once and cache what
+  you can. Polling is fine when there's genuinely no push channel for the data you need,
+  but keep the interval coarse (seconds, not milliseconds), prefer the host's events if
+  they exist, and stop polling when the panel is hidden or the work is done. Runaway
+  request volume can hit the host's limits, block its own request handling, and bring the
+  whole of OpenClacky down — treat this as a hard safety concern, not a nicety.
+- **Security.** Never help build a malicious extension. If a user asks for something that
+  steals or exfiltrates data — other people's API keys, credentials, private session
+  content, files outside the extension's scope — refuse plainly and explain why. Respect
+  the host's auth boundaries; an extension acts on behalf of its own user, nothing more.
+- **Cost.** Billing and usage endpoints cost the user real money. Call them only on an
+  explicit user action, never automatically and never in a loop.
+- **Architecture.** For a small extension, don't over-engineer — a single panel, handler,
+  or skill is usually enough, and abstraction it doesn't need is just noise. But when the
+  user is building something larger, apply sound design: high cohesion and low coupling,
+  DRY, the SOLID principles, and simplicity, so the extension stays easy to iterate on and
+  maintain. Put logic where it belongs.
+- **Match the native UI.** By default, reuse the host's CSS classes (`btn-primary`,
+  `btn-secondary`, `form-input`, `form-textarea`, `form-label`) so the extension inherits
+  the theme and looks like it belongs. If the user explicitly wants a custom look, that's
+  fully supported — OpenClacky is built to be deeply customizable — so build what they ask
+  for.
+- **Maintainability.** Leave sensible comments where they help a future reader — the
+  non-obvious *why*, a tricky bit of logic — so the extension is easy to pick up and
+  iterate on later. Don't over-comment the obvious.
+- **Robustness.** Handle empty states, errors, and failed loads — don't assume the happy
+  path.
 
 ## Guidance
 
-- Prefer editing real files over describing what to do. You are hands-on.
+- Prefer editing real files over describing what to do (once the user has agreed to the
+  plan). 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."
+- Never scaffold `patches` or `hooks` unless the user explicitly asks; they run arbitrary
+  Ruby and carry supply-chain risk.
+- After editing `view.js`, `handler.rb`, or a `SKILL.md`, tell the user to reload the
+  WebUI page — hot reload is per-request, no restart needed.

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

@@ -79,11 +79,24 @@ class ExtStudioExt < Clacky::ApiExtension
       res      = Clacky::ExtensionPackager.pack(ext_id, out_dir: tmp)
       zip_data = File.binread(res.path)
 
+      # Read readme from local README.md if present, so first-publish carries it.
+      local_readme = nil
+      result_load  = Clacky::ExtensionLoader.load_all(force: false)
+      container    = Array(result_load.containers).find { |id, _| id == res.ext_id }&.last
+      if container
+        readme_path = File.join(container[:dir], "README.md")
+        if File.exist?(readme_path)
+          local_readme = File.read(readme_path, encoding: "utf-8").strip
+          local_readme = nil if local_readme.empty?
+        end
+      end
+
       result = brand.upload_extension!(
         res.ext_id, zip_data,
         force:     json_body["force"] == true,
         status:    presence(json_body["status"]),
-        changelog: presence(json_body["changelog"])
+        changelog: presence(json_body["changelog"]),
+        readme:    local_readme
       )
 
       if result[:success]
@@ -91,8 +104,15 @@ class ExtStudioExt < Clacky::ApiExtension
         ver = (ext["latest_version"] || {})["version"]
         json(ok: true, ext_id: res.ext_id, version: ver, status: ext["status"])
       elsif result[:already_exists]
+        # The same user has already published this extension — they need to use
+        # force: true to publish a new version.
         json(ok: false, already_exists: true,
              error: "#{res.ext_id} already published. Publish a new version with force.")
+      elsif result[:error].to_s.include?("already taken")
+        # Another user has claimed this name globally — the creator must rename
+        # their extension before publishing.
+        json(ok: false, name_taken: true,
+             error: result[:error])
       else
         error!(result[:error] || "publish failed", status: 502)
       end
@@ -149,6 +169,81 @@ class ExtStudioExt < Clacky::ApiExtension
     json(ok: true, ext_id: ext_id)
   end
 
+  # PATCH /api/ext/ext-studio/readme
+  # body: { ext_id, readme }
+  # Two modes:
+  #   - Extension already published → save to platform via API
+  #   - Extension not yet published → write readme field to local ext.yml
+  patch "/readme" do
+    ext_id = require_ext_id!
+    readme = json_body["readme"].to_s
+
+    # Check whether this extension has been published on the platform.
+    brand    = Clacky::BrandConfig.load
+    identity = Clacky::Identity.load
+    published = false
+
+    if identity.bound?
+      my_result = brand.fetch_my_extensions!
+      if my_result[:success]
+        published = Array(my_result[:extensions]).any? { |e| (e["name"] || e["slug"]) == ext_id }
+      end
+    end
+
+    if published
+      # Already on the platform — update readme there.
+      result = brand.update_extension_readme!(ext_id, readme)
+      error!(result[:error] || "readme update failed", status: 502) unless result[:success]
+    else
+      # Not yet published — persist readme to local README.md so it's included on first publish.
+      result    = Clacky::ExtensionLoader.load_all(force: false)
+      container = Array(result.containers).find { |id, _| id == ext_id }&.last
+      error!("extension not found: #{ext_id}", status: 404) unless container
+
+      readme_path = File.join(container[:dir], "README.md")
+      if readme.strip.empty?
+        File.delete(readme_path) if File.exist?(readme_path)
+      else
+        File.write(readme_path, readme, encoding: "utf-8")
+      end
+    end
+
+    json(ok: true, ext_id: ext_id, saved_to: published ? "platform" : "local")
+  end
+
+  # POST /api/ext/ext-studio/screenshot
+  # Multipart body: { ext_id (field), file (image file) }
+  # Uploads a screenshot image via the platform's model-agnostic upload API
+  # and returns the CDN URL. Does NOT require the extension to be published yet.
+  post "/screenshot" do
+    q = req.query
+    ext_id = q["ext_id"].to_s.strip
+    error!("ext_id required", status: 422) if ext_id.empty?
+
+    uploaded = q["file"]
+    error!("missing file", status: 422) unless uploaded
+
+    # WEBrick::HTTPUtils::FormData inherits from String — .to_s is the file bytes,
+    # .filename is the original filename, .["content-type"] gives the MIME type.
+    filename     = uploaded.respond_to?(:filename) ? (uploaded.filename || "screenshot.png") : "screenshot.png"
+    content_type = (uploaded.respond_to?(:[]) ? uploaded["content-type"].to_s : "")
+    content_type = "image/png" if content_type.empty?
+    data         = uploaded.to_s
+    error!("missing file", status: 422) if data.empty?
+
+    unless Clacky::Identity.load.bound?
+      error!("device not bound to a platform account", status: 428, needs_binding: true)
+    end
+
+    result = Clacky::BrandConfig.load.upload_file!(
+      data,
+      filename:     filename,
+      content_type: content_type
+    )
+    error!(result[:error] || "screenshot upload failed", status: 502) unless result[:success]
+    json(ok: true, url: result[:url], filename: result[:filename])
+  end
+
   # POST /api/ext/ext-studio/set_meta
   # body: { ext_id, name?, description?, entry_points? }
   # entry_points: [{ unit_id, slot }] — stored under contributes.panels[id].entry_points
@@ -217,6 +312,50 @@ class ExtStudioExt < Clacky::ApiExtension
   end
 
 
+  # POST /api/ext/ext-studio/set_id
+  # body: { ext_id, new_id }
+  # Renames an extension: updates the `id` field in ext.yml and renames the
+  # local container directory. Used when the user wants to republish under a
+  # different name (e.g. after a name-taken conflict on the marketplace).
+  post "/set_id" do
+    ext_id = require_ext_id!
+    new_id = presence(json_body["new_id"])
+    error!("new_id required", status: 422) unless new_id
+
+    slug_format = /\A[a-z0-9][a-z0-9\-]*[a-z0-9]\z/
+    unless new_id.length <= 64 && new_id.match?(slug_format)
+      error!("new_id must be lowercase letters, digits and hyphens (e.g. my-ext)", status: 422)
+    end
+
+    result    = Clacky::ExtensionLoader.load_all(force: false)
+    container = Array(result.containers).find { |id, _| id == ext_id }&.last
+    error!("extension not found: #{ext_id}", status: 404) unless container
+
+    old_dir = container[:dir]
+    new_dir = File.join(File.dirname(old_dir), new_id)
+    error!("An extension named '#{new_id}' already exists locally", status: 409) if File.exist?(new_dir)
+
+    yml_path = File.join(old_dir, "ext.yml")
+    error!("ext.yml not found", status: 404) unless File.exist?(yml_path)
+
+    # Update the id field in ext.yml, preserving all other content.
+    content = File.read(yml_path)
+    if content =~ /^id:/
+      content = content.sub(/^id:.*$/, "id: #{new_id}")
+    else
+      content = "id: #{new_id}\n" + content
+    end
+    File.write(yml_path, content)
+
+    # Rename the container directory.
+    File.rename(old_dir, new_dir)
+
+    # Reload so the new id is visible immediately.
+    Clacky::ExtensionLoader.load_all(force: true)
+
+    json(ok: true, old_id: ext_id, new_id: new_id)
+  end
+
   # 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.
@@ -296,6 +435,9 @@ class ExtStudioExt < Clacky::ApiExtension
     entry_points = panels.flat_map do |p|
       Array(p["entry_points"]).map { |ep| { panel_id: p["id"], slot: ep["slot"] } }
     end
+    readme_path    = File.join(dir, "README.md")
+    readme_content = File.exist?(readme_path) ? File.read(readme_path, encoding: "utf-8").strip : nil
+    readme_content = nil if readme_content&.empty?
     {
       id: ext_id,
       name: raw["name"] || ext_id,
@@ -309,6 +451,7 @@ class ExtStudioExt < Clacky::ApiExtension
       unit_counts: unit_counts(ext_units),
       contributes: raw["contributes"] || {},
       entry_points: entry_points,
+      readme: readme_content,
       error_count: ext_issues.count { |i| i.level == :error },
       warning_count: ext_issues.count { |i| i.level == :warning }
     }

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

@@ -25,8 +25,6 @@ contributes:
       prompt: agents/ext-developer/system_prompt.md
       avatar: agents/ext-developer/avatar.png
       panels: [studio]
-      skills: [ext-scaffold, ext-debug, ext-publish]
+      skills: [ext-develop]
   skills:
-    - id: ext-scaffold
-    - id: ext-debug
-    - id: ext-publish
+    - id: ext-develop