zuzu 0.2.1-java → 0.2.3-java

data/templates/.claude/skills/customize/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: customize
+description: Customize the Zuzu app — change the app name, window size, system prompt persona, or extend the UI. Use when the developer wants to rebrand the app, add personality to the assistant, or make visual/behavioral changes.
+---
+
+# Customize Zuzu App
+
+Ask what the developer wants to change, then make the changes directly.
+
+## Step 1 — Understand the request
+
+AskUserQuestion: "What would you like to customize? Choose one or more:
+1. App name / window title
+2. Window size
+3. Assistant persona / system prompt instructions
+4. Add a new button or panel to the UI
+5. Something else — describe it"
+
+Route to the relevant section below based on the answer.
+
+---
+
+## Route A — App name and window title
+
+Read the current value from `app.rb`:
+
+```ruby
+Zuzu.configure do |c|
+  c.app_name = 'Current Name'
+```
+
+AskUserQuestion: "What should the app be called?"
+
+Edit `app.rb` — update `c.app_name`. Done. Tell the user to restart the app.
+
+---
+
+## Route B — Window size
+
+Read current values (`c.window_width`, `c.window_height`).
+
+AskUserQuestion: "What size should the window be? (e.g. 1024 × 768, 1280 × 800)"
+
+Edit `app.rb`:
+```ruby
+c.window_width  = 1024
+c.window_height = 768
+```
+
+Done. Tell the user to restart.
+
+---
+
+## Route C — Assistant persona and system prompt
+
+Read the current `c.system_prompt_extras` from `app.rb` (may be nil/absent).
+
+AskUserQuestion: "Describe the assistant's persona or any extra rules you want it to follow. Examples:
+- 'You are a Ruby developer assistant. Always use Ruby in code examples.'
+- 'You are a cooking assistant. Only discuss food, recipes, and nutrition.'
+- 'Always respond concisely in bullet points.'"
+
+AskUserQuestion: "Should this replace the current instructions or be added to them?"
+
+Edit `app.rb` — set or update `c.system_prompt_extras`:
+
+```ruby
+Zuzu.configure do |c|
+  # ...
+  c.system_prompt_extras = <<~EXTRA
+    <the persona instructions here>
+  EXTRA
+end
+```
+
+**Important rules to preserve** — always keep these in `system_prompt_extras` if the developer's text doesn't already cover them:
+- Do not override the tool-calling rules (those come from the base prompt automatically)
+- Keep instructions concise — the model sees this verbatim on every request
+
+Verify it loads:
+```bash
+bundle exec ruby -e "require 'zuzu'; load 'app.rb' rescue nil; puts Zuzu.config.system_prompt_extras" 2>&1
+```
+
+Done. Tell the user to restart.
+
+---
+
+## Route D — UI: add a button to the Admin Panel
+
+The Admin Panel is the popup window opened by the "Admin Panel" button.
+The easiest UI extension is adding a button there.
+
+AskUserQuestion: "What should the button do when clicked?"
+AskUserQuestion: "What label should the button have?"
+
+This requires subclassing `Zuzu::App`. Check if `app.rb` already subclasses it.
+
+**If not subclassing yet**, add this pattern to `app.rb` before `Zuzu::App.launch!`:
+
+```ruby
+class MyApp < Zuzu::App
+  private
+
+  def open_admin_panel
+    file_list_widget = nil
+
+    admin = shell {
+      text 'Admin Panel'
+      minimum_size 380, 500
+      grid_layout 1, false
+
+      label {
+        layout_data(:fill, :fill, true, false)
+        text 'AgentFS — Virtual File Browser'
+        font height: 12, style: :bold
+      }
+
+      file_list_widget = list(:single, :v_scroll, :border) {
+        layout_data(:fill, :fill, true, true)
+        font name: 'Monospace', height: 11
+      }
+
+      # ── Default buttons (keep these) ─────────────────────────
+      button {
+        layout_data(:fill, :fill, true, false)
+        text 'Create Test File'
+        on_widget_selected {
+          @fs.write_file('/test.txt', "Hello!\nCreated at: #{Time.now}")
+          populate_file_list(file_list_widget)
+        }
+      }
+
+      button {
+        layout_data(:fill, :fill, true, false)
+        text 'Clear Chat History'
+        on_widget_selected {
+          @memory.clear
+          message_box { text 'Done'; message 'History cleared.' }.open
+        }
+      }
+
+      button {
+        layout_data(:fill, :fill, true, false)
+        text 'Refresh'
+        on_widget_selected { populate_file_list(file_list_widget) }
+      }
+
+      # ── New custom button ─────────────────────────────────────
+      button {
+        layout_data(:fill, :fill, true, false)
+        text '<Button Label>'
+        on_widget_selected {
+          # your action here
+          message_box { text 'Done'; message 'Action completed.' }.open
+        }
+      }
+    }
+
+    populate_file_list(file_list_widget)
+    admin.open
+  end
+end
+```
+
+Then change the launch line to:
+```ruby
+MyApp.launch!(use_llamafile: true)
+```
+
+**Glimmer DSL rules to enforce:**
+- `layout_data(:fill, :fill, true, false)` — always use argument form, never block form
+- Never call widget methods from a background thread — wrap in `async_exec { }`
+- Never use `sash_form` — invisible on macOS
+
+Verify syntax:
+```bash
+bundle exec ruby -e "require 'zuzu'; load 'app.rb' rescue puts $!.message" 2>&1
+```
+
+Done. Tell the user to restart.
+
+---
+
+## Route E — Something else
+
+Read `AGENTS.md` for the relevant section and implement accordingly.
+Always verify with a syntax check after making changes:
+
+```bash
+bundle exec ruby -e "require 'zuzu'; load 'app.rb' rescue puts $!.message" 2>&1
+```

