zuzu 0.0.1-java → 0.2.2-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae81f9e580d8c3e0efd863e9f56b6719a9cd08a092dc6b998ab8bf703ddae000
-  data.tar.gz: 287c409a0507b53f2f313da7fb2b00466180680641b36b81cc1d23b9046654db
+  metadata.gz: b6098f883dec29f87b5dcece9c69f8e115608cfd89b9cf045fd442355fbf48c9
+  data.tar.gz: d9ffeb971f19158a6262401bdcadb7791bdbd70523c843dd6b7ac26cc3a4c536
 SHA512:
-  metadata.gz: 500c75552b9483fa2414a17971e3cce3d3c02f12ee0e02f63d723165e7ed1ba9c4b2f75b36d8520d4cbc52127331d11560e2bbca0eca4533e02c426e56e1e597
-  data.tar.gz: aa6f574afac309ef301b12632ee791521ee8ec287fcd4d933472c19cd7adc354e4d92c3f42871dc964ae343dde436ce0be01e6e83166ac7784f2389b9c3684db
+  metadata.gz: b7d6f2d65abfc635d0dceec2122a788d7d2cc03159969c9e06a1b03a45e73eb9c03bf430d5f1a6170a7aaa8c717961bc5c51311336cdf80ab4a3b28feb1dc8b4
+  data.tar.gz: b10535955c154eee0eaade46edb4ee5b1b9049e8e224cea1d49da58553d1bbd1ae263045977f9a1ac6d87dbb5bf0c7da62e26e73eb5ec0c4b3bf8152ba699f58

data/README.md

@@ -1,9 +1,22 @@
 # Zuzu
 
-**Local-first agentic desktop apps with JRuby.**
+**Build AI-native desktop apps that run entirely on the user's machine.**
 
-Zuzu is a framework for building privacy-respecting AI desktop assistants that
-run entirely on your machine. No cloud APIs required — your data stays local.
+Every application you install on an operating system does the same fundamental thing: it translates human intent into OS system calls. A text editor writes bytes to disk. A browser opens network connections. At its core, every installed app is an orchestrator of operating system capabilities.
+
+LLMs are simply a more expressive interface for exactly that orchestration. Zuzu is a framework built on this premise — for developers who want to ship installable, AI-native desktop apps where the intelligence runs on the user's hardware, not in a data center.
+
+**Why does this matter?**
+
+- **Privacy by architecture.** The agent operates inside AgentFS — a sandboxed virtual filesystem backed by a single SQLite file. It cannot touch the host OS unless you explicitly open that door. There is no network call to make, no token to rotate, no terms of service that changes next quarter.
+
+- **Deployable like software, not like a service.** Package your app as a single `.jar`. Users pay, download, double-click, and run. No Docker. No cloud subscription. No infrastructure to maintain. The JVM handles cross-platform distribution the way it has for 30 years.
+
+- **Built for regulated environments.** A therapist keeping session notes, an auditor running confidential analysis, a corporate team in a restricted environment — these are exactly the users who benefit most from powerful AI but are currently blocked by cloud dependency. A bundled LLM in a self-contained Java application needs no external approval to run.
+
+- **Developer experience that matches how software is actually built today.** `zuzu new my_app` scaffolds a project pre-wired for Claude Code: CLAUDE.md, skills for `/setup`, `/add-tool`, `/customize`, and `/debug` — all enforcing Zuzu's patterns. Open the folder, start your coding agent, describe what you want to build.
+
+→ [Why Zuzu exists](docs/why.md) · [Quick Demo](https://raw.githubusercontent.com/parolkar/zuzu/refs/heads/main/docs/demo/zuzu_quick_demo_01.mp4)
 
 <video src="https://raw.githubusercontent.com/parolkar/zuzu/refs/heads/main/docs/demo/zuzu_quick_demo_01.mp4" controls width="100%"></video>
 [Quick Demo](https://raw.githubusercontent.com/parolkar/zuzu/refs/heads/main/docs/demo/zuzu_quick_demo_01.mp4)
@@ -32,7 +45,7 @@ cd zuzu
 bin/setup
 ```
 
-`bin/setup` installs Java 21, JRuby 10.0.4.0, and all gem dependencies
+`bin/setup` installs Java 21, JRuby 10.0.3.0, and all gem dependencies
 automatically. If you prefer manual setup, see [Manual Setup](#manual-setup)
 below.
 
@@ -61,9 +74,11 @@ Edit `app.rb` to point at your model:
 
 ```ruby
 Zuzu.configure do |c|
-  c.app_name       = 'My Assistant'
-  c.llamafile_path = File.expand_path('models/llava-v1.5-7b-q4.llamafile', __dir__)
-  c.db_path        = File.expand_path('.zuzu/zuzu.db', __dir__)
+  c.app_name = 'My Assistant'
+  # Works both when run directly and from a packaged .jar
+  base = __dir__.to_s.start_with?('uri:classloader:') ? Dir.pwd : __dir__
+  c.llamafile_path = File.join(base, 'models', 'llava-v1.5-7b-q4.llamafile')
+  c.db_path        = File.join(base, '.zuzu', 'zuzu.db')
   c.port           = 8080
 end
 ```
@@ -71,16 +86,11 @@ end
 Launch:
 
 ```bash
-# macOS (SWT requires first-thread access):
-JRUBY_OPTS="-J-XstartOnFirstThread -J--enable-native-access=ALL-UNNAMED" bundle exec ruby app.rb
-
-# Linux:
-JRUBY_OPTS="-J--enable-native-access=ALL-UNNAMED" bundle exec ruby app.rb
+bundle exec zuzu start
 ```
 
-You'll see a native desktop window with a file browser on the left and a chat
-interface on the right. The llamafile model starts automatically in the
-background.
+You'll see a native desktop chat window. The llamafile model starts automatically
+in the background. Click **Admin Panel** to browse the AgentFS virtual filesystem.
 
 ---
 
@@ -90,18 +100,14 @@ If `bin/setup` doesn't suit your workflow, follow these steps.
 
 ### 1. Install Java 21+
 
-**macOS (Homebrew):**
+**macOS (Homebrew — recommended):**
 
 ```bash
-brew install openjdk@21
+brew install --cask temurin@21
 ```
 
-Add to your shell profile (`~/.zshrc` or `~/.bash_profile`):
-
-```bash
-export JAVA_HOME=$(/usr/libexec/java_home -v 21)
-export PATH="$JAVA_HOME/bin:$PATH"
-```
+Temurin is the Eclipse/Adoptium OpenJDK distribution. The cask sets up
+`JAVA_HOME` automatically — no manual PATH changes needed.
 
 **macOS (SDKMAN):**
 
@@ -125,17 +131,17 @@ java -version
 # → openjdk version "21.x.x" ...
 ```
 
-### 2. Install JRuby 10.0.4.0 via rbenv
+### 2. Install JRuby 10.0.3.0 via rbenv
 
 ```bash
 # Install rbenv if needed
 brew install rbenv ruby-build   # macOS
 # or: https://github.com/rbenv/rbenv#installation
 
-rbenv install jruby-10.0.4.0
-rbenv local jruby-10.0.4.0
+rbenv install jruby-10.0.3.0
+rbenv local jruby-10.0.3.0
 ruby -v
-# → jruby 10.0.4.0 (ruby 3.x.x) ...
+# → jruby 10.0.3.0 (ruby 3.x.x) ...
 ```
 
 ### 3. Install Gems
@@ -289,15 +295,23 @@ fs.kv_get('last_query')            # → "weather in Tokyo"
 
 ### Packaging as .jar
 
-Use Warbler to create a standalone Java archive:
+Package your app as a standalone Java archive with a single command:
+
+```bash
+bundle exec zuzu package
+```
+
+This auto-installs Warbler if needed, generates the necessary launcher, and
+produces a `.jar` named after your app directory. Run it with:
 
 ```bash
-gem install warbler
-warble jar
-java -XstartOnFirstThread -jar zuzu-app.jar   # macOS
-java -jar zuzu-app.jar                        # Linux
+java -XstartOnFirstThread -jar my_app.jar   # macOS
+java -jar my_app.jar                        # Linux / Windows
 ```
 
+> **Note:** Place your llamafile model in a `models/` directory alongside the
+> `.jar` — models are not bundled into the archive.
+
 ---
 
 ## Configuration Reference
@@ -323,6 +337,7 @@ end
 ```
 zuzu new APP_NAME    Scaffold a new Zuzu application
 zuzu start           Launch the Zuzu app in the current directory
+zuzu package         Package the app as a standalone .jar
 zuzu console         Open an IRB session with Zuzu loaded
 zuzu version         Print the Zuzu version
 zuzu help            Show this message

data/bin/setup

@@ -20,12 +20,9 @@ if java -version 2>&1 | grep -q 'version "2[1-9]\|version "3'; then
 else
   warn "Java 21+ not found."
   if [[ "$OSTYPE" == darwin* ]]; then
-    step "Installing Java 21 via Homebrew"
-    brew install openjdk@21
-    echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 21)' >> ~/.zshrc
-    export JAVA_HOME=$(/usr/libexec/java_home -v 21)
-    export PATH="$JAVA_HOME/bin:$PATH"
-    echo "  Installed. Restart your shell or run: source ~/.zshrc"
+    step "Installing Java 21 via Homebrew (Temurin)"
+    brew install --cask temurin@21
+    echo "  Installed. Restart your shell to pick up JAVA_HOME."
   elif [[ "$OSTYPE" == linux-gnu* ]]; then
     step "Installing Java 21 via apt"
     sudo apt-get update -qq && sudo apt-get install -y openjdk-21-jdk

data/bin/zuzu

@@ -33,10 +33,13 @@ when 'new'
   app_dir = File.expand_path(app_name)
   abort "Directory '#{app_name}' already exists." if File.exist?(app_dir)
 
-  template_src = File.expand_path('../templates/app.rb', __dir__)
+  templates_dir = File.expand_path('../templates', __dir__)
 
   FileUtils.mkdir_p(app_dir)
-  FileUtils.cp(template_src, File.join(app_dir, 'app.rb'))
+  FileUtils.cp(File.join(templates_dir, 'app.rb'),    File.join(app_dir, 'app.rb'))
+  FileUtils.cp(File.join(templates_dir, 'AGENTS.md'), File.join(app_dir, 'AGENTS.md'))
+  FileUtils.cp(File.join(templates_dir, 'CLAUDE.md'), File.join(app_dir, 'CLAUDE.md'))
+  FileUtils.cp_r(File.join(templates_dir, '.claude'), File.join(app_dir, '.claude'))
 
   # Generate Gemfile — uses local path when running from source tree,
   # published gem when installed via `gem install zuzu`.
@@ -55,6 +58,9 @@ when 'new'
   puts "Created new Zuzu app: #{app_name}/"
   puts "  #{app_name}/app.rb"
   puts "  #{app_name}/Gemfile"
+  puts "  #{app_name}/AGENTS.md"
+  puts "  #{app_name}/CLAUDE.md"
+  puts "  #{app_name}/.claude/skills/ (setup, add-tool, customize, debug)"
   puts ''
   if DEV_MODE
     puts "  (dev mode: Gemfile points to #{ZUZU_ROOT})"
@@ -69,6 +75,15 @@ when 'new'
 when 'start'
   entry = ['app.rb', 'lib/app.rb'].find { |f| File.exist?(f) }
   abort 'No app.rb found. Run `zuzu start` from your app directory.' unless entry
+
+  # SWT on Java 21+ requires --enable-native-access=ALL-UNNAMED.
+  # JVM flags must be set before the JVM starts, so re-exec via bundle
+  # with the flag injected into JRUBY_OPTS if it isn't already present.
+  unless ENV['JRUBY_OPTS'].to_s.include?('enable-native-access')
+    ENV['JRUBY_OPTS'] = "#{ENV['JRUBY_OPTS']} -J--enable-native-access=ALL-UNNAMED".strip
+    exec('bundle', 'exec', 'zuzu', 'start')
+  end
+
   load File.expand_path(entry)
 
 when 'package'
@@ -96,16 +111,28 @@ when 'package'
     abort 'warble binary not found after install. Try: gem install warbler' if warble_bin.empty?
   end
 
+  # Warbler 2.x auto-discovers the main script from bin/ — create a thin launcher
+  unless File.exist?('bin/app')
+    FileUtils.mkdir_p('bin')
+    File.write('bin/app', <<~SCRIPT)
+      #!/usr/bin/env jruby
+      load File.expand_path('../app.rb', __dir__)
+    SCRIPT
+    File.chmod(0o755, 'bin/app')
+    puts 'Created bin/app launcher for warbler.'
+  end
+
   puts 'Packaging app as zuzu-app.jar ...'
   puts '  (this may take a minute)'
   success = Bundler.with_unbundled_env { system(warble_bin, 'jar') }
   if success
     puts ''
-    puts 'Done! Created: zuzu-app.jar'
+    jar = Dir['*.jar'].first || 'app.jar'
+    puts "Done! Created: #{jar}"
     puts ''
     puts 'Run it with:'
-    puts '  java -XstartOnFirstThread -jar zuzu-app.jar   # macOS'
-    puts '  java -jar zuzu-app.jar                        # Linux / Windows'
+    puts "  java -XstartOnFirstThread -jar #{jar}   # macOS"
+    puts "  java -jar #{jar}                        # Linux / Windows"
   else
     abort 'warble jar failed. Check output above for details.'
   end

data/lib/zuzu/agent.rb

@@ -11,22 +11,13 @@ module Zuzu
     TOOL_CALL_RE   = /<zuzu_tool_call>(.*?)<\/zuzu_tool_call>/m
     TOOL_RESULT_RE = /<zuzu_tool_result>.*?<\/zuzu_tool_result>/m
 
-    SYSTEM_PROMPT = <<~PROMPT.strip
+    BASE_PROMPT = <<~PROMPT
       You are Zuzu, a helpful desktop AI assistant.
 
       You have access to a sandboxed virtual filesystem called AgentFS. It is completely
       separate from the host computer's filesystem. All file paths refer to AgentFS only.
       You cannot access or modify any files on the host system.
 
-      Available tools — use the tag format shown below:
-
-      - write_file     : Write text to an AgentFS file. Args: path (string), content (string)
-      - read_file      : Read an AgentFS file. Args: path (string)
-      - list_directory : List an AgentFS directory. Args: path (string, default "/")
-      - run_command    : Run a sandboxed command against AgentFS. Args: command (string)
-                         Supported: ls [path], cat <path>, pwd, echo <text>
-      - http_get       : Fetch a public URL from the internet. Args: url (string)
-
       To call a tool, output exactly this on its own line:
       <zuzu_tool_call>{"name":"TOOL_NAME","args":{"key":"value"}}</zuzu_tool_call>
 
@@ -51,7 +42,7 @@ module Zuzu
       # Only system prompt + current message — no history injected into agent context.
       # Prior non-tool-call responses cause models to skip tool use.
       messages = [
-        { 'role' => 'system', 'content' => SYSTEM_PROMPT },
+        { 'role' => 'system', 'content' => build_system_prompt },
         { 'role' => 'user',   'content' => user_message }
       ]
 
@@ -100,6 +91,22 @@ module Zuzu
 
     private
 
+    def build_system_prompt
+      tool_lines = ToolRegistry.tools.map do |t|
+        args = t.schema[:properties]&.keys&.map(&:to_s)&.join(', ')
+        line = "- #{t.name} : #{t.description}"
+        line += " Args: #{args}" if args && !args.empty?
+        line
+      end.join("\n")
+
+      extras = Zuzu.config.system_prompt_extras.to_s.strip
+
+      prompt = BASE_PROMPT.dup
+      prompt << "\nAvailable tools:\n#{tool_lines}\n"
+      prompt << "\n#{extras}" unless extras.empty?
+      prompt.strip
+    end
+
     def extract_tool_calls(content)
       content.scan(TOOL_CALL_RE).filter_map do |match|
         data = JSON.parse(match[0].strip)

data/lib/zuzu/config.rb

@@ -11,7 +11,7 @@ module Zuzu
   #
   class Config
     attr_accessor :port, :model, :channels, :log_level, :app_name,
-                  :window_width, :window_height
+                  :window_width, :window_height, :system_prompt_extras
 
     attr_reader :db_path, :llamafile_path
 
@@ -20,8 +20,9 @@ module Zuzu
       @model          = 'LLaMA_CPP'
       @db_path        = File.join('.zuzu', 'zuzu.db')
       @llamafile_path = nil
-      @channels       = []
-      @log_level      = :info
+      @channels             = []
+      @log_level            = :info
+      @system_prompt_extras = nil
       @app_name       = 'Zuzu'
       @window_width   = 860
       @window_height  = 620

data/lib/zuzu/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zuzu
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

data/templates/.claude/skills/add-tool/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: add-tool
+description: Add a new tool that the Zuzu agent can call during conversations. Guides through naming, arguments, implementation, and registers it correctly in app.rb. Use when the developer wants the AI assistant to gain a new capability (e.g. check weather, query a database, read a file, call an API).
+---
+
+# Add a Zuzu Tool
+
+A tool is a Ruby block the agent calls using `<zuzu_tool_call>` tags. Once registered, it is **automatically listed in the agent's system prompt** — no manual prompt editing needed.
+
+## Step 1 — Understand what the tool should do
+
+AskUserQuestion: "What should this tool do? Describe it in one sentence — this description will be shown to the AI agent."
+
+AskUserQuestion: "What arguments does it need? For each: name, type (string/number/boolean), and what it represents. Or 'none' if no arguments."
+
+AskUserQuestion: "Does it need to read/write files (use AgentFS), call an external API, query a database, or just compute something locally?"
+
+## Step 2 — Choose a tool name
+
+- Must be snake_case, descriptive, unambiguous
+- Examples: `get_weather`, `search_notes`, `send_email`, `calculate_tax`, `lookup_stock_price`
+- Check `app.rb` for existing tool names — avoid duplicates
+- AskUserQuestion: "I'll name this tool `<suggested_name>`. Does that work, or would you prefer a different name?"
+
+## Step 3 — Implement the tool
+
+Read `app.rb` to find the insertion point — tools go **between the `Zuzu.configure` block and `Zuzu::App.launch!`**.
+
+### Pattern A — No arguments, no AgentFS
+
+```ruby
+Zuzu::ToolRegistry.register(
+  'tool_name',
+  'One-sentence description shown to the agent.',
+  { type: 'object', properties: {}, required: [] }
+) { |_args, _fs| "result as a string" }
+```
+
+### Pattern B — With arguments
+
+```ruby
+Zuzu::ToolRegistry.register(
+  'tool_name',
+  'Description shown to the agent.',
+  {
+    type: 'object',
+    properties: {
+      param_one: { type: 'string', description: 'what it is' },
+      param_two: { type: 'integer', description: 'what it is' }
+    },
+    required: ['param_one']   # list only truly required params
+  }
+) do |args, _fs|
+  # args keys are STRINGS: args['param_one'] not args[:param_one]
+  value = args['param_one'].to_s
+  "result: #{value}"
+end
+```
+
+### Pattern C — Using AgentFS (sandboxed file/KV access)
+
+```ruby
+Zuzu::ToolRegistry.register(
+  'save_note',
+  'Save a note to the virtual filesystem.',
+  {
+    type: 'object',
+    properties: {
+      title:   { type: 'string', description: 'Note title' },
+      content: { type: 'string', description: 'Note content' }
+    },
+    required: %w[title content]
+  }
+) do |args, fs|
+  # fs is Zuzu::AgentFS — sandboxed, NOT the host filesystem
+  path = "/notes/#{args['title'].downcase.gsub(/\s+/, '_')}.txt"
+  fs.write_file(path, args['content'])
+  "Saved to #{path}"
+end
+```
+
+### Pattern D — Calling an external HTTP API
+
+```ruby
+require 'net/http'
+require 'json'
+
+Zuzu::ToolRegistry.register(
+  'get_weather',
+  'Get current weather for a city using wttr.in.',
+  {
+    type: 'object',
+    properties: {
+      city: { type: 'string', description: 'City name' }
+    },
+    required: ['city']
+  }
+) do |args, _fs|
+  uri = URI("https://wttr.in/#{URI.encode_uri_component(args['city'])}?format=3")
+  Net::HTTP.get(uri).strip
+rescue StandardError => e
+  "Error fetching weather: #{e.message}"
+end
+```
+
+## Step 4 — Enforce these rules before writing
+
+Before inserting code, verify:
+
+- [ ] Tool is placed **before** `Zuzu::App.launch!`
+- [ ] Block signature uses `|args, fs|` or `|args, _fs|` (never zero args)
+- [ ] `args` keys use **string** form: `args['name']` not `args[:name]`
+- [ ] Return value is a **String** (or will be `.to_s`'d automatically)
+- [ ] No `File.read` / `File.write` / `Dir` calls — use `fs` for file access
+- [ ] External HTTP calls have a rescue block returning an error string
+- [ ] Description is one clear sentence (the agent sees this verbatim)
+
+Write the tool to `app.rb` now.
+
+## Step 5 — Verify it loads
+
+```bash
+bundle exec ruby -e "
+require 'zuzu'
+load 'app.rb' rescue nil
+tool = Zuzu::ToolRegistry.find('<tool_name>')
+if tool
+  puts 'Tool registered: ' + tool.name
+  puts 'Description: ' + tool.description
+else
+  puts 'ERROR: tool not found'
+end
+" 2>&1
+```
+
+- If "tool not found": check for syntax errors, verify placement before `launch!`, retry.
+- If syntax error printed: fix it, retry.
+
+## Step 6 — Test in console (if possible without side effects)
+
+```bash
+bundle exec zuzu console
+```
+
+Then in the console:
+```ruby
+store = Zuzu::Store.new
+fs    = Zuzu::AgentFS.new(store)
+tool  = Zuzu::ToolRegistry.find('<tool_name>')
+puts tool.block.call({'param' => 'test_value'}, fs)
+```
+
+- If it returns a sensible result: done.
+- If error: fix and re-verify.
+
+## Step 7 — Tell the user
+
+Show the registered tool code and confirm:
+> ✅ Tool `<name>` registered. The agent will now automatically list it in its system prompt and call it when relevant. Restart the app (`bundle exec zuzu start`) to pick up the change.
+
+If the tool calls an external service that needs configuration (API key, URL, etc.):
+> ⚠️ Remember to set `ENV['YOUR_API_KEY']` or add the value to your configuration before running.