data/templates/.claude/skills/debug/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: debug
+description: Diagnose and fix Zuzu app issues. Use when the app won't start, the agent isn't responding, tools aren't being called, the LLM seems stuck, or the UI is broken. Runs a systematic health check and fixes what it finds.
+---
+
+# Debug Zuzu App
+
+Run each check in order. Fix problems as they're found — don't present a list and ask the user to fix them.
+
+## Check 1 — Ruby code syntax
+
+```bash
+bundle exec ruby -e "require 'zuzu'; load 'app.rb'" 2>&1
+```
+
+- If syntax error or LoadError: fix the error in `app.rb`, re-run, continue.
+- If clean: continue.
+
+## Check 2 — Registered tools
+
+```bash
+bundle exec ruby -e "
+require 'zuzu'
+load 'app.rb' rescue nil
+tools = Zuzu::ToolRegistry.tools
+if tools.empty?
+  puts 'WARNING: No tools registered'
+else
+  tools.each { |t| puts '  - ' + t.name + ': ' + t.description }
+end
+" 2>&1
+```
+
+- No tools: check `app.rb` — registrations must be before `Zuzu::App.launch!`. Fix and retry.
+- Tools listed: continue.
+
+## Check 3 — Model file
+
+Read `app.rb` to find `c.llamafile_path`. Then:
+
+```bash
+ls -lh <model_path> 2>&1
+```
+
+- File not found: tell the user they need to download the model to the `models/` directory.
+- File exists but not executable: `chmod +x <model_path>` — do this automatically.
+- File ok: continue.
+
+## Check 4 — Is llamafile running?
+
+```bash
+curl -s --max-time 3 http://127.0.0.1:8080/v1/models 2>&1
+```
+
+- Connection refused / timeout: llamafile isn't running. The app starts it — check the log:
+
+```bash
+ls models/*.log 2>/dev/null && tail -30 models/*.log 2>/dev/null || echo "No log file found"
+```
+
+Common causes:
+- Model file not found (covered above)
+- Port 8080 already in use: `lsof -i :8080` — if another process, kill it or change port in `app.rb`
+- Model too large for available RAM — check `tail -5 models/llama.log` for OOM errors
+
+- Returns JSON with models: llamafile is running. Continue.
+
+## Check 5 — LLM responds to a basic chat
+
+```bash
+curl -s --max-time 30 http://127.0.0.1:8080/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"LLaMA_CPP","messages":[{"role":"user","content":"reply with the single word: OK"}],"temperature":0.1}' \
+  2>&1 | head -5
+```
+
+- Returns JSON with `OK` in choices: LLM is healthy. Continue.
+- Times out: model is still loading. Wait 30s, retry.
+- Error: check `models/llama.log` for details.
+
+## Check 6 — Tool call parsing (agent loop)
+
+```bash
+bundle exec zuzu console 2>/dev/null <<'EOF'
+store  = Zuzu::Store.new
+fs     = Zuzu::AgentFS.new(store)
+memory = Zuzu::Memory.new(store)
+llm    = Zuzu::LlmClient.new
+agent  = Zuzu::Agent.new(agent_fs: fs, memory: memory, llm: llm)
+result = agent.process('What time is it? Use the current_time tool if available, otherwise just say hello.')
+puts "Agent response: #{result}"
+EOF
+```
+
+- Response contains sensible text: agent loop works.
+- `Max iterations reached`: model isn't calling tools. See "Agent not calling tools" below.
+- Error: read the traceback, fix the root cause.
+
+## Check 7 — Recent tool call history
+
+```bash
+bundle exec ruby -e "
+require 'zuzu'
+store = Zuzu::Store.new
+rows = store.query_all('SELECT tool_name, input, output, started_at FROM tool_calls ORDER BY started_at DESC LIMIT 10')
+if rows.empty?
+  puts 'No tool calls recorded yet'
+else
+  rows.each { |r| puts r['tool_name'] + ' → ' + r['output'].to_s[0,80] }
+end
+" 2>&1
+```
+
+- Shows recent calls: tools are firing.
+- Empty: either app hasn't been used yet, or tools aren't being called.
+
+## Check 8 — AgentFS health
+
+```bash
+bundle exec ruby -e "
+require 'zuzu'
+store = Zuzu::Store.new
+fs    = Zuzu::AgentFS.new(store)
+fs.write_file('/debug_test.txt', 'hello')
+result = fs.read_file('/debug_test.txt')
+puts result == 'hello' ? 'AgentFS OK' : 'AgentFS BROKEN: got ' + result.inspect
+fs.delete('/debug_test.txt')
+" 2>&1
+```
+
+- "AgentFS OK": filesystem healthy.
+- Error: check that `.zuzu/` directory is writable: `ls -la .zuzu/`
+
+---
+
+## Known issues and fixes
+
+### Agent not calling tools
+
+The most common cause is the model not following the system prompt reliably.
+
+1. **Check the system prompt is being built**: open `bundle exec zuzu console` and run:
+   ```ruby
+   require 'zuzu'; load 'app.rb' rescue nil
+   store = Zuzu::Store.new; fs = Zuzu::AgentFS.new(store); memory = Zuzu::Memory.new(store); llm = Zuzu::LlmClient.new
+   agent = Zuzu::Agent.new(agent_fs: fs, memory: memory, llm: llm)
+   puts agent.send(:build_system_prompt)
+   ```
+   Verify your tools appear in the "Available tools:" section.
+
+2. **Check `system_prompt_extras`** — if it contains conflicting instructions (e.g. "never use tools") it can override the base prompt.
+
+3. **Model quality** — llava-v1.5-7b-q4 is a vision model and follows tool-calling instructions inconsistently. Try a more capable model or rephrase your request to more explicitly ask for tool use.
+
+### Blank or invisible UI widgets
+
+Caused by wrong `layout_data`. Check `app.rb` for any subclassed body or UI code:
+
+- `layout_data(:fill, :fill, true, true)` on an input composite → change last arg to `false`
+- `layout_data { height_hint N }` → replace with `layout_data(:fill, :center, false, false)`
+- `sash_form` → remove and replace with plain `composite`
+
+### SWT thread error / crash on UI update
+
+Wrap all widget updates that happen inside `Thread.new` with `async_exec`:
+
+```ruby
+Thread.new do
+  result = do_something_slow
+  async_exec { @chat_display.swt_widget.set_text(result) }  # ← required
+end
+```
+
+### Port 8080 already in use
+
+```bash
+lsof -i :8080
+```
+
+Kill the occupying process, or change `c.port = 8081` in `app.rb` — the LLM client and manager both read from config.
+
+### Database locked
+
+Only one process can write to `.zuzu/zuzu.db` at a time. Ensure only one instance of the app is running.
+
+---
+
+## Summary output
+
+After all checks, tell the user:
+- ✅/❌ Ruby syntax
+- ✅/❌ Tools registered (list names)
+- ✅/❌ Model file
+- ✅/❌ LLM running
+- ✅/❌ LLM responding
+- ✅/❌ AgentFS healthy
+- Any fixes applied + next steps

data/templates/.claude/skills/setup/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: setup
+description: First-time setup for a Zuzu app. Verifies JRuby and Java versions, runs bundle install, checks the model file exists, and does a smoke-test launch. Use when the developer first clones or scaffolds the app, or when the runtime environment seems broken.
+---
+
+# Zuzu App Setup
+
+Run each step automatically. Only pause when the user must take an action (e.g. downloading a model file). Fix problems directly — don't tell the user to fix them unless it genuinely requires their input.
+
+## Step 1 — Verify Java 21+
+
+```bash
+java -version 2>&1
+```
+
+- If missing or < 21: `brew install --cask temurin@21` (macOS) or `sudo apt-get install openjdk-21-jdk` (Linux). Re-check after.
+- If correct: continue.
+
+## Step 2 — Verify JRuby 10.0.3.0
+
+```bash
+ruby -v
+```
+
+- Must show `jruby 10.0.3.0`. If not:
+  - Check rbenv: `rbenv versions`
+  - If jruby-10.0.3.0 is listed but not active: `rbenv local jruby-10.0.3.0`
+  - If not installed: `rbenv install jruby-10.0.3.0 && rbenv local jruby-10.0.3.0`
+  - Re-check after.
+
+## Step 3 — Bundle install
+
+```bash
+bundle install 2>&1
+```
+
+- If fails: read the error. Common fixes:
+  - Native extension failure → ensure Java 21 is on PATH, retry
+  - Network error → `bundle config mirror.https://rubygems.org https://rubygems.org`, retry
+  - Wrong ruby → `rbenv local jruby-10.0.3.0`, retry
+
+## Step 4 — Verify Zuzu loads
+
+```bash
+bundle exec ruby -e "require 'zuzu'; puts 'Zuzu ' + Zuzu::VERSION + ' loaded OK'"
+```
+
+- If LoadError: re-run `bundle install`, then retry.
+
+## Step 5 — Check model file
+
+Read `app.rb` and find the `c.llamafile_path` value.
+
+Check if the model file exists at that path:
+
+```bash
+ls -lh <extracted_model_path>
+```
+
+- If missing:
+  - AskUserQuestion: "No model file found. Would you like instructions for downloading llava-v1.5-7b-q4.llamafile (~4 GB)?"
+  - If yes, tell the user:
+    ```bash
+    mkdir -p models
+    curl -L -o models/llava-v1.5-7b-q4.llamafile \
+      https://huggingface.co/Mozilla/llava-v1.5-7b-llamafile/resolve/main/llava-v1.5-7b-q4.llamafile
+    chmod +x models/llava-v1.5-7b-q4.llamafile
+    ```
+  - This requires the user to run it (large download). Tell them to re-run `/setup` after.
+- If exists but not executable: `chmod +x <path>` — do this automatically.
+- If exists and executable: continue.
+
+## Step 6 — Smoke test (without model)
+
+Test that the Ruby code parses and tools load without launching the GUI:
+
+```bash
+bundle exec ruby -e "
+require 'zuzu'
+load 'app.rb' rescue nil
+puts 'Tools registered: ' + Zuzu::ToolRegistry.tools.map(&:name).join(', ')
+" 2>&1 | head -20
+```
+
+- If it shows tool names: good.
+- If Ruby syntax error or LoadError: read the error, fix it in `app.rb`, retry.
+
+## Step 7 — Summary
+
+Tell the user:
+- ✅ Java version found
+- ✅ JRuby version confirmed
+- ✅ Gems installed
+- ✅ Zuzu loads
+- ✅/⚠️ Model file status
+- ✅ Tools registered: (list them)
+
+If model is ready:
+> Everything is set. Run `bundle exec zuzu start` to launch the app.
+
+If model is missing:
+> Download the model file (see step 5), then run `bundle exec zuzu start`.