`: `{name}'s Homepage` or similar + +### Link icons (use emoji prefix in button text): +| Type | Emoji | +|----------|-------| +| github | 🐙 | +| twitter/x | 🐦 | +| linkedin | 💼 | +| website/blog | 🌐 | +| email | 📧 | +| instagram | 📸 | +| youtube | ▶️ | +| telegram | ✈️ | +| default | 🔗 | + +--- + +## Step 4 — Publish + +Find the skill directory (same folder as this SKILL.md). Call it `SKILL_DIR`. + +Run: +```bash +ruby SKILL_DIR/publish.rb publish \ + --name "NAME" \ + --html-file /tmp/profile-card.html +``` + +- First publish → creates new page, saves token to `~/clacky_workspace/personal_website/token.json` +- Subsequent runs → updates existing page at the same URL + +Capture stdout. Extract the URL from the output line starting with `✅`. + +--- + +## Step 5 — Done + +Tell the user their homepage is live. Share the URL. Be warm and natural. + +Example (adapt tone to personality): +> Your homepage is live 🌟 +> → http://localhost:3000/~ya-fei +> +> It's got all your links in one place. Share it anywhere. diff --git a/lib/clacky/default_skills/personal-website/publish.rb b/lib/clacky/default_skills/personal-website/publish.rb new file mode 100644 index 0000000..92d9b5b --- /dev/null +++ b/lib/clacky/default_skills/personal-website/publish.rb @@ -0,0 +1,235 @@ +#!/usr/bin/env ruby +# publish.rb — Publish or delete a profile card on the platform +# +# Usage: +# ruby publish.rb publish --name "NAME" --html-file /path/to/card.html +# ruby publish.rb delete --slug SLUG +# +# On first publish, prints the card URL and saves the update token to +# ~/.clacky/card_token (used for future updates/deletes). +# +# Environment: +# CLACKY_LICENSE_SERVER — platform base URL override (default: https://www.openclacky.com) +# CARD_HMAC_SECRET — shared secret (default matches platform default) + +require "net/http" +require "uri" +require "json" +require "openssl" +require "digest" +require "optparse" +require "fileutils" + +# ── Config ─────────────────────────────────────────────────────────────────── + +# Primary CDN-accelerated endpoint. +# Fallback bypasses EdgeOne and is used when the primary times out or errors. +PRIMARY_HOST = ENV.fetch("CLACKY_LICENSE_SERVER", "https://www.openclacky.com") +FALLBACK_HOST = "https://openclacky.up.railway.app" +# When the env override is set we use only that host (dev/test mode). +API_HOSTS = ENV["CLACKY_LICENSE_SERVER"] ? [PRIMARY_HOST] : [PRIMARY_HOST, FALLBACK_HOST] + +HMAC_SECRET = ENV.fetch("CARD_HMAC_SECRET", "openclacky-card-v1-default-secret-change-me") +TOKEN_FILE = File.expand_path("~/clacky_workspace/personal_website/token.json") + +# Retry / timeout config +OPEN_TIMEOUT = 8 +READ_TIMEOUT = 15 +ATTEMPTS_PER_HOST = 2 +INITIAL_BACKOFF = 0.5 + +# ── HMAC signing ───────────────────────────────────────────────────────────── + +def device_fingerprint + parts = [] + parts << `hostname`.strip + hw = `system_profiler SPHardwareDataType 2>/dev/null | grep 'Hardware UUID'`.strip + parts << hw unless hw.empty? + parts << ENV["USER"].to_s + Digest::SHA256.hexdigest(parts.join("|"))[0, 16] +end + +def hmac_headers + ts = Time.now.to_i.to_s + fingerprint = device_fingerprint + payload = "openclacky:#{ts}:#{fingerprint}" + signature = OpenSSL::HMAC.hexdigest("SHA256", HMAC_SECRET, payload) + { + "X-Card-Timestamp" => ts, + "X-Card-Fingerprint" => fingerprint, + "X-Card-Signature" => signature, + "Content-Type" => "application/json" + } +end + +# ── HTTP helpers ────────────────────────────────────────────────────────────── + +# Resilient HTTP request: retries on transient errors, then fails over to the +# fallback host before giving up. +# +# Returns [http_code_int, parsed_body_hash]. +# Calls exit(1) on network failure (all hosts/attempts exhausted). +def http_request(method, path, body: nil, extra_headers: {}) + last_error = nil + + API_HOSTS.each_with_index do |base, host_index| + ATTEMPTS_PER_HOST.times do |attempt| + begin + result = do_http_request(method, base, path, body: body, extra_headers: extra_headers) + return result + rescue RetryableError => e + last_error = e + backoff = INITIAL_BACKOFF * (2**attempt) + sleep(backoff) + end + end + end + + warn "❌ Network error: #{last_error&.message || "unknown"}" + exit 1 +end + +def do_http_request(method, base, path, body:, extra_headers:) + uri = URI.parse("#{base}#{path}") + http = Net::HTTP.new(uri.host, uri.port) + http.use_ssl = uri.scheme == "https" + http.open_timeout = OPEN_TIMEOUT + http.read_timeout = READ_TIMEOUT + + req_class = { "POST" => Net::HTTP::Post, "PATCH" => Net::HTTP::Patch, + "DELETE" => Net::HTTP::Delete }[method] + req = req_class.new(uri.path) + hmac_headers.each { |k, v| req[k] = v } + extra_headers.each { |k, v| req[k] = v } + req.body = body.to_json if body + + response = http.request(req) + parsed = JSON.parse(response.body) rescue { "raw" => response.body } + [response.code.to_i, parsed] +rescue Net::OpenTimeout, Net::ReadTimeout, + Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, + Errno::ECONNRESET, EOFError, OpenSSL::SSL::SSLError => e + raise RetryableError, e.message +end + +# Sentinel for transient network errors that should trigger retry/failover. +class RetryableError < StandardError; end + +# ── Token storage ───────────────────────────────────────────────────────────── + +def load_token_data + return {} unless File.exist?(TOKEN_FILE) + JSON.parse(File.read(TOKEN_FILE)) rescue {} +end + +def save_token_data(data) + FileUtils.mkdir_p(File.dirname(TOKEN_FILE)) + File.write(TOKEN_FILE, JSON.pretty_generate(data)) + File.chmod(0600, TOKEN_FILE) +end + +# ── Commands ────────────────────────────────────────────────────────────────── + +def cmd_publish(name:, html_file:) + unless File.exist?(html_file) + warn "❌ HTML file not found: #{html_file}" + exit 1 + end + + html_content = File.read(html_file, encoding: "utf-8") + + if html_content.bytesize > 1_048_576 + warn "❌ HTML file exceeds 1MB (#{html_content.bytesize / 1024}KB)" + exit 1 + end + + token_data = load_token_data + + # If we already have a slug + token, do an update (PATCH) instead of create + if token_data["slug"] && token_data["update_token"] + slug = token_data["slug"] + token = token_data["update_token"] + + status, body = http_request("PATCH", "/api/v1/personal_websites/#{slug}", + body: { html_content: html_content }, + extra_headers: { "X-Card-Token" => token }) + + if status == 200 + puts "✅ Website updated: #{body["url"]}" + else + warn "❌ Update failed (#{status}): #{body["error"] || body.inspect}" + exit 1 + end + else + # First publish — POST to create + status, body = http_request("POST", "/api/v1/personal_websites", + body: { name: name, html_content: html_content }) + + if status == 201 + save_token_data("slug" => body["slug"], "update_token" => body["update_token"]) + puts "✅ Website published: #{body["url"]}" + puts " Slug: #{body["slug"]}" + puts " Token saved to: #{TOKEN_FILE}" + else + warn "❌ Publish failed (#{status}): #{body["error"] || body.inspect}" + exit 1 + end + end +end + +def cmd_delete(slug: nil) + token_data = load_token_data + token = token_data["update_token"] + slug = slug || token_data["slug"] + + unless token && slug + warn "❌ No published website found (#{TOKEN_FILE} missing or incomplete)." + warn " Nothing to delete." + exit 1 + end + + status, body = http_request("DELETE", "/api/v1/personal_websites/#{slug}", + extra_headers: { "X-Card-Token" => token }) + + if status == 200 + File.delete(TOKEN_FILE) if File.exist?(TOKEN_FILE) + puts "✅ Personal website deleted: /~#{slug}" + else + warn "❌ Delete failed (#{status}): #{body["error"] || body.inspect}" + exit 1 + end +end + +# ── CLI parsing ─────────────────────────────────────────────────────────────── + +command = ARGV.shift + +case command +when "publish" + options = {} + OptionParser.new do |opts| + opts.on("--name NAME") { |v| options[:name] = v } + opts.on("--html-file FILE") { |v| options[:html_file] = v } + end.parse! + + unless options[:name] && options[:html_file] + warn "Usage: ruby publish.rb publish --name NAME --html-file FILE" + exit 1 + end + + cmd_publish(name: options[:name], html_file: File.expand_path(options[:html_file])) + +when "delete" + options = {} + OptionParser.new do |opts| + opts.on("--slug SLUG") { |v| options[:slug] = v } # optional, auto-read from token file + end.parse! + + cmd_delete(slug: options[:slug]) + +else + warn "Usage: ruby publish.rb publish|delete [options]" + warn " publish --name NAME --html-file FILE" + warn " delete --slug SLUG" + exit 1 +end diff --git a/lib/clacky/default_skills/product-help/SKILL.md b/lib/clacky/default_skills/product-help/SKILL.md new file mode 100644 index 0000000..b603c71 --- /dev/null +++ b/lib/clacky/default_skills/product-help/SKILL.md @@ -0,0 +1,113 @@ +--- +name: product-help +description: 'Use this skill when the user asks about my own features, configuration, or usage — installation, skills, Web UI, CLI, API config, memory, sessions, encryption, white-label, publishing, pricing, troubleshooting, or restarting the server. Do NOT trigger for general coding tasks unrelated to me.' +fork_agent: true +user-invocable: false +auto_summarize: true +forbidden_tools: + - write + - edit + - terminal + - web_search +--- + +# Product Help Subagent + +## My self-understanding + +I am an AI assistant powered by the **OpenClacky** platform. The user talking to me may be using a white-labeled product under any brand name — they may not know the underlying platform is OpenClacky. That's fine. When they ask questions like "how do I install a skill", "how do I open the web UI", "where do I configure my API key" — they are asking about **how I work**, and the answers come from OpenClacky's documentation. + +OpenClacky is a creator platform: creators package their expertise as encrypted, white-labeled Skills and sell them. I run those Skills. My core capabilities include: +- **Skills** — installable capability packs, activated via license +- **Web UI** — browser interface for running sessions +- **Memory** — persistent long-term memory across sessions +- **Sessions** — conversation history and context +- **CLI** — command-line interface (command name may vary by brand) +- **Config** — model and API key setup + +Answer the user's question using the official documentation below. Always fetch the doc first — never answer from memory alone. + +## Doc URL Table + +| Topic | URL | +|-------|-----| +| What is OpenClacky, product overview, difference from OpenClaw | https://www.openclacky.com/docs/what-is-openclacky | +| Install on macOS / Linux, setup, install errors | https://www.openclacky.com/docs/installation | +| Install on Windows | https://www.openclacky.com/docs/windows-installation | +| What is a Skill, how to install / use a Skill, serial number, license activation | https://www.openclacky.com/docs/how-to-use-a-skill | +| Common errors, troubleshooting, FAQ | https://www.openclacky.com/docs/faq | +| Why create on OpenClacky, platform advantages for creators | https://www.openclacky.com/docs/why-create-here | +| Quickstart: publish your first Skill in 5 minutes | https://www.openclacky.com/docs/publish-your-first-skill-in-5-min | +| Skill structure, SKILL.md format, fork_agent, frontmatter options | https://www.openclacky.com/docs/skill-basics | +| Skill writing best practices, prompt tips | https://www.openclacky.com/docs/writing-tips | +| White-label packaging, custom branding | https://www.openclacky.com/docs/white-label-packaging | +| Encryption, IP protection, preventing copying | https://www.openclacky.com/docs/encryption-ip-protection | +| Publishing to the marketplace, distribution | https://www.openclacky.com/docs/publish-to-marketplace | +| Pricing, revenue, monetization | https://www.openclacky.com/docs/pricing-revenue | +| Advanced patterns, best practices | https://www.openclacky.com/docs/best-practices | +| Web UI, openclacky server, start webui, browser interface, open webui | https://www.openclacky.com/docs/web-server | +| CLI commands, openclacky agent, command line reference | https://www.openclacky.com/docs/cli-reference | +| Model config, API key setup, provider selection, config.yml | https://www.openclacky.com/docs/agent-config | +| Project rules file, .clackyrules, custom instructions | https://www.openclacky.com/docs/clackyrules | +| SKILL.md frontmatter fields, all frontmatter options reference | https://www.openclacky.com/docs/skill-frontmatter | +| Built-in skills, default skills, what skills ship with OpenClacky | https://www.openclacky.com/docs/built-in-skills | +| Memory system, long-term memory, ~/.clacky/memories | https://www.openclacky.com/docs/memory-system | +| Session management, conversation history, context window | https://www.openclacky.com/docs/session-management | +| Browser automation, browser tool, Chrome, Edge, CDP, remote debugging, WSL browser, browser-setup skill | https://www.openclacky.com/docs/browser-tool | + +## Workflow + +### Step 1 — Pick the URL + +Look at the user's question and pick the **single most relevant URL** from the table above. + +Match on intent, not just keywords. Examples: +- "帮我打开webui" → `web-server` +- "api key怎么配" → `agent-config` +- "序列号在哪激活" → `how-to-use-a-skill` +- "skill加密后别人能复制吗" → `encryption-ip-protection` + +If genuinely unsure between two topics, pick both (max 2). + +### Step 2 — Fetch the doc + +``` +web_fetch(url: "<URL>", max_length: 5000) +``` + +### Step 3 — Answer directly + +- Answer the question directly — don't say "the docs say…" +- Match the user's language (Chinese question → Chinese answer) +- Use numbered steps for sequences +- Use code blocks for commands +- End with the source URL + +## Rules + +- Always fetch the doc first — never answer from memory +- Only use URLs from the table above — do NOT search the web +- If the fetched page doesn't answer the question, try the next most relevant URL (max 2 fetches) +- If still no answer, tell the user: "请访问 https://www.openclacky.com/docs 查看完整文档" +- Keep answers concise — extract what's relevant, don't paste the whole page + +## Server restart, upgrade, and downgrade + +### Normal restart + +If the user asks to restart the server normally (e.g. "重启", "restart", "请重启openclacky") — without mentioning failure or errors: + +**Do NOT fetch any docs.** Just return this answer directly: + +> To restart the server gracefully (hot restart, zero downtime): +> ``` +> kill -USR1 $CLACKY_MASTER_PID +> ``` +> This sends USR1 to the Master process, which spawns a new Worker and gracefully stops the old one. +> The `$CLACKY_MASTER_PID` environment variable is already set in the current session. + +### Restart failure, upgrade failure, or downgrade + +If the user mentions restart failure, upgrade failure, or how to downgrade (e.g. "重启失败", "升级失败", "降级", "restart failed", "upgrade failed", "downgrade", "如何降级"): + +→ Fetch the FAQ page: `https://www.openclacky.com/docs/faq` — it has a dedicated Troubleshooting section covering all three scenarios. diff --git a/lib/clacky/default_skills/recall-memory/SKILL.md b/lib/clacky/default_skills/recall-memory/SKILL.md new file mode 100644 index 0000000..ada1493 --- /dev/null +++ b/lib/clacky/default_skills/recall-memory/SKILL.md @@ -0,0 +1,65 @@ +--- +name: recall-memory +description: Recall relevant long-term memories on demand. Given a topic or question, judges relevance from pre-loaded metadata, loads only relevant files, and returns a concise summary to the main agent. +fork_agent: true +user-invocable: false +auto_summarize: true +forbidden_tools: + - write + - edit + - web_search + - web_fetch + - browser +--- + +# Recall Memory Subagent + +You are a **Memory Recall Subagent**. Your sole job is to find and return relevant long-term memories for the main agent. + +## Available Memory Files + +The following memory files exist in `~/.clacky/memories/`. This list was pre-loaded for you — **do NOT re-scan the directory**. + +<%= memories_meta %> + +## Your Workflow — follow strictly + +### Step 1: Judge relevance + +From the list above, decide which files are relevant to the task/topic passed to you. + +**Rules:** +- Match by `topic` and `description` against the requested task +- If nothing matches, immediately return: "No relevant memories found for: <task>" +- Do NOT load files that are clearly irrelevant + +### Step 2: Load relevant files and return + +For each relevant file: + +1. Read the full content: +``` +file_reader(path: "~/.clacky/memories/<filename>") +``` + +2. Touch the file to update its mtime (LRU signal — keeps it surfaced in future recalls): +``` +terminal(command: "touch ~/.clacky/memories/<filename>") +``` + +Return ONLY the memory content, structured as: + +``` +## Recalled Memories: <task> + +### <Topic Name> +<content verbatim or lightly summarized if very long> +``` + +## Rules + +- NEVER modify any files +- NEVER load irrelevant files — keep output minimal and focused +- NEVER add commentary beyond the memory content itself +- If a file exceeds 1000 tokens of content, summarize the least important parts +- Stop immediately after returning the summary diff --git a/lib/clacky/default_skills/search-skills/SKILL.md b/lib/clacky/default_skills/search-skills/SKILL.md new file mode 100644 index 0000000..81a8e37 --- /dev/null +++ b/lib/clacky/default_skills/search-skills/SKILL.md @@ -0,0 +1,61 @@ +--- +name: search-skills +description: 'Search ALL installed skills (including ones not shown in AVAILABLE SKILLS) by keyword. Use this whenever you suspect a fitting skill might exist but is not listed in your system prompt — for example before building a new skill, when the user mentions a domain not covered by visible skills, or after seeing the (N more skills installed) hint. Triggers on phrases like search skills, find a skill for, is there a skill that, 查找skill, 有没有skill做.' +disable-model-invocation: false +user-invocable: true +fork_agent: true +auto_summarize: true +forbidden_tools: + - write + - edit + - terminal + - web_search + - web_fetch + - browser +--- + +# Search Skills Subagent + +You are a Skill Search Subagent. Given a keyword or topic from the parent agent, scan the complete list of installed skills below and return the best matches. + +The AVAILABLE SKILLS section in the parent agent system prompt is capped (~30 entries). The list below is the FULL list — pre-loaded for you, no scanning required. Your job is to look beyond that cap so the parent does not redundantly create a new skill when one already exists. + +## Complete Skill Inventory + +This list was pre-loaded — do NOT re-scan the filesystem or call any tools. + +<%= all_skills_meta %> + +## Workflow + +### Step 1 — Extract keywords + +Pull 2-4 keywords from the input task. Both English and Chinese terms are valid (skill descriptions are bilingual). + +### Step 2 — Match against the inventory above + +For each skill in the inventory, judge relevance against the keywords: +- Strong match: keyword appears in the skill `name` or clearly in the `description`'s purpose statement +- Weak match: keyword appears only in the trigger examples or peripheral mentions + +### Step 3 — Return a ranked summary + +Return at most 5 results, strongest matches first: + +``` +Found N matching skill(s) for: <keywords> + +1. <name> (<source>) + <description trimmed to ~200 chars> + +2. ... +``` + +If nothing genuinely matches, return exactly: `No installed skill matches: <task>` + +## Rules + +- Do NOT invoke any tool. The inventory above is authoritative; just match and return. +- Do NOT recommend creating a new skill — that is the parent agent's call. +- If the task is vague, return what genuinely matched, do not invent relevance. +- Default skills (built-in) are part of the inventory but typically also visible to the parent — flagging them is still useful as a reminder. diff --git a/lib/clacky/default_skills/skill-add/SKILL.md b/lib/clacky/default_skills/skill-add/SKILL.md new file mode 100644 index 0000000..25c170c --- /dev/null +++ b/lib/clacky/default_skills/skill-add/SKILL.md @@ -0,0 +1,59 @@ +--- +name: skill-add +description: 'Install skills from a zip URL or local zip file path. Use this skill whenever the user wants to install a skill from a zip link or a local file, or uses commands like /skill-add with a URL or file path. Trigger on phrases like: install skill, install from zip, skill from zip, skill from url, add skill from zip, 安装skill, 从zip安装skill, 从本地安装skill.' +disable-model-invocation: false +user-invocable: true +--- + +# Skill Add — Zip Installer + +Installs a skill from a zip URL **or a local zip file path** using the bundled `install_from_zip.rb` script. + +## How to Install + +The script path is listed in the Supporting Files above (`scripts/install_from_zip.rb`) — use the full path directly, no `find` needed. + +The script accepts **either a remote URL or a local file path**: + +```bash +ruby "SKILL_DIR/scripts/install_from_zip.rb" <zip_url_or_path> [slug] +``` + +- `<zip_url_or_path>` — a remote `https://` URL **or** an absolute/relative local path to a `.zip` file +- `[slug]` — optional; the skill's directory name. If omitted, inferred from the filename (e.g. `canvas-design-1.2.0.zip` → `canvas-design`) + +The script handles everything automatically: +- For URLs: downloads the zip (follows HTTP redirects) +- For local paths: reads the file directly (no download needed) +- Extracts and locates all `SKILL.md` files inside +- Copies skill directories to `~/.clacky/skills/` +- Reports installed skills with their descriptions + +**Do NOT manually download or unzip — the script handles everything.** + +## Examples + +**From a remote URL:** +``` +/skill-add https://store.clacky.ai/skills/canvas-design-1.2.0.zip +``` +```bash +ruby "SKILL_DIR/scripts/install_from_zip.rb" \ + "https://store.clacky.ai/skills/canvas-design-1.2.0.zip" \ + "canvas-design" +``` + +**From a local file:** +``` +/skill-add /Users/alice/Downloads/my-skill-1.0.0.zip +``` +```bash +ruby "SKILL_DIR/scripts/install_from_zip.rb" \ + "/Users/alice/Downloads/my-skill-1.0.0.zip" +``` + +## Notes + +- Skills install to `~/.clacky/skills/` by default +- Local paths may be absolute (`/path/to/skill.zip`) or use `~` (`~/Downloads/skill.zip`) +- If the user doesn't provide a URL or path, ask them for the zip source diff --git a/lib/clacky/default_skills/skill-add/scripts/install_from_zip.rb b/lib/clacky/default_skills/skill-add/scripts/install_from_zip.rb new file mode 100755 index 0000000..05f5568 --- /dev/null +++ b/lib/clacky/default_skills/skill-add/scripts/install_from_zip.rb @@ -0,0 +1,295 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +require 'fileutils' +require 'tmpdir' +require 'uri' +require 'net/http' +require 'find' + +# Install a skill from a remote zip archive URL. +# Usage: ruby install_from_zip.rb <zip_url> +# +# The zip archive is expected to contain a skill directory at its root, e.g.: +# my-skill/ +# SKILL.md +# scripts/ +# +# Or the archive may contain multiple skill directories (each with a SKILL.md). +class ZipSkillInstaller + ZIP_URL_PATTERN = %r{^https?://.+\.zip(\?.*)?$}i + + def initialize(zip_source, skill_name: nil, target_dir: nil, skip_if_exists: false) + @zip_source = zip_source + @local_path = local_zip_path?(zip_source) + # skill_name can be provided explicitly (e.g. slug from the store API). + # If not provided, we try to infer it from the filename in the URL/path, e.g. + # "ui-ux-pro-max-1.0.0.zip" → "ui-ux-pro-max". + @skill_name = skill_name || infer_skill_name(zip_source) + @target_dir = target_dir || File.join(Dir.home, '.clacky', 'skills') + # When true, existing skill directories are preserved and the install for + # that specific skill is skipped (recorded in @skipped_skills). + # Default false keeps the legacy "overwrite" behaviour for `install`. + @skip_if_exists = skip_if_exists + # Suppresses user-facing puts for programmatic callers (set by `perform`). + @silent = false + @installed_skills = [] + @skipped_skills = [] + @errors = [] + end + + # Programmatic entry point for library-style callers (e.g. onboard pre-install). + # + # Unlike `install`, this method: + # - does NOT print user-facing output + # - does NOT call `exit` on failure (raises instead) + # - returns a result hash: { installed: [...], skipped: [...], errors: [...] } + # + # The caller is responsible for rendering feedback and deciding whether any + # error is fatal. + def perform + @silent = true + do_install + { installed: @installed_skills, skipped: @skipped_skills, errors: @errors } + end + + # Main installation entry point (CLI). Prints progress, prints a final + # report, and calls `exit` on failure. Use `perform` for programmatic use. + def install + do_install + report_results + rescue ArgumentError => e + puts "Error: #{e.message}" + exit 1 + rescue StandardError => e + puts "Error: Installation failed: #{e.message}" + exit 1 + end + + # Shared core used by both `install` (CLI) and `perform` (library). + # Raises on invalid input; the caller decides how to surface errors. + private def do_install + if @local_path + # Install directly from a local zip file — no download needed. + # Expand tilde in path (e.g. ~/Downloads/skill.zip). + expanded = File.expand_path(@zip_source) + raise ArgumentError, "File not found: #{@zip_source}" unless File.exist?(expanded) + raise ArgumentError, "Not a zip file: #{@zip_source}" unless expanded.end_with?('.zip') + + Dir.mktmpdir('clacky-zip-') do |tmpdir| + extract_zip(expanded, tmpdir) + discover_and_install_skills(File.join(tmpdir, 'extracted')) + end + else + # Install from a remote URL. + unless valid_zip_url? + raise ArgumentError, "Invalid zip source: #{@zip_source}\n" \ + "Provide an http(s) URL ending with .zip, or an absolute path to a local zip file." + end + + Dir.mktmpdir('clacky-zip-') do |tmpdir| + zip_path = download_zip(tmpdir) + extract_zip(zip_path, tmpdir) + discover_and_install_skills(File.join(tmpdir, 'extracted')) + end + end + end + + # Return true if the source looks like a local file path (absolute or relative ending in .zip). + private def local_zip_path?(source) + source.start_with?('/') || source.start_with?('~') || source.start_with?('./') || + (source.end_with?('.zip') && !source.start_with?('http')) + end + + # Infer a skill name from the zip filename, stripping version suffixes. + # Works for both URLs and local paths. + # e.g. "ui-ux-pro-max-1.0.0.zip" → "ui-ux-pro-max" + private def infer_skill_name(source) + filename = if source.start_with?('http') + File.basename(URI.parse(source).path, '.zip') rescue File.basename(source, '.zip') + else + File.basename(source, '.zip') + end + # Strip trailing version segment like "-1.0.0" or "-2.3" + filename.sub(/-\d+(\.\d+)+$/, '') + end + + private def valid_zip_url? + @zip_source.match?(ZIP_URL_PATTERN) + end + + # Download the zip file to tmpdir and return its local path. + private def download_zip(tmpdir) + unless @silent + puts "Downloading skill package..." + puts " #{@zip_source}" + end + + zip_path = File.join(tmpdir, 'skill.zip') + uri = URI.parse(@zip_source) + + # Follow redirects up to 5 times (ActiveStorage often redirects). + max_redirects = 5 + current_uri = uri + + max_redirects.times do + Net::HTTP.start(current_uri.host, current_uri.port, + use_ssl: current_uri.scheme == 'https', + open_timeout: 15, read_timeout: 60) do |http| + request = Net::HTTP::Get.new(current_uri.request_uri) + http.request(request) do |response| + case response.code.to_i + when 200 + File.open(zip_path, 'wb') { |f| response.read_body { |chunk| f.write(chunk) } } + return zip_path + when 301, 302, 303, 307, 308 + location = response['location'] + raise "Redirect loop or missing Location header" if location.nil? || location == current_uri.to_s + current_uri = URI.parse(location) + else + raise "HTTP #{response.code} while downloading #{@zip_source}" + end + end + end + end + + raise "Too many redirects downloading #{@zip_source}" + end + + # Extract the zip archive into <tmpdir>/extracted/. + private def extract_zip(zip_path, tmpdir) + puts "Extracting package..." unless @silent + extracted_dir = File.join(tmpdir, 'extracted') + FileUtils.mkdir_p(extracted_dir) + + # Prefer the 'unzip' system command; fall back to Ruby's built-in zip support via ZipFile. + if system('which', 'unzip', out: File::NULL, err: File::NULL) + result = system('unzip', '-q', zip_path, '-d', extracted_dir) + raise "unzip failed (exit code #{$?.exitstatus})" unless result + else + # Attempt to use the 'zip' gem if available, otherwise raise a clear error. + begin + require 'zip' + Zip::File.open(zip_path) do |zip| + zip.each do |entry| + dest = File.join(extracted_dir, entry.name) + FileUtils.mkdir_p(File.dirname(dest)) + entry.extract(dest) + end + end + rescue LoadError + raise "Cannot extract zip: 'unzip' command not found and 'zip' gem is not installed.\n" \ + "Install unzip (e.g. brew install unzip) and try again." + end + end + end + + # Walk the extracted directory and install every skill (directory containing SKILL.md). + # Supports two zip layouts: + # Layout A — SKILL.md at zip root (flat): extracted/SKILL.md + # Layout B — skill in subdirectory: extracted/my-skill/SKILL.md + private def discover_and_install_skills(extracted_dir) + # Layout A: SKILL.md directly under the extraction root. + if File.exist?(File.join(extracted_dir, 'SKILL.md')) + install_skill(extracted_dir, skill_name: @skill_name) + return + end + + # Layout B: one or more skill subdirectories each containing SKILL.md. + skill_dirs = Dir.glob(File.join(extracted_dir, '*/SKILL.md')).map { |f| File.dirname(f) } + + if skill_dirs.empty? + raise "No SKILL.md found in the zip archive. " \ + "Make sure the package contains a valid skill directory." + end + + skill_dirs.each { |dir| install_skill(dir) } + end + + # Copy a single skill directory into the target skills folder. + # skill_name overrides the directory basename (used for Layout A flat zips). + private def install_skill(skill_src_dir, skill_name: nil) + name = skill_name || File.basename(skill_src_dir) + target_path = File.join(@target_dir, name) + + if File.exist?(target_path) + if @skip_if_exists + @skipped_skills << { name: name, path: target_path, reason: 'already exists' } + return + end + puts "Skill '#{name}' already exists — overwriting..." unless @silent + FileUtils.rm_rf(target_path) + end + + FileUtils.mkdir_p(target_path) + # Copy contents of skill_src_dir into target_path (not the dir itself). + FileUtils.cp_r(Dir.glob("#{skill_src_dir}/*"), target_path) + + description = extract_description(File.join(target_path, 'SKILL.md')) + @installed_skills << { name: name, path: target_path, description: description } + rescue StandardError => e + @errors << "Failed to install '#{name}': #{e.message}" + end + + # Parse the description field from SKILL.md YAML frontmatter. + private def extract_description(skill_file) + return "No description" unless File.exist?(skill_file) + + content = File.read(skill_file) + if content =~ /\A---\s*\n(.*?)\n---/m + frontmatter = $1 + return $1.strip if frontmatter =~ /^description:\s*(.+)$/ + end + + "No description" + rescue StandardError + "No description" + end + + # Print a human-readable summary of what was installed. + private def report_results + puts "\n" + "=" * 60 + + if @installed_skills.empty? + puts "No skills were installed." + if @errors.any? + puts "\nErrors:" + @errors.each { |e| puts " • #{e}" } + end + exit 1 + end + + puts "Installation complete!" + puts "\nInstalled #{@installed_skills.size} skill(s):\n\n" + @installed_skills.each do |skill| + puts " ✓ #{skill[:name]}" + puts " #{skill[:description]}" + puts " → #{skill[:path]}" + puts + end + + if @errors.any? + puts "Warnings:" + @errors.each { |e| puts " • #{e}" } + puts + end + + puts "You can now use these skills with /skill-name" + puts "=" * 60 + end +end + +# ── Entry point ──────────────────────────────────────────────────────────────── +if __FILE__ == $0 + if ARGV.empty? + puts "Usage: ruby install_from_zip.rb <zip_url_or_path> [skill_name]" + puts "\nExamples:" + puts " ruby install_from_zip.rb https://example.com/my-skill-1.0.0.zip" + puts " ruby install_from_zip.rb https://example.com/my-skill-1.0.0.zip my-skill" + puts " ruby install_from_zip.rb /path/to/my-skill.zip" + puts " ruby install_from_zip.rb ~/Downloads/my-skill-1.0.0.zip my-skill" + exit 1 + end + + ZipSkillInstaller.new(ARGV[0], skill_name: ARGV[1]).install +end diff --git a/lib/clacky/default_skills/skill-creator/SKILL.md b/lib/clacky/default_skills/skill-creator/SKILL.md new file mode 100644 index 0000000..60a1797 --- /dev/null +++ b/lib/clacky/default_skills/skill-creator/SKILL.md @@ -0,0 +1,603 @@ +--- +name: skill-creator +description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. +always-show: true +--- + +# Skill Creator + +A skill for creating new skills and iteratively improving them. + +## Usage Modes + +This skill supports two modes: + +### 1. Interactive Mode (default) + +The full workflow with user interviews, test cases, and iteration cycles. +Use when creating or refining skills manually. + +At a high level, the process of creating a skill goes like this: + +- Decide what you want the skill to do and roughly how it should do it +- Write a draft of the skill +- Create a few test prompts and simulate running them (with vs. without the skill instructions) +- Help the user evaluate the results both qualitatively and quantitatively + - While reviewing, draft quantitative assertions if there aren't any + - Use `eval-viewer/generate_review.py` to generate a static HTML viewer for the user to review results and leave feedback +- Rewrite the skill based on the user's feedback +- Repeat until satisfied + +Your job is to figure out where the user is in this process and jump in to help them progress through these stages. Maybe they say "I want to make a skill for X" — help narrow down the intent, write a draft, write test cases, evaluate, and repeat. Or maybe they already have a draft — go straight to the eval/iterate part. + +Always be flexible. If the user says "skip the evals, just vibe with me", do that instead. + +### 2. Quick Mode (for agent self-evolution) + +**Trigger**: When invoked with `mode: "quick"` in the task arguments. + +Fast, opinionated skill creation without user interaction. This mode is used by the agent's self-evolution system to automatically create or improve skills. + +**Behavior**: +- Skip user interviews and detailed requirements gathering +- Extract workflow pattern from provided context +- Write a minimal but functional SKILL.md +- Save to `~/.clacky/skills/auto-<name>-<timestamp>/` (or improve existing skill in place) +- Skip test cases and evals (user can refine later if needed) +- Always validate frontmatter with the validator script after creation +- Focus on the happy path; edge cases can be added later + +**Expected arguments when using quick mode**: +- `task`: Clear description of what to automate and how (be specific about workflow steps) +- `mode`: Must be set to `"quick"` +- `suggested_name`: (optional) Proposed skill identifier (lowercase, hyphens OK) + +**Quick mode principles**: +- **Be opinionated**: Make reasonable assumptions without asking +- **Be concise**: Keep instructions simple and focused +- **Be practical**: Focus on the core workflow that will save the most time +- **Be correct**: Always set `disable-model-invocation: false` and `user-invocable: true` +- **Be validating**: Run the frontmatter validator immediately after creation + +**Example invocation from the agent's self-evolution system**: +``` +invoke_skill( + skill_name: "skill-creator", + task: "Create a skill to extract and summarize content from URLs. The skill should: 1) fetch the URL using terminal with curl, 2) parse the HTML to extract main text content, 3) generate a concise markdown summary. Expected input: URL string. Expected output: markdown summary with title and key points.", + mode: "quick", + suggested_name: "url-summarizer" +) +``` + +--- + +## Platform Context: Clacky + +This skill runs inside **Clacky** (openclacky). Key platform specifics: + +- **Skills** live at `~/.clacky/skills/<skill-name>/` — **always create new skills here** (global user skills, visible to Web UI and all sessions). To locate an existing skill, check these paths in order using `glob` or `ls`: (1) `.clacky/skills/` — project-level skills, (2) `~/.clacky/skills/` — user-level skills. Built-in skills (shipped with the gem) are always available via `invoke_skill` by name — no file lookup needed. Never use `find /` or broad filesystem searches to locate skills. +- **No parallel subagents** — Clacky runs as a single agent; all test cases execute serially in the current session +- **No external agent CLI** — for evals, just execute the task directly in-session (read the skill, follow instructions, save outputs) +- **Scripts** — prefer **Ruby** (`.rb` files); Clacky is Ruby-native. Run with `ruby path/to/script.rb`. Python is available but Ruby is the default choice +- **`python3`** — if Python scripts are needed (e.g., `generate_review.py`), use `python3` explicitly +- The description optimization scripts (`run_loop.py`, `run_eval.py`) work in Clacky — they use `clacky agent --json` to detect `invoke_skill` events. See the Description Optimization section for usage + +--- + +## Communicating with the user + +Pay attention to context cues to understand how technical the user is. In general: + +- "evaluation" and "benchmark" are fine +- For "JSON" and "assertion" — explain briefly if you're unsure the user knows these terms + +It's always OK to briefly explain a term if you're in doubt. + +--- + +## Creating a skill + +### Capture Intent + +Start by understanding what the user wants. If the current conversation already shows a workflow they want to capture (tools used, sequence of steps, corrections made, input/output formats), extract answers from history first — the user may just need to fill gaps and confirm. + +1. What should this skill enable Clacky to do? +2. When should this skill trigger? (what phrases/contexts) +3. What's the expected output format? +4. Should we set up test cases? Skills with objectively verifiable outputs (file transforms, data extraction, code generation) benefit from test cases. Skills with subjective outputs (writing style, creative work) often don't need them. + +### Interview and Research + +Ask about edge cases, input/output formats, example files, success criteria, and dependencies before writing test prompts. Come prepared with context to reduce burden on the user. + +### Write the SKILL.md + +Components to fill in: + +- **name**: Skill identifier (lowercase, hyphens OK) +- **description**: Primary triggering mechanism — include BOTH what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Make the description a little "pushy" — err toward over-triggering rather than under-triggering. Example: instead of "Helps with dashboard creation", write "Helps with dashboard creation. Use this skill whenever the user mentions dashboards, data visualization, or wants to display any kind of data, even if they don't explicitly say 'dashboard'." +- **disable-model-invocation**: Set to `false` (always include this) +- **user-invocable**: Set to `true` to make the skill appear in the WebUI chatbox `/` command list. **Always include this** — without it, users cannot manually invoke the skill from the Clacky Web UI session chat. +- **compatibility** (optional): Required tools or dependencies +- **Body**: The actual instructions + +> **Clacky-specific**: Every skill MUST include `disable-model-invocation: false` and `user-invocable: true` in the YAML frontmatter, or it will be invisible in the WebUI `/` command list. The minimal valid frontmatter is: +> ```yaml +> --- +> name: my-skill +> description: 'Your description here. Avoid colons followed by a space (like "wants to: do X") inside the description — they break YAML parsing and the skill will silently fail to load. Wrap the entire description in single quotes to be safe, or rephrase to avoid the colon pattern.' +> disable-model-invocation: false +> user-invocable: true +> --- +> ``` +> +> **YAML description gotcha**: If the description contains `word: value` patterns (colons followed by space), YAML treats them as key-value pairs and the frontmatter parse fails silently. Always wrap description values in single quotes. Avoid embedded double-quotes inside single-quoted strings (use rephrasing instead). + +> **After writing SKILL.md — always validate and auto-fix**: Run this immediately after creating or updating any skill file: +> ```bash +> ruby SKILL_DIR/scripts/validate_skill_frontmatter.rb /path/to/new-skill/SKILL.md +> ``` +> The script validates the YAML frontmatter and auto-fixes common issues (unquoted descriptions, multi-line block scalars with colons). If it prints `OK:` — you're done. If it prints `Auto-fixed and saved` — it repaired the file automatically. If it prints `ERROR` — manual fix required. + +### Skill Writing Guide + +#### Anatomy of a Skill + +Skills are created at `~/.clacky/skills/<skill-name>/`: + +``` +~/.clacky/skills/skill-name/ +├── SKILL.md (required) +│ ├── YAML frontmatter (name, description required) +│ └── Markdown instructions +└── Bundled Resources (optional) + ├── scripts/ - Executable code (prefer .rb Ruby scripts) + ├── references/ - Docs loaded into context as needed + └── assets/ - Files used in output (templates, icons, fonts) +``` + +#### Progressive Disclosure + +Skills use a three-level loading system: +1. **Metadata** (name + description) — Always in context (~100 words) +2. **SKILL.md body** — In context whenever skill triggers (<500 lines ideal) +3. **Bundled resources** — Loaded as needed (unlimited) + +**Key patterns:** +- Keep SKILL.md under 500 lines; if approaching the limit, extract content into `references/` files and add clear pointers +- Reference files from SKILL.md with guidance on when to read them +- For large reference files (>300 lines), include a table of contents + +**Domain organization** — When a skill supports multiple frameworks/domains, organize by variant: +``` +my-skill/ +├── SKILL.md (workflow + which reference to load) +└── references/ + ├── rails.md + ├── django.md + └── express.md +``` + +#### Bundled Scripts (Ruby preferred) + +When a skill needs to execute code — API calls, file processing, data transforms — bundle a Ruby script instead of writing inline shell commands. This is cleaner, reusable, and more maintainable. + +**Ruby script template:** +```ruby +#!/usr/bin/env ruby +# skill-name/scripts/do_something.rb +# Usage: ruby path/to/do_something.rb [args] + +require 'net/http' +require 'json' +require 'fileutils' + +# Read args +input = ARGV[0] +if input.nil? || input.strip.empty? + warn "Usage: ruby do_something.rb <input>" + exit 1 +end + +# ... logic ... + +puts result # stdout is the output +``` + +Invoke from SKILL.md by referencing the script via the Supporting Files block — at runtime, the AI receives the full absolute path of every supporting file. Refer to it as `SKILL_DIR` in instructions so the AI substitutes the correct path from the Supporting Files list: + +```bash +ruby "SKILL_DIR/scripts/do_something.rb" "argument" +``` + +Never hardcode paths like `~/.clacky/skills/my-skill/scripts/...` — they break when the skill is installed at a different location. Never use `find` to locate scripts — the Supporting Files block always provides the correct absolute paths. + +Ruby standard library covers most needs (`net/http`, `json`, `fileutils`, `uri`, `time`). No gems needed for basic API calls. + +#### Principle of Least Surprise + +Skills must not contain malware, exploit code, or anything that could compromise security. A skill's contents should not surprise the user if described. Don't create misleading skills or skills designed for unauthorized access or data exfiltration. + +#### Writing Patterns + +Use the imperative form in instructions. + +**Defining output formats:** +```markdown +## Report structure +Use this exact template: +# [Title] +## Executive summary +## Key findings +## Recommendations +``` + +**Examples pattern:** +```markdown +## Commit message format +**Example 1:** +Input: Added user authentication with JWT tokens +Output: feat(auth): implement JWT-based authentication +``` + +### Writing Style + +Explain *why* things are important rather than just issuing commands. Use theory of mind — make the skill general, not over-fitted to specific examples. Write a draft, then look at it with fresh eyes and improve it. If you find yourself writing ALWAYS or NEVER in all caps, that's a yellow flag — try to reframe as an explanation of why, so the agent understands the reasoning rather than just following a rule. + +### Test Cases + +After writing the skill draft, come up with 2–3 realistic test prompts — the kind of thing a real user would actually say. Share them with the user for review, then run them. + +Save test cases to `evals/evals.json`: + +```json +{ + "skill_name": "example-skill", + "evals": [ + { + "id": 1, + "prompt": "User's task prompt", + "expected_output": "Description of expected result", + "files": [] + } + ] +} +``` + +Don't write assertions yet — just the prompts. Add assertions in the next step. + +See `references/schemas.md` for the full schema. + +--- + +## Running and Evaluating Test Cases + +This is one continuous sequence — don't stop partway through. + +Since Clacky has no subagents, run test cases **serially** in the current session. For each test case, simulate two runs: + +- **with_skill**: Read the SKILL.md, then follow its instructions to complete the task +- **without_skill**: Complete the same task using only general knowledge (no skill instructions) + +Put results in `<skill-name>-workspace/` as a sibling to the skill directory. Organize by iteration (`iteration-1/`, `iteration-2/`, etc.), and within that by test case (use descriptive names like `eval-create-report`, not `eval-0`). + +### Step 1: For each test case, create the eval directory and run both variants + +``` +<skill-name>-workspace/ +└── iteration-1/ + ├── eval-<descriptive-name>/ + │ ├── eval_metadata.json + │ ├── with_skill/ + │ │ ├── outputs/ ← files produced + │ │ └── grading.json ← filled in later + │ └── without_skill/ + │ ├── outputs/ + │ └── grading.json + └── benchmark.json ← filled in after all evals +``` + +Write `eval_metadata.json` for each test case: +```json +{ + "eval_id": 1, + "eval_name": "descriptive-name", + "prompt": "The task prompt", + "assertions": [] +} +``` + +**Running a with_skill eval**: Read the skill's SKILL.md fully, then execute the task as instructed by the skill — create files, run scripts, write outputs to `with_skill/outputs/`. + +**Running a without_skill eval**: Execute the same task using only general knowledge. Write outputs to `without_skill/outputs/`. This is the baseline. + +### Step 2: Draft assertions while running + +Don't wait until all runs finish — draft quantitative assertions as you go and explain them to the user. + +Good assertions are **objectively verifiable** and **descriptively named** — someone glancing at the benchmark should immediately understand what each one checks. Subjective skills are better evaluated qualitatively; don't force assertions onto things that need human judgment. + +Update `eval_metadata.json` with assertions once drafted. Also update `evals/evals.json`. + +### Step 3: Grade each run + +For each run, evaluate assertions against the outputs. Save results to `grading.json` in each run directory. + +The `grading.json` format (exact field names matter for the viewer): +```json +{ + "eval_id": 1, + "configuration": "with_skill", + "expectations": [ + { + "text": "The script uses absolute paths", + "passed": true, + "evidence": "Script uses $HOME/... throughout" + } + ], + "pass_count": 1, + "total_count": 1, + "pass_rate": 1.0 +} +``` + +For assertions that can be checked programmatically, write and run a Ruby script — it's faster and more reliable than eyeballing: + +```ruby +#!/usr/bin/env ruby +# Check assertion: output file contains expected content +output = File.read("with_skill/outputs/result.md") +puts output.include?("expected phrase") ? "PASS" : "FAIL" +``` + +### Step 4: Aggregate into benchmark + +Create `benchmark.json` in the iteration directory. List `with_skill` before `without_skill` for each eval: + +```json +{ + "skill_name": "my-skill", + "iteration": 1, + "configurations": [ + { + "name": "with_skill", + "label": "With skill", + "evals": [ + {"eval_id": 1, "eval_name": "eval-name", "pass_rate": 1.0, "pass_count": 3, "total_count": 3} + ], + "overall_pass_rate": 1.0, + "total_pass": 3, + "total_assertions": 3 + }, + { + "name": "without_skill", + "label": "Without skill (baseline)", + "evals": [ + {"eval_id": 1, "eval_name": "eval-name", "pass_rate": 0.33, "pass_count": 1, "total_count": 3} + ], + "overall_pass_rate": 0.33, + "total_pass": 1, + "total_assertions": 3 + } + ], + "delta": { + "pass_rate_improvement": 0.67, + "summary": "With skill: 100% | Without skill: 33% | Delta: +67pp" + }, + "analyst_observations": [ + "..." + ] +} +``` + +Or run the aggregation script (from the skill-creator directory): +```bash +python3 -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name> +``` + +### Step 5: Do an analyst pass + +Read the benchmark data and surface patterns the aggregate stats might hide. See `agents/analyzer.md` for what to look for — things like assertions that always pass regardless of skill (non-discriminating), high-variance evals, and time/effort tradeoffs. + +### Step 6: Generate the eval viewer — ALWAYS DO THIS BEFORE REVISING THE SKILL + +**Generate the viewer first. Get the outputs in front of the user before making any changes.** + +```bash +python3 <skill-creator-path>/eval-viewer/generate_review.py \ + <workspace>/iteration-N \ + --skill-name "my-skill" \ + --benchmark <workspace>/iteration-N/benchmark.json \ + --static /tmp/<skill-name>-review.html + +open /tmp/<skill-name>-review.html +``` + +For iteration 2+, also pass `--previous-workspace <workspace>/iteration-<N-1>`. + +Tell the user: "I've opened the results in your browser. 'Outputs' tab lets you click through each test case and leave feedback; 'Benchmark' shows the quantitative comparison. When you're done, come back and let me know." + +### What the user sees in the viewer + +**Outputs tab**: One test case at a time. +- Prompt, output files (rendered inline where possible) +- Previous output (iteration 2+, collapsed) +- Formal grades (collapsed) +- Feedback textbox (auto-saves) +- Previous feedback (iteration 2+) + +**Benchmark tab**: Pass rates, per-eval breakdowns, analyst observations. + +Navigation: prev/next buttons or arrow keys. "Submit All Reviews" saves to `feedback.json`. + +### Step 7: Read the feedback + +When the user says they're done, read `feedback.json`: + +```json +{ + "reviews": [ + {"run_id": "eval-0-with_skill", "feedback": "missing axis labels on chart", "timestamp": "..."}, + {"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."} + ], + "status": "complete" +} +``` + +Empty feedback = user was happy with that test case. Focus on cases with specific complaints. + +--- + +## Improving the Skill + +This is the heart of the loop. You've run tests, the user reviewed results — now make the skill better. + +### How to think about improvements + +**Generalize from feedback.** You're iterating on a few examples, but the skill will be used across thousands of different prompts. Avoid overfitting to specific examples. If there's a stubborn issue, try different metaphors or different approaches rather than adding more rigid rules. + +**Keep it lean.** Remove things that aren't pulling their weight. Read the execution trace, not just the final output — if the skill is making the agent waste time on unproductive steps, cut those parts. + +**Explain the why.** Try hard to explain *why* each instruction matters. Agents are smart — they perform better when they understand the reasoning rather than following rules blindly. If you find yourself writing ALWAYS or NEVER in all caps, reframe it as an explanation. + +**Look for repeated work.** If every test case resulted in writing similar helper logic (e.g., an API call setup, a file parser), that's a signal to bundle a reusable Ruby script into `scripts/` and tell the skill to use it. + +### The iteration loop + +1. Apply improvements to the skill +2. Re-run all test cases into a new `iteration-<N+1>/` directory (with_skill and without_skill) +3. Generate the viewer with `--previous-workspace` pointing at the previous iteration +4. Wait for the user to review and tell you they're done +5. Read the new feedback, improve again, repeat + +Keep going until: +- The user says they're happy +- Feedback is all empty +- You're not making meaningful progress + +--- + +## Advanced: Blind Comparison + +For more rigorous comparison, read `agents/comparator.md` and `agents/analyzer.md`. Optional — the human review loop is usually sufficient. + +--- + +## Description Optimization + +The `description` field in SKILL.md frontmatter is the primary triggering mechanism. After creating or improving a skill, offer to optimize it. + +> **Clacky note**: `run_eval.py` and `run_loop.py` have been adapted for Clacky. They use `clacky agent --json` (NDJSON streaming) to detect `invoke_skill` tool calls targeting temp skills in `~/.clacky/skills/`. Queries run **serially** (single agent). `improve_description.py` calls the LLM directly via OpenRouter using `~/.clacky/config.yml` credentials. + +### Manual description optimization + +**Step 1: Generate trigger eval queries** + +Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON: + +```json +[ + {"query": "the user prompt", "should_trigger": true}, + {"query": "another prompt", "should_trigger": false} +] +``` + +Queries must be realistic — concrete, specific, with enough context that a real user would actually say them. Include file paths, personal context, column names, backstory. Use a mix of lengths and styles (casual, formal, typos, abbreviations). Focus on edge cases. + +Bad: `"Format this data"`, `"Extract text from PDF"`, `"Create a chart"` + +Good: `"ok so my boss just sent me this xlsx file (its in downloads, called Q4 sales final FINAL v2.xlsx) and she wants me to add a column showing profit margin. Revenue is column C, costs in column D i think"` + +**Should-trigger queries (8–10):** Different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill but clearly needs it. Uncommon use cases, and cases where this skill competes with another but should win. + +**Should-not-trigger queries (8–10):** Near-misses — queries that share keywords but actually need something different. The negative cases should be genuinely tricky, not obviously irrelevant ("write a fibonacci function" as a negative for a PDF skill is too easy). + +**Step 2: Review with user** + +Use the HTML template in `assets/eval_review.html`: +1. Read the template +2. Replace `__EVAL_DATA_PLACEHOLDER__` with the JSON array, `__SKILL_NAME_PLACEHOLDER__` with the skill name, `__SKILL_DESCRIPTION_PLACEHOLDER__` with the current description +3. Write to `/tmp/eval_review_<skill-name>.html` and `open` it +4. User edits queries, toggles should-trigger, clicks "Export Eval Set" +5. File downloads to `~/Downloads/eval_set.json` + +**Step 3: Run automated optimization (recommended)** + +Use the scripts from the skill-creator `scripts/` directory. Run from the skill-creator root: + +```bash +# Single eval run — check current description pass rate +python3 -m scripts.run_eval \ + --eval-set ~/Downloads/eval_set.json \ + --skill-path ~/.clacky/skills/my-skill \ + --verbose + +# Full optimize loop — auto-improves description over N iterations +python3 -m scripts.run_loop \ + --eval-set ~/Downloads/eval_set.json \ + --skill-path ~/.clacky/skills/my-skill \ + --max-iterations 5 \ + --runs-per-query 1 \ + --verbose + # Outputs: best description + HTML report (auto-opens in browser) +``` + +Notes: +- **No `--num-workers`** needed (or it's ignored) — Clacky runs queries serially +- **No `--model`** needed — uses the model from `~/.clacky/config.yml` automatically +- Temp skills are written to `~/.clacky/skills/` and cleaned up after each query +- Each query spawns a fresh `clacky agent --json` process to avoid session contamination + +**Step 3 (manual fallback)** + +If scripts fail, manually iterate: for each query in the eval set, judge whether the description would trigger. Tally passes/fails. Write improved description targeting failures. Repeat 2–3 times. + +Focus on: +- Failing should-trigger queries → description is too narrow; broaden the trigger language +- Failing should-not-trigger queries → description is too broad; tighten specificity + +**Step 4: Apply the result** + +Update the skill's SKILL.md frontmatter with the improved description. Show the user before/after. + +### How skill triggering works + +Skills appear in Clacky's `available_skills` list. The agent consults a skill based on the description match — but only for tasks it can't handle alone. Simple, one-step queries often won't trigger even with a good description. Make eval queries substantive enough that the skill genuinely helps. + +--- + +## Packaging + +New skills are created directly in `~/.clacky/skills/<skill-name>/` — no packaging step needed. The skill is immediately available in all sessions and the Web UI. + +If distributing externally, you can package it: + +```bash +python3 -m scripts.package_skill <path/to/skill-folder> +``` + +This creates a `.skill` file. Direct the user to the resulting file path. + +--- + +## Reference files + +- `agents/grader.md` — How to evaluate assertions against outputs +- `agents/comparator.md` — How to do blind A/B comparison between two outputs +- `agents/analyzer.md` — How to analyze why one version beat another +- `references/schemas.md` — JSON structures for evals.json, grading.json, benchmark.json + +--- + +## The core loop (summary) + +1. Understand what the skill should do +2. Draft or edit the SKILL.md +3. Run test prompts — with and without the skill — and save outputs +4. **Generate the eval viewer with `generate_review.py`** so the user can review +5. Grade assertions, aggregate benchmark +6. Get user feedback, improve the skill +7. Repeat until satisfied +8. Package and deliver + +Add these steps to your todo list. Specifically: **always generate the eval viewer before revising the skill** — the user's feedback is the primary signal, not your own judgment of the outputs. diff --git a/lib/clacky/default_skills/skill-creator/agents/analyzer.md b/lib/clacky/default_skills/skill-creator/agents/analyzer.md new file mode 100644 index 0000000..14e41d6 --- /dev/null +++ b/lib/clacky/default_skills/skill-creator/agents/analyzer.md @@ -0,0 +1,274 @@ +# Post-hoc Analyzer Agent + +Analyze blind comparison results to understand WHY the winner won and generate improvement suggestions. + +## Role + +After the blind comparator determines a winner, the Post-hoc Analyzer "unblids" the results by examining the skills and transcripts. The goal is to extract actionable insights: what made the winner better, and how can the loser be improved? + +## Inputs + +You receive these parameters in your prompt: + +- **winner**: "A" or "B" (from blind comparison) +- **winner_skill_path**: Path to the skill that produced the winning output +- **winner_transcript_path**: Path to the execution transcript for the winner +- **loser_skill_path**: Path to the skill that produced the losing output +- **loser_transcript_path**: Path to the execution transcript for the loser +- **comparison_result_path**: Path to the blind comparator's output JSON +- **output_path**: Where to save the analysis results + +## Process + +### Step 1: Read Comparison Result + +1. Read the blind comparator's output at comparison_result_path +2. Note the winning side (A or B), the reasoning, and any scores +3. Understand what the comparator valued in the winning output + +### Step 2: Read Both Skills + +1. Read the winner skill's SKILL.md and key referenced files +2. Read the loser skill's SKILL.md and key referenced files +3. Identify structural differences: + - Instructions clarity and specificity + - Script/tool usage patterns + - Example coverage + - Edge case handling + +### Step 3: Read Both Transcripts + +1. Read the winner's transcript +2. Read the loser's transcript +3. Compare execution patterns: + - How closely did each follow their skill's instructions? + - What tools were used differently? + - Where did the loser diverge from optimal behavior? + - Did either encounter errors or make recovery attempts? + +### Step 4: Analyze Instruction Following + +For each transcript, evaluate: +- Did the agent follow the skill's explicit instructions? +- Did the agent use the skill's provided tools/scripts? +- Were there missed opportunities to leverage skill content? +- Did the agent add unnecessary steps not in the skill? + +Score instruction following 1-10 and note specific issues. + +### Step 5: Identify Winner Strengths + +Determine what made the winner better: +- Clearer instructions that led to better behavior? +- Better scripts/tools that produced better output? +- More comprehensive examples that guided edge cases? +- Better error handling guidance? + +Be specific. Quote from skills/transcripts where relevant. + +### Step 6: Identify Loser Weaknesses + +Determine what held the loser back: +- Ambiguous instructions that led to suboptimal choices? +- Missing tools/scripts that forced workarounds? +- Gaps in edge case coverage? +- Poor error handling that caused failures? + +### Step 7: Generate Improvement Suggestions + +Based on the analysis, produce actionable suggestions for improving the loser skill: +- Specific instruction changes to make +- Tools/scripts to add or modify +- Examples to include +- Edge cases to address + +Prioritize by impact. Focus on changes that would have changed the outcome. + +### Step 8: Write Analysis Results + +Save structured analysis to `{output_path}`. + +## Output Format + +Write a JSON file with this structure: + +```json +{ + "comparison_summary": { + "winner": "A", + "winner_skill": "path/to/winner/skill", + "loser_skill": "path/to/loser/skill", + "comparator_reasoning": "Brief summary of why comparator chose winner" + }, + "winner_strengths": [ + "Clear step-by-step instructions for handling multi-page documents", + "Included validation script that caught formatting errors", + "Explicit guidance on fallback behavior when OCR fails" + ], + "loser_weaknesses": [ + "Vague instruction 'process the document appropriately' led to inconsistent behavior", + "No script for validation, agent had to improvise and made errors", + "No guidance on OCR failure, agent gave up instead of trying alternatives" + ], + "instruction_following": { + "winner": { + "score": 9, + "issues": [ + "Minor: skipped optional logging step" + ] + }, + "loser": { + "score": 6, + "issues": [ + "Did not use the skill's formatting template", + "Invented own approach instead of following step 3", + "Missed the 'always validate output' instruction" + ] + } + }, + "improvement_suggestions": [ + { + "priority": "high", + "category": "instructions", + "suggestion": "Replace 'process the document appropriately' with explicit steps: 1) Extract text, 2) Identify sections, 3) Format per template", + "expected_impact": "Would eliminate ambiguity that caused inconsistent behavior" + }, + { + "priority": "high", + "category": "tools", + "suggestion": "Add validate_output.py script similar to winner skill's validation approach", + "expected_impact": "Would catch formatting errors before final output" + }, + { + "priority": "medium", + "category": "error_handling", + "suggestion": "Add fallback instructions: 'If OCR fails, try: 1) different resolution, 2) image preprocessing, 3) manual extraction'", + "expected_impact": "Would prevent early failure on difficult documents" + } + ], + "transcript_insights": { + "winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script -> Fixed 2 issues -> Produced output", + "loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods -> No validation -> Output had errors" + } +} +``` + +## Guidelines + +- **Be specific**: Quote from skills and transcripts, don't just say "instructions were unclear" +- **Be actionable**: Suggestions should be concrete changes, not vague advice +- **Focus on skill improvements**: The goal is to improve the losing skill, not critique the agent +- **Prioritize by impact**: Which changes would most likely have changed the outcome? +- **Consider causation**: Did the skill weakness actually cause the worse output, or is it incidental? +- **Stay objective**: Analyze what happened, don't editorialize +- **Think about generalization**: Would this improvement help on other evals too? + +## Categories for Suggestions + +Use these categories to organize improvement suggestions: + +| Category | Description | +|----------|-------------| +| `instructions` | Changes to the skill's prose instructions | +| `tools` | Scripts, templates, or utilities to add/modify | +| `examples` | Example inputs/outputs to include | +| `error_handling` | Guidance for handling failures | +| `structure` | Reorganization of skill content | +| `references` | External docs or resources to add | + +## Priority Levels + +- **high**: Would likely change the outcome of this comparison +- **medium**: Would improve quality but may not change win/loss +- **low**: Nice to have, marginal improvement + +--- + +# Analyzing Benchmark Results + +When analyzing benchmark results, the analyzer's purpose is to **surface patterns and anomalies** across multiple runs, not suggest skill improvements. + +## Role + +Review all benchmark run results and generate freeform notes that help the user understand skill performance. Focus on patterns that wouldn't be visible from aggregate metrics alone. + +## Inputs + +You receive these parameters in your prompt: + +- **benchmark_data_path**: Path to the in-progress benchmark.json with all run results +- **skill_path**: Path to the skill being benchmarked +- **output_path**: Where to save the notes (as JSON array of strings) + +## Process + +### Step 1: Read Benchmark Data + +1. Read the benchmark.json containing all run results +2. Note the configurations tested (with_skill, without_skill) +3. Understand the run_summary aggregates already calculated + +### Step 2: Analyze Per-Assertion Patterns + +For each expectation across all runs: +- Does it **always pass** in both configurations? (may not differentiate skill value) +- Does it **always fail** in both configurations? (may be broken or beyond capability) +- Does it **always pass with skill but fail without**? (skill clearly adds value here) +- Does it **always fail with skill but pass without**? (skill may be hurting) +- Is it **highly variable**? (flaky expectation or non-deterministic behavior) + +### Step 3: Analyze Cross-Eval Patterns + +Look for patterns across evals: +- Are certain eval types consistently harder/easier? +- Do some evals show high variance while others are stable? +- Are there surprising results that contradict expectations? + +### Step 4: Analyze Metrics Patterns + +Look at time_seconds, tokens, tool_calls: +- Does the skill significantly increase execution time? +- Is there high variance in resource usage? +- Are there outlier runs that skew the aggregates? + +### Step 5: Generate Notes + +Write freeform observations as a list of strings. Each note should: +- State a specific observation +- Be grounded in the data (not speculation) +- Help the user understand something the aggregate metrics don't show + +Examples: +- "Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value" +- "Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure that may be flaky" +- "Without-skill runs consistently fail on table extraction expectations (0% pass rate)" +- "Skill adds 13s average execution time but improves pass rate by 50%" +- "Token usage is 80% higher with skill, primarily due to script output parsing" +- "All 3 without-skill runs for eval 1 produced empty output" + +### Step 6: Write Notes + +Save notes to `{output_path}` as a JSON array of strings: + +```json +[ + "Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value", + "Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure", + "Without-skill runs consistently fail on table extraction expectations", + "Skill adds 13s average execution time but improves pass rate by 50%" +] +``` + +## Guidelines + +**DO:** +- Report what you observe in the data +- Be specific about which evals, expectations, or runs you're referring to +- Note patterns that aggregate metrics would hide +- Provide context that helps interpret the numbers + +**DO NOT:** +- Suggest improvements to the skill (that's for the improvement step, not benchmarking) +- Make subjective quality judgments ("the output was good/bad") +- Speculate about causes without evidence +- Repeat information already in the run_summary aggregates diff --git a/lib/clacky/default_skills/skill-creator/agents/comparator.md b/lib/clacky/default_skills/skill-creator/agents/comparator.md new file mode 100644 index 0000000..80e00eb --- /dev/null +++ b/lib/clacky/default_skills/skill-creator/agents/comparator.md @@ -0,0 +1,202 @@ +# Blind Comparator Agent + +Compare two outputs WITHOUT knowing which skill produced them. + +## Role + +The Blind Comparator judges which output better accomplishes the eval task. You receive two outputs labeled A and B, but you do NOT know which skill produced which. This prevents bias toward a particular skill or approach. + +Your judgment is based purely on output quality and task completion. + +## Inputs + +You receive these parameters in your prompt: + +- **output_a_path**: Path to the first output file or directory +- **output_b_path**: Path to the second output file or directory +- **eval_prompt**: The original task/prompt that was executed +- **expectations**: List of expectations to check (optional - may be empty) + +## Process + +### Step 1: Read Both Outputs + +1. Examine output A (file or directory) +2. Examine output B (file or directory) +3. Note the type, structure, and content of each +4. If outputs are directories, examine all relevant files inside + +### Step 2: Understand the Task + +1. Read the eval_prompt carefully +2. Identify what the task requires: + - What should be produced? + - What qualities matter (accuracy, completeness, format)? + - What would distinguish a good output from a poor one? + +### Step 3: Generate Evaluation Rubric + +Based on the task, generate a rubric with two dimensions: + +**Content Rubric** (what the output contains): +| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) | +|-----------|----------|----------------|---------------| +| Correctness | Major errors | Minor errors | Fully correct | +| Completeness | Missing key elements | Mostly complete | All elements present | +| Accuracy | Significant inaccuracies | Minor inaccuracies | Accurate throughout | + +**Structure Rubric** (how the output is organized): +| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) | +|-----------|----------|----------------|---------------| +| Organization | Disorganized | Reasonably organized | Clear, logical structure | +| Formatting | Inconsistent/broken | Mostly consistent | Professional, polished | +| Usability | Difficult to use | Usable with effort | Easy to use | + +Adapt criteria to the specific task. For example: +- PDF form → "Field alignment", "Text readability", "Data placement" +- Document → "Section structure", "Heading hierarchy", "Paragraph flow" +- Data output → "Schema correctness", "Data types", "Completeness" + +### Step 4: Evaluate Each Output Against the Rubric + +For each output (A and B): + +1. **Score each criterion** on the rubric (1-5 scale) +2. **Calculate dimension totals**: Content score, Structure score +3. **Calculate overall score**: Average of dimension scores, scaled to 1-10 + +### Step 5: Check Assertions (if provided) + +If expectations are provided: + +1. Check each expectation against output A +2. Check each expectation against output B +3. Count pass rates for each output +4. Use expectation scores as secondary evidence (not the primary decision factor) + +### Step 6: Determine the Winner + +Compare A and B based on (in priority order): + +1. **Primary**: Overall rubric score (content + structure) +2. **Secondary**: Assertion pass rates (if applicable) +3. **Tiebreaker**: If truly equal, declare a TIE + +Be decisive - ties should be rare. One output is usually better, even if marginally. + +### Step 7: Write Comparison Results + +Save results to a JSON file at the path specified (or `comparison.json` if not specified). + +## Output Format + +Write a JSON file with this structure: + +```json +{ + "winner": "A", + "reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.", + "rubric": { + "A": { + "content": { + "correctness": 5, + "completeness": 5, + "accuracy": 4 + }, + "structure": { + "organization": 4, + "formatting": 5, + "usability": 4 + }, + "content_score": 4.7, + "structure_score": 4.3, + "overall_score": 9.0 + }, + "B": { + "content": { + "correctness": 3, + "completeness": 2, + "accuracy": 3 + }, + "structure": { + "organization": 3, + "formatting": 2, + "usability": 3 + }, + "content_score": 2.7, + "structure_score": 2.7, + "overall_score": 5.4 + } + }, + "output_quality": { + "A": { + "score": 9, + "strengths": ["Complete solution", "Well-formatted", "All fields present"], + "weaknesses": ["Minor style inconsistency in header"] + }, + "B": { + "score": 5, + "strengths": ["Readable output", "Correct basic structure"], + "weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"] + } + }, + "expectation_results": { + "A": { + "passed": 4, + "total": 5, + "pass_rate": 0.80, + "details": [ + {"text": "Output includes name", "passed": true}, + {"text": "Output includes date", "passed": true}, + {"text": "Format is PDF", "passed": true}, + {"text": "Contains signature", "passed": false}, + {"text": "Readable text", "passed": true} + ] + }, + "B": { + "passed": 3, + "total": 5, + "pass_rate": 0.60, + "details": [ + {"text": "Output includes name", "passed": true}, + {"text": "Output includes date", "passed": false}, + {"text": "Format is PDF", "passed": true}, + {"text": "Contains signature", "passed": false}, + {"text": "Readable text", "passed": true} + ] + } + } +} +``` + +If no expectations were provided, omit the `expectation_results` field entirely. + +## Field Descriptions + +- **winner**: "A", "B", or "TIE" +- **reasoning**: Clear explanation of why the winner was chosen (or why it's a tie) +- **rubric**: Structured rubric evaluation for each output + - **content**: Scores for content criteria (correctness, completeness, accuracy) + - **structure**: Scores for structure criteria (organization, formatting, usability) + - **content_score**: Average of content criteria (1-5) + - **structure_score**: Average of structure criteria (1-5) + - **overall_score**: Combined score scaled to 1-10 +- **output_quality**: Summary quality assessment + - **score**: 1-10 rating (should match rubric overall_score) + - **strengths**: List of positive aspects + - **weaknesses**: List of issues or shortcomings +- **expectation_results**: (Only if expectations provided) + - **passed**: Number of expectations that passed + - **total**: Total number of expectations + - **pass_rate**: Fraction passed (0.0 to 1.0) + - **details**: Individual expectation results + +## Guidelines + +- **Stay blind**: DO NOT try to infer which skill produced which output. Judge purely on output quality. +- **Be specific**: Cite specific examples when explaining strengths and weaknesses. +- **Be decisive**: Choose a winner unless outputs are genuinely equivalent. +- **Output quality first**: Assertion scores are secondary to overall task completion. +- **Be objective**: Don't favor outputs based on style preferences; focus on correctness and completeness. +- **Explain your reasoning**: The reasoning field should make it clear why you chose the winner. +- **Handle edge cases**: If both outputs fail, pick the one that fails less badly. If both are excellent, pick the one that's marginally better. diff --git a/lib/clacky/default_skills/skill-creator/agents/grader.md b/lib/clacky/default_skills/skill-creator/agents/grader.md new file mode 100644 index 0000000..558ab05 --- /dev/null +++ b/lib/clacky/default_skills/skill-creator/agents/grader.md @@ -0,0 +1,223 @@ +# Grader Agent + +Evaluate expectations against an execution transcript and outputs. + +## Role + +The Grader reviews a transcript and output files, then determines whether each expectation passes or fails. Provide clear evidence for each judgment. + +You have two jobs: grade the outputs, and critique the evals themselves. A passing grade on a weak assertion is worse than useless — it creates false confidence. When you notice an assertion that's trivially satisfied, or an important outcome that no assertion checks, say so. + +## Inputs + +You receive these parameters in your prompt: + +- **expectations**: List of expectations to evaluate (strings) +- **transcript_path**: Path to the execution transcript (markdown file) +- **outputs_dir**: Directory containing output files from execution + +## Process + +### Step 1: Read the Transcript + +1. Read the transcript file completely +2. Note the eval prompt, execution steps, and final result +3. Identify any issues or errors documented + +### Step 2: Examine Output Files + +1. List files in outputs_dir +2. Read/examine each file relevant to the expectations. If outputs aren't plain text, use the inspection tools provided in your prompt — don't rely solely on what the transcript says the executor produced. +3. Note contents, structure, and quality + +### Step 3: Evaluate Each Assertion + +For each expectation: + +1. **Search for evidence** in the transcript and outputs +2. **Determine verdict**: + - **PASS**: Clear evidence the expectation is true AND the evidence reflects genuine task completion, not just surface-level compliance + - **FAIL**: No evidence, or evidence contradicts the expectation, or the evidence is superficial (e.g., correct filename but empty/wrong content) +3. **Cite the evidence**: Quote the specific text or describe what you found + +### Step 4: Extract and Verify Claims + +Beyond the predefined expectations, extract implicit claims from the outputs and verify them: + +1. **Extract claims** from the transcript and outputs: + - Factual statements ("The form has 12 fields") + - Process claims ("Used pypdf to fill the form") + - Quality claims ("All fields were filled correctly") + +2. **Verify each claim**: + - **Factual claims**: Can be checked against the outputs or external sources + - **Process claims**: Can be verified from the transcript + - **Quality claims**: Evaluate whether the claim is justified + +3. **Flag unverifiable claims**: Note claims that cannot be verified with available information + +This catches issues that predefined expectations might miss. + +### Step 5: Read User Notes + +If `{outputs_dir}/user_notes.md` exists: +1. Read it and note any uncertainties or issues flagged by the executor +2. Include relevant concerns in the grading output +3. These may reveal problems even when expectations pass + +### Step 6: Critique the Evals + +After grading, consider whether the evals themselves could be improved. Only surface suggestions when there's a clear gap. + +Good suggestions test meaningful outcomes — assertions that are hard to satisfy without actually doing the work correctly. Think about what makes an assertion *discriminating*: it passes when the skill genuinely succeeds and fails when it doesn't. + +Suggestions worth raising: +- An assertion that passed but would also pass for a clearly wrong output (e.g., checking filename existence but not file content) +- An important outcome you observed — good or bad — that no assertion covers at all +- An assertion that can't actually be verified from the available outputs + +Keep the bar high. The goal is to flag things the eval author would say "good catch" about, not to nitpick every assertion. + +### Step 7: Write Grading Results + +Save results to `{outputs_dir}/../grading.json` (sibling to outputs_dir). + +## Grading Criteria + +**PASS when**: +- The transcript or outputs clearly demonstrate the expectation is true +- Specific evidence can be cited +- The evidence reflects genuine substance, not just surface compliance (e.g., a file exists AND contains correct content, not just the right filename) + +**FAIL when**: +- No evidence found for the expectation +- Evidence contradicts the expectation +- The expectation cannot be verified from available information +- The evidence is superficial — the assertion is technically satisfied but the underlying task outcome is wrong or incomplete +- The output appears to meet the assertion by coincidence rather than by actually doing the work + +**When uncertain**: The burden of proof to pass is on the expectation. + +### Step 8: Read Executor Metrics and Timing + +1. If `{outputs_dir}/metrics.json` exists, read it and include in grading output +2. If `{outputs_dir}/../timing.json` exists, read it and include timing data + +## Output Format + +Write a JSON file with this structure: + +```json +{ + "expectations": [ + { + "text": "The output includes the name 'John Smith'", + "passed": true, + "evidence": "Found in transcript Step 3: 'Extracted names: John Smith, Sarah Johnson'" + }, + { + "text": "The spreadsheet has a SUM formula in cell B10", + "passed": false, + "evidence": "No spreadsheet was created. The output was a text file." + }, + { + "text": "The assistant used the skill's OCR script", + "passed": true, + "evidence": "Transcript Step 2 shows: 'Tool: Bash - python ocr_script.py image.png'" + } + ], + "summary": { + "passed": 2, + "failed": 1, + "total": 3, + "pass_rate": 0.67 + }, + "execution_metrics": { + "tool_calls": { + "Read": 5, + "Write": 2, + "Bash": 8 + }, + "total_tool_calls": 15, + "total_steps": 6, + "errors_encountered": 0, + "output_chars": 12450, + "transcript_chars": 3200 + }, + "timing": { + "executor_duration_seconds": 165.0, + "grader_duration_seconds": 26.0, + "total_duration_seconds": 191.0 + }, + "claims": [ + { + "claim": "The form has 12 fillable fields", + "type": "factual", + "verified": true, + "evidence": "Counted 12 fields in field_info.json" + }, + { + "claim": "All required fields were populated", + "type": "quality", + "verified": false, + "evidence": "Reference section was left blank despite data being available" + } + ], + "user_notes_summary": { + "uncertainties": ["Used 2023 data, may be stale"], + "needs_review": [], + "workarounds": ["Fell back to text overlay for non-fillable fields"] + }, + "eval_feedback": { + "suggestions": [ + { + "assertion": "The output includes the name 'John Smith'", + "reason": "A hallucinated document that mentions the name would also pass — consider checking it appears as the primary contact with matching phone and email from the input" + }, + { + "reason": "No assertion checks whether the extracted phone numbers match the input — I observed incorrect numbers in the output that went uncaught" + } + ], + "overall": "Assertions check presence but not correctness. Consider adding content verification." + } +} +``` + +## Field Descriptions + +- **expectations**: Array of graded expectations + - **text**: The original expectation text + - **passed**: Boolean - true if expectation passes + - **evidence**: Specific quote or description supporting the verdict +- **summary**: Aggregate statistics + - **passed**: Count of passed expectations + - **failed**: Count of failed expectations + - **total**: Total expectations evaluated + - **pass_rate**: Fraction passed (0.0 to 1.0) +- **execution_metrics**: Copied from executor's metrics.json (if available) + - **output_chars**: Total character count of output files (proxy for tokens) + - **transcript_chars**: Character count of transcript +- **timing**: Wall clock timing from timing.json (if available) + - **executor_duration_seconds**: Time spent in executor subagent + - **total_duration_seconds**: Total elapsed time for the run +- **claims**: Extracted and verified claims from the output + - **claim**: The statement being verified + - **type**: "factual", "process", or "quality" + - **verified**: Boolean - whether the claim holds + - **evidence**: Supporting or contradicting evidence +- **user_notes_summary**: Issues flagged by the executor + - **uncertainties**: Things the executor wasn't sure about + - **needs_review**: Items requiring human attention + - **workarounds**: Places where the skill didn't work as expected +- **eval_feedback**: Improvement suggestions for the evals (only when warranted) + - **suggestions**: List of concrete suggestions, each with a `reason` and optionally an `assertion` it relates to + - **overall**: Brief assessment — can be "No suggestions, evals look solid" if nothing to flag + +## Guidelines + +- **Be objective**: Base verdicts on evidence, not assumptions +- **Be specific**: Quote the exact text that supports your verdict +- **Be thorough**: Check both transcript and output files +- **Be consistent**: Apply the same standard to each expectation +- **Explain failures**: Make it clear why evidence was insufficient +- **No partial credit**: Each expectation is pass or fail, not partial diff --git a/lib/clacky/default_skills/skill-creator/eval-viewer/generate_review.py b/lib/clacky/default_skills/skill-creator/eval-viewer/generate_review.py new file mode 100644 index 0000000..7fa5978 --- /dev/null +++ b/lib/clacky/default_skills/skill-creator/eval-viewer/generate_review.py @@ -0,0 +1,471 @@ +#!/usr/bin/env python3 +"""Generate and serve a review page for eval results. + +Reads the workspace directory, discovers runs (directories with outputs/), +embeds all output data into a self-contained HTML page, and serves it via +a tiny HTTP server. Feedback auto-saves to feedback.json in the workspace. + +Usage: + python generate_review.py <workspace-path> [--port PORT] [--skill-name NAME] + python generate_review.py <workspace-path> --previous-feedback /path/to/old/feedback.json + +No dependencies beyond the Python stdlib are required. +""" + +import argparse +import base64 +import json +import mimetypes +import os +import re +import signal +import subprocess +import sys +import time +import webbrowser +from functools import partial +from http.server import HTTPServer, BaseHTTPRequestHandler +from pathlib import Path + +# Files to exclude from output listings +METADATA_FILES = {"transcript.md", "user_notes.md", "metrics.json"} + +# Extensions we render as inline text +TEXT_EXTENSIONS = { + ".txt", ".md", ".json", ".csv", ".py", ".js", ".ts", ".tsx", ".jsx", + ".yaml", ".yml", ".xml", ".html", ".css", ".sh", ".rb", ".go", ".rs", + ".java", ".c", ".cpp", ".h", ".hpp", ".sql", ".r", ".toml", +} + +# Extensions we render as inline images +IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"} + +# MIME type overrides for common types +MIME_OVERRIDES = { + ".svg": "image/svg+xml", + ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", + ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", + ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation", +} + + +def get_mime_type(path: Path) -> str: + ext = path.suffix.lower() + if ext in MIME_OVERRIDES: + return MIME_OVERRIDES[ext] + mime, _ = mimetypes.guess_type(str(path)) + return mime or "application/octet-stream" + + +def find_runs(workspace: Path) -> list[dict]: + """Recursively find directories that contain an outputs/ subdirectory.""" + runs: list[dict] = [] + _find_runs_recursive(workspace, workspace, runs) + runs.sort(key=lambda r: (r.get("eval_id", float("inf")), r["id"])) + return runs + + +def _find_runs_recursive(root: Path, current: Path, runs: list[dict]) -> None: + if not current.is_dir(): + return + + outputs_dir = current / "outputs" + if outputs_dir.is_dir(): + run = build_run(root, current) + if run: + runs.append(run) + return + + skip = {"node_modules", ".git", "__pycache__", "skill", "inputs"} + for child in sorted(current.iterdir()): + if child.is_dir() and child.name not in skip: + _find_runs_recursive(root, child, runs) + + +def build_run(root: Path, run_dir: Path) -> dict | None: + """Build a run dict with prompt, outputs, and grading data.""" + prompt = "" + eval_id = None + + # Try eval_metadata.json + for candidate in [run_dir / "eval_metadata.json", run_dir.parent / "eval_metadata.json"]: + if candidate.exists(): + try: + metadata = json.loads(candidate.read_text()) + prompt = metadata.get("prompt", "") + eval_id = metadata.get("eval_id") + except (json.JSONDecodeError, OSError): + pass + if prompt: + break + + # Fall back to transcript.md + if not prompt: + for candidate in [run_dir / "transcript.md", run_dir / "outputs" / "transcript.md"]: + if candidate.exists(): + try: + text = candidate.read_text() + match = re.search(r"## Eval Prompt\n\n([\s\S]*?)(?=\n##|$)", text) + if match: + prompt = match.group(1).strip() + except OSError: + pass + if prompt: + break + + if not prompt: + prompt = "(No prompt found)" + + run_id = str(run_dir.relative_to(root)).replace("/", "-").replace("\\", "-") + + # Collect output files + outputs_dir = run_dir / "outputs" + output_files: list[dict] = [] + if outputs_dir.is_dir(): + for f in sorted(outputs_dir.iterdir()): + if f.is_file() and f.name not in METADATA_FILES: + output_files.append(embed_file(f)) + + # Load grading if present + grading = None + for candidate in [run_dir / "grading.json", run_dir.parent / "grading.json"]: + if candidate.exists(): + try: + grading = json.loads(candidate.read_text()) + except (json.JSONDecodeError, OSError): + pass + if grading: + break + + return { + "id": run_id, + "prompt": prompt, + "eval_id": eval_id, + "outputs": output_files, + "grading": grading, + } + + +def embed_file(path: Path) -> dict: + """Read a file and return an embedded representation.""" + ext = path.suffix.lower() + mime = get_mime_type(path) + + if ext in TEXT_EXTENSIONS: + try: + content = path.read_text(errors="replace") + except OSError: + content = "(Error reading file)" + return { + "name": path.name, + "type": "text", + "content": content, + } + elif ext in IMAGE_EXTENSIONS: + try: + raw = path.read_bytes() + b64 = base64.b64encode(raw).decode("ascii") + except OSError: + return {"name": path.name, "type": "error", "content": "(Error reading file)"} + return { + "name": path.name, + "type": "image", + "mime": mime, + "data_uri": f"data:{mime};base64,{b64}", + } + elif ext == ".pdf": + try: + raw = path.read_bytes() + b64 = base64.b64encode(raw).decode("ascii") + except OSError: + return {"name": path.name, "type": "error", "content": "(Error reading file)"} + return { + "name": path.name, + "type": "pdf", + "data_uri": f"data:{mime};base64,{b64}", + } + elif ext == ".xlsx": + try: + raw = path.read_bytes() + b64 = base64.b64encode(raw).decode("ascii") + except OSError: + return {"name": path.name, "type": "error", "content": "(Error reading file)"} + return { + "name": path.name, + "type": "xlsx", + "data_b64": b64, + } + else: + # Binary / unknown — base64 download link + try: + raw = path.read_bytes() + b64 = base64.b64encode(raw).decode("ascii") + except OSError: + return {"name": path.name, "type": "error", "content": "(Error reading file)"} + return { + "name": path.name, + "type": "binary", + "mime": mime, + "data_uri": f"data:{mime};base64,{b64}", + } + + +def load_previous_iteration(workspace: Path) -> dict[str, dict]: + """Load previous iteration's feedback and outputs. + + Returns a map of run_id -> {"feedback": str, "outputs": list[dict]}. + """ + result: dict[str, dict] = {} + + # Load feedback + feedback_map: dict[str, str] = {} + feedback_path = workspace / "feedback.json" + if feedback_path.exists(): + try: + data = json.loads(feedback_path.read_text()) + feedback_map = { + r["run_id"]: r["feedback"] + for r in data.get("reviews", []) + if r.get("feedback", "").strip() + } + except (json.JSONDecodeError, OSError, KeyError): + pass + + # Load runs (to get outputs) + prev_runs = find_runs(workspace) + for run in prev_runs: + result[run["id"]] = { + "feedback": feedback_map.get(run["id"], ""), + "outputs": run.get("outputs", []), + } + + # Also add feedback for run_ids that had feedback but no matching run + for run_id, fb in feedback_map.items(): + if run_id not in result: + result[run_id] = {"feedback": fb, "outputs": []} + + return result + + +def generate_html( + runs: list[dict], + skill_name: str, + previous: dict[str, dict] | None = None, + benchmark: dict | None = None, +) -> str: + """Generate the complete standalone HTML page with embedded data.""" + template_path = Path(__file__).parent / "viewer.html" + template = template_path.read_text() + + # Build previous_feedback and previous_outputs maps for the template + previous_feedback: dict[str, str] = {} + previous_outputs: dict[str, list[dict]] = {} + if previous: + for run_id, data in previous.items(): + if data.get("feedback"): + previous_feedback[run_id] = data["feedback"] + if data.get("outputs"): + previous_outputs[run_id] = data["outputs"] + + embedded = { + "skill_name": skill_name, + "runs": runs, + "previous_feedback": previous_feedback, + "previous_outputs": previous_outputs, + } + if benchmark: + embedded["benchmark"] = benchmark + + data_json = json.dumps(embedded) + + return template.replace("/*__EMBEDDED_DATA__*/", f"const EMBEDDED_DATA = {data_json};") + + +# --------------------------------------------------------------------------- +# HTTP server (stdlib only, zero dependencies) +# --------------------------------------------------------------------------- + +def _kill_port(port: int) -> None: + """Kill any process listening on the given port.""" + try: + result = subprocess.run( + ["lsof", "-ti", f":{port}"], + capture_output=True, text=True, timeout=5, + ) + for pid_str in result.stdout.strip().split("\n"): + if pid_str.strip(): + try: + os.kill(int(pid_str.strip()), signal.SIGTERM) + except (ProcessLookupError, ValueError): + pass + if result.stdout.strip(): + time.sleep(0.5) + except subprocess.TimeoutExpired: + pass + except FileNotFoundError: + print("Note: lsof not found, cannot check if port is in use", file=sys.stderr) + +class ReviewHandler(BaseHTTPRequestHandler): + """Serves the review HTML and handles feedback saves. + + Regenerates the HTML on each page load so that refreshing the browser + picks up new eval outputs without restarting the server. + """ + + def __init__( + self, + workspace: Path, + skill_name: str, + feedback_path: Path, + previous: dict[str, dict], + benchmark_path: Path | None, + *args, + **kwargs, + ): + self.workspace = workspace + self.skill_name = skill_name + self.feedback_path = feedback_path + self.previous = previous + self.benchmark_path = benchmark_path + super().__init__(*args, **kwargs) + + def do_GET(self) -> None: + if self.path == "/" or self.path == "/index.html": + # Regenerate HTML on each request (re-scans workspace for new outputs) + runs = find_runs(self.workspace) + benchmark = None + if self.benchmark_path and self.benchmark_path.exists(): + try: + benchmark = json.loads(self.benchmark_path.read_text()) + except (json.JSONDecodeError, OSError): + pass + html = generate_html(runs, self.skill_name, self.previous, benchmark) + content = html.encode("utf-8") + self.send_response(200) + self.send_header("Content-Type", "text/html; charset=utf-8") + self.send_header("Content-Length", str(len(content))) + self.end_headers() + self.wfile.write(content) + elif self.path == "/api/feedback": + data = b"{}" + if self.feedback_path.exists(): + data = self.feedback_path.read_bytes() + self.send_response(200) + self.send_header("Content-Type", "application/json") + self.send_header("Content-Length", str(len(data))) + self.end_headers() + self.wfile.write(data) + else: + self.send_error(404) + + def do_POST(self) -> None: + if self.path == "/api/feedback": + length = int(self.headers.get("Content-Length", 0)) + body = self.rfile.read(length) + try: + data = json.loads(body) + if not isinstance(data, dict) or "reviews" not in data: + raise ValueError("Expected JSON object with 'reviews' key") + self.feedback_path.write_text(json.dumps(data, indent=2) + "\n") + resp = b'{"ok":true}' + self.send_response(200) + except (json.JSONDecodeError, OSError, ValueError) as e: + resp = json.dumps({"error": str(e)}).encode() + self.send_response(500) + self.send_header("Content-Type", "application/json") + self.send_header("Content-Length", str(len(resp))) + self.end_headers() + self.wfile.write(resp) + else: + self.send_error(404) + + def log_message(self, format: str, *args: object) -> None: + # Suppress request logging to keep terminal clean + pass + + +def main() -> None: + parser = argparse.ArgumentParser(description="Generate and serve eval review") + parser.add_argument("workspace", type=Path, help="Path to workspace directory") + parser.add_argument("--port", "-p", type=int, default=3117, help="Server port (default: 3117)") + parser.add_argument("--skill-name", "-n", type=str, default=None, help="Skill name for header") + parser.add_argument( + "--previous-workspace", type=Path, default=None, + help="Path to previous iteration's workspace (shows old outputs and feedback as context)", + ) + parser.add_argument( + "--benchmark", type=Path, default=None, + help="Path to benchmark.json to show in the Benchmark tab", + ) + parser.add_argument( + "--static", "-s", type=Path, default=None, + help="Write standalone HTML to this path instead of starting a server", + ) + args = parser.parse_args() + + workspace = args.workspace.resolve() + if not workspace.is_dir(): + print(f"Error: {workspace} is not a directory", file=sys.stderr) + sys.exit(1) + + runs = find_runs(workspace) + if not runs: + print(f"No runs found in {workspace}", file=sys.stderr) + sys.exit(1) + + skill_name = args.skill_name or workspace.name.replace("-workspace", "") + feedback_path = workspace / "feedback.json" + + previous: dict[str, dict] = {} + if args.previous_workspace: + previous = load_previous_iteration(args.previous_workspace.resolve()) + + benchmark_path = args.benchmark.resolve() if args.benchmark else None + benchmark = None + if benchmark_path and benchmark_path.exists(): + try: + benchmark = json.loads(benchmark_path.read_text()) + except (json.JSONDecodeError, OSError): + pass + + if args.static: + html = generate_html(runs, skill_name, previous, benchmark) + args.static.parent.mkdir(parents=True, exist_ok=True) + args.static.write_text(html) + print(f"\n Static viewer written to: {args.static}\n") + sys.exit(0) + + # Kill any existing process on the target port + port = args.port + _kill_port(port) + handler = partial(ReviewHandler, workspace, skill_name, feedback_path, previous, benchmark_path) + try: + server = HTTPServer(("127.0.0.1", port), handler) + except OSError: + # Port still in use after kill attempt — find a free one + server = HTTPServer(("127.0.0.1", 0), handler) + port = server.server_address[1] + + url = f"http://localhost:{port}" + print(f"\n Eval Viewer") + print(f" ─────────────────────────────────") + print(f" URL: {url}") + print(f" Workspace: {workspace}") + print(f" Feedback: {feedback_path}") + if previous: + print(f" Previous: {args.previous_workspace} ({len(previous)} runs)") + if benchmark_path: + print(f" Benchmark: {benchmark_path}") + print(f"\n Press Ctrl+C to stop.\n") + + webbrowser.open(url) + + try: + server.serve_forever() + except KeyboardInterrupt: + print("\nStopped.") + server.server_close() + + +if __name__ == "__main__": + main() diff --git a/lib/clacky/default_skills/skill-creator/eval-viewer/viewer.html b/lib/clacky/default_skills/skill-creator/eval-viewer/viewer.html new file mode 100644 index 0000000..f0cebe1 --- /dev/null +++ b/lib/clacky/default_skills/skill-creator/eval-viewer/viewer.html @@ -0,0 +1,1325 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + <title>Eval Review

Iter	Train	Test	Description	{html.escape(qinfo["query"])}	{html.escape(qinfo["query"])}
{iteration}	{train_correct}/{train_runs}	{test_correct}/{test_runs}	{html.escape(description)}	{icon}{triggers}/{runs}	{icon}{triggers}/{runs}

+ snippet = "" + snippet_match = block.match(%r{]*class="b_lineclamp[^"]*"[^>]*>(.*?)

}m) || + block.match(%r{]*class="b_caption"[^>]*>.*?]*>(.*?)

}m) + if snippet_match + snippet = snippet_match[1].gsub(/<[^>]+>/, "").strip + snippet = CGI.unescapeHTML(snippet) if snippet.include?("&") + end + + results << { title: title, url: url, snippet: snippet } + end + + results + end + + # Decode Bing's redirect URL: bing.com/ck/a?...&u=a1BASE64URL&ntb=1 + # The "u" param is "a1" prefix + base64-encoded real URL + private def decode_bing_url(url) + return url unless url.include?("bing.com/ck/") + + u_param = url.match(/[?&]u=([^&]+)/) + return url unless u_param + + encoded = u_param[1] + # Remove "a1" prefix then base64-decode + return url unless encoded.start_with?("a1") + + base64_part = encoded[2..] + # Bing uses URL-safe base64 without padding + padded = base64_part + "=" * ((4 - base64_part.length % 4) % 4) + decoded = Base64.urlsafe_decode64(padded) + decoded.force_encoding("UTF-8").valid_encoding? ? decoded : url + rescue StandardError + url + end + + # ── Shared HTTP helper ───────────────────────────────────────────────── + + USER_AGENTS = [ + "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36", + "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36", + "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36", + "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36", + "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36" + ].freeze + + # Shared browser-like GET request — no Accept-Encoding to avoid gzip/br + # detection tricks used by Bing. Supports redirect following. + private def http_get(url, accept_language: "en-US,en;q=0.9", follow_redirects: 0, referer: nil) + request = Net::HTTP::Get.new(url) + request["User-Agent"] = USER_AGENTS.sample + request["Accept"] = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8" + request["Accept-Language"] = accept_language + # Deliberately omit Accept-Encoding — sending gzip causes Bing to return + # a JS-only skeleton (~39KB) instead of the real HTML results (~120KB) + request["Sec-Fetch-Dest"] = "document" + request["Sec-Fetch-Mode"] = "navigate" + request["Sec-Fetch-Site"] = referer ? "same-origin" : "none" + request["Upgrade-Insecure-Requests"] = "1" + request["Referer"] = referer if referer + + response = Net::HTTP.start(url.hostname, url.port, + use_ssl: url.scheme == "https", + read_timeout: 8, + open_timeout: 5) { |http| http.request(request) } + + # Follow redirects (e.g. cn.bing.com redirects to www.bing.com for non-China IPs) + if follow_redirects > 0 && response.is_a?(Net::HTTPRedirection) + location = response["location"] + redirect_url = location.start_with?("http") ? URI(location) : URI("#{url.scheme}://#{url.hostname}#{location}") + return http_get(redirect_url, accept_language: accept_language, follow_redirects: follow_redirects - 1, referer: referer) + end + + response + end + + # ── Formatting ───────────────────────────────────────────────────────── + + def format_call(args) + query = args[:query] || args["query"] || "" + display_query = query.length > 40 ? "#{query[0..37]}..." : query + "web_search(\"#{display_query}\")" + end + + def format_result(result) + if result[:error] + "[Error] #{result[:error]}" + else + count = result[:count] || 0 + provider = result[:provider] ? " via #{result[:provider]}" : "" + "[OK] Found #{count} results#{provider}" + end + end + end + end +end diff --git a/lib/clacky/tools/write.rb b/lib/clacky/tools/write.rb new file mode 100644 index 0000000..f812160 --- /dev/null +++ b/lib/clacky/tools/write.rb @@ -0,0 +1,68 @@ +# frozen_string_literal: true + +module Clacky + module Tools + class Write < Base + self.tool_name = "write" + self.tool_description = "Write content to a file. Creates new files or overwrites existing ones." + self.tool_category = "file_system" + self.tool_parameters = { + type: "object", + properties: { + path: { + type: "string", + description: "The path of the file to write (absolute or relative)" + }, + content: { + type: "string", + description: "The content to write to the file" + } + }, + required: %w[path content] + } + + def execute(path:, content:, working_dir: nil) + # Validate path + if path.nil? || path.strip.empty? + return { error: "Path cannot be empty" } + end + + begin + # Expand ~ to home directory, resolve relative paths against working_dir + path = expand_path(path, working_dir: working_dir) + + # Ensure parent directory exists + dir = File.dirname(path) + FileUtils.mkdir_p(dir) unless Dir.exist?(dir) + + # Write content to file + File.write(path, content) + + { + path: File.expand_path(path), + bytes_written: content.bytesize, + error: nil + } + rescue Errno::EACCES => e + { error: "Permission denied: #{e.message}" } + rescue Errno::ENOSPC => e + { error: "No space left on device: #{e.message}" } + rescue StandardError => e + { error: "Failed to write file: #{e.message}" } + end + end + + def format_call(args) + path = args[:path] || args['path'] + "Write(#{Utils::PathHelper.safe_basename(path)})" + end + + def format_result(result) + return result[:error] if result[:error] + + bytes = result[:bytes_written] || result['bytes_written'] || 0 + "Written #{bytes} bytes" + end + end + end +end diff --git a/lib/clacky/ui2.rb b/lib/clacky/ui2.rb new file mode 100644 index 0000000..9e1b446 --- /dev/null +++ b/lib/clacky/ui2.rb @@ -0,0 +1,40 @@ +# frozen_string_literal: true + +# UI2 - MVC-based terminal UI system for Clacky +# Provides split-screen interface with scrollable output and fixed input + +require_relative "ui2/thinking_verbs" +require_relative "ui2/progress_indicator" +require_relative "ui2/terminal_detector" +require_relative "ui2/theme_manager" +require_relative "ui2/screen_buffer" +require_relative "ui2/layout_manager" +require_relative "ui2/view_renderer" +require_relative "ui2/ui_controller" + +require_relative "ui2/components/base_component" +require_relative "ui2/components/input_area" +require_relative "ui2/components/message_component" +require_relative "ui2/components/tool_component" +require_relative "ui2/components/common_component" +require_relative "ui2/components/welcome_banner" +require_relative "ui2/components/modal_component" + +module Clacky + module UI2 + # Version of the UI2 system + VERSION = "1.0.0" + + # Quick start: Create a UI controller and run + # @param config [Hash] Optional configuration (working_dir, mode, model) + # @example + # controller = Clacky::UI2::UIController.new + # controller.on_input { |input| puts "Got: #{input}" } + # controller.start + def self.start(config = {}, &block) + controller = UIController.new(config) + controller.on_input(&block) if block_given? + controller.start + end + end +end diff --git a/lib/clacky/ui2/block_font.rb b/lib/clacky/ui2/block_font.rb new file mode 100644 index 0000000..62a5af0 --- /dev/null +++ b/lib/clacky/ui2/block_font.rb @@ -0,0 +1,10 @@ +# frozen_string_literal: true + +require_relative "../block_font" + +module Clacky + module UI2 + # Alias for backward compatibility — BlockFont now lives at Clacky::BlockFont. + BlockFont = Clacky::BlockFont + end +end diff --git a/lib/clacky/ui2/components/base_component.rb b/lib/clacky/ui2/components/base_component.rb new file mode 100644 index 0000000..a598fa5 --- /dev/null +++ b/lib/clacky/ui2/components/base_component.rb @@ -0,0 +1,163 @@ +# frozen_string_literal: true + +require "pastel" + +module Clacky + module UI2 + module Components + # BaseComponent provides common functionality for all UI components + class BaseComponent + def initialize + @pastel = Pastel.new + end + + # Render component with given data + # @param data [Hash] Data to render + # @return [String] Rendered output + def render(data) + raise NotImplementedError, "Subclasses must implement render method" + end + + # Class method to render without instantiating + # @param data [Hash] Data to render + # @return [String] Rendered output + def self.render(data) + new.render(data) + end + + protected + + # Get current theme from ThemeManager + # @return [Themes::BaseTheme] Current theme instance + def theme + UI2::ThemeManager.current_theme + end + + # Format symbol with color from theme + # @param symbol_key [Symbol] Symbol key (e.g., :user, :assistant) + # @return [String] Colored symbol + def format_symbol(symbol_key) + theme.format_symbol(symbol_key) + end + + # Format text with color from theme + # @param text [String] Text to format + # @param symbol_key [Symbol] Symbol key for color lookup + # @return [String] Colored text + def format_text(text, symbol_key) + theme.format_text(text, symbol_key) + end + + # Truncate text to max length + # @param text [String] Text to truncate + # @param max_length [Integer] Maximum length + # @return [String] Truncated text + def truncate(text, max_length) + return "" if text.nil? || text.empty? + + cleaned = text.strip.gsub(/\s+/, ' ') + + if cleaned.length > max_length + cleaned[0...max_length] + "..." + else + cleaned + end + end + + # Wrap text to specified width + # @param text [String] Text to wrap + # @param width [Integer] Maximum width + # @return [Array] Array of wrapped lines + def wrap_text(text, width) + return [] if text.nil? || text.empty? + + words = text.split(/\s+/) + lines = [] + current_line = "" + + words.each do |word| + if current_line.empty? + current_line = word + elsif (current_line.length + word.length + 1) <= width + current_line += " #{word}" + else + lines << current_line + current_line = word + end + end + + lines << current_line unless current_line.empty? + lines + end + + # Format timestamp + # @param time [Time] Time object + # @return [String] Formatted timestamp + def format_timestamp(time = Time.now) + time.strftime("%H:%M:%S") + end + + # Create indented text + # @param text [String] Text to indent + # @param spaces [Integer] Number of spaces + # @return [String] Indented text + def indent(text, spaces = 2) + prefix = " " * spaces + text.split("\n").map { |line| "#{prefix}#{line}" }.join("\n") + end + + # Format key-value pair + # @param key [String] Key name + # @param value [String] Value + # @return [String] Formatted key-value + def format_key_value(key, value) + "#{@pastel.cyan(key)}: #{@pastel.white(value)}" + end + + # Create a separator line + # @param char [String] Character to use + # @param width [Integer] Width of separator + # @return [String] Separator line + def separator(char = "─", width = 80) + @pastel.dim(char * width) + end + + # Format list item + # @param text [String] Item text + # @param bullet [String] Bullet character + # @return [String] Formatted list item + def format_list_item(text, bullet = "•") + "#{@pastel.dim(bullet)} #{@pastel.white(text)}" + end + + # Format code block + # @param code [String] Code content + # @param language [String, nil] Language for syntax highlighting hint + # @return [String] Formatted code block + def format_code_block(code, language = nil) + header = language ? @pastel.dim("```#{language}") : @pastel.dim("```") + footer = @pastel.dim("```") + content = @pastel.cyan(code) + + "#{header}\n#{content}\n#{footer}" + end + + # Format progress bar + # @param current [Integer] Current value + # @param total [Integer] Total value + # @param width [Integer] Bar width + # @return [String] Progress bar + def format_progress_bar(current, total, width = 20) + return "" if total == 0 + + percentage = (current.to_f / total * 100).round(1) + filled = (current.to_f / total * width).round + empty = width - filled + + bar = @pastel.green("█" * filled) + @pastel.dim("░" * empty) + "#{bar} #{percentage}%" + end + end + end + end +end diff --git a/lib/clacky/ui2/components/command_suggestions.rb b/lib/clacky/ui2/components/command_suggestions.rb new file mode 100644 index 0000000..e489400 --- /dev/null +++ b/lib/clacky/ui2/components/command_suggestions.rb @@ -0,0 +1,291 @@ +# frozen_string_literal: true + +require "pastel" +require_relative "../theme_manager" + +module Clacky + module UI2 + module Components + # CommandSuggestions displays a dropdown menu of available commands + # Supports keyboard navigation and filtering + class CommandSuggestions + attr_reader :selected_index, :visible + + # System commands available by default + SYSTEM_COMMANDS = [ + { command: "/clear", description: "Clear chat history and restart session" }, + { command: "/config", description: "Open configuration (models, API keys, settings)" }, + { command: "/model", description: "Quickly switch the current model" }, + { command: "/undo", description: "Undo the last task and restore previous state" }, + { command: "/help", description: "Show help information" }, + { command: "/exit", description: "Exit the chat session" }, + { command: "/quit", description: "Quit the application" } + ].freeze + + def initialize + @pastel = Pastel.new + @commands = [] + @filtered_commands = [] + @selected_index = 0 + @visible = false + @filter_text = "" + @skill_commands = [] + + # Initialize with system commands + update_commands + end + + # Get current theme from ThemeManager + def theme + UI2::ThemeManager.current_theme + end + + # Load skill commands from skill loader, filtered by agent profile whitelist + # @param skill_loader [Clacky::SkillLoader] The skill loader instance + # @param agent_profile [Clacky::AgentProfile, nil] Current agent profile (nil = allow all) + def load_skill_commands(skill_loader, agent_profile = nil) + return unless skill_loader + + skills = skill_loader.user_invocable_skills + skills = skills.select { |s| s.allowed_for_agent?(agent_profile.name) } if agent_profile + + @skill_commands = skills.map do |skill| + { + command: skill.slash_command, + description: skill.description || "No description available", + type: :skill, + argument_hint: skill.argument_hint + } + end + + update_commands + end + + # Show the suggestions dropdown + # @param filter_text [String] Initial filter text (everything after the /) + def show(filter_text = "") + @filter_text = filter_text + @visible = true + update_filtered_commands + @selected_index = 0 + end + + # Hide the suggestions dropdown + def hide + @visible = false + @filter_text = "" + @filtered_commands = [] + @selected_index = 0 + end + + # Update filter text and refresh filtered commands + # @param text [String] Filter text (everything after the /) + def update_filter(text) + @filter_text = text + update_filtered_commands + @selected_index = 0 # Reset selection when filter changes + end + + # Move selection up + def select_previous + return if @filtered_commands.empty? + @selected_index = (@selected_index - 1) % @filtered_commands.size + end + + # Move selection down + def select_next + return if @filtered_commands.empty? + @selected_index = (@selected_index + 1) % @filtered_commands.size + end + + # Get the currently selected command + # @return [Hash, nil] Selected command hash or nil if none selected + def selected_command + return nil if @filtered_commands.empty? + @filtered_commands[@selected_index] + end + + # Get the currently selected command text + # @return [String, nil] Selected command text or nil if none selected + def selected_command_text + cmd = selected_command + cmd ? cmd[:command] : nil + end + + # Get the argument hint for the currently selected command + # @return [String, nil] Argument hint string or nil if none + def selected_argument_hint + cmd = selected_command + cmd ? cmd[:argument_hint] : nil + end + + # Check if there are any suggestions to show + # @return [Boolean] + def has_suggestions? + @visible && !@filtered_commands.empty? + end + + # Calculate required height for rendering + # @return [Integer] Number of lines needed + def required_height + return 0 unless @visible + return 0 if @filtered_commands.empty? + + # Header + commands + footer + 1 + [@filtered_commands.size, 5].min + 1 # Max 5 visible items + end + + # Render the suggestions dropdown + # @param row [Integer] Starting row position + # @param col [Integer] Starting column position + # @param width [Integer] Maximum width for the dropdown + # @return [String] Rendered output + def render(row:, col:, width: 60) + return "" unless @visible + return "" if @filtered_commands.empty? + + output = [] + max_items = 5 # Maximum visible items + + # Sliding window: keep selected item visible + start_idx = [@selected_index - max_items + 1, 0].max + start_idx = [start_idx, [@filtered_commands.size - max_items, 0].max].min + visible_commands = @filtered_commands[start_idx, max_items] || [] + + # Header + header = @pastel.dim("┌─ Commands ") + @pastel.dim("─" * (width - 13)) + @pastel.dim("┐") + output << position_cursor(row, col) + header + + # Items + visible_commands.each_with_index do |cmd, idx| + is_selected = (start_idx + idx == @selected_index) + line = render_command_item(cmd, is_selected, width) + output << position_cursor(row + 1 + idx, col) + line + end + + # Footer with navigation hint + footer_row = row + 1 + visible_commands.size + total = @filtered_commands.size + hint = total > max_items ? " (#{total - max_items} more...)" : "" + footer = @pastel.dim("└") + @pastel.dim("─" * (width - 2)) + @pastel.dim("┘") + output << position_cursor(footer_row, col) + footer + + output.join + end + + # Clear the rendered dropdown from screen + # @param row [Integer] Starting row position + # @param col [Integer] Starting column position + def clear_from_screen(row:, col:) + return unless @visible + + height = required_height + output = [] + + height.times do |i| + output << position_cursor(row + i, col) + clear_line + end + + print output.join + flush + end + + + # Update the complete commands list (system + skills) + private def update_commands + system_cmds = SYSTEM_COMMANDS.map { |c| c.merge(type: :system) } + @commands = system_cmds + @skill_commands + update_filtered_commands if @visible + end + + # Update filtered commands based on current filter text + private def update_filtered_commands + if @filter_text.empty? + @filtered_commands = @commands + else + filter_lower = @filter_text.downcase + @filtered_commands = @commands.select do |cmd| + # Remove leading / for comparison + cmd_name = cmd[:command].sub(/^\//, "") + # Only match command name, not description + cmd_name.downcase.start_with?(filter_lower) + end + end + end + + # Render a single command item + # @param cmd [Hash] Command hash with :command and :description + # @param selected [Boolean] Whether this item is selected + # @param width [Integer] Maximum width + # @return [String] Rendered item + private def render_command_item(cmd, selected, width) + # Calculate available space + available = width - 4 # Account for borders and padding + + # Format command (e.g., "/clear") + command_text = cmd[:command] + + # Format description + max_desc_length = available - command_text.length - 3 # 3 for spacing + description = truncate_text(cmd[:description], max_desc_length) + + # Build line + if selected + # Highlighted selection + line = @pastel.on_blue(@pastel.white(" #{command_text} ")) + line += @pastel.on_blue(@pastel.dim(" #{description}")) + # Pad to full width + content_length = command_text.length + description.length + 2 + padding = " " * [available - content_length, 0].max + line += @pastel.on_blue(padding) + @pastel.dim("│") + line + @pastel.dim("│") + else + # Normal item + line = " #{@pastel.cyan(command_text)} #{@pastel.dim(description)}" + # Pad to full width + content_length = strip_ansi(line).length + padding = " " * [available - content_length, 0].max + @pastel.dim("│") + line + padding + @pastel.dim("│") + end + end + + # Truncate text to maximum length + # @param text [String] Text to truncate + # @param max_length [Integer] Maximum length + # @return [String] Truncated text + private def truncate_text(text, max_length) + return "" if max_length <= 3 + return text if text.length <= max_length + + text[0...(max_length - 3)] + "..." + end + + # Strip ANSI codes from text + # @param text [String] Text with ANSI codes + # @return [String] Plain text + private def strip_ansi(text) + text.gsub(/\e\[[0-9;]*m/, '') + end + + # Position cursor at specific row and column + # @param row [Integer] Row position (0-indexed) + # @param col [Integer] Column position (0-indexed) + # @return [String] ANSI escape sequence + private def position_cursor(row, col) + "\e[#{row + 1};#{col + 1}H" + end + + # Clear current line + # @return [String] ANSI escape sequence + private def clear_line + "\e[2K" + end + + # Flush output to terminal + private def flush + $stdout.flush + end + end + end + end +end diff --git a/lib/clacky/ui2/components/common_component.rb b/lib/clacky/ui2/components/common_component.rb new file mode 100644 index 0000000..59e1d90 --- /dev/null +++ b/lib/clacky/ui2/components/common_component.rb @@ -0,0 +1,98 @@ +# frozen_string_literal: true + +require_relative "base_component" + +module Clacky + module UI2 + module Components + # CommonComponent renders common UI elements (progress, success, error, warning) + class CommonComponent < BaseComponent + # Render thinking indicator + # @return [String] Thinking indicator + def render_thinking + symbol = format_symbol(:thinking) + text = format_text("Thinking...", :thinking) + "#{symbol} #{text}" + end + + # Render progress indicator (stopped state, gray) + # @param message [String] Progress message + # @return [String] Progress indicator + def render_progress(message) + symbol = format_symbol(:thinking) + text = format_text(message, :thinking) + "#{symbol} #{text}" + end + + # Render working indicator (active state, yellow) + # @param message [String] Progress message + # @return [String] Working indicator + def render_working(message) + symbol = format_symbol(:working) + text = format_text(message, :working) + "#{symbol} #{text}" + end + + # Render success message + # @param message [String] Success message + # @return [String] Success message + def render_success(message) + symbol = format_symbol(:success) + text = format_text(message, :success) + "#{symbol} #{text}" + end + + # Render error message + # @param message [String] Error message + # @return [String] Error message + def render_error(message) + symbol = format_symbol(:error) + text = format_text(message, :error) + "#{symbol} #{text}" + end + + # Render warning message + # @param message [String] Warning message + # @return [String] Warning message + def render_warning(message) + symbol = format_symbol(:warning) + text = format_text(message, :warning) + "#{symbol} #{text}" + end + + # Render task completion summary + # @param iterations [Integer] Number of iterations + # @param cost [Float] Cost in USD + # @param duration [Float] Duration in seconds + # @param cache_tokens [Integer] Cache read tokens + # @param cache_requests [Integer] Total cache requests count + # @param cache_hits [Integer] Cache hit requests count + # @return [String] Formatted completion summary + def render_task_complete(iterations:, cost:, duration: nil, cache_tokens: nil, cache_requests: nil, cache_hits: nil) + lines = [] + lines << "" + lines << @pastel.dim("─" * 60) + lines << render_success("Task Complete") + lines << "" + + # Display each stat on a separate line + lines << " Iterations: #{iterations}" + lines << " Cost: $#{cost.round(4)}" + lines << " Duration: #{duration.round(1)}s" if duration + + # Display cache information if available + if cache_tokens && cache_tokens > 0 + lines << " Cache Tokens: #{cache_tokens} tokens" + end + + if cache_requests && cache_requests > 0 + hit_rate = cache_hits > 0 ? ((cache_hits.to_f / cache_requests) * 100).round(1) : 0 + lines << " Cache Requests: #{cache_requests} (#{cache_hits} hits, #{hit_rate}% hit rate)" + end + + lines.join("\n") + end + end + end + end +end diff --git a/lib/clacky/ui2/components/inline_input.rb b/lib/clacky/ui2/components/inline_input.rb new file mode 100644 index 0000000..abe7214 --- /dev/null +++ b/lib/clacky/ui2/components/inline_input.rb @@ -0,0 +1,226 @@ +# frozen_string_literal: true + +require_relative "../line_editor" + +module Clacky + module UI2 + module Components + # InlineInput provides inline input for confirmations and simple prompts + # Renders at the end of output area, not at fixed bottom position + class InlineInput + include LineEditor + + attr_reader :prompt, :default_value + + def initialize(prompt: "", default: nil) + initialize_line_editor + @prompt = prompt + @default_value = default + @active = false + @result_queue = nil + @paste_counter = 0 + @paste_placeholders = {} + @continuation_prompt = "> " # Continuation prompt for wrapped lines + end + + # Activate inline input and wait for user input + # @return [String] User input + def collect + @active = true + @result_queue = Queue.new + # Don't set default as initial text - start empty + @result_queue.pop + end + + # Check if active + def active? + @active + end + + # Handle keyboard input + # @param key [Symbol, String] Key input + # @return [Hash] Result with action + def handle_key(key) + return { action: nil } unless @active + + case key + when Hash + if key[:type] == :rapid_input + # Handle multi-line paste with placeholder + pasted_text = key[:text] + pasted_lines = pasted_text.split(/\r\n|\r|\n/) + + if pasted_lines.size > 1 + # Multi-line paste - use placeholder + @paste_counter += 1 + placeholder = "[##{@paste_counter} Paste Text]" + @paste_placeholders[placeholder] = pasted_text + insert_text(placeholder) + else + # Single line - insert directly + insert_text(pasted_text) + end + end + { action: :update } + when :enter + handle_enter + when :backspace + backspace + { action: :update } + when :delete + delete_char + { action: :update } + when :left_arrow, :ctrl_b + cursor_left + { action: :update } + when :right_arrow, :ctrl_f + cursor_right + { action: :update } + when :home, :ctrl_a + cursor_home + { action: :update } + when :end, :ctrl_e + cursor_end + { action: :update } + when :ctrl_k + kill_to_end + { action: :update } + when :ctrl_u + kill_to_start + { action: :update } + when :ctrl_w + kill_word + { action: :update } + when :shift_tab + handle_shift_tab + when :ctrl_o + handle_toggle_expand + when :ctrl_c + handle_cancel + when :escape + handle_cancel + else + if key.is_a?(String) && key.length >= 1 && key.ord >= 32 + insert_char(key) + { action: :update } + else + { action: nil } + end + end + end + + # Render inline input with prompt and cursor + # @return [String] Rendered line (may wrap to multiple lines) + def render + width = TTY::Screen.width + # Use effective content width (respecting MAX_CONTENT_WIDTH_RATIO) + content_width = effective_content_width(width) + prompt_width = calculate_display_width(strip_ansi_codes(@prompt)) + available_width = content_width - prompt_width + + # Get wrapped segments + wrapped_segments = wrap_line(@line, available_width) + + # Build rendered output with cursor + output = "" + + wrapped_segments.each_with_index do |segment, idx| + prefix = if idx == 0 + @prompt + else + "> " # Continuation prompt indicator + end + + # Render segment with cursor if needed + segment_text = render_line_segment_with_cursor(@line, segment[:start], segment[:end]) + + output += "#{prefix}#{segment_text}" + output += "\n" unless idx == wrapped_segments.size - 1 + end + + output + end + + # Get cursor column position + # @return [Integer] Column position + def cursor_col + cursor_column(@prompt) + end + + # Get cursor position for display (considering line wrapping and continuation prompt) + # @param width [Integer] Terminal width + # @return [Array] Row and column position (0-indexed) + def cursor_position_for_display(width = TTY::Screen.width) + # Use effective content width (respecting MAX_CONTENT_WIDTH_RATIO) + content_width = effective_content_width(width) + cursor_position_with_wrap(@prompt, content_width, @continuation_prompt) + end + + # Get the number of lines this input will occupy when rendered + # @param width [Integer] Terminal width + # @return [Integer] Number of lines + def line_count(width = TTY::Screen.width) + # Use effective content width (respecting MAX_CONTENT_WIDTH_RATIO) + content_width = effective_content_width(width) + prompt_width = calculate_display_width(strip_ansi_codes(@prompt)) + available_width = content_width - prompt_width + return 1 if available_width <= 0 + + segments = wrap_line(@line, available_width) + segments.size + end + + # Deactivate inline input + def deactivate + @active = false + @result_queue = nil + end + + + def handle_enter + result = expand_placeholders(current_line) + # If empty and has default, use default + result = @default_value.to_s if result.empty? && @default_value + + queue = @result_queue + deactivate + queue&.push(result) + + { action: :submit, result: result } + end + + def expand_placeholders(text) + super(text, @paste_placeholders) + end + + def handle_cancel + queue = @result_queue + deactivate + queue&.push(nil) + + { action: :cancel } + end + + def handle_shift_tab + # Auto-confirm as yes (or use default if it's true) + result = if @default_value == true || @default_value.to_s.downcase == "yes" + @default_value.to_s + else + "yes" + end + + queue = @result_queue + deactivate + queue&.push(result) + + { action: :toggle_mode } + end + + private def handle_toggle_expand + # Toggle expansion of diff display + { action: :toggle_expand } + end + end + end + end +end diff --git a/lib/clacky/ui2/components/input_area.rb b/lib/clacky/ui2/components/input_area.rb new file mode 100644 index 0000000..6c14f79 --- /dev/null +++ b/lib/clacky/ui2/components/input_area.rb @@ -0,0 +1,1336 @@ +# frozen_string_literal: true + +require "pastel" +require "tempfile" +require_relative "../theme_manager" +require_relative "../line_editor" +require_relative "command_suggestions" +require_relative "../../utils/encoding" + +module Clacky + module UI2 + module Components + # InputArea manages the fixed input area at the bottom of the screen + # Enhanced with multi-line support, image paste, and more + class InputArea + include LineEditor + + # User tips pool - can be extended with more tips over time + USER_TIPS = [ + "Shift+Tab to toggle permission mode (confirm_safes ⇄ auto_approve)", + "Ctrl+C to interrupt AI execution or clear input", + "Shift+Enter to create multi-line input", + "Ctrl+V to paste images (supports up to 3 images)", + "Ctrl+D to delete pasted images", + "Use /clear to restart session, /help for commands" + ].freeze + + attr_accessor :row + attr_reader :cursor_position, :line_index, :files, :tips_message, :tips_type + + def initialize(row: 0) + @row = row + @lines = [""] + @line_index = 0 + @cursor_position = 0 + @history = [] + @history_index = -1 + @pastel = Pastel.new + @width = TTY::Screen.width + + @files = [] + @paste_counter = 0 + @paste_placeholders = {} + @last_ctrl_c_time = nil + @tips_message = nil + @tips_type = :info + @tips_timer = nil + @last_render_row = nil + + # User tip (usage suggestion) - separate from system tips + @user_tip = nil + @user_tip_timer = nil + @user_tip_count = 0 + + # Paused state - when InlineInput is active + @paused = false + + # Session bar info + @sessionbar_info = { + session_id: nil, # Full session id; rendered as first 8 chars (parity with WebUI) + working_dir: nil, + mode: nil, + model: nil, + tasks: 0, + cost: 0.0, + cost_source: nil, # nil / :api / :price / :default — :default means pricing unknown, show N/A + status: 'idle' # Workspace status: 'idle' or 'working' + } + + # Animation state for working status + @animation_frame = 0 + @last_animation_update = Time.now + @working_frames = ["❄", "❅", "❆"] + + # Command suggestions dropdown + @command_suggestions = CommandSuggestions.new + @skill_loader = nil # Will be set via set_skill_loader method + end + + # Get current theme from ThemeManager + def theme + UI2::ThemeManager.current_theme + end + + # Get prompt symbol from theme + def prompt + "#{theme.symbol(:user)} " + end + + def required_height + # When paused (InlineInput active), don't take up any space + return 0 if @paused + + height = 0 + + # Session bar - calculate actual wrapped height + height += calculate_sessionbar_height + + # Separator after session bar + height += 1 + + # Images + height += @files.size + + # Calculate height considering wrapped lines + # Use effective content width (respecting MAX_CONTENT_WIDTH_RATIO) + content_width = effective_content_width(@width) + @lines.each_with_index do |line, idx| + prefix = if idx == 0 + prompt + else + " " * prompt.length + end + prefix_width = calculate_display_width(strip_ansi_codes(prefix)) + available_width = [content_width - prefix_width, 20].max # At least 20 chars + wrapped_segments = wrap_line(line, available_width) + height += wrapped_segments.size + end + + # Bottom separator + height += 1 + + # Command suggestions (rendered above input) + height += @command_suggestions.required_height if @command_suggestions + + # Tips and user tips + height += 1 if @tips_message + height += 1 if @user_tip + + height + end + + # Set skill loader for command suggestions + # @param skill_loader [Clacky::SkillLoader] The skill loader instance + # @param agent_profile [Clacky::AgentProfile, nil] Current agent profile for skill filtering + def set_skill_loader(skill_loader, agent_profile = nil) + @skill_loader = skill_loader + @command_suggestions.load_skill_commands(skill_loader, agent_profile) if skill_loader + end + + # Update session bar info + # @param session_id [String] Full session id (rendered as first 8 chars) + # @param working_dir [String] Working directory + # @param mode [String] Permission mode + # @param model [String] AI model name + # @param tasks [Integer] Number of completed tasks + # @param cost [Float] Total cost + # @param cost_source [Symbol, nil] :api / :price / :default — :default renders as N/A + # @param status [String] Workspace status ('idle' or 'working') + def update_sessionbar(session_id: nil, working_dir: nil, mode: nil, model: nil, tasks: nil, cost: nil, cost_source: nil, status: nil) + @sessionbar_info[:session_id] = session_id if session_id + @sessionbar_info[:working_dir] = working_dir if working_dir + @sessionbar_info[:mode] = mode if mode + @sessionbar_info[:model] = model if model + @sessionbar_info[:tasks] = tasks if tasks + @sessionbar_info[:cost] = cost if cost + @sessionbar_info[:cost_source] = cost_source if cost_source + @sessionbar_info[:status] = status if status + end + + def input_buffer + @lines.join("\n") + end + + def handle_key(key) + # Ignore input when paused (InlineInput is active) + return { action: nil } if @paused + + old_height = required_height + + # Handle command suggestions navigation first if visible + if @command_suggestions.visible + case key + when :up_arrow + @command_suggestions.select_previous + return { action: nil } + when :down_arrow + @command_suggestions.select_next + return { action: nil } + when :enter + # Accept selected command and submit immediately + if @command_suggestions.has_suggestions? + selected = @command_suggestions.selected_command_text + if selected + # Replace current input with selected command + @lines = [selected] + @line_index = 0 + @cursor_position = selected.length + @command_suggestions.hide + # Submit the command immediately + return handle_enter + end + end + # Fall through to normal enter handling if no suggestion + when :escape + @command_suggestions.hide + return { action: nil } + when :tab + # Tab accepts the currently highlighted suggestion + if @command_suggestions.has_suggestions? + selected = @command_suggestions.selected_command_text + if selected + hint = @command_suggestions.selected_argument_hint + completed = "#{selected} " + @lines = [completed] + @line_index = 0 + @cursor_position = completed.length + @command_suggestions.hide + # Show argument hint as a tip if available + set_tips("Usage: #{selected} #{hint}", type: :info) if hint && !hint.empty? + return { action: nil } + end + end + end + end + + # Tab with no visible suggestions: trigger slash-command completion + if key == :tab + trigger_tab_completion + return { action: nil } + end + + result = case key + when Hash + if key[:type] == :rapid_input + insert_text(key[:text]) + clear_tips + update_command_suggestions + end + { action: nil } + when :enter then handle_enter + when :newline then newline; { action: nil } + when :backspace + backspace + update_command_suggestions + { action: nil } + when :delete + delete_char + update_command_suggestions + { action: nil } + when :left_arrow, :ctrl_b then cursor_left; { action: nil } + when :right_arrow, :ctrl_f then cursor_right; { action: nil } + when :up_arrow then handle_up_arrow + when :down_arrow then handle_down_arrow + when :home, :ctrl_a then cursor_home; { action: nil } + when :end, :ctrl_e then cursor_end; { action: nil } + when :ctrl_k then kill_to_end; { action: nil } + when :ctrl_u then kill_to_start; { action: nil } + when :ctrl_w then kill_word; { action: nil } + when :ctrl_c then handle_ctrl_c + when :ctrl_d then handle_ctrl_d + when :ctrl_v then handle_paste + when :ctrl_o then { action: :toggle_expand } + when :shift_tab then { action: :toggle_mode } + when :escape + if @command_suggestions.visible + @command_suggestions.hide + { action: nil } + else + # Trigger time machine when ESC is pressed and suggestions not visible + { action: :time_machine } + end + else + if key.is_a?(String) && key.length >= 1 && key.ord >= 32 + insert_char(key) + update_command_suggestions + end + { action: nil } + end + + new_height = required_height + if new_height != old_height + result[:height_changed] = true + result[:new_height] = new_height + end + + result + end + + def render(start_row:, width: nil) + @width = width || TTY::Screen.width + @last_render_row = start_row # Save for tips auto-clear + + # When paused, don't render anything (InlineInput is active) + return if @paused + + current_row = start_row + + # Session bar at top + render_sessionbar(current_row) + current_row += 1 + + # Separator after session bar + render_separator(current_row) + current_row += 1 + + # Files (images / documents) + @files.each_with_index do |f, idx| + move_cursor(current_row, 0) + filename = f[:name] || f["name"] || "file" + size = f[:size] || f["size"] + size_str = size ? " #{format_filesize(size)}" : "" + content = @pastel.dim("[File #{idx + 1}] #{filename}#{size_str} (Ctrl+D to delete)") + print_with_padding(content) + current_row += 1 + end + + # Input lines with auto-wrap support + current_row = render_input_lines(current_row) + + # Bottom separator + render_separator(current_row) + current_row += 1 + + # Command suggestions (rendered above tips) + if @command_suggestions && @command_suggestions.visible + # Render suggestions at current row + print @command_suggestions.render(row: current_row, col: 0, width: [@width - 4, 60].min) + current_row += @command_suggestions.required_height + end + + # Tips bar (if any) + if @tips_message + move_cursor(current_row, 0) + content = format_tips(@tips_message, @tips_type) + print_with_padding(content) + current_row += 1 + end + + # User tip (if any) + if @user_tip + move_cursor(current_row, 0) + content = format_user_tip(@user_tip) + print_with_padding(content) + current_row += 1 + end + + # Position cursor at current edit position + position_cursor(start_row) + flush + end + + def position_cursor(start_row) + # Calculate which wrapped line the cursor is on + cursor_row = start_row + 2 + @files.size # session_bar + separator + images + # Use effective content width (respecting MAX_CONTENT_WIDTH_RATIO) + content_width = effective_content_width(@width) + + # Add rows for lines before current line + @lines[0...@line_index].each_with_index do |line, idx| + prefix = if idx == 0 + prompt + else + " " * prompt.length + end + prefix_width = calculate_display_width(strip_ansi_codes(prefix)) + available_width = [content_width - prefix_width, 20].max + wrapped_segments = wrap_line(line, available_width) + cursor_row += wrapped_segments.size + end + + # Find which wrapped segment of current line contains cursor + current = current_line + prefix = if @line_index == 0 + prompt + else + " " * prompt.length + end + prefix_width = calculate_display_width(strip_ansi_codes(prefix)) + available_width = [content_width - prefix_width, 20].max + wrapped_segments = wrap_line(current, available_width) + + # Find cursor segment and position within segment + cursor_segment_idx = 0 + cursor_pos_in_segment = @cursor_position + + wrapped_segments.each_with_index do |segment, idx| + if @cursor_position >= segment[:start] && @cursor_position < segment[:end] + cursor_segment_idx = idx + cursor_pos_in_segment = @cursor_position - segment[:start] + break + elsif @cursor_position >= segment[:end] && idx == wrapped_segments.size - 1 + # Cursor at very end + cursor_segment_idx = idx + cursor_pos_in_segment = segment[:end] - segment[:start] + break + end + end + + cursor_row += cursor_segment_idx + + # Calculate display width of text before cursor in this segment + chars = current.chars + segment_start = wrapped_segments[cursor_segment_idx][:start] + text_in_segment_before_cursor = chars[segment_start...(segment_start + cursor_pos_in_segment)].join + display_width = calculate_display_width(text_in_segment_before_cursor) + + cursor_col = prefix_width + display_width + move_cursor(cursor_row, cursor_col) + end + + def set_tips(message, type: :info) + # Cancel existing timer if any + if @tips_timer&.alive? + @tips_timer.kill + end + + @tips_message = message + @tips_type = type + + # Auto-clear tips after 2 seconds + @tips_timer = Thread.new do + sleep 2 + # Clear tips from state and screen + @tips_message = nil + # Tips row: start_row + session_bar(1) + separator(1) + images + lines + separator(1) + tips_row = @last_render_row + 2 + @files.size + @lines.size + 1 + move_cursor(tips_row, 0) + clear_line + flush + end + end + + def clear_tips + # Cancel timer if any + if @tips_timer&.alive? + @tips_timer.kill + end + @tips_message = nil + end + + # Show a random user tip with probability and auto-rotation (max 3 tips) + # @param probability [Float] Probability of showing tip (0.0 to 1.0, default: 0.4) + # @param rotation_interval [Integer] Seconds between tip rotation (default: 12) + # @param max_tips [Integer] Maximum number of tips to show before stopping (default: 3) + def show_user_tip(probability: 0.4, rotation_interval: 12, max_tips: 3) + # Random chance to show tip + return unless rand < probability + + # Stop existing timer if any + stop_user_tip_timer + + # Reset counter and pick first random tip + @user_tip_count = 1 + @user_tip = USER_TIPS.sample + + # Start rotation timer (will show max_tips total) + @user_tip_timer = Thread.new do + while @user_tip_count < max_tips + sleep rotation_interval + @user_tip_count += 1 + + # Pick a different tip + old_tip = @user_tip + loop do + @user_tip = USER_TIPS.sample + break if @user_tip != old_tip || USER_TIPS.size == 1 + end + end + + # After showing max_tips, wait then clear + sleep rotation_interval + @user_tip = nil + @user_tip_count = 0 + rescue => e + # Silently handle thread errors + end + end + + # Clear user tip and stop rotation + def clear_user_tip + stop_user_tip_timer + @user_tip = nil + @user_tip_count = 0 + end + + private def stop_user_tip_timer + if @user_tip_timer&.alive? + @user_tip_timer.kill + @user_tip_timer = nil + end + end + + # Pause input area (when InlineInput is active) + def pause + @paused = true + end + + # Resume input area (when InlineInput is done) + def resume + @paused = false + end + + # Check if paused + def paused? + @paused + end + + def current_content + text = expand_placeholders(@lines.join("\n")) + + # If both text and images are empty, return empty string + return "" if text.empty? && @files.empty? + + # Format user input with color and spacing from theme + symbol = theme.format_symbol(:user) + content = theme.format_text(text, :user) + + result = "\n#{symbol} #{content}\n" + + # Append file information if present + if @files.any? + @files.each_with_index do |f, idx| + filename = f[:name] || f["name"] || "file" + result += @pastel.dim(" [File #{idx + 1}] #{filename}") + "\n" + end + end + + result + end + + def current_value + expand_placeholders(@lines.join("\n")) + end + + def empty? + @lines.all?(&:empty?) && @files.empty? + end + + def multiline? + @lines.size > 1 + end + + def has_images? + @files.any? + end + + def set_prompt(prompt) + prompt = prompt + end + + # --- Public editing methods --- + + def insert_char(char) + chars = current_line.chars + chars.insert(@cursor_position, char) + @lines[@line_index] = chars.join + @cursor_position += 1 + end + + def backspace + if @cursor_position > 0 + chars = current_line.chars + chars.delete_at(@cursor_position - 1) + @lines[@line_index] = chars.join + @cursor_position -= 1 + elsif @line_index > 0 + prev_line = @lines[@line_index - 1] + current = @lines[@line_index] + @lines.delete_at(@line_index) + @line_index -= 1 + @cursor_position = prev_line.chars.length + @lines[@line_index] = prev_line + current + end + end + + def delete_char + chars = current_line.chars + return if @cursor_position >= chars.length + chars.delete_at(@cursor_position) + @lines[@line_index] = chars.join + end + + def cursor_left + @cursor_position = [@cursor_position - 1, 0].max + end + + def cursor_right + @cursor_position = [@cursor_position + 1, current_line.chars.length].min + end + + def cursor_home + @cursor_position = 0 + end + + def cursor_end + @cursor_position = current_line.chars.length + end + + def clear + @lines = [""] + @line_index = 0 + @cursor_position = 0 + @history_index = -1 + @files = [] + @paste_counter = 0 + @paste_placeholders = {} + clear_tips + @command_suggestions.hide if @command_suggestions + end + + def submit + text = current_value + files = @files.dup + add_to_history(text) unless text.empty? + clear + { text: text, files: files } + end + + def history_prev + return if @history.empty? + if @history_index == -1 + @history_index = @history.size - 1 + else + @history_index = [@history_index - 1, 0].max + end + load_history_entry + end + + def history_next + return if @history_index == -1 + @history_index += 1 + if @history_index >= @history.size + @history_index = -1 + @lines = [""] + @line_index = 0 + @cursor_position = 0 + else + load_history_entry + end + end + + + # Update command suggestions based on current input + # Shows suggestions when input starts with / + private def update_command_suggestions + return unless @command_suggestions + + current = current_line.strip + + # Check if we should show suggestions (input starts with /) + if current.start_with?('/') && @line_index == 0 + # Extract the filter text (everything after /) + filter_text = current[1..-1] || "" + @command_suggestions.show(filter_text) + else + @command_suggestions.hide + end + end + + # Trigger tab completion: show all commands or filter by current slash input + # Called when Tab is pressed and no suggestions dropdown is visible + private def trigger_tab_completion + return unless @command_suggestions + + current = current_line.strip + + if current.empty? + # Empty input: type "/" and show all commands + insert_char("/") + @command_suggestions.show("") + elsif current.start_with?("/") + # Already typing a slash command: show/refresh filtered suggestions + filter_text = current[1..-1] || "" + @command_suggestions.show(filter_text) + end + # Tab on normal text has no effect + end + + # Render all input lines with auto-wrap support + # @param start_row [Integer] Starting row position + # @return [Integer] Next available row after rendering all lines + def render_input_lines(start_row) + current_row = start_row + # Use effective content width (respecting MAX_CONTENT_WIDTH_RATIO) + content_width = effective_content_width(@width) + + @lines.each_with_index do |line, line_idx| + prefix = calculate_line_prefix(line_idx) + prefix_width = calculate_display_width(strip_ansi_codes(prefix)) + available_width = content_width - prefix_width + wrapped_segments = wrap_line(line, available_width) + + wrapped_segments.each_with_index do |segment_info, wrap_idx| + content = render_line_segment(line, line_idx, segment_info, wrap_idx, prefix, prefix_width) + move_cursor(current_row, 0) + print_with_padding(content) + current_row += 1 + end + end + + current_row + end + + # Calculate the prefix (prompt or indent) for a given line index + # @param line_idx [Integer] Index of the line + # @return [String] Prefix string (with formatting) + private def calculate_line_prefix(line_idx) + if line_idx == 0 + theme.format_symbol(:user) + " " + else + " " * prompt.length + end + end + + # Render a single segment of a line (handling cursor and wrapping) + # @param line [String] Full line text + # @param line_idx [Integer] Index of the line in @lines + # @param segment_info [Hash] Segment information from wrap_line + # @param wrap_idx [Integer] Index of this segment in wrapped segments + # @param prefix [String] Line prefix (prompt or indent) + # @param prefix_width [Integer] Display width of the prefix + # @return [String] Formatted content for this segment + private def render_line_segment(line, line_idx, segment_info, wrap_idx, prefix, prefix_width) + segment_text = segment_info[:text] + segment_start = segment_info[:start] + segment_end = segment_info[:end] + + is_current_line = (line_idx == @line_index) + is_first_segment = (wrap_idx == 0) + + # Determine the line prefix + line_prefix = if is_first_segment + prefix + else + " " * prefix_width # Continuation indent + end + + # Render the segment content (with or without cursor) + segment_content = if is_current_line + render_line_segment_with_cursor(line, segment_start, segment_end) + else + theme.format_text(segment_text, :user) + end + + "#{line_prefix}#{segment_content}" + end + + # Wrap a line into multiple segments based on available width + # Considers display width of characters (multi-byte characters like Chinese) + # @param line [String] The line to wrap + # @param max_width [Integer] Maximum display width per wrapped line + # @return [Array] Array of segment info: { text: String, start: Integer, end: Integer } + def wrap_line(line, max_width) + super(line, max_width) + end + + # Calculate display width of a single character + # @param char [String] Single character + # @return [Integer] Display width (1 or 2) + def char_display_width(char) + super(char) + end + + # Strip ANSI escape codes from a string + # @param text [String] Text with ANSI codes + # @return [String] Text without ANSI codes + def strip_ansi_codes(text) + text.gsub(/\e\[[0-9;]*m/, '') + end + + # Print content and pad with spaces to clear any remaining characters from previous render + # This avoids flickering from clear_line while ensuring old content is erased + def print_with_padding(content) + # Calculate visible width (strip ANSI codes for width calculation) + visible_content = content.gsub(/\e\[[0-9;]*m/, '') + visible_width = calculate_display_width(visible_content) + + # IMPORTANT: If content exceeds screen width, truncate to prevent terminal auto-wrap + if visible_width > @width + # Content too long - truncate to fit (loses ANSI colors but prevents wrapping) + truncate_at = 0 + current_width = 0 + visible_content.each_char.with_index do |char, idx| + char_width = char_display_width(char) + break if current_width + char_width + 3 > @width # Reserve 3 for "..." + current_width += char_width + truncate_at = idx + 1 + end + print visible_content[0...truncate_at] + print "..." + # Pad remaining + remaining = @width - current_width - 3 + print " " * remaining if remaining > 0 + else + # Content fits - print normally + print content + # Pad with spaces if needed to clear old content + remaining = @width - visible_width + print " " * remaining if remaining > 0 + end + end + + def handle_enter + text = current_value.strip + + # Prepare display content and data BEFORE clearing + content_to_display = current_content + result_text = current_value + result_files = @files.dup + + # Handle commands (with or without slash) + if text.start_with?('/') + # Check if it's a command (single slash followed by English letters only) + # Paths like /xxx/xxxx should not be treated as commands + if text =~ /^\/([a-zA-Z-]+)$/ + case text + when '/clear' + add_to_history(result_text) unless result_text.empty? + clear + return { action: :clear_output, data: { text: result_text, files: result_files, display: content_to_display } } + when '/help' + add_to_history(result_text) unless result_text.empty? + clear + return { action: :help, data: { text: result_text, files: result_files, display: content_to_display } } + when '/exit', '/quit' + return { action: :exit } + else + # Let other commands (like skills) pass through to agent + # Fall through to submit + end + end + # If it's not a command pattern (e.g., /xxx/xxxx), treat as normal input + elsif text == '?' + add_to_history(result_text) unless result_text.empty? + clear + return { action: :help, data: { text: result_text, files: result_files, display: content_to_display } } + elsif text == 'exit' || text == 'quit' + return { action: :exit } + end + + if text.empty? && @files.empty? + return { action: nil } + end + + add_to_history(result_text) unless result_text.empty? + clear + + { action: :submit, data: { text: result_text, files: result_files, display: content_to_display } } + end + + def handle_up_arrow + if multiline? + unless cursor_up + history_prev + end + else + # Navigate history when single line (empty or not) + history_prev + end + { action: nil } + end + + def handle_down_arrow + if multiline? + unless cursor_down + history_next + end + else + # Navigate history when single line (empty or not) + history_next + end + { action: nil } + end + + def handle_ctrl_c + { action: :interrupt } + end + + def handle_ctrl_d + if has_images? + if @files.size == 1 + @files.clear + else + @files.shift + end + clear_tips + { action: nil } + elsif empty? + { action: :exit } + else + { action: nil } + end + end + + def handle_paste + pasted = paste_from_clipboard + if pasted[:type] == :image + path = pasted[:path] + mime_type = pasted[:mime_type] || "image/png" + size = File.exist?(path) ? File.size(path) : 0 + @files << { name: File.basename(path), mime_type: mime_type, path: path, size: size } + clear_tips + else + insert_text(pasted[:text]) + clear_tips + end + { action: nil } + end + + def insert_text(text) + return if text.nil? || text.empty? + + text_lines = text.split(/\r\n|\r|\n/) + + if text_lines.size > 1 + @paste_counter += 1 + placeholder = "[##{@paste_counter} Paste Text]" + @paste_placeholders[placeholder] = text + + chars = current_line.chars + chars.insert(@cursor_position, *placeholder.chars) + @lines[@line_index] = chars.join + @cursor_position += placeholder.length + else + chars = current_line.chars + text.chars.each_with_index do |c, i| + chars.insert(@cursor_position + i, c) + end + @lines[@line_index] = chars.join + @cursor_position += text.length + end + end + + def newline + chars = current_line.chars + @lines[@line_index] = chars[0...@cursor_position].join + @lines.insert(@line_index + 1, chars[@cursor_position..-1]&.join || "") + @line_index += 1 + @cursor_position = 0 + end + + def cursor_up + return false if @line_index == 0 + @line_index -= 1 + @cursor_position = [@cursor_position, current_line.chars.length].min + true + end + + def cursor_down + return false if @line_index >= @lines.size - 1 + @line_index += 1 + @cursor_position = [@cursor_position, current_line.chars.length].min + true + end + + def kill_to_end + chars = current_line.chars + @lines[@line_index] = chars[0...@cursor_position].join + end + + def kill_to_start + chars = current_line.chars + @lines[@line_index] = chars[@cursor_position..-1]&.join || "" + @cursor_position = 0 + end + + def kill_word + chars = current_line.chars + pos = @cursor_position - 1 + + while pos >= 0 && chars[pos] =~ /\s/ + pos -= 1 + end + while pos >= 0 && chars[pos] =~ /\S/ + pos -= 1 + end + + delete_start = pos + 1 + chars.slice!(delete_start...@cursor_position) + @lines[@line_index] = chars.join + @cursor_position = delete_start + end + + def load_history_entry + return unless @history_index >= 0 && @history_index < @history.size + entry = @history[@history_index] + @lines = entry.split("\n") + @lines = [""] if @lines.empty? + @line_index = @lines.size - 1 + @cursor_position = current_line.chars.length + end + + def add_to_history(entry) + @history << entry + @history = @history.last(100) if @history.size > 100 + end + + def paste_from_clipboard + case RbConfig::CONFIG["host_os"] + when /darwin/i + paste_from_clipboard_macos + when /linux/i + paste_from_clipboard_linux + else + { type: :text, text: "" } + end + end + + def paste_from_clipboard_macos + has_image = system("osascript -e 'try' -e 'the clipboard as «class PNGf»' -e 'on error' -e 'return false' -e 'end try' >/dev/null 2>&1") + + if has_image + temp_dir = Dir.tmpdir + temp_filename = "clipboard-#{Time.now.to_i}-#{rand(10000)}.png" + temp_path = File.join(temp_dir, temp_filename) + + script = <<~APPLESCRIPT + set png_data to the clipboard as «class PNGf» + set the_file to open for access POSIX file "#{temp_path}" with write permission + write png_data to the_file + close access the_file + APPLESCRIPT + + success = system("osascript", "-e", script, out: File::NULL, err: File::NULL) + + if success && File.exist?(temp_path) && File.size(temp_path) > 0 + return { type: :image, path: temp_path } + end + end + + text = `pbpaste 2>/dev/null`.to_s + text = Clacky::Utils::Encoding.to_utf8(text) + { type: :text, text: text } + rescue => e + { type: :text, text: "" } + end + + def paste_from_clipboard_linux + if system("which xclip >/dev/null 2>&1") + text = `xclip -selection clipboard -o 2>/dev/null`.to_s + text = Clacky::Utils::Encoding.to_utf8(text) + { type: :text, text: text } + elsif system("which xsel >/dev/null 2>&1") + text = `xsel --clipboard --output 2>/dev/null`.to_s + text = Clacky::Utils::Encoding.to_utf8(text) + { type: :text, text: text } + else + { type: :text, text: "" } + end + rescue => e + { type: :text, text: "" } + end + + def current_line + @lines[@line_index] || "" + end + + def expand_placeholders(text) + super(text, @paste_placeholders) + end + + def render_line_with_cursor(line) + chars = line.chars + before_cursor = chars[0...@cursor_position].join + cursor_char = chars[@cursor_position] || " " + after_cursor = chars[(@cursor_position + 1)..-1]&.join || "" + + "#{@pastel.white(before_cursor)}#{@pastel.on_white(@pastel.black(cursor_char))}#{@pastel.white(after_cursor)}" + end + + # Render a segment of a line with cursor if cursor is in this segment + # Applies theme colors to the text + # @param line [String] Full line text + # @param segment_start [Integer] Start position of segment in line (char index) + # @param segment_end [Integer] End position of segment in line (char index) + # @return [String] Rendered segment with cursor and theme colors applied + def render_line_segment_with_cursor(line, segment_start, segment_end) + chars = line.chars + segment_chars = chars[segment_start...segment_end] + + # Check if cursor is in this segment + if @cursor_position >= segment_start && @cursor_position < segment_end + # Cursor is in this segment + cursor_pos_in_segment = @cursor_position - segment_start + before_cursor = segment_chars[0...cursor_pos_in_segment].join + cursor_char = segment_chars[cursor_pos_in_segment] || " " + after_cursor = segment_chars[(cursor_pos_in_segment + 1)..-1]&.join || "" + + # Apply theme color to text parts, keep cursor highlight as is + "#{theme.format_text(before_cursor, :user)}#{@pastel.on_white(@pastel.black(cursor_char))}#{theme.format_text(after_cursor, :user)}" + elsif @cursor_position == segment_end && segment_end == line.length + # Cursor is at the very end of the line, show it in last segment + segment_text = segment_chars.join + "#{theme.format_text(segment_text, :user)}#{@pastel.on_white(@pastel.black(' '))}" + else + # Cursor is not in this segment, apply theme color + theme.format_text(segment_chars.join, :user) + end + end + + # Render a separator line (ensures it doesn't exceed screen width) + # @param row [Integer] Row position to render + def render_separator(row) + move_cursor(row, 0) + # Ensure separator doesn't exceed screen width to prevent wrapping + separator_width = [@width, 1].max + content = @pastel.dim("─" * separator_width) + print content + # Clear any remaining space + remaining = @width - separator_width + print " " * remaining if remaining > 0 + end + + # Render session bar with wrapping support + # @param row [Integer] Starting row position + # @return [Integer] Number of rows actually used + def render_sessionbar(row) + move_cursor(row, 0) + + # If no sessionbar info, just render a separator + unless @sessionbar_info[:working_dir] + separator_width = [@width, 1].max + content = @pastel.dim("─" * separator_width) + print content + remaining = @width - separator_width + print " " * remaining if remaining > 0 + return 1 + end + + session_line = build_sessionbar_content + + # IMPORTANT: Always use print_with_padding which handles truncation + # to prevent terminal auto-wrap + print_with_padding(session_line) + 1 + end + + # Build the session bar content string + # @return [String] Formatted session bar content + private def build_sessionbar_content + parts = [] + separator = @pastel.dim(" │ ") + + # Workspace status with animation + if @sessionbar_info[:status] + status_color = status_color_for(@sessionbar_info[:status]) + status_indicator = get_status_indicator(@sessionbar_info[:status], status_color) + parts << "#{status_indicator} #{@pastel.public_send(status_color, @sessionbar_info[:status])}" + end + + # Session id — first 8 chars (parity with WebUI #sib-id) + if @sessionbar_info[:session_id] + sid_short = @sessionbar_info[:session_id].to_s[0, 8] + parts << theme.format_text(sid_short, :statusbar_secondary) unless sid_short.empty? + end + + # Working directory (shortened if too long) + if @sessionbar_info[:working_dir] + dir_display = shorten_path(@sessionbar_info[:working_dir]) + parts << theme.format_text(dir_display, :statusbar_path) + end + + # Permission mode + if @sessionbar_info[:mode] + mode_color = mode_color_for(@sessionbar_info[:mode]) + parts << @pastel.public_send(mode_color, @sessionbar_info[:mode]) + end + + # Model + if @sessionbar_info[:model] + parts << theme.format_text(@sessionbar_info[:model], :statusbar_secondary) + end + + # Tasks count + parts << theme.format_text("#{@sessionbar_info[:tasks]} tasks", :statusbar_secondary) + + # Cost + # If cost_source is :default (pricing unknown for this model), show N/A + # to stay consistent with the per-iteration token line. + cost_display = if @sessionbar_info[:cost_source] == :default + "$N/A" + else + format("$%.1f", @sessionbar_info[:cost]) + end + parts << theme.format_text(cost_display, :statusbar_secondary) + + " " + parts.join(separator) + end + + # Truncate session bar content to fit within max length + # @param content [String] Full session bar content with ANSI codes + # @param max_length [Integer] Maximum visible length + # @return [String] Truncated content + private def truncate_sessionbar_content(content, max_length) + # Strip ANSI codes to calculate visible length + visible_content = strip_ansi_codes(content) + visible_width = calculate_display_width(visible_content) + + return content if visible_width <= max_length + + # Truncate from the end with "..." indicator + chars = visible_content.chars + current_width = 0 + truncate_at = 0 + + chars.each_with_index do |char, idx| + char_width = char_display_width(char) + if current_width + char_width + 3 > max_length # Reserve 3 for "..." + truncate_at = idx + break + end + current_width += char_width + truncate_at = idx + 1 + end + + # For simplicity with ANSI codes, just show first part + ... + # This is a simplified version - proper implementation would preserve ANSI codes + visible_content[0...truncate_at] + "..." + end + + # Calculate how many rows the session bar will occupy + # @return [Integer] Number of rows needed + private def calculate_sessionbar_height + return 1 unless @sessionbar_info[:working_dir] + + # Session bar always renders on one line (we truncate if needed) + 1 + end + + def shorten_path(path) + return path if path.length <= 40 + + # Replace home directory with ~ + home = ENV["HOME"] + if home && path.start_with?(home) + path = path.sub(home, "~") + end + + # If still too long, show last parts + if path.length > 40 + parts = path.split("/") + if parts.length > 3 + ".../" + parts[-3..-1].join("/") + else + path[0..40] + "..." + end + else + path + end + end + + def mode_color_for(mode) + case mode.to_s + when /auto_approve/ + :magenta + when /confirm_safes/ + :cyan + else + :white + end + end + + def status_color_for(status) + case status.to_s.downcase + when 'idle' + :cyan # Use darker cyan for idle state + when 'working' + :yellow # Use yellow to highlight working state + else + :cyan + end + end + + def get_status_indicator(status, color) + case status.to_s.downcase + when 'working' + # Update animation frame if enough time has passed + now = Time.now + if now - @last_animation_update >= 0.3 + @animation_frame = (@animation_frame + 1) % @working_frames.length + @last_animation_update = now + end + @pastel.public_send(color, @working_frames[@animation_frame]) + else + @pastel.public_send(color, "●") # Idle indicator with same color as text + end + end + + def format_tips(message, type) + # Limit message length to prevent line wrapping + # Reserve space for prefix like "[Warn] " (about 8 chars) and some margin + max_length = @width - 10 + if message.length > max_length + message = message[0...(max_length - 3)] + "..." + end + + case type + when :warning + @pastel.dim("[") + @pastel.yellow("Warn") + @pastel.dim("] ") + @pastel.yellow(message) + when :error + @pastel.dim("[") + @pastel.red("Error") + @pastel.dim("] ") + @pastel.red(message) + else + @pastel.dim("[") + @pastel.cyan("Info") + @pastel.dim("] ") + @pastel.white(message) + end + end + + def format_filesize(size) + if size < 1024 + "#{size}B" + elsif size < 1024 * 1024 + "#{(size / 1024.0).round(1)}KB" + else + "#{(size / 1024.0 / 1024.0).round(1)}MB" + end + end + + # Format user tip (usage suggestion) with lightbulb icon + # @param tip [String] Tip message + # @return [String] Formatted tip with styling + def format_user_tip(tip) + # Limit message length to prevent line wrapping + max_length = @width - 5 # Reserve space for icon and margins + if tip.length > max_length + tip = tip[0...(max_length - 3)] + "..." + end + + # Use lightbulb icon and dim cyan color for subtle appearance + @pastel.dim(@pastel.cyan("💡 #{tip}")) + end + + def move_cursor(row, col) + print "\e[#{row + 1};#{col + 1}H" + end + + def clear_line + print "\e[2K" + end + + def flush + $stdout.flush + end + end + end + end +end diff --git a/lib/clacky/ui2/components/message_component.rb b/lib/clacky/ui2/components/message_component.rb new file mode 100644 index 0000000..542e20d --- /dev/null +++ b/lib/clacky/ui2/components/message_component.rb @@ -0,0 +1,99 @@ +# frozen_string_literal: true + +require_relative "base_component" + +module Clacky + module UI2 + module Components + # MessageComponent renders user and assistant messages + class MessageComponent < BaseComponent + # Render a message + # @param data [Hash] Message data + # - :role [String] "user" or "assistant" + # - :content [String] Message content + # - :timestamp [Time, nil] Optional timestamp + # - :files [Array] Optional file hashes (for user messages) + # - :prefix_newline [Boolean] Whether to add newline before message (for system messages) + # @return [String] Rendered message + def render(data) + role = data[:role] + content = data[:content] + timestamp = data[:timestamp] + files = data[:files] || [] + prefix_newline = data.fetch(:prefix_newline, true) + + case role + when "user" + render_user_message(content, timestamp, files) + when "assistant" + render_assistant_message(content, timestamp) + else + render_system_message(content, timestamp, prefix_newline) + end + end + + + # Render user message + # @param content [String] Message content + # @param timestamp [Time, nil] Optional timestamp + # @param files [Array] Optional file hashes { name:, mime_type:, ... } + # @return [String] Rendered message + def render_user_message(content, timestamp = nil, files = []) + symbol = format_symbol(:user) + text = format_text(content, :user) + time_str = timestamp ? @pastel.dim("[#{format_timestamp(timestamp)}]") : "" + + result = "\n#{symbol} #{text} #{time_str}".rstrip + + # Append file attachment info if present + if files && files.any? + files.each_with_index do |f, idx| + filename = f[:name] || f["name"] || "file" + result += "\n" + @pastel.dim(" [File #{idx + 1}] #{filename}") + end + end + + result + end + + private def format_filesize(bytes) + if bytes < 1024 + "#{bytes}b" + elsif bytes < 1024 * 1024 + "#{(bytes / 1024.0).round(1)}kb" + else + "#{(bytes / (1024.0 * 1024)).round(1)}mb" + end + end + + # Render assistant message + # @param content [String] Message content + # @param timestamp [Time, nil] Optional timestamp + # @return [String] Rendered message + def render_assistant_message(content, timestamp = nil) + return "" if content.nil? || content.empty? + + symbol = format_symbol(:assistant) + text = format_text(content, :assistant) + time_str = timestamp ? @pastel.dim("[#{format_timestamp(timestamp)}]") : "" + + "\n#{symbol} #{text} #{time_str}".rstrip + end + + # Render system message + # @param content [String] Message content + # @param timestamp [Time, nil] Optional timestamp + # @param prefix_newline [Boolean] Whether to add newline before message + # @return [String] Rendered message + private def render_system_message(content, timestamp = nil, prefix_newline = true) + symbol = format_symbol(:info) + text = format_text(content, :info) + time_str = timestamp ? @pastel.dim("[#{format_timestamp(timestamp)}]") : "" + + prefix = prefix_newline ? "\n" : "" + "#{prefix}#{symbol} #{text} #{time_str}".rstrip + end + end + end + end +end diff --git a/lib/clacky/ui2/components/modal_component.rb b/lib/clacky/ui2/components/modal_component.rb new file mode 100644 index 0000000..f93e263 --- /dev/null +++ b/lib/clacky/ui2/components/modal_component.rb @@ -0,0 +1,446 @@ +# frozen_string_literal: true + +require 'io/console' +require 'tty-prompt' +require_relative 'base_component' + +module Clacky + module UI2 + module Components + # ModalComponent - Displays a centered modal dialog with form fields + class ModalComponent < BaseComponent + attr_reader :width, :height + + def initialize + super + @width = 70 + @height = 16 + @title = "" + @fields = [] + @choices = [] + @values = {} + @selected_index = 0 + @mode = :form + end + + # Configure and show the modal + # @param title [String] Modal title + # @param fields [Array] Field definitions (for form mode) + # @param choices [Array] Choice definitions (for menu mode) + # Example: [{ name: "Option 1", value: :opt1 }, { name: "---", disabled: true }] + # @param validator [Proc, nil] Optional validation callback that receives values hash + # Should return { success: true } or { success: false, error: "message" } + # @param on_close [Proc, nil] Optional callback to execute when modal closes (e.g., to re-render screen) + # @return [Hash, nil] Hash of field values or selected value, or nil if cancelled + # @param nav_keys [Boolean] when true, → on an expandable choice returns + # { nav: :expand, value: } and ←/Esc returns { nav: :back }, letting the + # caller drive multi-page (drawer) navigation within one modal flow. + # @param instructions [String, nil] override the bottom hint line. + def show(title:, fields: nil, choices: nil, validator: nil, on_close: nil, initial_index: nil, nav_keys: false, instructions: nil) + @title = title + @mode = choices ? :menu : :form + @fields = fields || [] + @choices = choices || [] + @values = {} + @error_message = nil + @selected_index = 0 + @nav_keys = nav_keys + @instructions = instructions + + # For menu mode, default to first non-disabled choice, unless the + # caller pinned an initial cursor position (e.g. Time Machine wants + # the cursor to land on the currently-active task). + if @mode == :menu + if initial_index && @choices[initial_index] && !@choices[initial_index][:disabled] + @selected_index = initial_index + else + @selected_index = @choices.index { |c| !c[:disabled] } || 0 + end + end + + # Adjust height based on mode + if @mode == :menu + visible_items = [@choices.length, 15].min + @height = visible_items + 4 # +4 for title, borders, and instructions + else + # Form mode - adjust height based on number of fields + # Each field takes 2 rows (label + input) + # +3 for title and top border + # +5 for error message area, buttons, and bottom border + @height = (@fields.length * 2) + 3 + 5 + end + + # Get terminal size + term_height, term_width = IO.console.winsize + + # Calculate modal position (centered) + start_row = [(term_height - @height) / 2, 1].max + start_col = [(term_width - @width) / 2, 1].max + + begin + if @mode == :menu + # Menu mode - show choices and handle selection + return show_menu_mode(start_row, start_col) + else + # Form mode - collect field inputs + return show_form_mode(start_row, start_col, validator) + end + ensure + # Clear modal area + clear_modal(start_row, start_col) + # Call on_close callback if provided (e.g., to re-render screen) + on_close&.call + end + end + + # Render method (required by BaseComponent, not used for modal) + def render(data) + # Modal uses interactive show() method instead + "" + end + + + # Show menu mode + private def show_menu_mode(start_row, start_col) + loop do + # Draw menu + draw_modal(start_row, start_col) + draw_menu_choices(start_row + 2, start_col) + draw_menu_instructions(start_row + @height - 2, start_col) + + # Read input + char = STDIN.getch + + case char + when "\r", "\n" # Enter - select current choice + selected = @choices[@selected_index] + return nil if selected.nil? || selected[:disabled] + print "\e[?25l" # Hide cursor + return selected[:value] + when "\e" # Escape sequence + seq = STDIN.read_nonblock(2) rescue '' + if seq.empty? + # Just Esc key. With nav_keys, Esc means "back" (the caller + # decides whether that's go-to-parent or cancel); otherwise cancel. + print "\e[?25l" + return @nav_keys ? { nav: :back } : nil + elsif seq == '[A' # Up arrow + move_menu_selection(-1) + elsif seq == '[B' # Down arrow + move_menu_selection(1) + elsif seq == '[C' && @nav_keys # Right arrow - expand + selected = @choices[@selected_index] + if selected && !selected[:disabled] && selected[:expandable] + print "\e[?25l" + return { nav: :expand, value: selected[:value] } + end + elsif seq == '[D' && @nav_keys # Left arrow - back + print "\e[?25l" + return { nav: :back } + end + when "\u0003" # Ctrl+C + print "\e[?25l" + return nil + when 'k', 'K' # Vim-style up + move_menu_selection(-1) + when 'j', 'J' # Vim-style down + move_menu_selection(1) + when 'q', 'Q' # Quit + print "\e[?25l" + return nil + end + end + end + + # Show form mode + private def show_form_mode(start_row, start_col, validator) + loop do + # Draw modal background and border + draw_modal(start_row, start_col) + + # Draw error message if present + if @error_message + draw_error_message(start_row + @height - 5, start_col) + end + + # Draw instructions + draw_buttons(start_row + @height - 3, start_col) + + # Collect input for each field + current_row = start_row + 3 + @fields.each do |field| + # Use previously entered value as default if validation failed + field_with_previous = field.dup + field_with_previous[:default] = @values[field[:name]] || field[:default] + + value = collect_field_input(field_with_previous, current_row, start_col) + if value == :cancelled + print "\e[?25l" # Hide cursor + return nil # User pressed Esc + end + @values[field[:name]] = value + current_row += 2 + end + + # All fields collected - validate if validator provided + if validator + # Show "Testing..." message + testing_row = start_row + @height - 5 + testing_col = start_col + 3 + print "\e[#{testing_row};#{testing_col}H\e[K" + print "\e[#{testing_row + 1};#{testing_col}H\e[K" + print @pastel.cyan("⏳ Testing connection...") + STDOUT.flush + + validation_result = validator.call(@values) + + # Clear testing messages + print "\e[#{testing_row};#{testing_col}H\e[K" + print "\e[#{testing_row + 1};#{testing_col}H\e[K" + + if validation_result[:success] + # Validation passed - hide cursor and return values + print "\e[?25l" + return @values + else + # Validation failed - show error and loop again to let user correct input + @error_message = validation_result[:error] || "Validation failed" + # Don't clear modal - just loop again to redraw with error message + # This prevents the modal from flickering + end + else + # No validator - return immediately + print "\e[?25l" + return @values + end + end + end + + # Draw the modal background and border + private def draw_modal(start_row, start_col) + # Use theme colors - cyan for border, bright_cyan for title + reset = "\e[0m" + + # Draw box with border + @height.times do |i| + print "\e[#{start_row + i};#{start_col}H" + + if i == 0 + # Top border with title + title_text = " #{@title} " + padding = (@width - title_text.length - 2) / 2 + remaining = @width - padding - title_text.length - 2 + border_line = @pastel.cyan("┌" + "─" * padding) + title_part = @pastel.bright_cyan(title_text) + border_rest = @pastel.cyan("─" * remaining + "┐") + print border_line + title_part + border_rest + elsif i == @height - 1 + # Bottom border + print @pastel.cyan("└" + "─" * (@width - 2) + "┘") + else + # Side borders with background + left_border = @pastel.cyan("│") + right_border = @pastel.cyan("│") + print left_border + " " * (@width - 2) + right_border + end + end + end + + # Collect input for a single field + private def collect_field_input(field, row, col) + require 'io/console' + + label_text = @pastel.white(field[:label]) + + # Draw field label + print "\e[#{row};#{col + 2}H#{label_text}" + + # Input field position + input_row = row + 1 + input_col = col + 4 + input_width = @width - 8 + + # Initialize input buffer with default value + buffer = field[:default].to_s.dup + cursor_pos = buffer.length + placeholder = "Press Enter to keep current" + + # Show cursor for input + print "\e[?25h" + + loop do + # Draw input field with cursor or placeholder + if buffer.empty? + # Show placeholder in dim gray + display_text = @pastel.dim(placeholder) + elsif field[:mask] + # Show masked input - limit display length to prevent overflow + mask_length = [buffer.length, input_width].min + display_text = @pastel.cyan('*' * mask_length) + else + # Show normal input + display_text = @pastel.cyan(buffer) + end + + # Clear line and draw input + print "\e[#{input_row};#{input_col}H\e[K" + print display_text + + # Position cursor and ensure it's visible + visible_cursor_pos = [cursor_pos, input_width - 1].min + print "\e[#{input_row};#{input_col + visible_cursor_pos}H" + STDOUT.flush + + # Read character + char = STDIN.getch + + case char + when "\r", "\n" # Enter - confirm input + # Clear placeholder if input is empty + if buffer.empty? + print "\e[#{input_row};#{input_col}H\e[K" + end + # Don't hide cursor here - next field will reuse it + return buffer + when "\e" # Escape sequence + seq = STDIN.read_nonblock(2) rescue '' + if seq.empty? + # Just Esc key - cancel (hide cursor when cancelling) + print "\e[?25l" + return :cancelled + elsif seq == '[C' # Right arrow + cursor_pos = [cursor_pos + 1, buffer.length].min + elsif seq == '[D' # Left arrow + cursor_pos = [cursor_pos - 1, 0].max + elsif seq == '[H' # Home + cursor_pos = 0 + elsif seq == '[F' # End + cursor_pos = buffer.length + end + when "\u007F", "\b" # Backspace + if cursor_pos > 0 + buffer[cursor_pos - 1] = '' + cursor_pos -= 1 + end + when "\u0003" # Ctrl+C (hide cursor when cancelling) + print "\e[?25l" + return :cancelled + when "\u0015" # Ctrl+U - clear line + buffer = String.new + cursor_pos = 0 + else + # Regular character input + if char.ord >= 32 && char.ord < 127 + buffer.insert(cursor_pos, char) + cursor_pos += 1 + end + end + end + end + + # Draw error message + private def draw_error_message(row, col) + return if @error_message.nil? || @error_message.empty? + + max_width = @width - 6 + # Truncate error message if too long + error_text = @error_message.length > max_width ? @error_message[0..max_width-4] + "..." : @error_message + error_col = col + 3 + + # Clear the line first to prevent leftover characters + print "\e[#{row};#{error_col}H\e[K" + formatted = @pastel.red("⚠ #{error_text}") + print formatted + end + + # Draw confirmation buttons + private def draw_buttons(row, col) + # Show instructions at bottom of modal + buttons_text = "Press Enter after each field • Press Esc to cancel" + button_col = col + (@width - buttons_text.length) / 2 + + formatted = @pastel.dim(buttons_text) + print "\e[#{row};#{button_col}H#{formatted}" + end + + # Clear the modal area + private def clear_modal(start_row, start_col) + @height.times do |i| + print "\e[#{start_row + i};#{start_col}H#{' ' * @width}" + end + end + + # Draw menu choices + private def draw_menu_choices(start_row, start_col) + @choices.each_with_index do |choice, index| + row = start_row + index + draw_menu_choice(choice, index, row, start_col) + end + end + + # Draw a single menu choice + private def draw_menu_choice(choice, index, row, col) + is_selected = (index == @selected_index) + + # Calculate available width for text + text_width = @width - 6 # Account for borders, marker, and padding + + # Prepare choice text + choice_text = choice[:name] || "" + if choice_text.length > text_width + choice_text = choice_text[0..text_width-4] + "..." + end + + # Prepare marker and styling + if choice[:disabled] + # Disabled choice (like separator) + marker = " " + text = @pastel.dim(choice_text) + elsif is_selected + marker = @pastel.bright_cyan("→ ") + text = choice[:dim] ? @pastel.dim(choice_text) : @pastel.bright_white(choice_text) + elsif choice[:dim] + # Undone / abandoned-branch task: keep it visually de-emphasized + # even when not under the cursor. + marker = " " + text = @pastel.dim(choice_text) + else + marker = " " + text = @pastel.white(choice_text) + end + + # Draw line + print "\e[#{row};#{col}H" + print @pastel.cyan("│") + marker + text + + # Pad to width + used_length = choice_text.length + 2 # marker is 2 chars + padding_needed = @width - used_length - 2 # -2 for borders + print " " * padding_needed + @pastel.cyan("│") + end + + # Draw menu instructions + private def draw_menu_instructions(row, col) + instructions = @instructions || "↑↓/jk: Navigate • Enter: Select • Esc/q: Cancel" + padding = (@width - instructions.length - 2) / 2 + remaining = @width - padding - instructions.length - 2 + + print "\e[#{row};#{col}H" + border_line = @pastel.cyan("└" + "─" * padding) + instr_part = @pastel.dim(instructions) + border_rest = @pastel.cyan("─" * remaining + "┘") + print border_line + instr_part + border_rest + end + + # Move menu selection up or down + private def move_menu_selection(direction) + loop do + @selected_index = (@selected_index + direction) % @choices.length + # Skip disabled choices + break unless @choices[@selected_index][:disabled] + end + end + end + end + end +end diff --git a/lib/clacky/ui2/components/todo_area.rb b/lib/clacky/ui2/components/todo_area.rb new file mode 100644 index 0000000..8c0d77b --- /dev/null +++ b/lib/clacky/ui2/components/todo_area.rb @@ -0,0 +1,149 @@ +# frozen_string_literal: true + +require "pastel" + +module Clacky + module UI2 + module Components + # TodoArea displays active todos above the separator line + class TodoArea + attr_accessor :height + attr_reader :todos + + MAX_DISPLAY_TASKS = 3 # Show current + next 2 tasks + + def initialize + @todos = [] + @pending_todos = [] + @completed_count = 0 + @total_count = 0 + @pastel = Pastel.new + @width = TTY::Screen.width + @height = 0 # Dynamic height based on todos + @hidden = false + end + + # Update todos list + # @param todos [Array] Array of todo items + def update(todos) + @todos = todos || [] + @pending_todos = @todos.select { |t| t[:status] == "pending" } + @completed_count = @todos.count { |t| t[:status] == "completed" } + @total_count = @todos.size + + recalc_height + end + + # Hide the area without discarding todos data; show again to restore. + def hide + return if @hidden + @hidden = true + @height = 0 + end + + def show + return unless @hidden + @hidden = false + recalc_height + end + + private def recalc_height + if @hidden || @pending_todos.empty? + @height = 0 + else + @height = [@pending_todos.size, MAX_DISPLAY_TASKS].min + end + end + + # Check if there are todos to display + def visible? + @height > 0 + end + + # Render todos area + # @param start_row [Integer] Screen row to start rendering + def render(start_row:) + return unless visible? + + update_width + + # Render each task on separate line + tasks_to_show = @pending_todos.take(MAX_DISPLAY_TASKS) + + tasks_to_show.each_with_index do |task, index| + move_cursor(start_row + index, 0) + + # Build the line content + line_content = if index == 0 + # First line: Task [2/4]: #3 - Current task description + progress = "#{@completed_count}/#{@total_count}" + prefix = "Task [#{progress}]: " + task_text = "##{task[:id]} - #{task[:task]}" + available_width = @width - prefix.length - 2 + truncated_task = truncate_text(task_text, available_width) + + "#{@pastel.cyan(prefix)}#{truncated_task}" + else + # Subsequent lines: -> Next: #4 - Next task description + label = index == 1 ? "Next" : "After" + prefix = "-> #{label}: " + task_text = "##{task[:id]} - #{task[:task]}" + available_width = @width - prefix.length - 2 + truncated_task = truncate_text(task_text, available_width) + + "#{@pastel.dim(prefix)}#{@pastel.dim(truncated_task)}" + end + + # Use carriage return and print content directly (overwrite existing content) + print "\r#{line_content}" + # Clear any remaining characters from previous render if line is shorter + clear_to_end_of_line + end + + flush + end + + # Clear the area + def clear + @todos = [] + @pending_todos = [] + @completed_count = 0 + @total_count = 0 + @height = 0 + end + + + # Truncate text to fit width + def truncate_text(text, max_width) + return "" if text.nil? + + if text.length > max_width + text[0...(max_width - 3)] + "..." + else + text + end + end + + # Update width on resize + def update_width + @width = TTY::Screen.width + end + + # Move cursor to position + def move_cursor(row, col) + print "\e[#{row + 1};#{col + 1}H" + end + + # Clear from cursor to end of line + def clear_to_end_of_line + print "\e[0K" + end + + # Flush output + def flush + $stdout.flush + end + end + end + end +end diff --git a/lib/clacky/ui2/components/tool_component.rb b/lib/clacky/ui2/components/tool_component.rb new file mode 100644 index 0000000..e654342 --- /dev/null +++ b/lib/clacky/ui2/components/tool_component.rb @@ -0,0 +1,107 @@ +# frozen_string_literal: true + +require_relative "base_component" + +module Clacky + module UI2 + module Components + # ToolComponent renders tool calls and results + class ToolComponent < BaseComponent + # Render a tool event + # @param data [Hash] Tool event data + # - :type [Symbol] :call, :result, :error, :denied, :planned + # - :tool_name [String] Name of the tool + # - :formatted_call [String] Formatted tool call description + # - :result [String] Tool result (for :result type) + # - :error [String] Error message (for :error type) + # @return [String] Rendered tool event + def render(data) + type = data[:type] + + case type + when :call + render_tool_call(data) + when :result + render_tool_result(data) + when :error + render_tool_error(data) + when :denied + render_tool_denied(data) + when :planned + render_tool_planned(data) + else + render_unknown_tool_event(data) + end + end + + + # Render tool call + # @param data [Hash] Tool call data + # @return [String] Rendered tool call + def render_tool_call(data) + symbol = format_symbol(:tool_call) + formatted_call = data[:formatted_call] || "#{data[:tool_name]}(...)" + text = format_text(formatted_call, :tool_call) + + "\n#{symbol} #{text}" + end + + # Render tool result + # @param data [Hash] Tool result data + # @return [String] Rendered tool result + def render_tool_result(data) + symbol = format_symbol(:tool_result) + result = data[:result] || data[:summary] || "completed" + text = format_text(truncate(result, 200), :tool_result) + + "#{symbol} #{text}" + end + + # Render tool error + # Use a low-key style (same as tool_result) since most tool errors + # (e.g. tool not found, invalid args) are non-critical and the agent can retry. + # @param data [Hash] Tool error data + # @return [String] Rendered tool error + def render_tool_error(data) + symbol = format_symbol(:tool_result) + error_msg = data[:error] || "Unknown error" + text = format_text(truncate(error_msg, 200), :tool_result) + + "#{symbol} #{text}" + end + + # Render tool denied + # @param data [Hash] Tool denied data + # @return [String] Rendered tool denied + def render_tool_denied(data) + symbol = format_symbol(:tool_denied) + tool_name = data[:tool_name] || "unknown" + text = format_text("Tool denied: #{tool_name}", :tool_denied) + + "\n#{symbol} #{text}" + end + + # Render tool planned + # @param data [Hash] Tool planned data + # @return [String] Rendered tool planned + def render_tool_planned(data) + symbol = format_symbol(:tool_planned) + tool_name = data[:tool_name] || "unknown" + text = format_text("Planned: #{tool_name}", :tool_planned) + + "\n#{symbol} #{text}" + end + + # Render unknown tool event + # @param data [Hash] Tool event data + # @return [String] Rendered unknown event + def render_unknown_tool_event(data) + symbol = format_symbol(:info) + text = format_text("Tool event: #{data.inspect}", :info) + + "#{symbol} #{text}" + end + end + end + end +end diff --git a/lib/clacky/ui2/components/welcome_banner.rb b/lib/clacky/ui2/components/welcome_banner.rb new file mode 100644 index 0000000..afacce0 --- /dev/null +++ b/lib/clacky/ui2/components/welcome_banner.rb @@ -0,0 +1,201 @@ +# frozen_string_literal: true + +require "pastel" +require_relative "../../version" +require_relative "../block_font" +require_relative "../../utils/workspace_rules" + +module Clacky + module UI2 + module Components + # WelcomeBanner displays the startup screen with ASCII logo, tagline, tips, and agent info. + # + # When a product_name is configured via BrandConfig, the hardcoded OPENCLACKY + # ASCII art is replaced by a dynamically generated logo using artii (FIGlet). + # Falls back to plain text when the terminal is too narrow or artii fails. + class WelcomeBanner + LOGO = <<~'LOGO' + ██████╗ ██████╗ ███████╗███╗ ██╗ ██████╗██╗ █████╗ ██████╗██╗ ██╗██╗ ██╗ + ██╔═══██╗██╔══██╗██╔════╝████╗ ██║██╔════╝██║ ██╔══██╗██╔════╝██║ ██╔╝╚██╗ ██╔╝ + ██║ ██║██████╔╝█████╗ ██╔██╗ ██║██║ ██║ ███████║██║ █████╔╝ ╚████╔╝ + ██║ ██║██╔═══╝ ██╔══╝ ██║╚██╗██║██║ ██║ ██╔══██║██║ ██╔═██╗ ╚██╔╝ + ╚██████╔╝██║ ███████╗██║ ╚████║╚██████╗███████╗██║ ██║╚██████╗██║ ██╗ ██║ + ╚═════╝ ╚═╝ ╚══════╝╚═╝ ╚═══╝ ╚═════╝╚══════╝╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝ ╚═╝ + LOGO + + TAGLINE = "[>] Your personal Assistant & Technical Co-founder" + + TIPS = [ + "[*] Ask questions, edit files, or run commands", + "[*] Be specific for the best results", + "[*] Create .clackyrules or AGENTS.md to customize interactions", + "[*] Type /help for more commands" + ].freeze + + # Minimum terminal width required for full logo display + MIN_WIDTH_FOR_LOGO = 90 + + def initialize + @pastel = Pastel.new + end + + # Get current theme from ThemeManager + def theme + UI2::ThemeManager.current_theme + end + + # Render only the logo (ASCII art or simple text based on terminal width) + # @param width [Integer] Terminal width + # @return [String] Formatted logo only + def render_logo(width:) + lines = [] + lines << "" + lines << logo_content(width) + lines << "" + lines.join("\n") + end + + # Render startup banner + # @param width [Integer] Terminal width + # @return [String] Formatted startup banner + def render_startup(width:) + lines = [] + lines << "" + lines << logo_content(width) + lines << "" + lines << @pastel.bright_cyan(TAGLINE) + lines << @pastel.dim(" Version #{Clacky::VERSION}") + lines << "" + TIPS.each do |tip| + lines << @pastel.dim(tip) + end + lines << "" + lines.join("\n") + end + + # Render agent welcome section + # @param working_dir [String] Working directory + # @param mode [String] Permission mode + # @return [String] Formatted agent welcome section + def render_agent_welcome(working_dir:, mode:) + lines = [] + lines << "" + lines << separator("=") + lines << @pastel.bright_green("[+] AGENT MODE INITIALIZED") + lines << separator("=") + lines << "" + lines << info_line("Working Directory", working_dir) + lines << info_line("Permission Mode", mode) + + # Show loaded project rules file if present + main = Utils::WorkspaceRules.find_main(working_dir) + lines << info_line("Project Rules", "#{main[:name]} ✓") if main + + lines << "" + lines << theme.format_text("[!] Type 'exit' or 'quit' to terminate session", :thinking) + lines << separator("-") + lines << "" + + # Show sub-project agents block if any sub-dirs have .clackyrules + sub_projects = Utils::WorkspaceRules.find_sub_projects(working_dir) + unless sub_projects.empty? + lines << @pastel.bright_cyan("[>] SUB-PROJECT AGENT MODE") + lines << @pastel.dim(" #{sub_projects.size} sub-project(s) detected with rules:") + sub_projects.each do |sp| + first_line = sp[:summary].lines.first&.strip&.delete_prefix("#")&.strip + label = @pastel.cyan(" • #{sp[:sub_name]}/") + desc = first_line && !first_line.empty? ? @pastel.dim(" — #{first_line}") : "" + lines << "#{label}#{desc}" + end + lines << @pastel.dim(" AI will read each sub-project's full .clackyrules before working in it.") + lines << separator("-") + lines << "" + end + + lines.join("\n") + end + + # Render full welcome (startup + agent info) + # @param working_dir [String] Working directory + # @param mode [String] Permission mode + # @param width [Integer] Terminal width + # @return [String] Full welcome content + def render_full(working_dir:, mode:, width:) + render_startup(width: width) + render_agent_welcome( + working_dir: working_dir, + mode: mode + ) + end + + + # Returns the colourised logo block. + # - Branded install: dynamically generated artii ASCII art for the brand name + # - Standard install: hardcoded OPENCLACKY block-letter logo + # Falls back to plain text when the terminal is too narrow or artii fails. + private def logo_content(width) + brand = brand_config + if brand.branded? + generate_brand_logo(brand, width) + else + if width >= MIN_WIDTH_FOR_LOGO + @pastel.bright_green(LOGO) + else + @pastel.bright_green("Welcome, OpenClacky is here") + end + end + end + + # Generate a brand logo using BlockFont (Unicode █ ╗ ╔ style). + # Renders package_name as the big ASCII art logo. + # Shows product_name as a subtitle when it differs from package_name. + # Falls back to plain product_name text when terminal is too narrow. + private def generate_brand_logo(brand, width) + # Use package_name as the renderable ASCII-safe identifier for the logo. + # product_name may contain CJK or special characters unsuitable for block art. + render_key = brand.package_name.to_s.strip + render_key = brand.product_name.to_s.strip if render_key.empty? + + art = UI2::BlockFont.render(render_key) + + lines = [] + if !art.strip.empty? && art_fits?(art, width) + lines << @pastel.bright_green(art) + else + lines << @pastel.bright_green(render_key) + end + + # Show product_name as subtitle when it differs from the render key + if brand.product_name.to_s.strip != render_key + lines << @pastel.bright_cyan(" #{brand.product_name}") + end + + lines.join("\n") + end + + # Check whether the ASCII art fits within the terminal width. + private def art_fits?(art, width) + art.lines.map { |l| l.chomp.length }.max.to_i <= width + end + + # Lazily load and cache BrandConfig to avoid circular require issues. + private def brand_config + require_relative "../../brand_config" + Clacky::BrandConfig.load + rescue LoadError, StandardError + # Return a neutral stub when brand_config is unavailable + Object.new.tap { |o| o.define_singleton_method(:branded?) { false } } + end + + private def info_line(label, value) + label_text = @pastel.cyan("[#{label}]") + value_text = theme.format_text(value, :info) + " #{label_text} #{value_text}" + end + + private def separator(char = "-") + theme.format_text(char * 80, :thinking) + end + end + end + end +end diff --git a/lib/clacky/ui2/layout_manager.rb b/lib/clacky/ui2/layout_manager.rb new file mode 100644 index 0000000..13354c4 --- /dev/null +++ b/lib/clacky/ui2/layout_manager.rb @@ -0,0 +1,816 @@ +# frozen_string_literal: true + +require_relative "screen_buffer" +require_relative "output_buffer" +require_relative "../utils/encoding" + +module Clacky + module UI2 + # LayoutManager coordinates the split-screen layout: + # [ scrollable output area ] + # [ gap / todo / input (fixed) ] + # + # Responsibilities: + # - Own an OutputBuffer (logical source of truth for output content). + # - Translate buffer mutations into screen paints, handling: + # * Native terminal scrolling when output overflows the output area. + # * Committing scrolled lines to the buffer (so they are never repainted + # from the buffer again — prevents the classic "double render on + # scroll up" bug). + # - Keep the fixed area (gap + todo + input) pinned at the bottom of the + # screen, repainting it only when it is dirty. + # + # Public API (id-based, preferred): + # append(content, kind: :text) -> id # add entry, returns id + # replace_entry(id, content) # edit entry's content + # remove_entry(id) # drop entry + # + # Legacy API (shims, still used by InlineInput / progress): + # append_output(content) -> id # alias for append + # update_last_line(content, old_n, id: nil) # uses id if given + # remove_last_line(n, id: nil) # uses id if given + class LayoutManager + attr_reader :screen, :input_area, :todo_area, :buffer + + def initialize(input_area:, todo_area: nil) + @screen = ScreenBuffer.new + @input_area = input_area + @todo_area = todo_area + @buffer = OutputBuffer.new + @render_mutex = Mutex.new + + @output_row = 0 # Next output row to paint into + @last_fixed_area_height = 0 + @fullscreen_mode = false + @resize_pending = false + + # Tracks the most recent append's id so the legacy + # update_last_line / remove_last_line shims still work without the + # caller threading an id through. + @last_append_id = nil + + calculate_layout + setup_resize_handler + end + + # ----------------------------------------------------------------------- + # Layout math + # ----------------------------------------------------------------------- + + def calculate_layout + todo_height = @todo_area&.height || 0 + input_height = @input_area.required_height + gap_height = 1 + + @output_height = screen.height - gap_height - todo_height - input_height + @output_height = [1, @output_height].max + + @gap_row = @output_height + @todo_row = @gap_row + gap_height + @input_row = @todo_row + todo_height + + @input_area.row = @input_row + end + + def fixed_area_height + todo_h = @todo_area&.height || 0 + input_h = @input_area.required_height + 1 + todo_h + input_h + end + + def fixed_area_start_row + screen.height - fixed_area_height + end + + # ----------------------------------------------------------------------- + # Public output API (id-based) + # ----------------------------------------------------------------------- + + # Append an output entry. Returns the entry id so callers can later + # replace_entry / remove_entry. Multi-line content is wrapped and + # stored as one logical entry. + def append(content, kind: :text) + return nil if content.nil? + content = sanitize(content) + + @render_mutex.synchronize do + lines = wrap_content_to_lines(content) + id = @buffer.append(lines, kind: kind) + @last_append_id = id + + paint_new_lines(lines) unless @fullscreen_mode + render_fixed_areas + screen.flush + id + end + end + + # Legacy: append, return id (callers that ignore it still work). + def append_output(content) + append(content) + end + + # Replace an existing entry's content. The screen is updated in place + # if the entry still lives in the output area; otherwise (committed + # to scrollback, or partially scrolled off) this is a silent no-op. + def replace_entry(id, content) + return if id.nil? || content.nil? + content = sanitize(content) + + @render_mutex.synchronize do + entry = @buffer.entry_by_id(id) + if entry.nil? + return + end + if entry.committed + return + end + if (entry.committed_line_offset || 0) > 0 + return + end + + old_lines = entry.lines.dup + new_lines = wrap_content_to_lines(content) + if old_lines == new_lines + screen.flush + return + end + @buffer.replace(id, new_lines) + is_tail = @buffer.live_entries.last&.id == id + + unless @fullscreen_mode + # repaint_entry_in_place relies on the entry being the tail of + # live entries (it computes the entry's top row from @output_row + # and old height). When the entry is NOT the tail — e.g. a + # background progress ticker fires after a newer entry was + # appended — that assumption silently corrupts the screen: + # the new frame gets painted at the tail's row, clobbering the + # latest log line, and @output_row is reset to a position that + # predates appended-but-still-live entries. On next scroll, + # those stale-now-present rows end up in terminal scrollback as + # duplicated lines (the user-visible "output repeats" bug). + # + # For non-tail replaces, fall back to a full rebuild of the + # output area from the buffer. Slower, but correct regardless + # of where the entry lives. + if is_tail + repaint_entry_in_place(entry, old_lines, new_lines) + else + render_output_from_buffer + end + end + render_fixed_areas + screen.flush + end + end + + # Is this id still a live (not yet committed to scrollback) entry? + # Cheap probe callers use before deciding between replace vs append. + def live_entry?(id) + return false if id.nil? + @buffer.live?(id) + end + + # Remove an entry. If it's the last live entry, the screen area it + # occupied is cleared and the output cursor rolls back. + def remove_entry(id) + return if id.nil? + + @render_mutex.synchronize do + entry = @buffer.entry_by_id(id) + return if entry.nil? || entry.committed + # Can't remove an entry whose prefix has already scrolled into + # terminal scrollback — those rows are immutable. The visible + # suffix will roll off on its own as more output is produced. + return if (entry.committed_line_offset || 0) > 0 + + height = entry.height + # Check whether this entry is the tail of live entries. Only tail + # removal is cheap — mid-buffer removal would require a full + # output repaint. In practice only the progress / inline-input + # entries are removed, and they are always the tail. + is_tail = @buffer.live_entries.last&.id == id + + @buffer.remove(id) + @last_append_id = nil if @last_append_id == id + + unless @fullscreen_mode + if is_tail + clear_tail_rows(height) + else + # Non-tail removal: rebuild the entire output area from buffer + render_output_from_buffer + end + end + + render_fixed_areas + screen.flush + end + end + + # ----------------------------------------------------------------------- + # Legacy shims (kept for InlineInput + other callers that don't carry ids) + # ----------------------------------------------------------------------- + + # Update the most recently appended entry. Prefer passing +id:+; when + # omitted the last-append id is used. +old_line_count+ is ignored + # (buffer knows the true height). + def update_last_line(content, old_line_count = nil, id: nil) + target = id || @last_append_id + replace_entry(target, content) if target + end + + # Remove the most recently appended entry (or the given id). + def remove_last_line(line_count = 1, id: nil) + target = id || @last_append_id + remove_entry(target) if target + end + + # ----------------------------------------------------------------------- + # Paint primitives (private) + # ----------------------------------------------------------------------- + + # Paint fresh lines into the output area, scrolling via native \n when + # we reach the fixed area. CRUCIAL INVARIANT: every time we scroll, + # we tell the buffer "N oldest live lines just moved into scrollback" + # so they are NEVER re-painted from the buffer again. This is what + # eliminates the double-render bug. + private def paint_new_lines(lines) + max_output_row = fixed_area_start_row + + lines.each do |line| + if @output_row >= max_output_row + # Scroll the terminal by emitting a real \n at the very bottom. + # That pushes the top visible row into the native scrollback + # buffer — exactly where the user will see it on scroll-up. + screen.move_cursor(screen.height - 1, 0) + print "\n" + + # Tell the buffer one line of live content just left the screen. + # Committed entries become untouchable, so a later full repaint + # (resize, fixed-area height change, fullscreen exit) will NOT + # re-emit them and duplicate them in scrollback. + @buffer.commit_oldest_lines(1) + + @output_row = max_output_row - 1 + + # The fixed area got scrolled up too — restore it. Don't trigger + # an output rebuild; the buffer's tail hasn't changed. + render_fixed_areas(skip_buffer_rerender: true) + end + + screen.move_cursor(@output_row, 0) + screen.clear_line + print line + @output_row += 1 + end + end + + # Repaint a single entry in place after its content changed. + # Handles both grow and shrink. If the new content would overflow + # into the fixed area, we scroll up to make room (same rules as + # paint_new_lines — scrolled rows get committed to scrollback). + private def repaint_entry_in_place(entry, old_lines, new_lines) + old_n = old_lines.length + new_n = new_lines.length + return if @output_row == 0 + + start_row = @output_row - old_n + start_row = 0 if start_row < 0 + + max_output_row = fixed_area_start_row + + # Grow + would overflow → scroll first + if new_n > old_n + needed_end = start_row + new_n + if needed_end > max_output_row + overflow = needed_end - max_output_row + overflow.times do + screen.move_cursor(screen.height - 1, 0) + print "\n" + @buffer.commit_oldest_lines(1) + end + start_row -= overflow + start_row = 0 if start_row < 0 + @output_row = [start_row + old_n, max_output_row].min + render_fixed_areas(skip_buffer_rerender: true) + end + end + + # Clear only rows whose content actually changed, then repaint + # those. Lines that are byte-identical to the previous frame stay + # untouched — avoiding the clear-then-redraw flicker that an + # always-on ticker produces 2-10x per second on slower terminals. + cur = start_row + new_lines.each_with_index do |line, i| + if i >= old_n || old_lines[i] != line + screen.move_cursor(cur, 0) + screen.clear_line + print line + end + cur += 1 + end + # If content shrank, blank out the rows the old frame occupied + # below the new tail. + if new_n < old_n + (cur...(start_row + old_n)).each do |row| + screen.move_cursor(row, 0) + screen.clear_line + end + end + @output_row = start_row + new_n + end + + # Clear the last N rows of the output area (used by remove_entry on tail). + private def clear_tail_rows(n) + return if n <= 0 || @output_row == 0 + + start_row = @output_row - n + start_row = 0 if start_row < 0 + + (start_row...@output_row).each do |row| + screen.move_cursor(row, 0) + screen.clear_line + end + @output_row = start_row + end + + # Repaint the entire output area from the buffer's live entries. + # Only called on layout changes (resize, fixed-area height change, + # /clear, fullscreen exit) — never on a normal append path. + private def render_output_from_buffer + max_output_row = fixed_area_start_row + + # Wipe the output area + (0...max_output_row).each do |row| + screen.move_cursor(row, 0) + screen.clear_line + end + + # Fill from the buffer's tail (live lines only — committed lines + # are already in terminal scrollback and MUST NOT be repainted). + lines = @buffer.tail_lines(max_output_row) + @output_row = 0 + lines.each do |line| + screen.move_cursor(@output_row, 0) + print line + @output_row += 1 + end + end + + # Wrap user content into screen-width visual lines using the existing + # ANSI-aware helper. Guarantees at least one line (possibly empty). + private def wrap_content_to_lines(content) + raw_lines = content.split("\n", -1) + wrapped = [] + raw_lines.each do |rl| + wrapped.concat(wrap_long_line(rl)) + end + wrapped = [""] if wrapped.empty? + wrapped + end + + private def sanitize(content) + return content if content.valid_encoding? + Clacky::Utils::Encoding.sanitize_utf8(content) + end + + # ----------------------------------------------------------------------- + # Lifecycle + layout + # ----------------------------------------------------------------------- + + def initialize_screen + screen.clear_screen + screen.hide_cursor + @output_row = 0 + render_all + end + + def cleanup_screen(clear_screen: false) + @render_mutex.synchronize do + if clear_screen + screen.clear_screen(mode: :reset) + else + fixed_start = fixed_area_start_row + (fixed_start...screen.height).each do |row| + screen.move_cursor(row, 0) + screen.clear_line + end + screen.move_cursor([@output_row, 0].max, 0) + print "\r" + end + screen.show_cursor + screen.flush + end + end + + # /clear: wipe output area + buffer, keep fixed area. + def clear_output + @render_mutex.synchronize do + max_row = fixed_area_start_row + (0...max_row).each do |row| + screen.move_cursor(row, 0) + screen.clear_line + end + @output_row = 0 + @last_append_id = nil + @buffer.clear + render_fixed_areas + screen.flush + end + end + + # Recalculate layout after input height changed. If the layout moved, + # clear the old fixed area rows and re-render at the new position. + def recalculate_layout + @render_mutex.synchronize do + old_gap_row = @gap_row + old_input_row = @input_row + + calculate_layout + + if @input_row != old_input_row + ([old_gap_row, 0].max...screen.height).each do |row| + screen.move_cursor(row, 0) + screen.clear_line + end + + if input_area.paused? + # Input paused (InlineInput active) — fixed area shrank, so the + # cleared rows are now part of the output area. Repaint from + # buffer to fill them in. + render_output_from_buffer + else + render_fixed_areas + end + screen.flush + end + end + end + + def render_all + @render_mutex.synchronize { render_all_internal } + end + + def render_output + @render_mutex.synchronize do + render_fixed_areas + screen.flush + end + end + + def render_input + @render_mutex.synchronize do + render_fixed_areas + screen.flush + end + end + + def rerender_all + @render_mutex.synchronize do + screen.clear_screen + render_output_from_buffer + render_fixed_areas + screen.flush + end + end + + # Restore cursor to input area (used after dialogs). + def restore_cursor_to_input + input_row = fixed_area_start_row + 1 + (@todo_area&.height || 0) + input_area.position_cursor(input_row) + screen.show_cursor + end + + # Position cursor for inline input in output area. + def position_inline_input_cursor(inline_input) + return unless inline_input + width = screen.width + wrap_row, wrap_col = inline_input.cursor_position_for_display(width) + line_count = inline_input.line_count(width) + + cursor_row = @output_row - line_count + wrap_row + cursor_col = wrap_col + screen.move_cursor(cursor_row, cursor_col) + screen.flush + end + + # Update todos display; recalculates layout if height changed. + def update_todos(todos) + return unless @todo_area + + @render_mutex.synchronize do + old_height = @todo_area.height + old_gap_row = @gap_row + + @todo_area.update(todos) + new_height = @todo_area.height + + if old_height != new_height + calculate_layout + ([old_gap_row, 0].max...screen.height).each do |row| + screen.move_cursor(row, 0) + screen.clear_line + end + end + + render_fixed_areas + screen.flush + end + end + + # Hide todo area while preserving its data; pair with show_todos. + def hide_todos + return unless @todo_area + + @render_mutex.synchronize do + old_height = @todo_area.height + old_gap_row = @gap_row + + @todo_area.hide + new_height = @todo_area.height + + if old_height != new_height + calculate_layout + ([old_gap_row, 0].max...screen.height).each do |row| + screen.move_cursor(row, 0) + screen.clear_line + end + end + + render_fixed_areas + screen.flush + end + end + + # Show todo area again after a previous hide_todos. + def show_todos + return unless @todo_area + + @render_mutex.synchronize do + old_height = @todo_area.height + old_gap_row = @gap_row + + @todo_area.show + new_height = @todo_area.height + + if old_height != new_height + calculate_layout + ([old_gap_row, 0].max...screen.height).each do |row| + screen.move_cursor(row, 0) + screen.clear_line + end + end + + render_fixed_areas + screen.flush + end + end + + + + # ----------------------------------------------------------------------- + # Fixed area (gap + todo + input) rendering + # ----------------------------------------------------------------------- + + # Repaint gap + todo + input at the bottom of the screen. + # + # @param skip_buffer_rerender [Boolean] When true, skip repainting the + # output area from the buffer even if the fixed-area height changed. + # Used by the scroll path in paint_new_lines — the caller has just + # written the correct content directly; a full buffer repaint would + # duplicate it in terminal scrollback. + def render_fixed_areas(skip_buffer_rerender: false) + # When input is paused (InlineInput active), the "input area" is + # rendered inline with output. Nothing to paint down here. + return if input_area.paused? + return if @fullscreen_mode + + current_fixed_height = fixed_area_height + start_row = fixed_area_start_row + gap_row = start_row + todo_row = gap_row + 1 + + # Fixed-area height changed (e.g. multi-line input appeared or + # command-suggestions popped) → repaint the output from buffer so + # nothing is hidden. + if !skip_buffer_rerender && + @last_fixed_area_height > 0 && + @last_fixed_area_height != current_fixed_height + render_output_from_buffer + end + @last_fixed_area_height = current_fixed_height + + # gap line + screen.move_cursor(gap_row, 0) + screen.clear_line + + # todo + @todo_area.render(start_row: todo_row) if @todo_area&.visible? + + # input (renders its own visual cursor) + input_row = todo_row + (@todo_area&.height || 0) + input_area.render(start_row: input_row, width: screen.width) + end + + private def render_all_internal + render_fixed_areas + screen.flush + end + + # Legacy no-ops — terminal handles native scroll natively. + def scroll_output_up(_lines = 1); end + def scroll_output_down(_lines = 1); end + + + + # ----------------------------------------------------------------------- + # Wrapping helpers (ANSI-aware, East-Asian-width aware) + # ----------------------------------------------------------------------- + + # Wrap a long line into multiple lines based on terminal width. + # Considers display width of multi-byte characters (e.g., Chinese characters). + def wrap_long_line(line) + return [""] if line.nil? || line.empty? + + max_width = screen.width + return [line] if max_width <= 0 + + # Strip ANSI codes for width calculation + visible_line = line.gsub(/\e\[[0-9;]*m/, '') + + display_width = calculate_display_width(visible_line) + return [line] if display_width <= max_width + + wrapped = [] + current_line = "" + current_width = 0 + ansi_codes = [] + + segments = line.split(/(\e\[[0-9;]*m)/) + + segments.each do |segment| + if segment =~ /^\e\[[0-9;]*m$/ + ansi_codes << segment + current_line += segment + else + segment.each_char do |char| + char_width = char_display_width(char) + if current_width + char_width > max_width && !current_line.empty? + wrapped << current_line + current_line = ansi_codes.join + current_width = 0 + end + current_line += char + current_width += char_width + end + end + end + + wrapped << current_line unless current_line.empty? || current_line == ansi_codes.join + wrapped.empty? ? [""] : wrapped + end + + def char_display_width(char) + code = char.ord + if (code >= 0x1100 && code <= 0x115F) || + (code >= 0x2329 && code <= 0x232A) || + (code >= 0x2E80 && code <= 0x303E) || + (code >= 0x3040 && code <= 0xA4CF) || + (code >= 0xAC00 && code <= 0xD7A3) || + (code >= 0xF900 && code <= 0xFAFF) || + (code >= 0xFE10 && code <= 0xFE19) || + (code >= 0xFE30 && code <= 0xFE6F) || + (code >= 0xFF00 && code <= 0xFF60) || + (code >= 0xFFE0 && code <= 0xFFE6) || + (code >= 0x1F300 && code <= 0x1F9FF) || + (code >= 0x20000 && code <= 0x2FFFD) || + (code >= 0x30000 && code <= 0x3FFFD) + 2 + else + 1 + end + end + + def calculate_display_width(text) + width = 0 + text.each_char { |c| width += char_display_width(c) } + width + end + + # ----------------------------------------------------------------------- + # Resize handling + # ----------------------------------------------------------------------- + + private def handle_resize + old_height = screen.height + old_width = screen.width + + screen.update_dimensions + calculate_layout + + shrinking = screen.height < old_height || screen.width < old_width + screen.clear_screen(mode: shrinking ? :reset : :current) + + # Repaint from buffer — only live (uncommitted) lines, which is + # exactly what we want: committed content already sits in the + # native scrollback above. + render_output_from_buffer + + # Sync so render_fixed_areas won't think height changed and + # trigger a second repaint. + @last_fixed_area_height = fixed_area_height + render_fixed_areas + screen.flush + end + + private def setup_resize_handler + Signal.trap("WINCH") { @resize_pending = true } + rescue ArgumentError => e + warn "WINCH signal already trapped: #{e.message}" + end + + def process_pending_resize + return unless @resize_pending + @resize_pending = false + handle_resize_safely + end + + private def handle_resize_safely + @render_mutex.synchronize { handle_resize } + rescue => e + warn "Resize error: #{e.message}" + warn e.backtrace.first(5).join("\n") if e.backtrace + end + + # ----------------------------------------------------------------------- + # Fullscreen (alternate screen buffer) + # ----------------------------------------------------------------------- + + def fullscreen_mode? + @fullscreen_mode + end + + def enter_fullscreen(lines, hint: "Press Ctrl+O to return") + @render_mutex.synchronize do + return if @fullscreen_mode + @fullscreen_mode = true + @fullscreen_hint = hint + + # Switch to alternate screen, clear it, position top-left. + print "\e[?1049h\e[2J\e[H" + $stdout.flush + render_fullscreen_content(lines) + end + end + + def refresh_fullscreen(lines) + @render_mutex.synchronize do + return unless @fullscreen_mode + print "\e[2J\e[H" + render_fullscreen_content(lines) + end + end + + def exit_fullscreen + @render_mutex.synchronize do + return unless @fullscreen_mode + @fullscreen_mode = false + @fullscreen_hint = nil + print "\e[?1049l" + $stdout.flush + end + end + + def restore_screen + @render_mutex.synchronize do + screen.clear_screen + screen.hide_cursor + render_all_internal + end + end + + private def render_fullscreen_content(lines) + term_height = screen.height + term_width = screen.width + + content_rows = term_height - 1 + display_lines = lines.first(content_rows) + + display_lines.each do |line| + visible = line.chomp.gsub(/\e\[[0-9;]*m/, "") + padding = [term_width - visible.length, 0].max + print line.chomp + (" " * padding) + "\r\n" + end + + blank_row = " " * term_width + (display_lines.length...content_rows).each { print blank_row + "\r\n" } + + hint_text = "\e[36m#{@fullscreen_hint}\e[0m" + print "\e[#{term_height};1H#{hint_text}\e[0K" + $stdout.flush + end + + end + end +end diff --git a/lib/clacky/ui2/line_editor.rb b/lib/clacky/ui2/line_editor.rb new file mode 100644 index 0000000..6c5797f --- /dev/null +++ b/lib/clacky/ui2/line_editor.rb @@ -0,0 +1,363 @@ +# frozen_string_literal: true + +require "pastel" + +module Clacky + module UI2 + # LineEditor module provides single-line text editing functionality + # Shared by InputArea and InlineInput components + module LineEditor + # Maximum content width ratio (percentage of terminal width) + # Use 90% of terminal width for better readability on wide screens + # This dynamically adjusts based on terminal size + MAX_CONTENT_WIDTH_RATIO = 0.9 + + attr_reader :cursor_position + + def initialize_line_editor + @line = "" + @cursor_position = 0 + @pastel = Pastel.new + end + + # Get current line content + def current_line + @line + end + + # Set line content + def set_line(text) + @line = text + @cursor_position = [@cursor_position, @line.chars.length].min + end + + # Clear line + def clear_line_content + @line = "" + @cursor_position = 0 + end + + # Insert character at cursor position + def insert_char(char) + chars = @line.chars + chars.insert(@cursor_position, char) + @line = chars.join + @cursor_position += 1 + end + + # Backspace - delete character before cursor + def backspace + return if @cursor_position == 0 + chars = @line.chars + chars.delete_at(@cursor_position - 1) + @line = chars.join + @cursor_position -= 1 + end + + # Delete character at cursor position + def delete_char + chars = @line.chars + return if @cursor_position >= chars.length + chars.delete_at(@cursor_position) + @line = chars.join + end + + # Move cursor left + def cursor_left + @cursor_position = [@cursor_position - 1, 0].max + end + + # Move cursor right + def cursor_right + @cursor_position = [@cursor_position + 1, @line.chars.length].min + end + + # Move cursor to start of line + def cursor_home + @cursor_position = 0 + end + + # Move cursor to end of line + def cursor_end + @cursor_position = @line.chars.length + end + + # Kill from cursor to end of line (Ctrl+K) + def kill_to_end + chars = @line.chars + @line = chars[0...@cursor_position].join + end + + # Kill from start to cursor (Ctrl+U) + def kill_to_start + chars = @line.chars + @line = chars[@cursor_position..-1]&.join || "" + @cursor_position = 0 + end + + # Kill word before cursor (Ctrl+W) + def kill_word + chars = @line.chars + pos = @cursor_position - 1 + + # Skip whitespace + while pos >= 0 && chars[pos] =~ /\s/ + pos -= 1 + end + # Delete word characters + while pos >= 0 && chars[pos] =~ /\S/ + pos -= 1 + end + + delete_start = pos + 1 + chars.slice!(delete_start...@cursor_position) + @line = chars.join + @cursor_position = delete_start + end + + # Insert text at cursor position + def insert_text(text) + return if text.nil? || text.empty? + chars = @line.chars + text.chars.each_with_index do |c, i| + chars.insert(@cursor_position + i, c) + end + @line = chars.join + @cursor_position += text.length + end + + # Expand placeholders and normalize line endings + def expand_placeholders(text, placeholders) + result = text.dup + placeholders.each do |placeholder, actual_content| + # Normalize line endings to \n + normalized_content = actual_content.gsub(/\r\n|\r/, "\n") + result.gsub!(placeholder, normalized_content) + end + result + end + + # Render line with cursor highlight + # @return [String] Rendered line with cursor + def render_line_with_cursor + chars = @line.chars + before_cursor = chars[0...@cursor_position].join + cursor_char = chars[@cursor_position] || " " + after_cursor = chars[(@cursor_position + 1)..-1]&.join || "" + + "#{@pastel.white(before_cursor)}#{@pastel.on_white(@pastel.black(cursor_char))}#{@pastel.white(after_cursor)}" + end + + # Calculate display width of a string, considering multi-byte characters + # East Asian Wide and Fullwidth characters (like Chinese) take 2 columns + # @param text [String] UTF-8 encoded text + # @return [Integer] Display width in terminal columns + def calculate_display_width(text) + width = 0 + text.each_char do |char| + code = char.ord + # East Asian Wide and Fullwidth characters + # See: https://www.unicode.org/reports/tr11/ + if (code >= 0x1100 && code <= 0x115F) || # Hangul Jamo + (code >= 0x2329 && code <= 0x232A) || # Left/Right-Pointing Angle Brackets + (code >= 0x2E80 && code <= 0x303E) || # CJK Radicals Supplement .. CJK Symbols and Punctuation + (code >= 0x3040 && code <= 0xA4CF) || # Hiragana .. Yi Radicals + (code >= 0xAC00 && code <= 0xD7A3) || # Hangul Syllables + (code >= 0xF900 && code <= 0xFAFF) || # CJK Compatibility Ideographs + (code >= 0xFE10 && code <= 0xFE19) || # Vertical Forms + (code >= 0xFE30 && code <= 0xFE6F) || # CJK Compatibility Forms .. Small Form Variants + (code >= 0xFF00 && code <= 0xFF60) || # Fullwidth Forms + (code >= 0xFFE0 && code <= 0xFFE6) || # Fullwidth Forms + (code >= 0x1F300 && code <= 0x1F9FF) || # Emoticons, Symbols, etc. + (code >= 0x20000 && code <= 0x2FFFD) || # CJK Unified Ideographs Extension B..F + (code >= 0x30000 && code <= 0x3FFFD) # CJK Unified Ideographs Extension G + width += 2 + else + width += 1 + end + end + width + end + + # Strip ANSI escape codes from a string + # @param text [String] Text with ANSI codes + # @return [String] Text without ANSI codes + def strip_ansi_codes(text) + text.gsub(/\e\[[0-9;]*m/, '') + end + + # Get cursor column position (considering multi-byte characters) + # @param prompt [String] Prompt string before the line (may contain ANSI codes) + # @return [Integer] Column position for cursor + def cursor_column(prompt = "") + # Strip ANSI codes from prompt to get actual display width + visible_prompt = strip_ansi_codes(prompt) + prompt_display_width = calculate_display_width(visible_prompt) + + # Calculate display width of text before cursor + chars = @line.chars + text_before_cursor = chars[0...@cursor_position].join + text_display_width = calculate_display_width(text_before_cursor) + + prompt_display_width + text_display_width + end + + # Get cursor position considering line wrapping + # @param prompt [String] Prompt string before the line (may contain ANSI codes) + # @param width [Integer] Terminal width for wrapping + # @param continuation_prompt [String] Prompt for continuation lines (default: "> ") + # @return [Array] Row and column position (0-indexed) + def cursor_position_with_wrap(prompt = "", width = TTY::Screen.width, continuation_prompt = "> ") + return [0, cursor_column(prompt)] if width <= 0 + + prompt_width = calculate_display_width(strip_ansi_codes(prompt)) + available_width = width - prompt_width + + # Get wrapped segments for current line + wrapped_segments = wrap_line(@line, available_width) + + # Find which segment contains cursor + cursor_segment_idx = 0 + cursor_pos_in_segment = @cursor_position + + wrapped_segments.each_with_index do |segment, idx| + if @cursor_position >= segment[:start] && @cursor_position < segment[:end] + cursor_segment_idx = idx + cursor_pos_in_segment = @cursor_position - segment[:start] + break + elsif @cursor_position >= segment[:end] && idx == wrapped_segments.size - 1 + cursor_segment_idx = idx + cursor_pos_in_segment = segment[:end] - segment[:start] + break + end + end + + # Calculate display width of text before cursor in this segment + chars = @line.chars + segment_start = wrapped_segments[cursor_segment_idx][:start] + text_in_segment_before_cursor = chars[segment_start...(segment_start + cursor_pos_in_segment)].join + display_width = calculate_display_width(text_in_segment_before_cursor) + + # Use appropriate prompt width based on which segment (row) we're on + # First line uses original prompt, subsequent lines use continuation prompt + actual_prompt_width = if cursor_segment_idx == 0 + prompt_width + else + calculate_display_width(strip_ansi_codes(continuation_prompt)) + end + + col = actual_prompt_width + display_width + row = cursor_segment_idx + + [row, col] + end + + # Wrap a line into multiple segments based on available width + # Considers display width of characters (multi-byte characters like Chinese) + # @param line [String] The line to wrap + # @param max_width [Integer] Maximum display width per wrapped line + # @return [Array] Array of segment info: { text: String, start: Integer, end: Integer } + def wrap_line(line, max_width) + return [{ text: "", start: 0, end: 0 }] if line.empty? + return [{ text: line, start: 0, end: line.length }] if max_width <= 0 + + segments = [] + chars = line.chars + segment_start = 0 + current_width = 0 + current_end = 0 + + chars.each_with_index do |char, idx| + char_width = char_display_width(char) + + # If adding this character exceeds max width, complete current segment + if current_width + char_width > max_width && current_end > segment_start + segments << { + text: chars[segment_start...current_end].join, + start: segment_start, + end: current_end + } + segment_start = idx + current_end = idx + 1 + current_width = char_width + else + current_end = idx + 1 + current_width += char_width + end + end + + # Add the last segment + if current_end > segment_start + segments << { + text: chars[segment_start...current_end].join, + start: segment_start, + end: current_end + } + end + + segments.empty? ? [{ text: "", start: 0, end: 0 }] : segments + end + + # Calculate display width of a single character + # @param char [String] Single character + # @return [Integer] Display width (1 or 2) + def char_display_width(char) + code = char.ord + # East Asian Wide and Fullwidth characters take 2 columns + if (code >= 0x1100 && code <= 0x115F) || + (code >= 0x2329 && code <= 0x232A) || + (code >= 0x2E80 && code <= 0x303E) || + (code >= 0x3040 && code <= 0xA4CF) || + (code >= 0xAC00 && code <= 0xD7A3) || + (code >= 0xF900 && code <= 0xFAFF) || + (code >= 0xFE10 && code <= 0xFE19) || + (code >= 0xFE30 && code <= 0xFE6F) || + (code >= 0xFF00 && code <= 0xFF60) || + (code >= 0xFFE0 && code <= 0xFFE6) || + (code >= 0x1F300 && code <= 0x1F9FF) || + (code >= 0x20000 && code <= 0x2FFFD) || + (code >= 0x30000 && code <= 0x3FFFD) + 2 + else + 1 + end + end + + # Calculate effective content width (respecting MAX_CONTENT_WIDTH_RATIO) + # @param screen_width [Integer] Terminal screen width + # @return [Integer] Effective content width to use + private def effective_content_width(screen_width) + (screen_width * MAX_CONTENT_WIDTH_RATIO).to_i + end + + # Render a segment of a line with cursor if cursor is in this segment + # @param line [String] Full line text + # @param segment_start [Integer] Start position of segment in line (char index) + # @param segment_end [Integer] End position of segment in line (char index) + # @return [String] Rendered segment with cursor if applicable (without text color, only cursor highlight) + def render_line_segment_with_cursor(line, segment_start, segment_end) + chars = line.chars + segment_chars = chars[segment_start...segment_end] + + # Check if cursor is in this segment + if @cursor_position >= segment_start && @cursor_position < segment_end + # Cursor is in this segment + cursor_pos_in_segment = @cursor_position - segment_start + before_cursor = segment_chars[0...cursor_pos_in_segment].join + cursor_char = segment_chars[cursor_pos_in_segment] || " " + after_cursor = segment_chars[(cursor_pos_in_segment + 1)..-1]&.join || "" + + # Only apply cursor highlight, let subclasses apply text color + "#{before_cursor}#{@pastel.on_white(@pastel.black(cursor_char))}#{after_cursor}" + elsif @cursor_position == segment_end && segment_end == line.length + # Cursor is at the very end of the line, show it in last segment + segment_text = segment_chars.join + "#{segment_text}#{@pastel.on_white(@pastel.black(' '))}" + else + # Cursor is not in this segment, return plain text without color + segment_chars.join + end + end + end + end +end diff --git a/lib/clacky/ui2/markdown_renderer.rb b/lib/clacky/ui2/markdown_renderer.rb new file mode 100644 index 0000000..c38e1e1 --- /dev/null +++ b/lib/clacky/ui2/markdown_renderer.rb @@ -0,0 +1,100 @@ +# frozen_string_literal: true + +require "tty-markdown" +require_relative "theme_manager" + +module Clacky + module UI2 + # MarkdownRenderer handles rendering Markdown content with syntax highlighting + module MarkdownRenderer + class << self + # Render markdown content with theme-aware colors + # @param content [String] Markdown content to render + # @return [String] Rendered content with ANSI colors + def render(content) + return content if content.nil? || content.empty? + + # Get current theme colors + theme = ThemeManager.current_theme + + # Configure tty-markdown with custom theme and symbols + parsed = TTY::Markdown.parse(content, + theme: theme_colors, + symbols: custom_symbols, + width: TTY::Screen.width - 4 # Leave some margin + ) + + parsed + rescue StandardError => e + warn "[markdown] render failed: #{e.class}: #{e.message}" if ENV["CLACKY_DEBUG"] + content + end + + # Check if content looks like markdown + # @param content [String] Content to check + # @return [Boolean] true if content appears to be markdown + def markdown?(content) + return false if content.nil? || content.empty? + + # Check for common markdown patterns + content.match?(/^#+ /) || # Headers + content.match?(/```/) || # Code blocks + content.match?(/^\s*[-*+] /) || # Unordered lists + content.match?(/^\s*\d+\. /) || # Ordered lists + content.match?(/\[.+\]$.+$/) || # Links + content.match?(/^\s*> /) || # Blockquotes + content.match?(/\*\*.+\*\*/) || # Bold + content.match?(/`.+`/) || # Inline code + content.match?(/^\s*\|.+\|/) || # Tables + content.match?(/^---+$/) # Horizontal rules + end + + + # Get theme-aware colors for markdown rendering + # @return [Hash] Color configuration for tty-markdown + def theme_colors + theme = ThemeManager.current_theme + + # Map our theme colors to tty-markdown's expected format + # Note: theme.colors values are already arrays, so we need to flatten when adding styles + { + # Headers use info color (cyan/blue) + h1: Array(theme.colors[:info]) + [:bold], + h2: Array(theme.colors[:info]) + [:bold], + h3: Array(theme.colors[:info]), + h4: Array(theme.colors[:info]), + h5: Array(theme.colors[:info]), + h6: Array(theme.colors[:info]), + # Horizontal rule - make it subtle (dim gray) + hr: [:bright_black], + # Code blocks use dim color + code: Array(theme.colors[:thinking]), + # Links use success color (green) + link: Array(theme.colors[:success]), + # Lists use default text color + list: [:bright_white], + # Strong/bold use bright white + strong: [:bright_white, :bold], + # Emphasis/italic use white + em: [:white], + # Note/blockquote use dim color + note: Array(theme.colors[:thinking]), + quote: Array(theme.colors[:thinking]), + } + end + + # Get custom symbols for markdown rendering + # @return [Hash] Symbol configuration for tty-markdown + def custom_symbols + { + override: { + # Make horizontal rule simpler - just a line without decorative diamonds + diamond: "", + line: "-" + } + } + end + end + end + end +end diff --git a/lib/clacky/ui2/output_buffer.rb b/lib/clacky/ui2/output_buffer.rb new file mode 100644 index 0000000..0ed5aff --- /dev/null +++ b/lib/clacky/ui2/output_buffer.rb @@ -0,0 +1,370 @@ +# frozen_string_literal: true + +require_relative "../utils/limit_stack" + +module Clacky + module UI2 + # OutputBuffer manages the logical sequence of rendered output lines. + # + # It replaces the scattered state that used to live across + # LayoutManager (@output_buffer + @output_row) and UIController + # (@progress_message / "last line" assumptions). + # + # Core concepts: + # + # - Every append returns an +id+. Callers can later +replace(id, ...)+ + # or +remove(id)+ that exact entry without relying on "the last line". + # - Each entry tracks whether it has been "committed" to the terminal + # scrollback (i.e. scrolled off the top of the visible window by a + # native terminal \n). Committed entries are NEVER re-drawn from the + # buffer again — this is what prevents the classic "scroll up shows + # a duplicated line" bug. + # - Entries may contain multi-line content (already wrapped). Each entry + # stores its visual line count so the renderer can compute exact rows + # to clear when replacing or removing. + # + # The buffer itself does NOT talk to the terminal. It is a pure data + # structure; a renderer (LayoutManager) consumes it through the + # snapshot APIs: +visible_entries+, +entry_by_id+, +tail_lines+. + class OutputBuffer + # A single logical output entry. + # + # @!attribute id [Integer] Monotonic id, unique within the buffer + # @!attribute lines [Array] Rendered (already-wrapped) visual lines + # @!attribute kind [Symbol] :text | :progress | :system (hint for renderer) + # @!attribute committed [Boolean] True once pushed into terminal scrollback + Entry = Struct.new(:id, :lines, :kind, :committed, :committed_line_offset, keyword_init: true) do + # Visual row count this entry currently OCCUPIES on screen. Once a + # prefix of the entry's lines has been pushed into scrollback by + # a scroll+partial-commit, those prefix rows are no longer on + # screen — so height drops accordingly. When +committed+ flips to + # true the entry is considered fully off-screen and height is 0. + def height + return 0 if committed + lines.length - (committed_line_offset || 0) + end + + # The currently on-screen lines of this entry (lines that haven't + # been pushed to scrollback yet). Returns [] once fully committed. + def visible_lines + return [] if committed + off = committed_line_offset || 0 + off.zero? ? lines : lines[off..] || [] + end + + def to_s + lines.join("\n") + end + end + + DEFAULT_MAX_ENTRIES = 2000 + + attr_reader :entries + + def initialize(max_entries: DEFAULT_MAX_ENTRIES) + @entries = [] # Array in insertion order + @index = {} # id => Entry (fast lookup) + @next_id = 1 + @max_entries = max_entries + @mutex = Mutex.new + # Monotonic counter incremented every time the buffer changes. + # Renderers can compare this against a saved version to decide + # whether their cached screen image is still valid. + @version = 0 + end + + # Append a new entry. +content+ may be a String (may include \n) or + # an Array of already-split lines. + # + # @param content [String, Array] + # @param kind [Symbol] :text (default), :progress, :system + # @return [Integer] id of the newly created entry + def append(content, kind: :text) + @mutex.synchronize do + lines = normalize_lines(content) + entry = Entry.new(id: next_id!, lines: lines, kind: kind, committed: false, committed_line_offset: 0) + @entries << entry + @index[entry.id] = entry + trim_if_needed + bump_version + entry.id + end + end + + # Replace an existing entry's content. If the id no longer exists + # (e.g. the entry was trimmed or already committed and recycled), + # this is a no-op and returns nil. + # + # Replacing a committed entry is silently ignored — committed content + # lives in terminal scrollback and cannot be edited in place. Same + # for an entry whose prefix has been partial-committed: the prefix + # is already in scrollback and replacing the entry would either + # strand those lines (if shorter) or duplicate them (if longer). + # + # @param id [Integer] + # @param content [String, Array] + # @return [Integer, nil] Old visible height if replaced, nil if no-op + def replace(id, content) + @mutex.synchronize do + entry = @index[id] + return nil unless entry + return nil if entry.committed + return nil if (entry.committed_line_offset || 0) > 0 + + old_height = entry.height + entry.lines = normalize_lines(content) + bump_version + old_height + end + end + + # Remove an entry. Committed entries cannot be removed (they are in + # terminal scrollback). Partially-committed entries also cannot be + # removed — their prefix is frozen in scrollback. Returns the + # removed Entry, or nil if no-op. + # + # @param id [Integer] + # @return [Entry, nil] + def remove(id) + @mutex.synchronize do + entry = @index[id] + return nil unless entry + return nil if entry.committed + return nil if (entry.committed_line_offset || 0) > 0 + + @entries.delete(entry) + @index.delete(id) + bump_version + entry + end + end + + # Mark an entry (and every older live entry) as committed to terminal + # scrollback. Called by the renderer after it has emitted a native \n + # that scrolled the top-of-screen row off into scrollback. + # + # Committing always flows from oldest → newest: if entry X is + # committed, every entry older than X must also be committed, because + # they have already scrolled past X on the screen. + # + # @param id [Integer] + def commit_through(id) + @mutex.synchronize do + committed_any = false + @entries.each do |e| + break if e.id > id + unless e.committed + e.committed = true + committed_any = true + end + end + bump_version if committed_any + end + end + + # Commit the oldest N VISUAL rows. Used when the renderer scrolls N + # lines off the top via native \n. Commits are precise at the visual + # row granularity (even mid-entry): if the oldest live entry is + # multi-line and only its prefix has scrolled off, that prefix is + # recorded in +committed_line_offset+ and only the still-visible + # suffix remains eligible for future repaints. + # + # This is the critical invariant for preventing the "scroll up to + # see a line already in scrollback, then render_output_from_buffer + # repaints it again on screen" duplicate-output regression: every + # visual row that went into terminal scrollback MUST be removed + # from the buffer's pool of repaintable live rows, regardless of + # whether it sat alone in a 1-line entry or at the top of a 10-line + # entry. + # + # @param line_count [Integer] Number of visual lines pushed to scrollback + # @return [Integer] Number of entries NEWLY marked fully committed + # (partial commits on an entry do NOT count toward this total — + # callers use the return value only as a debug hint, not for row + # bookkeeping). + def commit_oldest_lines(line_count) + return 0 if line_count <= 0 + + @mutex.synchronize do + remaining = line_count + committed = 0 + changed = false + @entries.each do |e| + break if remaining <= 0 + next if e.committed + + h = e.height + if h <= remaining + # Full scroll-off of this entry's remaining visible rows. + e.committed = true + e.committed_line_offset = e.lines.length # normalize + remaining -= h + committed += 1 + changed = true + else + # Partial scroll: record the new offset and stop (there are + # still visible rows of this entry on screen). + e.committed_line_offset = (e.committed_line_offset || 0) + remaining + remaining = 0 + changed = true + break + end + end + bump_version if changed + committed + end + end + + # Entries that are still live (not committed). These are candidates + # for re-rendering into the visible output area. + # + # @return [Array] + def live_entries + @mutex.synchronize { @entries.reject(&:committed).dup } + end + + # The last N *visual lines* across live entries, preserving entry + # boundaries. Returns an Array suitable for row-by-row + # painting. If the last live entry is taller than +n+, only its last + # +n+ lines are returned. + # + # @param n [Integer] + # @return [Array] + def tail_lines(n) + return [] if n <= 0 + + @mutex.synchronize do + collected = [] + @entries.reverse_each do |e| + break if collected.length >= n + next if e.committed + + # The entry's still-visible lines (excluding any prefix already + # committed to scrollback via a partial commit). + vis = e.visible_lines + next if vis.empty? + + # Prepend the entry's visible lines in order + remaining = n - collected.length + if vis.length <= remaining + collected = vis + collected + else + collected = vis.last(remaining) + collected + break + end + end + collected + end + end + + # Look up an entry by id. + # @param id [Integer] + # @return [Entry, nil] + def entry_by_id(id) + @mutex.synchronize { @index[id] } + end + + # Does this id still refer to a live, editable entry? + # @param id [Integer] + def live?(id) + @mutex.synchronize do + e = @index[id] + !!(e && !e.committed) + end + end + + # Does this id refer to an entry that can still be replaced or + # removed in place? A partially-committed entry (prefix already in + # scrollback via a scroll) is NOT editable — its visible suffix is + # frozen until it either fully commits or (rare) a full repaint + # rewrites the screen. + # + # @param id [Integer] + def fully_editable?(id) + @mutex.synchronize do + e = @index[id] + !!(e && !e.committed && (e.committed_line_offset || 0) == 0) + end + end + + # Total number of entries (committed + live) currently tracked. + def size + @mutex.synchronize { @entries.size } + end + + # Number of live entries. + def live_size + @mutex.synchronize { @entries.count { |e| !e.committed } } + end + + # Total visual lines across live entries. + def live_line_count + @mutex.synchronize { @entries.sum { |e| e.committed ? 0 : e.height } } + end + + # Monotonic version (incremented on every mutation). + def version + @version + end + + # Clear everything. Used by /clear command. + def clear + @mutex.synchronize do + @entries.clear + @index.clear + bump_version + end + end + + # --- helpers ---------------------------------------------------------- + + private def next_id! + id = @next_id + @next_id += 1 + id + end + + private def bump_version + @version += 1 + end + + # Drop the oldest entries when the buffer grows past the cap. This is + # a soft safety net — in practice live entries stay small because + # write_output_line commits them to scrollback as they scroll off. + private def trim_if_needed + while @entries.size > @max_entries + dropped = @entries.shift + @index.delete(dropped.id) + end + end + + # Normalize input into an array of visual lines (no trailing \n kept). + # Empty strings are preserved so callers can explicitly append blank + # rows. + # + # Rules: + # - nil → [""] + # - Array → deep copy (caller has pre-split) + # - "hello" → ["hello"] + # - "a\nb" → ["a", "b"] + # - "a\n" → ["a"] (trailing newline is not a new line) + # - "a\n\n" → ["a", ""] (explicit blank line preserved) + # - "" → [""] + private def normalize_lines(content) + case content + when nil + [""] + when Array + content.map(&:to_s) + else + str = content.to_s + return [""] if str.empty? + # Strip a single trailing newline so "a\n" → ["a"], but keep + # explicit blank lines ("a\n\n" → ["a", ""]). + str = str.chomp("\n") + str.split("\n", -1) + end + end + end + end +end diff --git a/lib/clacky/ui2/progress_handle.rb b/lib/clacky/ui2/progress_handle.rb new file mode 100644 index 0000000..6c0a0b3 --- /dev/null +++ b/lib/clacky/ui2/progress_handle.rb @@ -0,0 +1,369 @@ +# frozen_string_literal: true + +require "monitor" + +module Clacky + module UI2 + # An *owned* progress indicator. + # + # Why this exists + # --------------- + # The previous design had a single, globally-shared spinner slot on + # UiController (`@progress_id` / `@progress_thread` / `@progress_message` + # / `@progress_start_time`). Every caller — Agent#run, Agent#think, + # LlmCaller retry, idle compression, MemoryUpdater — wrote into the + # same slot and hoped to remember to close it. When control flow was + # interrupted (user types a new message during idle compression, + # AgentInterrupted is raised) a ticker thread would be left running + # and a new spinner would reuse the same entry, producing two + # concurrent tickers repainting the same line in different colors. + # + # In the new design each caller owns a ProgressHandle. The handle + # encapsulates: + # + # - its own OutputBuffer entry id (may become nil while another + # handle is on top — see "Stack semantics" below); + # - its own ticker thread (exactly one per handle, stopped and + # joined on +finish+); + # - its own message, style, start time; + # + # Owners (UiController) keep a stack of live handles and follow the + # protocol below. + # + # Owner protocol + # -------------- + # An "owner" must respond to three methods: + # + # register_progress(handle) -> Integer (entry_id) | nil + # Called exactly once when the handle starts. The owner pushes + # the handle onto its stack, creates an OutputBuffer entry, and + # returns that entry id. Before pushing, the owner may detach + # the previous top-of-stack (Plan B: its entry is removed from + # the buffer until the new top finishes). + # + # unregister_progress(handle, final_frame:) -> void + # Called exactly once when the handle finishes. The owner pops + # the handle from its stack, renders +final_frame+ into the + # entry (or removes the entry if +final_frame+ is nil), and may + # reattach the new top-of-stack if one exists. + # + # render_frame(handle, frame) -> void + # Called by the ticker (and by +update+) on every paint. The + # owner is responsible for ignoring the call if +handle+ is not + # currently top-of-stack — the handle itself does NOT know about + # the stack. + # + # Stack semantics (Plan B) + # ------------------------ + # When a new handle is pushed on top of an existing one, the lower + # handle's OutputBuffer entry is removed (owner calls + # +__detach_entry!+ on it). When the new top finishes, the owner + # re-creates an entry for the lower handle and calls + # +__reattach_entry!+ with the new id. This keeps the visible output + # clean: exactly one progress line on screen at a time, and no + # visual "stacking" of frozen progress lines. + # + # Thread safety + # ------------- + # The handle uses a Monitor (reentrant) to serialize state changes + # between the caller thread and the ticker thread. Public methods + # (+start+, +update+, +finish+) are safe to call from any thread. + class ProgressHandle + # Default tick interval (seconds). Matches the old global spinner + # cadence. Tests may pass a smaller interval for speed. + DEFAULT_TICK_INTERVAL = 0.25 + + # Style hint for the renderer. The owner decides what colors to use; + # the handle only forwards the hint as part of the frame metadata + # so the renderer can pick between e.g. yellow "working" and gray + # "quiet" palettes. + # + # :primary — foreground task, should also update sessionbar + # :quiet — background task (idle compression, retries); does + # NOT bump sessionbar to 'working' + VALID_STYLES = %i[primary quiet].freeze + + attr_reader :entry_id, :message, :style, :start_time + + # Threshold (seconds) below which a +quiet_on_fast_finish+ handle + # collapses its final frame — i.e. the progress line is REMOVED + # from the output buffer instead of being kept as a permanent + # "Executing foo… (0s)" log line. Operations that finish this fast + # didn't need a spinner in the first place; keeping the final + # frame would be visual noise. + FAST_FINISH_THRESHOLD_SECONDS = 2 + + # Show "Thinking for Ns" once the gap since the last LLM stream + # chunk reaches this many seconds. Bedrock often pauses 5–18s + # while generating large content blocks (long tool_use JSON in + # particular); without this hint users assume the agent is stuck. + IDLE_HINT_THRESHOLD_SECONDS = 2 + + # @param owner [#register_progress, #unregister_progress, #render_frame] + # @param message [String] Initial progress message. + # @param style [Symbol] :primary or :quiet (see VALID_STYLES). + # @param tick_interval [Float] Seconds between auto-renders. + # @param quiet_on_fast_finish [Boolean] When true and the elapsed + # time on +finish+ is under FAST_FINISH_THRESHOLD_SECONDS, the + # owner is told to remove the progress entry (+final_frame: nil+) + # instead of committing a permanent final frame. This is the + # preferred mode for tool execution wrappers, where fast tools + # (edit, write, read) don't need a lingering "Executing edit… + # (0s)" line after completion. + # @param clock [#call] Test hook: returns current Time (default Time.now). + def initialize(owner:, message:, style: :primary, tick_interval: DEFAULT_TICK_INTERVAL, quiet_on_fast_finish: false, clock: -> { Time.now }) + unless VALID_STYLES.include?(style) + raise ArgumentError, "unknown progress style: #{style.inspect} (valid: #{VALID_STYLES.inspect})" + end + + @owner = owner + @message = message.to_s + @style = style + @tick_interval = tick_interval + @quiet_on_fast_finish = quiet_on_fast_finish + @clock = clock + + @entry_id = nil + @start_time = nil + @ticker = nil + @state = :fresh # :fresh → :running → :closed + @unregistered = false + @metadata = {} + @last_chunk_at = nil + @monitor = Monitor.new + end + + # Start rendering. Registers with the owner (allocating an entry id + # and pushing onto its stack) and launches the ticker thread. + # + # @return [self] + def start + @monitor.synchronize do + return self unless @state == :fresh + + @state = :running + @start_time = @clock.call + @last_chunk_at = @start_time + @entry_id = @owner.register_progress(self) + end + + # Fire one initial frame synchronously so the user sees the + # spinner immediately — no "blank line for half a second" bug. + render_now + + start_ticker + self + end + + # Change the message or metadata mid-flight. Safe to call from any + # thread. Triggers an immediate re-render (if top-of-stack; the + # owner will ignore the call otherwise). + # + # @param message [String, nil] + # @param metadata [Hash] Renderer-specific extras (e.g. retry counts). + def update(message: nil, metadata: nil) + @monitor.synchronize do + return if @state != :running + @message = message.to_s if message + if metadata + @metadata = metadata + @last_chunk_at = @clock.call + end + end + end + + # Stop the ticker, render one final frame, and unregister from the + # owner. Idempotent and crash-safe — if a previous finish was + # interrupted (e.g. Thread#raise(AgentInterrupted) hit between + # +stop_ticker+ and +unregister_progress+), a follow-up finish + # will still complete the unregister so the handle does not stay + # orphaned on the owner's progress stack. + # + # @param final_message [String, nil] Optional override for the last + # frame. If nil, the handle composes "… (s)". + def finish(final_message: nil) + snapshot = @monitor.synchronize do + return if @unregistered + first_close = @state == :running + @state = :closed if first_close + { + first_close: first_close, + message: final_message || @message, + elapsed: elapsed_seconds, + } + end + + stop_ticker + final_frame = + if @quiet_on_fast_finish && snapshot[:elapsed] < FAST_FINISH_THRESHOLD_SECONDS + nil + else + compose_final_frame(snapshot[:message], snapshot[:elapsed]) + end + @owner.unregister_progress(self, final_frame: final_frame) + @monitor.synchronize { @unregistered = true } + end + alias_method :cancel, :finish + + # True while the ticker thread is alive. + def ticker_alive? + t = @ticker + !!(t && t.alive?) + end + + # True between +start+ and +finish+. + def running? + @monitor.synchronize { @state == :running } + end + + # Compose the current visual frame. The owner gets this string via + # +render_frame+ and is responsible for writing it into the entry. + def current_frame + @monitor.synchronize do + compose_frame(@message, elapsed_seconds, @metadata, idle_seconds) + end + end + + # ---- owner-facing hooks (Plan B stack machinery) ---------------- + # + # These double-underscore methods are part of the owner protocol. + # They are NOT meant for general callers. + + # Owner calls this when this handle is being pushed below a new + # top. The handle loses its OutputBuffer entry until restored. + def __detach_entry! + @monitor.synchronize { @entry_id = nil } + end + + # Owner calls this when this handle becomes top-of-stack again + # (the handle above finished). A fresh entry id is supplied. + def __reattach_entry!(new_entry_id) + @monitor.synchronize { @entry_id = new_entry_id } + render_now + end + + # Like __reattach_entry! but skips the render_now hop. Used by the + # owner when it has just painted a frame into the new entry itself + # (e.g. while rotating the handle to remain at the buffer tail) and + # is still inside its own synchronization — calling render_now there + # would re-enter the owner's mutex. + def __rebind_entry!(new_entry_id) + @monitor.synchronize { @entry_id = new_entry_id } + end + + # Test hook: force a synchronous render regardless of tick cadence. + def __force_render! + render_now + end + + private def start_ticker + @ticker = Thread.new do + Thread.current.name = "progress-ticker-#{object_id}" + begin + loop do + sleep @tick_interval + break if @monitor.synchronize { @state != :running } + render_now + end + rescue StandardError + # Ticker must never crash the process — the caller's main + # thread still owns the real control flow. + end + end + end + + private def stop_ticker + t = @ticker + return unless t + # The loop checks @state on each iteration, so once we're + # :closed the next wake-up exits cleanly. Give it 1s; if + # something is stuck, kill as a last resort. + joined = t.join(1.0) + t.kill unless joined + @ticker = nil + end + + private def render_now + frame = current_frame + @owner.render_frame(self, frame) + rescue StandardError + # Rendering must never propagate. + end + + private def elapsed_seconds + return 0 unless @start_time + (@clock.call - @start_time).to_i + end + + # Seconds since the last metadata update (i.e. the last LLM stream + # chunk that carried token info). Used to surface "Thinking for Ns" + # in the live frame so users can see the agent isn't stuck even + # when token counts plateau during long Bedrock content blocks. + private def idle_seconds + return 0 unless @last_chunk_at + (@clock.call - @last_chunk_at).to_i + end + + # Live-frame format: + # "… (s · ↓N tokens · reasoning…)" + # The "reasoning" tail only appears once tokens have started + # streaming AND the gap since the last chunk reaches the threshold + # — signalling the model is between tool_use blocks doing extended + # thinking. No seconds shown there to avoid duplicating elapsed; + # animated dots (1→2→3) provide the "still alive" cue. + private def compose_frame(message, elapsed, metadata, idle = 0) + head = message.to_s + if metadata && (attempt = metadata[:attempt]) && (total = metadata[:total]) + head = "#{head} [#{attempt}/#{total}]" + end + + token_part = metadata && format_token_progress(metadata) + + suffix_parts = [] + suffix_parts << "#{elapsed}s" if elapsed > 0 + suffix_parts << token_part if token_part + if token_part && idle >= IDLE_HINT_THRESHOLD_SECONDS + suffix_parts << "reasoning #{spinner_frame} " + end + + return "#{head}…" if suffix_parts.empty? + "#{head}… (#{suffix_parts.join(" · ")})" + end + + SPINNER_FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze + SPINNER_INTERVAL_MS = 250 + + private def spinner_frame + ms = (@clock.call.to_f * 1000).to_i + SPINNER_FRAMES[(ms / SPINNER_INTERVAL_MS) % SPINNER_FRAMES.length] + end + + # Render LLM streaming token counts as "↑1.2k ↓234 tokens". + # When input_tokens is unknown (e.g. OpenAI-compat streaming where + # prompt_tokens only arrives in the final frame), shows "↑—" so the + # column doesn't flicker between absent / present. + private def format_token_progress(metadata) + output = metadata[:output_tokens] + return nil if output.nil? || output.to_i <= 0 + "↓ #{compact_count(output.to_i)} tokens" + end + + private def compact_count(n) + return n.to_s if n < 1000 + if n < 1_000_000 + k = n / 1000.0 + k >= 10 ? "#{k.to_i}k" : "%.1fk" % k + else + m = n / 1_000_000.0 + m >= 10 ? "#{m.to_i}M" : "%.1fM" % m + end + end + + # Final frame (used by +finish+). Same as +compose_frame+ but we + # always include elapsed time so the last line carries a duration. + private def compose_final_frame(message, elapsed) + "#{message}… (#{elapsed}s)" + end + end + end +end diff --git a/lib/clacky/ui2/progress_indicator.rb b/lib/clacky/ui2/progress_indicator.rb new file mode 100644 index 0000000..1003847 --- /dev/null +++ b/lib/clacky/ui2/progress_indicator.rb @@ -0,0 +1,55 @@ +# frozen_string_literal: true + +module Clacky + class ProgressIndicator + def initialize(verbose: false, message: nil) + @verbose = verbose + @start_time = nil + @custom_message = message + @thinking_verb = message || THINKING_VERBS.sample + @running = false + @update_thread = nil + end + + def start + @start_time = Time.now + @running = true + # Save cursor position after the [..] symbol + print "\e[s" # Save cursor position + print_thinking_status("#{@thinking_verb}… (ctrl+c to interrupt)") + + # Start background thread to update elapsed time + @update_thread = Thread.new do + while @running + sleep 0.1 + update if @running + end + end + end + + def update + return unless @start_time + + elapsed = (Time.now - @start_time).to_i + print_thinking_status("#{@thinking_verb}… (ctrl+c to interrupt · #{elapsed}s)") + end + + def finish + @running = false + @update_thread&.join + # Restore cursor and clear to end of line + print "\e[u" # Restore cursor position + print "\e[K" # Clear to end of line + puts "" # Add newline after finishing + end + + + def print_thinking_status(text) + print "\e[u" # Restore cursor position (to after [..] symbol) + print "\e[K" # Clear to end of line from cursor + print text + print " " + $stdout.flush + end + end +end diff --git a/lib/clacky/ui2/screen_buffer.rb b/lib/clacky/ui2/screen_buffer.rb new file mode 100644 index 0000000..ecd0eb4 --- /dev/null +++ b/lib/clacky/ui2/screen_buffer.rb @@ -0,0 +1,273 @@ +# frozen_string_literal: true + +require "tty-screen" +require "io/console" +require_relative "../utils/encoding" + +module Clacky + module UI2 + # ScreenBuffer manages terminal screen state and provides low-level rendering primitives + class ScreenBuffer + attr_reader :width, :height + + def initialize + @width = TTY::Screen.width + @height = TTY::Screen.height + @buffer = [] + @last_input_time = nil + @rapid_input_threshold = 0.01 # 10ms threshold for detecting paste-like rapid input + + # Keep stdin in UTF-8 mode so getc returns complete multi-byte characters (e.g. CJK). + # Switching to BINARY would cause getc to return one byte at a time, breaking Chinese input. + $stdin.set_encoding('UTF-8') + end + + # Move cursor to specific position (0-indexed) + # @param row [Integer] Row position + # @param col [Integer] Column position + def move_cursor(row, col) + print "\e[#{row + 1};#{col + 1}H" + end + + # Clear screen with different modes: + # :preserve - clear visible screen, scrollback history preserved (default) + # :current - cursor to top-left and erase to end, no new scrollback produced + # :reset - clear visible screen AND scrollback history (full reset) + # @param mode [Symbol] Clear mode (:preserve, :current, :reset) + def clear_screen(mode: :preserve) + case mode + when :reset + print "\e[3J" # erase scrollback buffer + print "\e[H\e[J" # cursor to top-left, erase to end of screen + when :current + print "\e[H\e[J" # cursor to top-left, erase to end of screen + else # :preserve + print "\e[2J\e[H" # erase visible screen, scrollback preserved + end + move_cursor(0, 0) + end + + # Clear current line + def clear_line + print "\e[2K" + end + + # Clear from cursor to end of line + def clear_to_eol + print "\e[K" + end + + # Hide cursor + def hide_cursor + print "\e[?25l" + end + + # Show cursor + def show_cursor + print "\e[?25h" + end + + # Save cursor position + def save_cursor + print "\e[s" + end + + # Restore cursor position + def restore_cursor + print "\e[u" + end + + # Enable alternative screen buffer (like vim/less) + def enable_alt_screen + print "\e[?1049h" + end + + # Disable alternative screen buffer + def disable_alt_screen + print "\e[?1049l" + end + + # Set scroll region (DECSTBM - DEC Set Top and Bottom Margins) + # Content written in this region will scroll, content outside will stay fixed + # @param top [Integer] Top row (1-indexed) + # @param bottom [Integer] Bottom row (1-indexed) + def set_scroll_region(top, bottom) + print "\e[#{top};#{bottom}r" + end + + # Reset scroll region to full screen + def reset_scroll_region + print "\e[r" + end + + # Scroll the scroll region up by n lines + # @param n [Integer] Number of lines to scroll + def scroll_up(n = 1) + print "\e[#{n}S" + end + + # Scroll the scroll region down by n lines + # @param n [Integer] Number of lines to scroll + def scroll_down(n = 1) + print "\e[#{n}T" + end + + # Get current screen dimensions + def update_dimensions + @width = TTY::Screen.width + @height = TTY::Screen.height + end + + # Enable raw mode (disable line buffering) + def enable_raw_mode + $stdin.raw! + end + + # Disable raw mode + def disable_raw_mode + $stdin.cooked! + end + + # Read a single character without echo + # @param timeout [Float] Timeout in seconds (nil for blocking) + # @return [String, nil] Character or nil if timeout + def read_char(timeout: nil) + if timeout + return nil unless IO.select([$stdin], nil, nil, timeout) + end + + $stdin.getc + end + + # Read a key including special keys (arrows, etc.) + # @param timeout [Float] Timeout in seconds + # @return [Symbol, String, Hash, nil] Key symbol, character, or { type: :rapid_input, text: String } + def read_key(timeout: nil) + current_time = Time.now.to_f + is_rapid_input = @last_input_time && (current_time - @last_input_time) < @rapid_input_threshold + @last_input_time = current_time + + char = read_char(timeout: timeout) + return nil unless char + + # Convert raw BINARY bytes to valid UTF-8. Invalid/undefined bytes are dropped + # rather than raising ArgumentError (which would crash the input loop). + char = safe_to_utf8(char) if char.is_a?(String) + + # Handle escape sequences for special keys + if char == "\e" + # Non-blocking read for escape sequence + char2 = read_char(timeout: 0.01) + return :escape unless char2 + + if char2 == "[" + char3 = read_char(timeout: 0.01) + case char3 + when "A" then return :up_arrow + when "B" then return :down_arrow + when "C" then return :right_arrow + when "D" then return :left_arrow + when "H" then return :home + when "F" then return :end + when "Z" then return :shift_tab + when "3" + char4 = read_char(timeout: 0.01) + return :delete if char4 == "~" + end + end + end + + # Check if there are more characters available (for rapid input detection) + has_more_input = IO.select([$stdin], nil, nil, 0) + + # If this is rapid input or there are more characters available + if is_rapid_input || has_more_input + buffer = char.to_s.dup + + # Keep reading available characters + loop_count = 0 + empty_checks = 0 + + loop do + # Check if there's data available immediately + has_data = IO.select([$stdin], nil, nil, 0) + + if has_data + next_char = $stdin.getc rescue nil + break unless next_char + + next_char = safe_to_utf8(next_char) + buffer << next_char + loop_count += 1 + empty_checks = 0 # Reset empty check counter + else + # No immediate data, but wait a bit to see if more is coming + # This handles the case where paste data arrives in chunks + empty_checks += 1 + if empty_checks == 1 + # First empty check - wait 10ms for more data + sleep 0.01 + else + # Second empty check - really no more data + break + end + end + end + + # If we buffered multiple characters or newlines, treat as rapid input (paste) + if buffer.length > 1 || buffer.include?("\n") || buffer.include?("\r") + # Ensure the accumulated buffer is valid UTF-8 before regex operations + buffer = safe_to_utf8(buffer) + # Remove any trailing \r or \n from rapid input buffer + cleaned_buffer = buffer.gsub(/[\r\n]+\z/, '') + return { type: :rapid_input, text: cleaned_buffer } if cleaned_buffer.length > 0 + end + + # Single character, continue to normal handling + char = buffer[0] if buffer.length == 1 + end + + # Handle control characters + case char + when "\r" then :enter + when "\n" then :newline # Shift+Enter sends \n + when "\u007F", "\b" then :backspace + when "\u0001" then :ctrl_a + when "\u0002" then :ctrl_b + when "\u0003" then :ctrl_c + when "\u0004" then :ctrl_d + when "\u0005" then :ctrl_e + when "\u0006" then :ctrl_f + when "\u000B" then :ctrl_k + when "\u000C" then :ctrl_l + when "\u000F" then :ctrl_o + when "\u0012" then :ctrl_r + when "\u0015" then :ctrl_u + when "\u0016" then :ctrl_v + when "\u0017" then :ctrl_w + when "\t" then :tab + else char + end + end + + # Flush output + def flush + $stdout.flush + end + + + # Ensure a string is valid UTF-8. + # stdin stays in UTF-8 mode so getc returns complete characters (including CJK). + # This method handles the rare case where an invalid byte slips through + # (e.g. a stray terminal escape or a partial sequence) by scrubbing it out + # rather than letting ArgumentError crash the input loop. + # @param str [String] String from getc (UTF-8 encoded, but may have invalid bytes) + # @return [String] Valid UTF-8 string + private def safe_to_utf8(str) + return str if str.valid_encoding? + + Clacky::Utils::Encoding.sanitize_utf8(str) + end + end + end +end diff --git a/lib/clacky/ui2/terminal_detector.rb b/lib/clacky/ui2/terminal_detector.rb new file mode 100644 index 0000000..a86ca15 --- /dev/null +++ b/lib/clacky/ui2/terminal_detector.rb @@ -0,0 +1,119 @@ +# frozen_string_literal: true + +module Clacky + module UI2 + # TerminalDetector - Detect terminal background color before UI starts + class TerminalDetector + # Detect if terminal has dark background + # Uses multiple strategies to determine background color + # @return [Boolean] true if dark background, false if light background + def self.detect_dark_background + # Strategy 1: Check $COLORFGBG environment variable (fast, set by some terminals) + if ENV.key?('COLORFGBG') + # Format is like "15;0" where second number is background ANSI code + # 0-7 are dark, 8-15 are light + parts = ENV['COLORFGBG'].split(';') + if parts.size >= 2 + bg_code = parts.last.to_i + if bg_code >= 0 && bg_code <= 15 + return bg_code < 8 + end + end + end + + # Strategy 2: Query terminal background using OSC 11 sequence + begin + rgb = query_terminal_background_color + if rgb + # Calculate luma (perceived brightness): 0.0 (black) to 1.0 (white) + # Formula: 0.299*R + 0.587*G + 0.114*B + luma = (0.299 * rgb[:r] + 0.587 * rgb[:g] + 0.114 * rgb[:b]) / 255.0 + return luma < 0.5 + end + rescue => e + # Silently fall through to default + end + + # Default: assume dark background (most common for terminals) + true + end + + # Query terminal background color using OSC 11 sequence + # This should be called BEFORE UI starts to avoid interference + # @return [Hash, nil] RGB hash like {r: 26, g: 43, b: 60} or nil if failed + def self.query_terminal_background_color + require 'io/console' + + # Only works on TTY + return nil unless $stdin.tty? + return nil unless $stdout.tty? + + old_state = nil + begin + # Save current terminal state + old_state = $stdin.raw! + + # Clear any pending input first + while IO.select([$stdin], nil, nil, 0) + $stdin.read_nonblock(1000) rescue break + end + + # Send OSC 11 query: ESC ] 11 ; ? ST + # Use ST terminator (ESC \) instead of BEL for better compatibility + $stdout.print "\e]11;?\e\\\\" + $stdout.flush + + # Read response with timeout (terminal should respond quickly) + response = String.new # Use String.new to create mutable string + timeout = 0.1 # 100ms timeout + start_time = Time.now + + while Time.now - start_time < timeout + if IO.select([$stdin], nil, nil, 0.01) + char = $stdin.read_nonblock(1) rescue nil + break unless char + response << char + + # Look for complete response pattern + # Response format: ESC ] 11 ; rgb:RRRR/GGGG/BBBB BEL or ST + if response.match?(/\e\]11;rgb:[0-9a-fA-F]+\/[0-9a-fA-F]+\/[0-9a-fA-F]+(\e\\|\a)/) + break + end + + # Safety: stop if response gets too long (probably garbage) + break if response.length > 100 + end + end + + # Parse response: look for rgb:RRRR/GGGG/BBBB + # Example: ]11;rgb:1a2b/3c4d/5e6f or ]11;rgb:ffff/ffff/ffff + if response =~ /rgb:([0-9a-fA-F]+)\/([0-9a-fA-F]+)\/([0-9a-fA-F]+)/ + r_hex, g_hex, b_hex = $1, $2, $3 + # Take first 2 hex digits (terminals may return 4 or 2 hex digits per channel) + r = r_hex[0, 2].to_i(16) + g = g_hex[0, 2].to_i(16) + b = b_hex[0, 2].to_i(16) + return { r: r, g: g, b: b } + end + + nil + rescue => e + # If anything goes wrong, return nil to fall back to default + nil + ensure + # Make sure we restore terminal state even if error occurs + old_state.restore if old_state rescue nil + + # Clear any remaining input to prevent leakage + begin + while IO.select([$stdin], nil, nil, 0) + $stdin.read_nonblock(1000) rescue break + end + rescue + # Ignore cleanup errors + end + end + end + end + end +end diff --git a/lib/clacky/ui2/theme_manager.rb b/lib/clacky/ui2/theme_manager.rb new file mode 100644 index 0000000..0e6e126 --- /dev/null +++ b/lib/clacky/ui2/theme_manager.rb @@ -0,0 +1,85 @@ +# frozen_string_literal: true + +require_relative "themes/base_theme" +require_relative "themes/hacker_theme" +require_relative "themes/minimal_theme" + +module Clacky + module UI2 + # ThemeManager handles theme registration and switching + class ThemeManager + class << self + def instance + @instance ||= new + end + + # Delegate methods to instance + def current_theme + instance.current_theme + end + + def set_theme(name) + instance.set_theme(name) + end + + def available_themes + instance.available_themes + end + + def register_theme(name, theme_class) + instance.register_theme(name, theme_class) + end + end + + def initialize + @themes = {} + @current_theme = nil + @is_dark_background = nil # Store detected background mode + register_default_themes + set_theme(:hacker) + end + + # Set the detected terminal background mode + # This should be called BEFORE UI starts (from CLI) + # @param is_dark [Boolean] true if dark background, false if light + def set_background_mode(is_dark) + @is_dark_background = is_dark + # Pass to current theme if already initialized + @current_theme&.set_background_mode(is_dark) + end + + # Get the detected background mode + # @return [Boolean, nil] true if dark, false if light, nil if not detected + def dark_background? + @is_dark_background + end + + def current_theme + @current_theme + end + + def set_theme(name) + name = name.to_sym + raise ArgumentError, "Unknown theme: #{name}" unless @themes.key?(name) + + @current_theme = @themes[name].new + # Pass background mode to new theme if already detected + @current_theme.set_background_mode(@is_dark_background) unless @is_dark_background.nil? + end + + def available_themes + @themes.keys + end + + def register_theme(name, theme_class) + @themes[name.to_sym] = theme_class + end + + + def register_default_themes + register_theme(:hacker, Themes::HackerTheme) + register_theme(:minimal, Themes::MinimalTheme) + end + end + end +end diff --git a/lib/clacky/ui2/themes/base_theme.rb b/lib/clacky/ui2/themes/base_theme.rb new file mode 100644 index 0000000..2c32861 --- /dev/null +++ b/lib/clacky/ui2/themes/base_theme.rb @@ -0,0 +1,105 @@ +# frozen_string_literal: true + +require "pastel" + +module Clacky + module UI2 + module Themes + # BaseTheme defines the abstract interface for all themes + # Subclasses MUST define SYMBOLS and COLORS constants + class BaseTheme + def initialize + @pastel = Pastel.new + @is_dark_background = nil # Will be set by ThemeManager + validate_theme_definition! + end + + # Set background mode (called by ThemeManager after detection) + # @param is_dark [Boolean] true if dark background, false if light + def set_background_mode(is_dark) + @is_dark_background = is_dark + end + + # Get all symbols defined by this theme + # @return [Hash] Symbol definitions + def symbols + self.class::SYMBOLS + end + + # Get all colors defined by this theme + # @return [Hash] Color definitions + def colors + self.class::COLORS + end + + # Get symbol for a specific key + # @param key [Symbol] Symbol key + # @return [String] Symbol string + def symbol(key) + symbols[key] || "[??]" + end + + # Get symbol color for a specific key + # @param key [Symbol] Color key + # @return [Symbol] Pastel color method name + def symbol_color(key) + colors.dig(key, 0) || :white + end + + # Get text color for a specific key + # Automatically selects appropriate color based on terminal background + # Color format: [symbol_color, dark_bg_text_color, light_bg_text_color] + # @param key [Symbol] Color key + # @return [Symbol] Pastel color method name + def text_color(key) + color_def = colors[key] + return :white unless color_def + + # Use index 1 for dark background, index 2 for light background + dark_background? ? color_def[1] : color_def[2] + end + + # Format symbol with its color + # @param key [Symbol] Symbol key (e.g., :user, :assistant) + # @return [String] Colored symbol + def format_symbol(key) + @pastel.public_send(symbol_color(key), symbol(key)) + end + + # Format text with color for given key + # @param text [String] Text to format + # @param key [Symbol] Color key (e.g., :user, :assistant) + # @return [String] Colored text + def format_text(text, key) + @pastel.public_send(text_color(key), text) + end + + # Theme name for display (subclasses should override) + # @return [String] Theme name + def name + raise NotImplementedError, "Subclass must implement #name method" + end + + # Check if terminal has dark background + # Uses pre-detected value from ThemeManager, or defaults to true + # @return [Boolean] true if dark background, false if light background + def dark_background? + # Use pre-detected value if available, otherwise default to dark + @is_dark_background.nil? ? true : @is_dark_background + end + + + # Validate that subclass has defined required constants + def validate_theme_definition! + unless self.class.const_defined?(:SYMBOLS) + raise NotImplementedError, "Theme #{self.class.name} must define SYMBOLS constant" + end + + unless self.class.const_defined?(:COLORS) + raise NotImplementedError, "Theme #{self.class.name} must define COLORS constant" + end + end + end + end + end +end diff --git a/lib/clacky/ui2/themes/hacker_theme.rb b/lib/clacky/ui2/themes/hacker_theme.rb new file mode 100644 index 0000000..12008a5 --- /dev/null +++ b/lib/clacky/ui2/themes/hacker_theme.rb @@ -0,0 +1,62 @@ +# frozen_string_literal: true + +require_relative "base_theme" + +module Clacky + module UI2 + module Themes + # HackerTheme - Matrix/hacker-style with bracket symbols + class HackerTheme < BaseTheme + SYMBOLS = { + user: "[>>]", + assistant: "[<<]", + tool_call: "[=>]", + tool_result: "[<=]", + tool_denied: "[!!]", + tool_planned: "[??]", + tool_error: "[XX]", + thinking: "[..]", + working: "[..]", + success: "[OK]", + error: "[ER]", + warning: "[!!]", + info: "[--]", + task: "[##]", + progress: "[>>]", + file: "[F]", + command: "[C]", + cached: "[*]" + }.freeze + + COLORS = { + # Format: [symbol_color, dark_bg_text, light_bg_text] + user: [:bright_black, :white, :black], # User prompt and input + assistant: [:bright_green, :bright_black, :bright_black], # AI response - keep green hacker style + tool_call: [:bright_cyan, :cyan, :cyan], # Tool execution + tool_result: [:bright_cyan, :bright_black, :bright_black], # Tool output + tool_denied: [:bright_yellow, :yellow, :yellow], # Denied actions + tool_planned: [:bright_cyan, :cyan, :cyan], # Planned actions + tool_error: [:bright_red, :red, :red], # Errors + thinking: [:bright_black, :bright_black, :bright_black], # Thinking status + working: [:bright_yellow, :yellow, :yellow], # Working status + success: [:bright_green, :green, :green], # Success messages + error: [:bright_red, :red, :red], # Error messages + warning: [:bright_yellow, :yellow, :yellow], # Warnings + info: [:bright_black, :bright_black, :bright_black], # Info messages + task: [:bright_yellow, :bright_black, :bright_black], # Task items + progress: [:bright_cyan, :cyan, :cyan], # Progress indicators + file: [:cyan, :bright_black, :bright_black], # File references + command: [:cyan, :bright_black, :bright_black], # Command references + cached: [:cyan, :cyan, :cyan], # Cached indicators + # Status bar colors + statusbar_path: [:bright_black, :bright_black, :bright_black], # Path + statusbar_secondary: [:bright_black, :bright_black, :bright_black] # Model/tasks/cost + }.freeze + + def name + "hacker" + end + end + end + end +end diff --git a/lib/clacky/ui2/themes/minimal_theme.rb b/lib/clacky/ui2/themes/minimal_theme.rb new file mode 100644 index 0000000..ad0939c --- /dev/null +++ b/lib/clacky/ui2/themes/minimal_theme.rb @@ -0,0 +1,56 @@ +# frozen_string_literal: true + +require_relative "base_theme" + +module Clacky + module UI2 + module Themes + # MinimalTheme - Clean, simple symbols + class MinimalTheme < BaseTheme + SYMBOLS = { + user: ">", + assistant: "<", + tool_call: "*", + tool_result: "-", + tool_denied: "!", + tool_planned: "?", + tool_error: "x", + thinking: ".", + working: ".", + success: "+", + error: "x", + warning: "!", + info: "-", + task: "#", + progress: ">" + }.freeze + + COLORS = { + # Format: [symbol_color, dark_bg_text, light_bg_text] + user: [:bright_black, :bright_black, :black], # User prompt and input + assistant: [:green, :bright_black, :bright_black], # AI response + tool_call: [:cyan, :cyan, :cyan], # Tool execution + tool_result: [:cyan, :bright_black, :bright_black], # Tool output + tool_denied: [:yellow, :yellow, :yellow], # Denied actions + tool_planned: [:cyan, :cyan, :cyan], # Planned actions + tool_error: [:red, :red, :red], # Errors + thinking: [:bright_black, :bright_black, :bright_black], # Thinking status + working: [:bright_yellow, :yellow, :yellow], # Working status + success: [:green, :green, :green], # Success messages + error: [:red, :red, :red], # Error messages + warning: [:yellow, :yellow, :yellow], # Warnings + info: [:bright_black, :bright_black, :bright_black], # Info messages + task: [:yellow, :bright_black, :bright_black], # Task items + progress: [:cyan, :cyan, :cyan], # Progress indicators + # Status bar colors + statusbar_path: [:bright_black, :bright_black, :bright_black], # Path + statusbar_secondary: [:bright_black, :bright_black, :bright_black] # Model/tasks/cost + }.freeze + + def name + "minimal" + end + end + end + end +end diff --git a/lib/clacky/ui2/thinking_verbs.rb b/lib/clacky/ui2/thinking_verbs.rb new file mode 100644 index 0000000..17fdee8 --- /dev/null +++ b/lib/clacky/ui2/thinking_verbs.rb @@ -0,0 +1,26 @@ +# frozen_string_literal: true + +module Clacky + THINKING_VERBS = [ + "Cogitating", + "Pondering", + "Ruminating", + "Deliberating", + "Contemplating", + "Flibbertigibbeting", + "Percolating", + "Noodling", + "Brewing", + "Marinating", + "Stewing", + "Mulling", + "Processing", + "Computing", + "Calculating", + "Analyzing", + "Synthesizing", + "Ideating", + "Brainstorming", + "Reasoning" + ].freeze +end diff --git a/lib/clacky/ui2/ui_controller.rb b/lib/clacky/ui2/ui_controller.rb new file mode 100644 index 0000000..6029e44 --- /dev/null +++ b/lib/clacky/ui2/ui_controller.rb @@ -0,0 +1,1946 @@ +# frozen_string_literal: true + +require_relative "layout_manager" +require_relative "view_renderer" +require_relative "progress_handle" +require_relative "components/input_area" +require_relative "components/todo_area" +require_relative "components/welcome_banner" +require_relative "components/inline_input" +require_relative "thinking_verbs" +require_relative "../ui_interface" + +module Clacky + module UI2 + # UIController is the MVC controller layer that coordinates UI state and user interactions + class UIController + include Clacky::UIInterface + + attr_reader :layout, :renderer, :running, :inline_input, :input_area + attr_accessor :config, :available_models + + def initialize(config = {}) + @renderer = ViewRenderer.new + + # Set theme if specified + ThemeManager.set_theme(config[:theme]) if config[:theme] + + # Store configuration + @config = { + working_dir: config[:working_dir], + mode: config[:mode], + model: config[:model], + theme: config[:theme] + } + + # Initialize layout components + @input_area = Components::InputArea.new + @todo_area = Components::TodoArea.new + @welcome_banner = Components::WelcomeBanner.new + @inline_input = nil # Created when needed + @feedback_countdown = nil # Active auto-approve feedback countdown session + @layout = LayoutManager.new( + input_area: @input_area, + todo_area: @todo_area + ) + + @running = false + @input_callback = nil + @interrupt_callback = nil + @time_machine_callback = nil + @model_switch_callback = nil + @tasks_count = 0 + @total_cost = 0.0 + @session_id = nil + @last_diff_lines = nil + + # ── Progress subsystem (v2: owned handles, stacked) ────────────── + # Every progress indicator is an owned ProgressHandle. UiController + # is the "owner" in the handle protocol: it keeps a stack of live + # handles, only the top of which is rendered. See ProgressHandle + # for the full protocol and stack semantics. + @progress_stack = [] + @progress_mutex = Mutex.new + end + + # Start the UI controller + def start + initialize_and_show_banner + start_input_loop + end + + # Initialize screen and show banner (separate from input loop) + # @param recent_user_messages [Array, nil] Recent user messages when loading session + def initialize_and_show_banner(recent_user_messages: nil) + @running = true + + # Set session bar data before initializing screen + @input_area.update_sessionbar( + session_id: @session_id, + working_dir: @config[:working_dir], + mode: @config[:mode], + model: @config[:model], + tasks: @tasks_count, + cost: @total_cost + ) + + @layout.initialize_screen + + # Display welcome banner or session history + if recent_user_messages && !recent_user_messages.empty? + display_session_history(recent_user_messages) + else + display_welcome_banner + end + end + + # Start input loop (separate from initialization) + def start_input_loop + @running = true + input_loop + end + + # Set skill loader for command suggestions in the input area + # @param skill_loader [Clacky::SkillLoader] The skill loader instance + # @param agent_profile [Clacky::AgentProfile, nil] Current agent profile for skill filtering + def set_skill_loader(skill_loader, agent_profile = nil) + @input_area.set_skill_loader(skill_loader, agent_profile) + end + + # Update session bar with current stats + # @param tasks [Integer] Number of completed tasks (optional) + # @param cost [Float] Total cost (optional) + # @param cost_source [Symbol, nil] :api / :price / :default (optional) + # @param status [String] Workspace status ('idle' or 'working') (optional) + # @param latency [Hash, nil] Latency metrics; accepted but not displayed in the TUI. + # @param session_id [String, nil] Full session id; rendered as first 8 chars (parity with WebUI). + def update_sessionbar(tasks: nil, cost: nil, cost_source: nil, status: nil, latency: nil, session_id: nil) + @tasks_count = tasks if tasks + @total_cost = cost if cost + @session_id = session_id if session_id + @input_area.update_sessionbar( + session_id: @session_id, + working_dir: @config[:working_dir], + mode: @config[:mode], + model: @config[:model], + tasks: @tasks_count, + cost: @total_cost, + cost_source: cost_source, + status: status + ) + @layout.render_input + end + + # Toggle permission mode between confirm_safes and auto_approve + def toggle_mode + current_mode = @config[:mode] + new_mode = case current_mode.to_s + when /confirm_safes/ + "auto_approve" + when /auto_approve/ + "confirm_safes" + else + "auto_approve" # Default to auto_approve if unknown mode + end + + @config[:mode] = new_mode + + # Notify CLI to update agent_config + @mode_toggle_callback&.call(new_mode) + + update_sessionbar + end + + # Stop the UI controller. Keeps the screen by default so any final + # output (e.g. the "clacky -a " resume hint) survives in scrollback. + def stop(clear_screen: false) + @running = false + @layout.cleanup_screen(clear_screen: clear_screen) + end + + # Clear the input area + def clear_input + @input_area.clear + end + + # Set input tips message + # @param message [String] Tip message to display + # @param type [Symbol] Tip type (:info, :warning, etc.) + def set_input_tips(message, type: :info) + @input_area.set_tips(message, type: type) + end + + # Set callback for user input + # @param block [Proc] Callback to execute with user input + def on_input(&block) + @input_callback = block + end + + # Set callback for interrupt (Ctrl+C) + # @param block [Proc] Callback to execute on interrupt + def on_interrupt(&block) + @interrupt_callback = block + end + + # Set callback for mode toggle (Shift+Tab) + # @param block [Proc] Callback to execute on mode toggle + def on_mode_toggle(&block) + @mode_toggle_callback = block + end + + # Set callback for time machine (ESC key) + # @param block [Proc] Callback to execute on time machine + def on_time_machine(&block) + @time_machine_callback = block + end + + # Set callback for model switch (from /model slash command) + # @param block [Proc] Callback to execute on model switch + def on_model_switch(&block) + @model_switch_callback = block + end + + # Set agent for command suggestions + # @param agent [Clacky::Agent] The agent instance with skill management + # @param agent_profile [Clacky::AgentProfile, nil] Current agent profile for skill filtering + def set_agent(agent, agent_profile = nil) + @input_area.set_agent(agent, agent_profile) + end + + # Append output to the output area. + # + # If a progress indicator is currently active (somewhere in the + # buffer), rotate it to the tail after the append: business content + # ends up above, the spinner stays at the bottom. Without this, + # every subsequent ticker tick on a non-tail progress entry would + # trigger a full output repaint (visible flicker) and the visual + # order would have business messages appearing below the spinner. + def append_output(content) + @progress_mutex.synchronize do + top = @progress_stack.last + if top && top.entry_id + @layout.remove_entry(top.entry_id) + top.__detach_entry! + new_id = @layout.append_output(content) + progress_id = @layout.append_output(render_for(top)) + top.__rebind_entry!(progress_id) + new_id + else + @layout.append_output(content) + end + end + end + + # Internal append that bypasses the progress-rotation logic and the + # @progress_mutex. Used by register_progress / unregister_progress, + # which already hold the mutex and are themselves placing a fresh + # progress entry at the tail. + private def append_output_unlocked(content) + @layout.append_output(content) + end + + # Log message to output area (use instead of puts) + # @param message [String] Message to log + # @param level [Symbol] Log level (:debug, :info, :warning, :error) + def log(message, level: :info) + theme = ThemeManager.current_theme + + output = case level + when :debug + # Gray dimmed text for debug messages + theme.format_text(" [DEBUG] #{message}", :thinking) + when :info + # Info symbol with normal text + "#{theme.format_symbol(:info)} #{message}" + when :warning + # Warning rendering + @renderer.render_warning(message) + when :error + # Error rendering + @renderer.render_error(message) + else + # Default to info + "#{theme.format_symbol(:info)} #{message}" + end + + append_output(output) + end + + # Update an OutputBuffer entry's content by id. + # @param id [Integer, nil] Entry id (no-op if nil or already committed) + # @param content [String] New content for the entry + private def update_entry(id, content) + return unless id + @layout.replace_entry(id, content) + end + + # Remove an OutputBuffer entry by id (no-op if nil or committed). + # @param id [Integer, nil] + private def remove_entry(id) + return unless id + @layout.remove_entry(id) + end + + # Update todos display + # @param todos [Array] Array of todo items + def update_todos(todos) + @layout.update_todos(todos) + end + + # Display token usage statistics + # @param token_data [Hash] Token usage data containing: + # - delta_tokens: token delta from previous iteration + # - prompt_tokens: input tokens + # - completion_tokens: output tokens + # - total_tokens: total tokens + # - cache_write: cache write tokens + # - cache_read: cache read tokens + # - cost: cost for this iteration + def show_token_usage(token_data) + theme = ThemeManager.current_theme + pastel = Pastel.new + + token_info = [] + + # Delta tokens with color coding (green/yellow/red + dim) + delta_tokens = token_data[:delta_tokens] + delta_str = delta_tokens.negative? ? "#{delta_tokens}" : "+#{delta_tokens}" + color_style = if delta_tokens > 10000 + :red + elsif delta_tokens > 5000 + :yellow + else + :green + end + colored_delta = if delta_tokens.negative? + pastel.cyan(delta_str) + else + pastel.decorate(delta_str, color_style, :dim) + end + token_info << colored_delta + + # Cache status indicator (using theme) + cache_write = token_data[:cache_write] + cache_read = token_data[:cache_read] + cache_used = cache_read > 0 || cache_write > 0 + if cache_used + token_info << pastel.dim(theme.symbol(:cached)) + end + + # Input tokens (with cache breakdown if available) + prompt_tokens = token_data[:prompt_tokens] + if cache_write > 0 || cache_read > 0 + input_detail = "#{prompt_tokens} (cache: #{cache_read} read, #{cache_write} write)" + token_info << pastel.dim("Input: #{input_detail}") + else + token_info << pastel.dim("Input: #{prompt_tokens}") + end + + # Output tokens + token_info << pastel.dim("Output: #{token_data[:completion_tokens]}") + + # Total + token_info << pastel.dim("Total: #{token_data[:total_tokens]}") + + # Cost for this iteration with color coding (red/yellow for high cost, dim for normal) + # :api => "$0.001234" (exact, from API) + # :price => "~$0.001234" (estimated from pricing table) + # :default => "N/A" (model not in pricing table, unknown cost) + cost_source = token_data[:cost_source] + if cost_source == :default + token_info << pastel.dim("Cost: N/A") + elsif token_data[:cost] + cost = token_data[:cost] + cost_value = cost_source == :price ? "~$#{cost.round(6)}" : "$#{cost.round(6)}" + if cost >= 0.1 + # High cost - red warning + colored_cost = pastel.decorate(cost_value, :red, :dim) + token_info << pastel.dim("Cost: ") + colored_cost + elsif cost >= 0.05 + # Medium cost - yellow warning + colored_cost = pastel.decorate(cost_value, :yellow, :dim) + token_info << pastel.dim("Cost: ") + colored_cost + else + # Low cost - normal gray + token_info << pastel.dim("Cost: #{cost_value}") + end + end + + # Display through output system (already all dimmed, just add prefix) + token_display = pastel.dim(" [Tokens] ") + token_info.join(pastel.dim(' | ')) + append_output(token_display) + end + + # Show tool call arguments + # @param formatted_args [String] Formatted arguments string + def show_tool_args(formatted_args) + theme = ThemeManager.current_theme + append_output("\n#{theme.format_text("Args: #{formatted_args}", :thinking)}") + end + + # Show file operation preview (Write tool) + # @param path [String] File path + # @param is_new_file [Boolean] Whether this is a new file + def show_file_write_preview(path, is_new_file:) + theme = ThemeManager.current_theme + file_label = theme.format_symbol(:file) + status = is_new_file ? theme.format_text("Creating new file", :success) : theme.format_text("Modifying existing file", :warning) + append_output("\n#{file_label} #{path || '(unknown)'}") + append_output(status) + end + + # Show file operation preview (Edit tool) + # @param path [String] File path + def show_file_edit_preview(path) + theme = ThemeManager.current_theme + file_label = theme.format_symbol(:file) + append_output("\n#{file_label} #{path || '(unknown)'}") + end + + # Show file operation error + # @param error_message [String] Error message + def show_file_error(error_message) + theme = ThemeManager.current_theme + append_output(" #{theme.format_text("Warning:", :error)} #{error_message}") + end + + # Show shell command preview + # @param command [String] Shell command + def show_shell_preview(command) + theme = ThemeManager.current_theme + cmd_label = theme.format_symbol(:command) + append_output("\n#{cmd_label} #{command}") + end + + # === Semantic UI Methods (for Agent to call directly) === + + # Show assistant message + # @param content [String] Message content + def show_assistant_message(content, files:) + # Filter out thinking tags from models like MiniMax M2.1 that use ... + filtered_content = filter_thinking_tags(content) + return if filtered_content.nil? || filtered_content.strip.empty? + + output = @renderer.render_assistant_message(filtered_content) + append_output(output) + end + + # Filter out thinking tags from content + # Some models (e.g., MiniMax M2.1) wrap their reasoning in ... tags + # @param content [String] Raw content from model + # @return [String] Content with thinking tags removed + def filter_thinking_tags(content) + return content if content.nil? + + # Remove ... blocks (multiline, case-insensitive) + # Also handles variations like ... + filtered = content.gsub(%r{[\s\S]*?}mi, '') + + # Clean up multiple empty lines left behind (max 2 consecutive newlines) + filtered.gsub!(/\n{3,}/, "\n\n") + + # Remove leading and trailing whitespace + filtered.strip + end + + # Show tool call + # @param name [String] Tool name + # @param args [String, Hash] Tool arguments (JSON string or Hash) + def show_tool_call(name, args) + # Reset stdout buffer on each new tool call so previous command output + # doesn't bleed into the next one, and so the buffer is ready before + # on_output starts firing (which can happen before show_progress is called). + @stdout_lines = nil + @stdout_partial_tail = false + + # Special handling for request_user_feedback: render as a readable interactive card + # with the full question and options, rather than the truncated format_call summary. + if name.to_s == "request_user_feedback" + args_data = args.is_a?(String) ? (JSON.parse(args, symbolize_names: true) rescue {}) : args + args_data = args_data.transform_keys(&:to_sym) if args_data.is_a?(Hash) + + question = args_data[:question].to_s.strip + context = args_data[:context].to_s.strip + options = Array(args_data[:options]) + + theme = ThemeManager.current_theme + parts = [] + + parts << context unless context.empty? + parts << question unless question.empty? + + if options.any? + parts << "" + options.each_with_index { |opt, i| parts << " #{i + 1}. #{opt}" } + end + + card_text = parts.join("\n") + output = @renderer.render_system_message(card_text, prefix_newline: true) + append_output(output) + return + end + + formatted_call = format_tool_call(name, args) + output = @renderer.render_tool_call(tool_name: name, formatted_call: formatted_call) + append_output(output) + end + + # Show tool result + # @param result [String] Formatted tool result + def show_tool_result(result) + output = @renderer.render_tool_result(result: result) + append_output(output) + end + + # Show tool error + # @param error [String, Exception] Error message or exception + def show_tool_error(error) + error_msg = error.is_a?(Exception) ? error.message : error.to_s + output = @renderer.render_tool_error(error: error_msg) + append_output(output) + end + + # Receive a chunk of shell stdout from the on_output callback. + # Lines are buffered into @stdout_lines so that Ctrl+O can open a + # fullscreen live view, matching the original output_buffer interaction. + # @param lines [Array] One or more stdout chunks (may contain + # embedded newlines or be partial lines) + def show_tool_stdout(lines) + return if lines.nil? || lines.empty? + @stdout_lines ||= [] + # Chunks may carry multiple newlines or trailing partial lines. + # Re-split on \n so the fullscreen view renders one logical line per row. + lines.each do |chunk| + next if chunk.nil? || chunk.empty? + chunk.to_s.split("\n", -1).each_with_index do |part, idx| + if idx == 0 && !@stdout_lines.empty? && @stdout_partial_tail + @stdout_lines[-1] = @stdout_lines[-1] + part + else + @stdout_lines << part + end + end + # Track whether the chunk ended on a partial line (no trailing \n) + # so the next chunk's first segment appends to it instead of + # starting a new row. + @stdout_partial_tail = !chunk.to_s.end_with?("\n") + end + end + + # Show completion status (only for tasks with more than 5 iterations) + # @param iterations [Integer] Number of iterations + # @param cost [Float] Cost of this run + # @param duration [Float] Duration in seconds + # @param cache_stats [Hash] Cache statistics + # @param awaiting_user_feedback [Boolean] Whether agent is waiting for user feedback + def show_complete(iterations:, cost:, duration: nil, cache_stats: nil, awaiting_user_feedback: false, cost_source: nil) + # Update status back to 'idle' when task is complete + update_sessionbar(status: 'idle') + + # Clear user tip when agent stops working + @input_area.clear_user_tip + # Hide todo area while idle (data preserved, restored on next work) + @layout.hide_todos + @layout.render_input + + # Don't show completion message if awaiting user feedback + return if awaiting_user_feedback + + # Only show completion message for complex tasks (>5 iterations) + return if iterations <= 5 + + cache_tokens = cache_stats&.dig(:cache_read_input_tokens) + cache_requests = cache_stats&.dig(:total_requests) + cache_hits = cache_stats&.dig(:cache_hit_requests) + + output = @renderer.render_task_complete( + iterations: iterations, + cost: cost, + duration: duration, + cache_tokens: cache_tokens, + cache_requests: cache_requests, + cache_hits: cache_hits + ) + append_output(output) + end + + # Show progress indicator with dynamic elapsed time + # @param message [String] Progress message (optional, will use random thinking verb if nil) + # --------------------------------------------------------------------- + # Progress indicator API (v2) + # + # The preferred public API is +start_progress+ / +with_progress+, which + # returns a ProgressHandle the caller owns. Use +with_progress+ whenever + # possible — it uses +ensure+ to guarantee cleanup even on exceptions + # (e.g. AgentInterrupted during idle compression). + # + # The legacy +show_progress(message, phase:, ...)+ method is kept as a + # thin shim for existing call sites that haven't been migrated yet. + # --------------------------------------------------------------------- + + # Start a new progress indicator and return its owned handle. + # + # @param message [String] Initial progress message. + # @param style [Symbol] :primary (foreground, yellow, bumps sessionbar) + # or :quiet (background, gray, no sessionbar change). + # @param quiet_on_fast_finish [Boolean] See ProgressHandle — when true, + # a finish that elapses under FAST_FINISH_THRESHOLD_SECONDS removes + # the entry instead of leaving a permanent final frame. Preferred + # for tool-execution wrappers. + # @return [Clacky::UI2::ProgressHandle] + def start_progress(message: nil, style: :primary, quiet_on_fast_finish: false) + display = (message.nil? || message.to_s.strip.empty?) ? Clacky::THINKING_VERBS.sample : message.to_s + ProgressHandle.new( + owner: self, + message: display, + style: style, + quiet_on_fast_finish: quiet_on_fast_finish + ).start + end + + # Run the given block with a progress indicator active. The handle is + # always finished in an +ensure+ block, so exceptions (including + # Thread#raise) cannot leave the ticker or entry orphaned. + # + # @yieldparam handle [Clacky::UI2::ProgressHandle] + def with_progress(message: nil, style: :primary, quiet_on_fast_finish: false) + handle = start_progress( + message: message, + style: style, + quiet_on_fast_finish: quiet_on_fast_finish + ) + begin + yield handle + ensure + handle.finish + end + end + + # Returns true if any progress indicator is currently active. + def progress_active? + @progress_mutex.synchronize { !@progress_stack.empty? } + end + + # Finish every active progress handle, top to bottom. Used by the + # interrupt path (Ctrl+C) so a single keypress guarantees the UI is + # quiescent regardless of how many nested/background progresses are + # running. + def interrupt_all_progress + # Snapshot outside the handle's finish() (which also grabs the + # mutex via unregister_progress) to avoid re-entrant lock issues. + handles = @progress_mutex.synchronize { @progress_stack.dup } + # Finish from top (newest) to bottom (oldest) so each top is the + # one currently rendering when it finishes. + handles.reverse_each(&:finish) + # Also drop legacy-shim handle registry so a subsequent + # show_progress(phase: "done") from unmigrated callers is a no-op. + @legacy_progress_handles&.clear + end + + # ----- Owner protocol for ProgressHandle ---------------------------- + # + # These three methods implement the contract described in + # ProgressHandle's class documentation. They are part of the public + # API only for ProgressHandle — external callers should use + # +start_progress+ / +with_progress+ instead. + + # Called by ProgressHandle#start. + def register_progress(handle) + @progress_mutex.synchronize do + prev_top = @progress_stack.last + if prev_top + # Plan B: the lower handle loses its OutputBuffer entry until + # the new top finishes. We remove its on-screen line now and + # tell it to forget its id; we'll allocate a new id on restore. + remove_entry(prev_top.entry_id) + prev_top.__detach_entry! + end + + @progress_stack.push(handle) + entry_id = append_output_unlocked(render_for(handle)) + recompute_sessionbar_status + entry_id + end + end + + # Called by ProgressHandle#finish. + def unregister_progress(handle, final_frame:) + @progress_mutex.synchronize do + if handle.entry_id + if final_frame && !final_frame.to_s.strip.empty? + update_entry(handle.entry_id, @renderer.render_progress(final_frame)) + else + remove_entry(handle.entry_id) + end + end + + @progress_stack.delete(handle) + + # Restore the new top, if any: allocate a fresh entry and let it + # resume rendering from where it left off. + if (restored = @progress_stack.last) + new_id = append_output_unlocked(render_for(restored)) + restored.__reattach_entry!(new_id) + end + + # Recompute sessionbar status from whatever remains on the stack. + # This handles: (a) empty stack → idle, (b) mixed stack (e.g. a + # long-running quiet tool still active underneath) → working. + recompute_sessionbar_status + end + end + + # Called by ProgressHandle's ticker and +update+. Writes +frame+ into + # the handle's entry iff it is currently top-of-stack. Non-top + # handles silently do nothing (their entry was detached in + # +register_progress+). + def render_frame(handle, frame) + @progress_mutex.synchronize do + return unless @progress_stack.last == handle + return unless handle.entry_id + + has_output = @stdout_lines && !@stdout_lines.empty? + suffix = has_output ? + " (Ctrl+C to interrupt · Ctrl+O to view output)" : + " (Ctrl+C to interrupt)" + decorated = "#{frame}#{suffix}" + + painted = handle.style == :primary ? + @renderer.render_working(decorated) : + @renderer.render_progress(decorated) + update_entry(handle.entry_id, painted) + + # Re-evaluate sessionbar: a quiet handle that crosses the fast-finish + # threshold should upgrade the status bar to "working" so long-running + # tools (terminal running a build, web_fetch) visibly reflect activity. + recompute_sessionbar_status + end + end + + # Render the very first frame of +handle+ (used when registering or + # restoring). Mirrors +render_frame+'s formatting minus the implicit + # elapsed-time tick (handle hasn't ticked yet). + private def render_for(handle) + frame = handle.current_frame + has_output = @stdout_lines && !@stdout_lines.empty? + suffix = has_output ? + " (Ctrl+C to interrupt · Ctrl+O to view output)" : + " (Ctrl+C to interrupt)" + decorated = "#{frame}#{suffix}" + handle.style == :primary ? + @renderer.render_working(decorated) : + @renderer.render_progress(decorated) + end + + # Derive the sessionbar workspace status from the live progress stack. + # + # Rules: + # - Any :primary handle alive → "working" (fast path for LLM thinking) + # - Any :quiet handle that has been alive longer than + # FAST_FINISH_THRESHOLD_SECONDS → "working" (so long tools like + # `terminal` running a build or test suite correctly flip the bar + # to working instead of staying on "idle" for minutes) + # - Otherwise → "idle" + # + # Must be called with @progress_mutex held. Emits update_sessionbar + # only when the computed status differs from the last one we wrote, + # avoiding pointless re-renders on every tick. + private def recompute_sessionbar_status + new_status = compute_sessionbar_status + return if @last_sessionbar_status == new_status + @last_sessionbar_status = new_status + update_sessionbar(status: new_status) + end + + private def compute_sessionbar_status + return 'idle' if @progress_stack.empty? + + threshold = ProgressHandle::FAST_FINISH_THRESHOLD_SECONDS + now = Time.now + @progress_stack.each do |h| + return 'working' if h.style == :primary + # Quiet handles only "count" once they've been alive long enough + # that a user would naturally expect a busy indicator. + start = h.start_time + return 'working' if start && (now - start) >= threshold + end + 'idle' + end + + # --------------------------------------------------------------------- + # Legacy shim: show_progress(message, phase:, progress_type:, ...) + # + # This method preserves the pre-refactor API so existing call sites + # (Agent#run, Agent#think, LlmCaller retry, trigger_idle_compression, + # MemoryUpdater) keep working until they're migrated to the owned- + # handle API. + # + # Each progress_type owns its own handle slot so two concurrent + # background flows (e.g. idle compression + thinking) can coexist + # without stomping on each other — exactly the race that caused the + # yellow/gray flicker bug. + # --------------------------------------------------------------------- + def show_progress(message = nil, prefix_newline: true, progress_type: "thinking", phase: "active", metadata: {}) + _ = prefix_newline # ignored in v2; layout is not the caller's concern + + type = progress_type.to_s + style = %w[retrying idle_compress].include?(type) ? :quiet : :primary + + @legacy_progress_handles ||= {} + + if phase.to_s == "done" + handle = @legacy_progress_handles[type] + handle&.finish(final_message: message) + @legacy_progress_handles.delete(type) + return + end + + # "active" phase — start a new handle or update the existing one. + existing = @legacy_progress_handles[type] + if existing&.running? + # Bare re-entry: no new info → just leave the existing spinner alone. + # This preserves the long-standing "Agent#run and Agent#think both + # call show_progress for fast feedback" idiom. + return if message.nil? && metadata.empty? + + attempt = metadata[:attempt] + total = metadata[:total] + suffix = (attempt && total) ? " (#{attempt}/#{total})" : "" + existing.update(message: "#{message || existing.message}#{suffix}", metadata: metadata) + return + end + + attempt = metadata[:attempt] + total = metadata[:total] + suffix = (attempt && total) ? " (#{attempt}/#{total})" : "" + display = ((message && !message.to_s.strip.empty?) ? message.to_s : Clacky::THINKING_VERBS.sample) + suffix + + @legacy_progress_handles[type] = start_progress(message: display, style: style) + end + + # Stream-only update for the live thinking progress. Unlike + # +show_progress(progress_type: "thinking", phase: "active")+, this + # NEVER creates a new handle — if no thinking handle is currently + # alive (e.g. we're inside an idle-compression call_llm where only + # the quiet "Compressing..." handle is on the stack), the streamed + # token counts are silently dropped instead of spawning a primary + # spinner that would push the compression progress off-screen. + def stream_thinking_progress(input_tokens:, output_tokens:) + @legacy_progress_handles ||= {} + existing = @legacy_progress_handles["thinking"] + return unless existing&.running? + existing.update(metadata: { input_tokens: input_tokens, output_tokens: output_tokens }) + end + + # --------------------------------------------------------------------- + # (Legacy dead-code removed: the old imperative show_progress body + # used to live here and is now superseded by the shim + owner + # protocol above. Keeping this note so a future grep for + # "@progress_id" / "@progress_thread" finds the migration explanation.) + # --------------------------------------------------------------------- + + # Stop the fullscreen refresh thread gracefully via flag + join. + def stop_fullscreen_refresh_thread + @fullscreen_refresh_stop = true + if @fullscreen_refresh_thread&.alive? + joined = @fullscreen_refresh_thread.join(1.0) + @fullscreen_refresh_thread.kill unless joined + end + @fullscreen_refresh_thread = nil + @fullscreen_refresh_stop = false + end + + # Show info message + # @param message [String] Info message + # @param prefix_newline [Boolean] Whether to add newline before message (default: true) + def show_info(message, prefix_newline: true) + output = @renderer.render_system_message(message, prefix_newline: prefix_newline) + append_output(output) + end + + # Show warning message + # @param message [String] Warning message + def show_warning(message) + output = @renderer.render_warning(message) + append_output(output) + end + + # Show error message + # @param message [String] Error message + def show_error(message, code: nil, top_up_url: nil, raw_message: nil) + output = @renderer.render_error(message) + append_output(output) + end + + # Show success message + # @param message [String] Success message + def show_success(message) + output = @renderer.render_success(message) + append_output(output) + end + + def phase_start(kind:, label:) + phase_id = SecureRandom.uuid + @active_phases ||= {} + @active_phases[phase_id] = { kind: kind, label: label, started_at: Time.now } + Thread.current[:clacky_phase_id] = phase_id + + banner = "──────── ▼ #{label} ────────" + append_output(@renderer.render_system_message(banner, prefix_newline: true)) + phase_id + end + + def phase_end(phase_id, summary: nil) + Thread.current[:clacky_phase_id] = nil + return unless @active_phases&.key?(phase_id) + + info = @active_phases.delete(phase_id) + label = info[:label] + tail = summary && !summary.to_s.strip.empty? ? " — #{summary.to_s.strip}" : "" + banner = "──────── ▲ #{label} done#{tail} ────────" + append_output(@renderer.render_system_message(banner, prefix_newline: false)) + end + + # Set workspace status to idle (called when agent stops working) + def set_idle_status + # Safety net: close any legacy progress slots that were opened via + # show_progress(progress_type: X, phase: "active") but never paired + # with a corresponding phase: "done" call. Historically the + # "retrying" slot in LlmCaller was leaked on every successful + # recovery, leaving the user with a stale "Network failed ... (NNN s)" + # line ticking forever. LlmCaller now closes its own slot (see the + # ensure in call_llm), but we mirror that defense here so any + # future code path that forgets to close a slot still gets cleaned + # up at the well-defined idle boundary. + close_leaked_legacy_progress_handles + + update_sessionbar(status: 'idle') + @last_sessionbar_status = 'idle' + # Clear user tip when agent stops working + @input_area.clear_user_tip + # Hide todo area while idle (data preserved, restored on next work) + @layout.hide_todos + @layout.render_input + end + + # Finish every ProgressHandle still registered in the legacy + # (show_progress) handle map. Called from set_idle_status as a + # defense-in-depth against unpaired active/done calls. + private def close_leaked_legacy_progress_handles + return unless @legacy_progress_handles + + leaked = @legacy_progress_handles.reject { |_type, h| h.nil? || !h.running? } + return if leaked.empty? + + # Finish top-down so each handle is the one currently rendering + # when it closes (matches the invariant in interrupt_all_progress). + leaked.values.reverse_each(&:finish) + + @legacy_progress_handles.clear + end + + # Set workspace status to working (called when agent starts working) + def set_working_status + update_sessionbar(status: 'working') + # Restore todo area if it was hidden during idle + @layout.show_todos + # Show a random user tip with 40% probability when agent starts working + @input_area.show_user_tip(probability: 0.4) + @layout.render_input + end + + # Show help text + def show_help + theme = ThemeManager.current_theme + + # Separator line + separator = theme.format_text("─" * 60, :info) + + lines = [ + separator, + "", + theme.format_text("Commands:", :info), + " #{theme.format_text("/model", :success)} - Quickly switch the current model", + " #{theme.format_text("/config", :success)} - Configure models, API keys, settings", + " #{theme.format_text("/clear", :success)} - Clear output and restart session", + " #{theme.format_text("/exit", :success)} - Exit application", + "", + theme.format_text("Input:", :info), + " #{theme.format_text("Shift+Enter", :success)} - New line", + " #{theme.format_text("Up/Down", :success)} - History navigation", + " #{theme.format_text("Ctrl+V", :success)} - Paste image (Ctrl+D to delete, max 3)", + " #{theme.format_text("Ctrl+C", :success)} - Clear input (press 2x to exit)", + "", + theme.format_text("Other:", :info), + " Supports Emacs-style shortcuts (Ctrl+A, Ctrl+E, etc.)", + "", + separator + ] + + lines.each { |line| append_output(line) } + end + + # Request confirmation from user (blocking) + # @param message [String] Confirmation prompt + # @param default [Boolean] Default value if user presses Enter + # @return [Boolean, String, nil] true/false for yes/no, String for feedback, nil for cancelled + def request_confirmation(message, default: true) + # Show question in output with theme styling + theme = ThemeManager.current_theme + question_symbol = theme.format_symbol(:info) + append_output("#{question_symbol} #{message}") + + # Pause InputArea + @input_area.pause + @layout.recalculate_layout + + # Create InlineInput with styled prompt + inline_input = Components::InlineInput.new( + prompt: "Press Enter/y to approve(Shift+Tab for all), 'n' to reject, or type feedback: ", + default: nil + ) + @inline_input = inline_input + + # Add inline input line to output (use layout to track position) + inline_id = @layout.append_output(inline_input.render) + @layout.position_inline_input_cursor(inline_input) + + result_text = nil + begin + # Collect input (blocks until user presses Enter). + # May raise AgentInterrupted if main thread Thread#raises the + # worker mid-pop — we MUST still restore input state in ensure. + result_text = inline_input.collect + ensure + # Clean up - remove the inline input lines (handle wrapped lines). + # Use the tracked id so removal is safe even when more output + # was appended in between. + @layout.remove_entry(inline_id) if inline_id + + # Deactivate InlineInput and restore the main InputArea. This + # MUST run even on exception so the user can type after + # interrupting a confirmation prompt. + @inline_input = nil + @input_area.resume + @layout.recalculate_layout + @layout.render_all + end + + # Append the final response to output (only on normal return) + if result_text.nil? + append_output(theme.format_text(" [Cancelled]", :error)) + else + display_text = result_text.empty? ? (default ? "y" : "n") : result_text + append_output(theme.format_text(" #{display_text}", :success)) + end + + # Parse result + return nil if result_text.nil? # Cancelled + + response = result_text.strip.downcase + case response + when "y", "yes" then true + when "n", "no" then false + when "" then default + else + result_text # Return feedback text + end + end + + # Auto-approve countdown for request_user_feedback: show a single live + # countdown line. If the user presses any key before timeout, collect + # their answer and return it (intervention). Otherwise return :timeout so + # the agent auto-decides and continues. + # @param seconds [Integer] Countdown duration + # @return [String, Symbol] feedback string, "" (bare Enter), or :timeout + # Show a live single-line countdown in the output area while keeping the + # normal input box usable. The agent thread blocks here until either: + # * the user submits a message in the regular input box -> returns the text + # * the user starts typing (cancels the auto-timeout but keeps waiting) + # * the countdown reaches zero with no interaction -> returns :timeout + # @param seconds [Integer] Countdown duration + # @return [String, Symbol] feedback text, or :timeout + def request_feedback_with_countdown(seconds: 10) + theme = ThemeManager.current_theme + + queue = Queue.new + entry_id = @layout.append_output(countdown_prompt(seconds, theme)) + + session = { + queue: queue, + entry_id: entry_id, + intervened: false, + watchdog: nil + } + @feedback_countdown = session + + session[:watchdog] = Thread.new do + remaining = seconds.to_i + while remaining.positive? + break if session[:intervened] + + @layout.replace_entry(entry_id, countdown_prompt(remaining, theme)) + sleep 1 + remaining -= 1 + end + queue.push(:timeout) unless session[:intervened] + end + + begin + result = queue.pop + ensure + session[:watchdog].kill if session[:watchdog]&.alive? + @feedback_countdown = nil + @layout.remove_entry(entry_id) if entry_id + @layout.recalculate_layout + @layout.render_all + end + + if result == :timeout + append_output(theme.format_text(" No response — continuing automatically.", :thinking)) + elsif result.to_s.strip.empty? + append_output(theme.format_text(" → (continue)", :success)) + result = "" + end + + result + end + + # Cancel the countdown's auto-timeout when the user starts interacting, + # but keep waiting for their submitted answer. Returns true if a + # countdown was active. + private def intervene_feedback_countdown + session = @feedback_countdown + return false unless session && !session[:intervened] + + session[:intervened] = true + session[:watchdog].kill if session[:watchdog]&.alive? + if session[:entry_id] + @layout.remove_entry(session[:entry_id]) + session[:entry_id] = nil + @layout.recalculate_layout + @layout.render_all + end + true + end + + private def countdown_prompt(remaining, theme) + theme.format_text(" Auto-continuing in #{remaining}s — type your answer to step in…", :info) + end + + # Whether a keystroke should count as the user stepping into a countdown. + # Plain typing and pastes do; pure scroll/navigation keys do not. + private def countdown_intervening_key?(key) + case key + when Hash + key[:type] == :rapid_input + when String + key.length >= 1 && key.ord >= 32 + when :backspace, :enter + true + else + false + end + end + + # Show diff between old and new content + # @param old_content [String] Old content + # @param new_content [String] New content + # @param max_lines [Integer] Maximum lines to show + def show_diff(old_content, new_content, max_lines: 50) + require 'diffy' + + diff = Diffy::Diff.new(old_content, new_content, context: 3) + diff_lines = diff.to_s(:color).lines + + # Store for fullscreen toggle + @last_diff_lines = diff_lines + + # Show diff without line numbers + diff_lines.take(max_lines).each do |line| + append_output(line.chomp) + end + + if diff_lines.size > max_lines + append_output("\n... (#{diff_lines.size - max_lines} more lines hidden. Press Ctrl+O to open full diff in pager)") + end + rescue LoadError + # Fallback if diffy is not available + append_output(" Old size: #{old_content.bytesize} bytes") + append_output(" New size: #{new_content.bytesize} bytes") + @last_diff_lines = nil + end + + # Show fullscreen diff view (only if not already expanded) + private def redisplay_diff + return unless @last_diff_lines + return if @layout.fullscreen_mode? + + # Use `less -R` as pager: it handles its own alternate screen + scrolling, + # and restores the terminal perfectly on exit — no DIY scrolling needed. + content = @last_diff_lines.join + + # Write diff to a temp file so less can read it + require "tempfile" + tmpfile = Tempfile.new(["clacky_diff", ".txt"]) + tmpfile.write(content) + tmpfile.flush + + # Suspend raw mode so less can take full control of the terminal + @layout.screen.disable_raw_mode + + # --mouse : enable mouse wheel scrolling inside less + # --wheel-lines : scroll 3 lines per wheel click (comfortable default) + # -R : pass through ANSI colour codes + # Unset LESSOPEN/LESSCLOSE so less doesn't try to pre-process the file + system( + { "LESSOPEN" => nil, "LESSCLOSE" => nil }, + "less", "--mouse", "--wheel-lines=3", "-R", tmpfile.path + ) + + # Restore raw mode and repaint the main screen + @layout.screen.enable_raw_mode + @layout.rerender_all + ensure + tmpfile&.close + tmpfile&.unlink + end + + # Show fullscreen command output view + def show_command_output + return unless @stdout_lines && !@stdout_lines.empty? + return if @layout.fullscreen_mode? + + lines = build_command_output_lines + @layout.enter_fullscreen(lines, hint: "Press Ctrl+O to return · Output updates in real-time") + + # Start background thread to refresh fullscreen content in real-time. + # Use a dedicated stop flag so we can join() the thread cleanly and + # avoid Thread#kill interrupting the thread while it holds @render_mutex. + @fullscreen_refresh_stop = false + @fullscreen_refresh_thread = Thread.new do + until @fullscreen_refresh_stop || !@layout.fullscreen_mode? + sleep 0.3 + next if @fullscreen_refresh_stop || !@layout.fullscreen_mode? + + @layout.refresh_fullscreen(build_command_output_lines) + end + rescue StandardError + # Silently handle thread errors + end + end + + + # Build command output lines snapshot from @stdout_lines + # @return [Array] Lines to display in fullscreen + private def build_command_output_lines + lines = @stdout_lines&.dup || [] + lines.empty? ? ["(No output yet)"] : lines + end + + # Format tool call for display + # @param name [String] Tool name + # @param args [String, Hash] Tool arguments + # @return [String] Formatted call string + def format_tool_call(name, args) + args_hash = args.is_a?(String) ? JSON.parse(args, symbolize_names: true) : args + + # Try to get tool instance for custom formatting + tool = get_tool_instance(name) + if tool + begin + return tool.format_call(args_hash) + rescue StandardError + # Fallback + end + end + + # Simple fallback + "#{name}(...)" + rescue JSON::ParserError + "#{name}(...)" + end + + # Get tool instance by name + # @param tool_name [String] Tool name + # @return [Object, nil] Tool instance or nil + def get_tool_instance(tool_name) + # Convert tool_name to class name (e.g., "file_reader" -> "FileReader") + class_name = tool_name.split('_').map(&:capitalize).join + + # Try to find the class in Clacky::Tools namespace + if Clacky::Tools.const_defined?(class_name) + tool_class = Clacky::Tools.const_get(class_name) + tool_class.new + else + nil + end + rescue NameError + nil + end + + # Display welcome banner with logo and agent info + def display_welcome_banner + content = @welcome_banner.render_full( + working_dir: @config[:working_dir], + mode: @config[:mode], + width: @layout.screen.width + ) + append_output(content) + + # Check if API key is configured (show warning AFTER banner) + check_api_key_configuration + end + + # Check if API key is configured and show warning if missing + private def check_api_key_configuration + config = Clacky::AgentConfig.load + + if !config.models_configured? + show_warning("No models configured! Please run /config to set up your models and API keys.") + elsif config.api_key.nil? || config.api_key.empty? + show_warning("API key is not configured! Please run /config to set up your API key.") + end + end + + # Display recent user messages when loading session + # @param user_messages [Array] Array of recent user message texts + def display_session_history(user_messages) + theme = ThemeManager.current_theme + + # Show logo banner only + append_output(@welcome_banner.render_logo(width: @layout.screen.width)) + + # Show simple header + append_output(theme.format_text("Recent conversation:", :info)) + + # Display each user message with numbering + user_messages.each_with_index do |msg, index| + # Truncate long messages + display_msg = if msg.length > 140 + "#{msg[0..137]}..." + else + msg + end + + # Show with number and indentation + append_output(" #{index + 1}. #{display_msg}") + end + + # Bottom spacing and continuation prompt + append_output("") + append_output(theme.format_text("Session restored. Feel free to continue with your next task.", :success)) + end + + # Main input loop + def input_loop + @layout.screen.enable_raw_mode + + while @running + # Process any pending resize events + @layout.process_pending_resize + + key = @layout.screen.read_key(timeout: 0.1) + next unless key + + handle_key(key) + end + rescue Clacky::AgentInterrupted + # Signal.trap("INT") raised AgentInterrupted on the main thread. + # Route through the normal Ctrl+C path so on_interrupt callback fires + # (interrupt task thread if running, or exit if idle) instead of quitting blindly. + handle_key(:ctrl_c) + rescue => e + stop + raise e + ensure + @layout.screen.disable_raw_mode + end + + # Handle keyboard input - delegate to InputArea or InlineInput + # @param key [Symbol, String, Hash] Key input or rapid input hash + def handle_key(key) + # If in fullscreen mode, only handle Ctrl+O to exit + if @layout.fullscreen_mode? + if key == :ctrl_o + # Signal the real-time refresh thread to stop gracefully, then join it. + # Avoid Thread#kill which can interrupt the thread mid-render and + # leave @render_mutex permanently locked. + stop_fullscreen_refresh_thread + @layout.exit_fullscreen + # Restore main screen content after returning from alternate buffer + @layout.rerender_all + end + return + end + + # If InlineInput is active, delegate to it + if @inline_input&.active? + handle_inline_input_key(key) + return + end + + # During an auto-approve feedback countdown the normal input box stays + # live; the first meaningful keystroke cancels the auto-timeout so the + # user can finish typing their answer without being rushed. + if @feedback_countdown && !@feedback_countdown[:intervened] && countdown_intervening_key?(key) + intervene_feedback_countdown + end + + result = @input_area.handle_key(key) + + # Handle height change first + if result[:height_changed] + @layout.recalculate_layout + end + + # Handle actions + case result[:action] + when :submit + handle_submit(result[:data]) + when :exit + stop + exit(0) + when :interrupt + # Stop all active progress indicators (ticker threads + entries). + # An interrupt may happen at any point in a nested flow (e.g. + # idle compression during a task); finish the whole stack from + # top to bottom so nothing is left running. + interrupt_all_progress + + # Check if input area has content + input_was_empty = @input_area.empty? + + # Notify CLI to handle interrupt (stop agent or exit) + @interrupt_callback&.call(input_was_empty: input_was_empty) + when :clear_output + # Pass to callback with data for display + @input_callback&.call("/clear", [], display: result[:data][:display]) + when :scroll_up + @layout.scroll_output_up + when :scroll_down + @layout.scroll_output_down + when :help + # Pass to callback with data for display + @input_callback&.call("/help", [], display: result[:data][:display]) + when :toggle_mode + toggle_mode + when :toggle_expand + # If there's command output available, show it; otherwise show diff + if @stdout_lines && !@stdout_lines.empty? + show_command_output + else + redisplay_diff + end + when :time_machine + # Trigger time machine callback + @time_machine_callback&.call + end + + # Always re-render input area after key handling + @layout.render_input + end + + # Handle key input for InlineInput + def handle_inline_input_key(key) + # Get old line count BEFORE modification + old_line_count = @inline_input.line_count + + result = @inline_input.handle_key(key) + + case result[:action] + when :update + # Update the output area with current input (considering wrapped lines) + @layout.update_last_line(@inline_input.render, old_line_count) + # Position cursor for inline input + @layout.position_inline_input_cursor(@inline_input) + when :submit, :cancel + # InlineInput is done, will be cleaned up by request_confirmation after collect returns + # Don't render anything here - let request_confirmation handle cleanup + return + when :toggle_expand + # If there's command output available, show it; otherwise show diff + if @stdout_lines && !@stdout_lines.empty? + show_command_output + else + redisplay_diff + end + when :toggle_mode + # Update mode and session bar info, but don't render yet + current_mode = @config[:mode] + new_mode = case current_mode.to_s + when /confirm_safes/ + "auto_approve" + when /auto_approve/ + "confirm_safes" + else + "auto_approve" + end + + @config[:mode] = new_mode + @mode_toggle_callback&.call(new_mode) + + # Update session bar data (will be rendered by request_confirmation's render_all) + @input_area.update_sessionbar( + session_id: @session_id, + working_dir: @config[:working_dir], + mode: @config[:mode], + model: @config[:model], + tasks: @tasks_count, + cost: @total_cost + ) + end + end + + # Handle submit action + private def handle_submit(data) + # If any progress indicator is currently active (e.g. an idle-compression + # :quiet handle running in the background), finish them all top-to-bottom + # so no ticker thread is left writing into the buffer while we render + # the new user message. Each handle's finish() renders its own final + # frame with elapsed time, so the user still sees a summary. + interrupt_all_progress if progress_active? + + # Also clear stdout buffer used by Ctrl+O (unrelated to progress, but + # we don't want stale command output carried across user turns). + @stdout_lines = nil + @stdout_partial_tail = false + + # Render user message immediately before running agent + unless data[:text].empty? && data[:files].empty? + output = @renderer.render_user_message(data[:text], files: data[:files]) + append_output(output) + end + + # If an auto-approve feedback countdown is waiting for an answer, this + # submission IS that answer — deliver it to the waiting agent thread + # instead of starting a brand-new turn. + if (session = @feedback_countdown) + session[:queue].push(data[:text].to_s) + return + end + + # Then call callback (allows interrupting previous agent before processing new input) + @input_callback&.call(data[:text], data[:files]) + end + + # Show configuration modal dialog with multi-model support + # @param current_config [Clacky::AgentConfig] Current configuration object + # @return [Hash, nil] Hash with updated config values, or nil if cancelled + public def show_config_modal(current_config, test_callback: nil) + modal = Components::ModalComponent.new + + loop do + # Build menu choices + choices = [] + + # Add model list + current_config.models.each_with_index do |model, idx| + is_current = (idx == current_config.current_model_index) + model_name = model["model"] || "unnamed" + masked_key = mask_api_key(model["api_key"]) + + # Add type badge if present + type_badge = case model["type"] + when "default" then "[default] " + when "lite" then "[lite] " + else "" + end + + display_name = "#{type_badge}#{model_name} (#{masked_key})" + choices << { + name: display_name, + value: { action: :switch, model_id: model["id"] } + } + end + + # Add action buttons + choices << { name: "─" * 50, disabled: true } + choices << { name: "[+] Add New Model", value: { action: :add } } + if current_config.models.length > 0 + choices << { name: "[*] Edit Current Model", value: { action: :edit } } + choices << { name: "[-] Delete Model", value: { action: :delete } } if current_config.models.length > 1 + end + choices << { name: "[X] Close", value: { action: :close } } + + # Show menu + result = modal.show( + title: "Model Configuration", + choices: choices, + on_close: -> { @layout.rerender_all } + ) + + return nil if result.nil? + + case result[:action] + when :switch + # Just signal the caller which model to switch to. + # All side effects (agent.switch_model_by_id to rebuild the Client, + # set_default_model_by_id, persistence) are done by the CLI layer + # in handle_config_command — this keeps show_config_modal a pure + # UI component and avoids the modal half-mutating config while + # the agent's @client still points at the old credentials. + return { action: :switch, model_id: result[:model_id] } + when :add + new_model = show_model_edit_form(nil, test_callback: test_callback) + if new_model + # Determine anthropic_format based on provider + # For Anthropic provider, use Anthropic API format + anthropic_format = new_model[:provider] == "anthropic" + + current_config.add_model( + model: new_model[:model], + api_key: new_model[:api_key], + base_url: new_model[:base_url], + anthropic_format: anthropic_format + ) + # Hand off the new model's stable id to the caller. CLI layer + # decides whether to switch to it / mark default / persist. + new_id = current_config.models.last["id"] + return { action: :add, model_id: new_id } + end + when :edit + current_model = current_config.current_model + edited = show_model_edit_form(current_model, test_callback: test_callback) + if edited + # Update current model in place (keep anthropic_format unchanged). + # Because we mutate the same hash that's in @models, the model's + # stable id is preserved — the caller will rebuild the agent's + # Client by calling agent.switch_model_by_id with the same id, + # which reruns the Bedrock/anthropic/api_key detection. + current_model["api_key"] = edited[:api_key] + current_model["model"] = edited[:model] + current_model["base_url"] = edited[:base_url] + return { action: :edit, model_id: current_model["id"] } + end + when :delete + if current_config.models.length <= 1 + # Can't delete - show error and continue + next + end + + # Delete current model — this clears @current_model_id so the + # next current_model lookup picks type:default or index fallback. + current_config.remove_model(current_config.current_model_index) + # New current model id after deletion (may be nil briefly; resolved + # on next current_model call, which also re-anchors @current_model_id). + new_current = current_config.current_model + return { action: :delete, model_id: new_current && new_current["id"] } + when :close + # Just close the modal + return nil + end + end + end + + # Quick model switcher — lists configured model cards and returns the + # picked card's stable id. Unlike show_config_modal this never mutates + # config; it's a pure picker. All side effects live in the CLI layer. + # @return [Hash, nil] { model_id: } or nil if cancelled / no models + # Two-level drawer picker for /model. + # + # Level 1 (card list): Enter selects a card and uses its default model + # (clearing any sub-model overlay); → opens that card's sub-model drawer + # (only for cards whose provider exposes >= 2 sub-models, marked "›"). + # + # Level 2 (sub-model list): Enter pins the chosen sub-model (or Default); + # ← / Esc returns to the card list. + # + # @param current_config [AgentConfig] + # @param submodels_for [Proc] called with a card hash, returns its provider + # sub-model names (or [] if none / single). + # @return [Hash, nil] { model_id:, model_name: } where model_name is the + # chosen sub-model (nil = the card's own default), or nil if cancelled. + public def show_model_switch_modal(current_config, submodels_for) + return nil if current_config.models.empty? + + on_close = -> { @layout.rerender_all } + + loop do + card = show_model_card_level(current_config, submodels_for, on_close) + return nil if card.nil? + + # Plain card pick (Enter): use the card default, clear overlay. + return { model_id: card[:model_id], model_name: nil } unless card[:expand] + + # → opened the drawer: let the user pick a sub-model for this card. + model = current_config.models.find { |m| m["id"] == card[:model_id] } + drawer = { + model_id: card[:model_id], + card_model: card[:card_model], + submodels: submodels_for.call(model) || [], + current_overlay: current_config.session_model_overlay_name + } + sub = show_model_submodel_level(drawer, on_close) + next if sub == :back # ← / Esc: back to the card list + + return { model_id: card[:model_id], model_name: sub } + end + end + + # Level 1: card list. Returns { model_id:, expand: bool } on Enter/→, + # or nil if cancelled. + private def show_model_card_level(current_config, submodels_for, on_close) + current_overlay = current_config.session_model_overlay_name + + choices = current_config.models.each_with_index.map do |model, idx| + is_current = (idx == current_config.current_model_index) + card_model = model["model"] || "unnamed" + type_badge = case model["type"] + when "default" then " [default]" + when "lite" then " [lite]" + else "" + end + expandable = (submodels_for.call(model) || []).length >= 2 + + marker = is_current ? "● " : " " + arrow = expandable ? " ›" : "" + { + name: "#{marker}#{card_model}#{type_badge}#{arrow}", + value: { model_id: model["id"], card_model: card_model }, + expandable: expandable + } + end + + result = Components::ModalComponent.new.show( + title: "Switch Model", + choices: choices, + nav_keys: true, + instructions: "↑↓ move • Enter select • → submodels • Esc cancel", + on_close: on_close + ) + + return nil if result.nil? || (result.is_a?(Hash) && result[:nav] == :back) + + if result.is_a?(Hash) && result[:nav] == :expand + { model_id: result[:value][:model_id], card_model: result[:value][:card_model], expand: true } + else + { model_id: result[:model_id], card_model: result[:card_model], expand: false } + end + end + + # Level 2: sub-model list for one card. Returns the chosen sub-model name, + # nil (the card default), or :back to return to the card list. + private def show_model_submodel_level(card, on_close) + submodels = card[:submodels] + current = card[:current_overlay] + card_model = card[:card_model] + + choices = [{ + name: "#{current.nil? ? '● ' : ' '}Default (#{card_model})", + value: { model_name: nil } + }] + submodels.each do |name| + choices << { + name: "#{name == current ? '● ' : ' '}#{name}", + value: { model_name: name } + } + end + + result = Components::ModalComponent.new.show( + title: card_model, + choices: choices, + nav_keys: true, + instructions: "↑↓ move • Enter select • ←/Esc back", + on_close: on_close + ) + + return :back if result.nil? || (result.is_a?(Hash) && result[:nav] == :back) + + result[:model_name] + end + + # Show time machine menu for task undo/redo + # @param history [Array] Task history with format: [{task_id, summary, status, has_branches}] + # @return [Integer, nil] Selected task ID or nil if cancelled + public def show_time_machine_menu(history) + modal = Components::ModalComponent.new + + active_index = nil + + # Build menu choices from history + choices = history.each_with_index.map do |task, idx| + # Status marker. The cursor itself draws a "→", so use distinct + # glyphs here to avoid visual collision: + # ● current · on-path history ✗ undone/abandoned branch + marker = case task[:status] + when :current + active_index = idx + "● " + when :undone + "✗ " + else + "· " + end + + # Branch indicator + marker += "⎇ " if task[:has_branches] + + # Truncate summary to fit on screen + max_summary_length = 60 + summary = task[:summary] + if summary.length > max_summary_length + summary = summary[0...max_summary_length] + "..." + end + + label = "#{marker}Task #{task[:task_id]}: #{summary}" + label += " (undone)" if task[:status] == :undone + + { + name: label, + value: task[:task_id], + dim: task[:status] == :undone + } + end + + # Show modal, landing the cursor on the currently-active task. + result = modal.show( + title: "Time Machine - Select Task to Navigate", + choices: choices, + initial_index: active_index, + on_close: -> { @layout.rerender_all } + ) + + result # Return selected task_id or nil + end + + # Show form for editing a model + # @param model [Hash, nil] Existing model hash or nil for new model + # @return [Hash, nil] Updated model hash or nil if cancelled + private def show_model_edit_form(model, test_callback: nil) + modal = Components::ModalComponent.new + + is_new = model.nil? + model ||= {} + + # For new models, show provider selection first + selected_provider = nil + if is_new + # Build provider choices + provider_choices = Clacky::Providers.list.map do |id, name| + { name: name, value: id } + end + provider_choices << { name: "─" * 40, disabled: true } + provider_choices << { name: "Custom (manual configuration)", value: "custom" } + + # Show provider selection + selected_provider = modal.show( + title: "Select Provider", + choices: provider_choices, + on_close: -> { @layout.rerender_all } + ) + + # User cancelled + return nil if selected_provider.nil? + end + + # Prepare masked API key for display + masked_key = mask_api_key(model["api_key"]) + + # Pre-fill values from provider preset if selected + provider_preset = nil + if selected_provider && selected_provider != "custom" + provider_preset = Clacky::Providers.get(selected_provider) + end + + # Get default values from provider or existing model + default_model = provider_preset ? provider_preset["default_model"] : model["model"] + default_base_url = provider_preset ? provider_preset["base_url"] : model["base_url"] + default_api_key = model["api_key"] || "" + + # Define fields + fields = [ + { + name: :api_key, + label: "API Key #{is_new ? '' : "(current: #{masked_key})"}:", + default: "", + mask: true + }, + { + name: :model, + label: "Model #{is_new && default_model ? "(default: #{default_model})" : (is_new ? '' : "(current: #{model['model']})")}:", + default: default_model || "" + }, + { + name: :base_url, + label: "Base URL #{is_new && default_base_url ? "(default: #{default_base_url})" : (is_new ? '' : "(current: #{model['base_url']})")}:", + default: default_base_url || "" + } + ] + + # Create validator if test_callback provided + validator = if test_callback + lambda do |values| + # Merge values: use user input if provided, otherwise keep existing model value + api_key = values[:api_key].to_s.empty? ? model["api_key"] : values[:api_key] + model_name = values[:model].to_s.empty? ? model["model"] : values[:model] + base_url = values[:base_url].to_s.empty? ? model["base_url"] : values[:base_url] + anthropic_format = model["anthropic_format"] # Not editable in form, use model's value + + test_config_values = { + "api_key" => api_key, + "model" => model_name, + "base_url" => base_url, + "anthropic_format" => anthropic_format + } + + # For new models, require all fields + if is_new + if test_config_values["api_key"].to_s.empty? + return { success: false, error: "API Key is required for new model" } + end + if test_config_values["model"].to_s.empty? + return { success: false, error: "Model name is required" } + end + if test_config_values["base_url"].to_s.empty? + return { success: false, error: "Base URL is required" } + end + end + + # Create a temporary config for testing + temp_config = Clacky::AgentConfig.new(models: [test_config_values], current_model_index: 0) + test_callback.call(temp_config) + end + else + nil + end + + # Determine modal title based on provider + modal_title = if is_new && selected_provider && selected_provider != "custom" + provider_name = Clacky::Providers.get(selected_provider)&.dig("name") || selected_provider + "Add #{provider_name} Model" + elsif is_new + "Add Custom Model" + else + "Edit Model" + end + + # Show modal and collect values + result = modal.show( + title: modal_title, + fields: fields, + validator: validator, + on_close: -> { @layout.rerender_all } + ) + + return nil if result.nil? + + # Merge with existing model values or provider defaults + { + api_key: result[:api_key].to_s.empty? ? model["api_key"] : result[:api_key], + model: result[:model].to_s.empty? ? (model["model"] || default_model) : result[:model], + base_url: result[:base_url].to_s.empty? ? (model["base_url"] || default_base_url) : result[:base_url], + provider: selected_provider + } + end + + # Mask API key for display + private def mask_api_key(api_key) + if api_key && !api_key.empty? + "#{api_key[0..5]}...#{api_key[-4..]}" + else + "not set" + end + end + end + end +end diff --git a/lib/clacky/ui2/view_renderer.rb b/lib/clacky/ui2/view_renderer.rb new file mode 100644 index 0000000..3944740 --- /dev/null +++ b/lib/clacky/ui2/view_renderer.rb @@ -0,0 +1,179 @@ +# frozen_string_literal: true + +require_relative "components/message_component" +require_relative "components/tool_component" +require_relative "components/common_component" +require_relative "markdown_renderer" + +module Clacky + module UI2 + # ViewRenderer coordinates all UI components and provides a unified rendering interface + class ViewRenderer + def initialize + @message_component = Components::MessageComponent.new + @tool_component = Components::ToolComponent.new + @common_component = Components::CommonComponent.new + end + + # Render a user message + # @param content [String] Message content + # @param timestamp [Time, nil] Optional timestamp + # @param files [Array] Optional file hashes { name:, mime_type:, ... } + # @return [String] Rendered message + def render_user_message(content, timestamp: nil, files: []) + @message_component.render( + role: "user", + content: content, + timestamp: timestamp, + files: files + ) + end + + # Render an assistant message + # @param content [String] Message content + # @param timestamp [Time, nil] Optional timestamp + # @return [String] Rendered message + def render_assistant_message(content, timestamp: nil) + # Render markdown if content contains markdown syntax + rendered_content = if MarkdownRenderer.markdown?(content) + MarkdownRenderer.render(content) + else + content + end + + @message_component.render( + role: "assistant", + content: rendered_content, + timestamp: timestamp + ) + end + + # Render a system message + # @param content [String] Message content + # @param timestamp [Time, nil] Optional timestamp + # @param prefix_newline [Boolean] Whether to add newline before message + # @return [String] Rendered message + def render_system_message(content, timestamp: nil, prefix_newline: true) + @message_component.render( + role: "system", + content: content, + timestamp: timestamp, + prefix_newline: prefix_newline + ) + end + + # Render a tool call + # @param tool_name [String] Tool name + # @param formatted_call [String] Formatted call description + # @return [String] Rendered tool call + def render_tool_call(tool_name:, formatted_call:) + @tool_component.render( + type: :call, + tool_name: tool_name, + formatted_call: formatted_call + ) + end + + # Render a tool result + # @param result [String] Tool result + # @return [String] Rendered tool result + def render_tool_result(result:) + @tool_component.render( + type: :result, + result: result + ) + end + + # Render a tool error + # @param error [String] Error message + # @return [String] Rendered tool error + def render_tool_error(error:) + @tool_component.render( + type: :error, + error: error + ) + end + + # Render a tool denied message + # @param tool_name [String] Tool name + # @return [String] Rendered tool denied + def render_tool_denied(tool_name:) + @tool_component.render( + type: :denied, + tool_name: tool_name + ) + end + + # Render a tool planned message + # @param tool_name [String] Tool name + # @return [String] Rendered tool planned + def render_tool_planned(tool_name:) + @tool_component.render( + type: :planned, + tool_name: tool_name + ) + end + + # Render thinking indicator + # @return [String] Thinking indicator + def render_thinking + @common_component.render_thinking + end + + # Render progress message (stopped state, gray) + # @param message [String] Progress message + # @return [String] Progress indicator + def render_progress(message) + @common_component.render_progress(message) + end + + # Render working message (active state, yellow) + # @param message [String] Progress message + # @return [String] Working indicator + def render_working(message) + @common_component.render_working(message) + end + + # Render success message + # @param message [String] Success message + # @return [String] Success message + def render_success(message) + @common_component.render_success(message) + end + + # Render error message + # @param message [String] Error message + # @return [String] Error message + def render_error(message) + @common_component.render_error(message) + end + + # Render warning message + # @param message [String] Warning message + # @return [String] Warning message + def render_warning(message) + @common_component.render_warning(message) + end + + # Render task completion summary + # @param iterations [Integer] Number of iterations + # @param cost [Float] Cost in USD + # @param duration [Float] Duration in seconds + # @param cache_tokens [Integer] Cache read tokens + # @param cache_requests [Integer] Total cache requests count + # @param cache_hits [Integer] Cache hit requests count + # @return [String] Formatted completion summary + def render_task_complete(iterations:, cost:, duration: nil, cache_tokens: nil, cache_requests: nil, cache_hits: nil) + @common_component.render_task_complete( + iterations: iterations, + cost: cost, + duration: duration, + cache_tokens: cache_tokens, + cache_requests: cache_requests, + cache_hits: cache_hits + ) + end + + end + end +end diff --git a/lib/clacky/ui_interface.rb b/lib/clacky/ui_interface.rb new file mode 100644 index 0000000..da0827e --- /dev/null +++ b/lib/clacky/ui_interface.rb @@ -0,0 +1,171 @@ +# frozen_string_literal: true + +require "securerandom" + +module Clacky + # UIInterface defines the standard interface between Agent/CLI and UI implementations. + # All UI controllers (UIController, JsonUIController) must implement these methods. + module UIInterface + # === Output display === + # @param content [String] text portion of the assistant reply (file:// links stripped) + # @param files [Array] extracted file refs: [{ name:, path:, inline: }] + def show_assistant_message(content, files:); end + def show_feedback_request(question, context, options); end + def show_tool_call(name, args); end + def show_tool_result(result); end + def show_tool_stdout(lines); end + def show_tool_error(error); end + def show_tool_args(formatted_args); end + def show_file_write_preview(path, is_new_file:); end + def show_file_edit_preview(path); end + def show_file_error(error_message); end + def show_shell_preview(command); end + def show_diff(old_content, new_content, max_lines: 50); end + def show_token_usage(token_data); end + def show_complete(iterations:, cost:, duration: nil, cache_stats: nil, awaiting_user_feedback: false, cost_source: nil); end + def append_output(content); end + + # === Status messages === + def show_info(message, prefix_newline: true); end + def show_warning(message); end + def show_error(message, code: nil, top_up_url: nil, raw_message: nil); end + def show_success(message); end + def log(message, level: :info); end + + # === Progress === + # Unified progress indicator with type-based display customization. + # progress_type: "thinking" | "retrying" | "idle_compress" | custom + # phase: "active" | "done" + # metadata: extensible hash (e.g., {attempt: 3, total: 10} for retries) + def show_progress(message = nil, prefix_newline: true, progress_type: "thinking", phase: "active", metadata: {}); end + + # Update the live "thinking" progress with streamed token counts. + # This is *purely decorative*: it must NEVER start a new progress + # indicator. If no thinking progress is currently active (e.g. during + # idle compression, where only a quiet "Compressing..." progress is + # live), the call is a no-op. UI2 overrides this; other UIs delegate + # to show_progress. + def stream_thinking_progress(input_tokens:, output_tokens:) + show_progress( + progress_type: "thinking", + phase: "active", + metadata: { input_tokens: input_tokens, output_tokens: output_tokens } + ) + end + + # === Progress (v2: owned handles) === + # + # Start a new progress indicator and return an owned handle. The caller + # is responsible for finishing it — use +with_progress+ (below) whenever + # possible to get ensure-based auto-close. + # + # @param message [String, nil] Initial progress message (nil picks a random thinking verb). + # @param style [Symbol] :primary (foreground, yellow, bumps sessionbar) + # or :quiet (background, gray, no sessionbar change). + # @param quiet_on_fast_finish [Boolean] When true, a finish under + # FAST_FINISH_THRESHOLD_SECONDS removes the progress line entirely + # (preferred for per-tool wrappers so fast tools don't leave a + # permanent "Executing foo… (0s)" log line). The default + # implementation ignores this flag — it only affects the native + # UI2::UIController + ProgressHandle path. + # @return [#update, #finish, #cancel] a ProgressHandle-like object. + # + # Default implementation degrades gracefully to the old show_progress API + # so UI implementations that haven't migrated still behave correctly. + def start_progress(message: nil, style: :primary, quiet_on_fast_finish: false) + _ = quiet_on_fast_finish # default impl doesn't honor fast-collapse + progress_type = style == :primary ? "thinking" : "idle_compress" + show_progress(message, progress_type: progress_type, phase: "active") + LegacyProgressHandleAdapter.new(self, progress_type: progress_type) + end + + # Run the given block with a progress indicator active. The handle is + # always finished in an +ensure+ block — exceptions (including + # AgentInterrupted) cannot leave the ticker or entry orphaned. + # + # @yieldparam handle the progress handle + def with_progress(message: nil, style: :primary, quiet_on_fast_finish: false) + handle = start_progress( + message: message, + style: style, + quiet_on_fast_finish: quiet_on_fast_finish + ) + begin + yield handle + ensure + handle.finish + end + end + + # Minimal adapter that lets UIs without a native ProgressHandle still + # participate in the new +with_progress+ API by delegating to the old + # +show_progress(phase: ...)+ contract. UI2::UIController overrides + # +start_progress+ directly with a native ProgressHandle, so this + # adapter is only used by plain/json/web/channel UIs. + class LegacyProgressHandleAdapter + def initialize(ui, progress_type:) + @ui = ui + @progress_type = progress_type + @closed = false + end + + def update(message: nil, metadata: nil) + return if @closed + @ui.show_progress(message, progress_type: @progress_type, phase: "active", metadata: metadata || {}) + end + + def finish(final_message: nil) + return if @closed + @closed = true + @ui.show_progress(final_message, progress_type: @progress_type, phase: "done") + end + alias_method :cancel, :finish + end + + # === State updates === + def update_sessionbar(tasks: nil, cost: nil, cost_source: nil, status: nil, latency: nil); end + def update_todos(todos); end + def set_working_status; end + def set_idle_status; end + + # === Blocking interaction === + def request_confirmation(message, default: true); end + + # Auto-approve countdown for request_user_feedback. Shows a live countdown + # and lets the user press a key to take over and answer. Returns :timeout + # when no one intervenes (agent should auto-decide and continue), or a + # feedback string / "" when the user steps in. Non-interactive UIs (web, + # json, channel) have no human watching a TTY, so they default to :timeout. + def request_feedback_with_countdown(seconds: 10) + :timeout + end + + # === Input control (CLI layer) === + def clear_input; end + def set_input_tips(message, type: :info); end + + # === Path redaction (for encrypted brand skill tmpdirs) === + # === Lifecycle === + def stop(clear_screen: false); end + + # === Phase grouping (optional, web UI uses this to fold subagent runs) === + # Begin a logical phase. Events emitted between phase_start and phase_end + # carry the phase_id so the UI can group them visually. + # Returns the phase_id (caller is responsible for passing it to phase_end). + def phase_start(kind:, label: nil) + SecureRandom.uuid + end + + def phase_end(phase_id, summary: nil); end + + # Run block within a phase. Always closes via ensure. + def with_phase(kind:, label: nil) + pid = phase_start(kind: kind, label: label) + begin + yield pid + ensure + phase_end(pid) + end + end + end +end diff --git a/lib/clacky/utils/arguments_parser.rb b/lib/clacky/utils/arguments_parser.rb new file mode 100644 index 0000000..99389bb --- /dev/null +++ b/lib/clacky/utils/arguments_parser.rb @@ -0,0 +1,191 @@ +# frozen_string_literal: true + +require "json" + +module Clacky + module Utils + class ArgumentsParser + # Parse and validate tool call arguments with JSON repair capability + def self.parse_and_validate(call, tool_registry) + # 1. Try standard parsing + begin + args = JSON.parse(call[:arguments], symbolize_names: true) + + # Check if any key contains XML tags (< or >) indicating contamination + # Even though JSON.parse succeeded, the keys might be malformed + has_xml_contamination = args.keys.any? { |k| k.to_s.include?('<') || k.to_s.include?('>') } + + if has_xml_contamination + # Force repair even though JSON.parse succeeded + raise JSON::ParserError.new("Keys contain XML contamination") + end + + return validate_required_params(call, args, tool_registry) + rescue JSON::ParserError => e + # Continue to repair + end + + # 2. Try simple repair + repaired = repair_json(call[:arguments]) + + begin + args = JSON.parse(repaired, symbolize_names: true) + return validate_required_params(call, args, tool_registry) + rescue JSON::ParserError, MissingRequiredParamsError => e + # 3. Repair failed or missing params, return helpful error + raise_helpful_error(call, tool_registry, e) + end + end + + + # Simple JSON repair: complete brackets and quotes, and remove XML contamination + def self.repair_json(json_str) + + result = json_str.strip + # Step 0: Convert literal \n (backslash+n) to real newlines + result = result.gsub(/\\n/, "\n") + # Step 0.5: Unescape quotes in JSON keys and values (\" -> ") + # This handles cases like {"end_line\":550 or name=\"path\" + result = result.gsub(/\\"/, '"') + # Step 1: Remove XML-style parameter tags that Claude might mix in + # Pattern 1: closing tags - remove completely + result = result.gsub(/<\/parameter>/, '') + + # Pattern 2: or convert to JSON key + # Example: \n 330 -> , "end_line": 330 + # Also handles: \n , "end_line": 330 + # result = result.gsub(//) { |match| ", \"#{$1}\":" } + result = result.gsub(/:]?\s*/) { |match| ", \"#{$1}\": " } + + # Pattern 3: Remove any remaining XML-like tags + result = result.gsub(/<[^>]+>/, '') + + # Step 2: Clean up newlines with commas + # Example: 315\n, "end_line" -> 315, "end_line" + result = result.gsub(/\n\s*,/, ',') + result = result.gsub(/\n,/, ',') + result = result.gsub(/,\s*\n/, ',') + + # Step 3: Clean up formatting issues + # Remove multiple consecutive commas + result = result.gsub(/,+/, ',') + # Remove trailing commas before closing braces/brackets + result = result.gsub(/,\s*}/, '}') + result = result.gsub(/,\s*\]/, ']') + # Remove leading commas after opening braces/brackets + result = result.gsub(/\{\s*,/, '{') + result = result.gsub(/\[\s*,/, '[') + + # Step 4: Complete unclosed strings + result += '"' if result.count('"').odd? + + # Step 5: Complete unclosed braces + depth = 0 + result.each_char { |c| depth += 1 if c == '{'; depth -= 1 if c == '}' } + result += '}' * depth if depth > 0 + + result + end + + # Validate required parameters and filter unknown parameters + def self.validate_required_params(call, args, tool_registry) + tool = tool_registry.get(call[:name]) + required = tool.parameters&.dig(:required) || [] + properties = tool.parameters&.dig(:properties) || {} + + missing = required.reject { |param| + args.key?(param.to_sym) || args.key?(param.to_s) + } + + if missing.any? + raise MissingRequiredParamsError.new(call[:name], missing, args.keys) + end + + # Filter out unknown parameters to prevent errors when LLM sends extra arguments + known_params = properties.keys.map(&:to_sym) + properties.keys.map(&:to_s) + filtered_args = args.select { |key, _| known_params.include?(key) } + + filtered_args + end + + # Generate error message with tool definition + def self.raise_helpful_error(call, tool_registry, original_error) + tool = tool_registry.get(call[:name]) + error_msg = build_error_message(call, tool, original_error) + raise BadArgumentsError, error_msg + end + + def self.build_error_message(call, tool, original_error) + # Extract tool information + required_params = tool.parameters&.dig(:required) || [] + + # Try to parse provided parameters from incomplete JSON + provided_params = extract_provided_params(call[:arguments]) + + # Build clear error message + msg = [] + msg << "Failed to parse arguments for tool '#{call[:name]}'." + msg << "" + msg << "Error: #{original_error.message}" + msg << "" + + if provided_params.any? + msg << "Provided parameters: #{provided_params.join(', ')}" + else + msg << "No valid parameters could be extracted." + end + + msg << "Required parameters: #{required_params.join(', ')}" + msg << "" + msg << "Tool definition:" + msg << format_tool_definition(tool) + msg << "" + msg << "Suggestions:" + msg << "- If the parameter value is too large (e.g., large file content), consider breaking it into smaller operations" + msg << "- Ensure all required parameters are provided" + msg << "- Simplify complex parameter values" + + msg.join("\n") + end + + # Extract parameter names from incomplete JSON + def self.extract_provided_params(json_str) + # Simple extraction: find all "key": patterns + json_str.scan(/"(\w+)"\s*:/).flatten.uniq + end + + # Format tool definition (concise version) + def self.format_tool_definition(tool) + lines = [] + lines << " Name: #{tool.name}" + lines << " Description: #{tool.description}" + + if tool.parameters[:properties] + lines << " Parameters:" + tool.parameters[:properties].each do |param, spec| + required_mark = tool.parameters[:required]&.include?(param.to_s) ? " (required)" : "" + lines << " - #{param}#{required_mark}: #{spec[:description]}" + end + end + + lines.join("\n") + end + end + + # Raised when tool call arguments are malformed or missing required params. + class BadArgumentsError < StandardError; end + + # Custom exception for missing required parameters + class MissingRequiredParamsError < BadArgumentsError + attr_reader :tool_name, :missing_params, :provided_params + + def initialize(tool_name, missing_params, provided_params) + @tool_name = tool_name + @missing_params = missing_params + @provided_params = provided_params + super("Missing required parameters: #{missing_params.join(', ')}") + end + end + end +end diff --git a/lib/clacky/utils/browser_detector.rb b/lib/clacky/utils/browser_detector.rb new file mode 100644 index 0000000..226b0f9 --- /dev/null +++ b/lib/clacky/utils/browser_detector.rb @@ -0,0 +1,195 @@ +# frozen_string_literal: true + +require "socket" + +module Clacky + module Utils + # Detects a running browser (Chrome/Edge) that has remote debugging enabled. + # + # Detection strategy: + # + # 1. Scan known UserData directories for DevToolsActivePort file. + # This file contains the exact port + WS path — most reliable. + # Returns { mode: :ws_endpoint, value: "ws://127.0.0.1:PORT/PATH" } + # + # 2. Verify the port is actually reachable via TCP probe. + # + # 3. Nothing found or port unreachable → returns nil (browser not running). + # + # Supported environments: WSL, Linux, macOS. + module BrowserDetector + + # Detect a running debuggable browser. + # Scans for DevToolsActivePort file across all platforms (macOS/Linux/WSL). + # Returns the detected WebSocket endpoint only if the port is reachable. + # @return [Hash] { mode: :ws_endpoint, value: String, status: :ok|:not_found } + def self.detect + os = EnvironmentDetector.os_type + Clacky::Logger.debug("[BrowserDetector] Starting browser detection (OS: #{os})...") + + detected = detect_via_active_port_file + + unless detected + Clacky::Logger.warn("[BrowserDetector] ✗ No reachable browser found") + return { status: :not_found } + end + + Clacky::Logger.info("[BrowserDetector] ✓ Browser detected and reachable: #{detected[:mode]} → #{detected[:value]}") + detected.merge(status: :ok) + end + + # ----------------------------------------------------------------------- + # DevToolsActivePort file scan + # ----------------------------------------------------------------------- + + # @return [Hash, nil] + def self.detect_via_active_port_file + Clacky::Logger.debug("[BrowserDetector] Scanning UserData directories for DevToolsActivePort...") + + dirs = user_data_dirs + Clacky::Logger.debug("[BrowserDetector] Candidate directories: #{dirs.size} found") + + dirs.each do |dir| + port_file = File.join(dir, "DevToolsActivePort") + next unless File.exist?(port_file) + + Clacky::Logger.debug("[BrowserDetector] Found DevToolsActivePort: #{port_file}") + + ws = parse_active_port_file(port_file) + unless ws + Clacky::Logger.debug("[BrowserDetector] ✗ Failed to parse #{port_file}") + next + end + + Clacky::Logger.debug("[BrowserDetector] Parsed WS endpoint: #{ws}") + + # ⭐️ Verify port BEFORE returning — skip stale files + candidate = { mode: :ws_endpoint, value: ws } + if verify_port(candidate) + Clacky::Logger.debug("[BrowserDetector] ✓ Port is reachable, using this endpoint") + return candidate + else + Clacky::Logger.debug("[BrowserDetector] ✗ Port not reachable, trying next directory...") + end + end + + Clacky::Logger.debug("[BrowserDetector] No reachable browser found") + nil + end + + # Verify that the detected browser port is actually reachable. + # Extracts port from ws:// URL and attempts TCP connection. + # @param detected [Hash] { mode: :ws_endpoint, value: String } + # @return [Boolean] true if port is open and reachable + def self.verify_port(detected) + return false unless detected + + port = case detected[:mode] + when :ws_endpoint + # ws://127.0.0.1:9222/devtools/... + detected[:value][/ws:\/\/127\.0\.0\.1:(\d+)/, 1]&.to_i + end + + return false unless port && port > 0 + + reachable = tcp_open?("127.0.0.1", port) + Clacky::Logger.debug("[BrowserDetector] Port #{port} reachable: #{reachable}") + reachable + end + + # ----------------------------------------------------------------------- + # UserData directory candidates per OS + # ----------------------------------------------------------------------- + + # Returns ordered list of candidate UserData dirs to check. + # @return [Array] + def self.user_data_dirs + os = EnvironmentDetector.os_type + Clacky::Logger.debug("[BrowserDetector] Detected OS: #{os}") + + case os + when :wsl then wsl_user_data_dirs + when :linux then linux_user_data_dirs + when :macos then macos_user_data_dirs + else + Clacky::Logger.warn("[BrowserDetector] Unknown OS type: #{os}") + [] + end + end + + # WSL: Chrome/Edge run on Windows side — resolve via LOCALAPPDATA. + private_class_method def self.wsl_user_data_dirs + appdata = Utils::Encoding.cmd_to_utf8( + `powershell.exe -NoProfile -Command '$env:LOCALAPPDATA' 2>/dev/null` + ).strip.tr("\r\n", "") + return [] if appdata.empty? + + win_paths = [ + "#{appdata}\\Microsoft\\Edge\\User Data", + "#{appdata}\\Google\\Chrome\\User Data", + "#{appdata}\\Google\\Chrome Beta\\User Data", + "#{appdata}\\Google\\Chrome SxS\\User Data", + ] + + win_paths.filter_map do |win_path| + linux_path = Utils::Encoding.cmd_to_utf8( + `wslpath '#{win_path}' 2>/dev/null`, source_encoding: "UTF-8" + ).strip + linux_path.empty? ? nil : linux_path + end + end + + # Linux: standard XDG config paths for Chrome and Edge. + private_class_method def self.linux_user_data_dirs + config_home = ENV["XDG_CONFIG_HOME"] || File.join(Dir.home, ".config") + [ + File.join(config_home, "microsoft-edge"), + File.join(config_home, "google-chrome"), + File.join(config_home, "google-chrome-beta"), + File.join(config_home, "google-chrome-unstable"), + ] + end + + # macOS: Application Support paths for Chrome and Edge. + private_class_method def self.macos_user_data_dirs + base = File.join(Dir.home, "Library", "Application Support") + [ + File.join(base, "Microsoft Edge"), + File.join(base, "Google", "Chrome"), + File.join(base, "Google", "Chrome Beta"), + File.join(base, "Google", "Chrome Canary"), + ] + end + + # ----------------------------------------------------------------------- + # Helpers + # ----------------------------------------------------------------------- + + # Parse DevToolsActivePort file. + # Format: first line = port number, second line = WS path + # @return [String, nil] ws://127.0.0.1:PORT/PATH or nil on parse error + private_class_method def self.parse_active_port_file(path) + lines = File.read(path, encoding: "utf-8").split("\n").map(&:strip).reject(&:empty?) + return nil unless lines.size >= 2 + + port = lines[0].to_i + ws_path = lines[1] + return nil if port <= 0 || port > 65_535 || ws_path.empty? + + "ws://127.0.0.1:#{port}#{ws_path}" + rescue StandardError + nil + end + + # Probe TCP port with a short timeout to verify port is actually reachable. + # @param host [String] hostname + # @param port [Integer] port number + # @return [Boolean] true if port is open and reachable + private_class_method def self.tcp_open?(host, port) + Socket.tcp(host, port, connect_timeout: 0.5) { true } + rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError, Errno::EHOSTUNREACH + false + end + end + end +end diff --git a/lib/clacky/utils/encoding.rb b/lib/clacky/utils/encoding.rb new file mode 100644 index 0000000..a69088f --- /dev/null +++ b/lib/clacky/utils/encoding.rb @@ -0,0 +1,117 @@ +# frozen_string_literal: true + +module Clacky + module Utils + # Centralised UTF-8 encoding helpers used throughout the codebase. + # + # Three distinct use-cases exist: + # + # 1. to_utf8 – binary/unknown bytes → valid UTF-8 String. + # Used when reading shell output, HTTP response bodies, + # or any raw byte stream that is *expected* to be UTF-8 + # but arrives with ASCII-8BIT (binary) encoding. + # Strategy: force_encoding("UTF-8") then scrub invalid + # sequences with U+FFFD so multibyte characters (CJK, + # emoji, …) are preserved as-is. + # + # 2. sanitize_utf8 – UTF-8 String → clean UTF-8 String. + # Used for UI rendering (terminal output, screen + # buffers) where the string is already nominally UTF-8 + # but may still contain isolated invalid bytes. + # Strategy: encode UTF-8→UTF-8 replacing invalid / + # undefined codepoints with an empty string so the + # rendered output never contains replacement characters. + # + # 3. safe_check – any String → ASCII-safe UTF-8 String for regex. + # Used only for security pattern matching (terminal/Security). + # Multibyte bytes are replaced with '?' so that Ruby's + # regex engine operates on a plain ASCII-compatible + # string without raising Encoding errors. + # + module Encoding + # Convert a binary (or unknown-encoding) byte string to a valid UTF-8 + # String. Multibyte sequences that are already valid UTF-8 (e.g. CJK + # characters) are preserved unchanged; only genuinely invalid byte + # sequences are replaced with U+FFFD (the Unicode replacement character). + # + # @param data [String, nil] raw bytes, typically from a pipe or HTTP body + # @return [String] valid UTF-8 string + def self.to_utf8(data) + return "" if data.nil? || data.empty? + + data.dup.force_encoding("UTF-8").scrub("\u{FFFD}") + end + + # Clean an already-UTF-8 string by removing (not replacing) any invalid + # or undefined byte sequences. Suitable for terminal / UI rendering where + # replacement characters would appear as visual noise. + # + # @param str [String, nil] nominally UTF-8 string + # @return [String] clean UTF-8 string (invalid bytes silently dropped) + def self.sanitize_utf8(str) + return "" if str.nil? || str.empty? + + str.encode("UTF-8", "UTF-8", invalid: :replace, undef: :replace, replace: "") + end + + # Convert raw shell command output to valid UTF-8. + # Handles two common cases: + # - Windows commands (e.g. powershell.exe) that output GBK/CP936 bytes + # - Unix commands that output UTF-8 or ASCII bytes with ASCII-8BIT encoding + # + # Strategy: try GBK decode first (superset of ASCII, covers Chinese Windows); + # if that fails fall back to UTF-8 scrub. + # + # @param data [String, nil] raw bytes from backtick / IO.popen + # @param source_encoding [String] hint for source encoding (default: "GBK") + # @return [String] valid UTF-8 string + def self.cmd_to_utf8(data, source_encoding: "GBK") + return "" if data.nil? || data.empty? + + data.dup + .force_encoding(source_encoding) + .encode("UTF-8", invalid: :replace, undef: :replace, replace: "") + rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError + to_utf8(data) + end + + # Decode a raw PTY byte stream to valid UTF-8, auto-detecting the source + # encoding. UTF-8 is tried first (Linux/macOS and modern programs); when + # the bytes are not valid UTF-8 they are decoded as GBK/CP936 (Simplified + # Chinese Windows powershell.exe / cmd.exe default output); anything that + # still fails is scrubbed. + # + # MUST be called on complete byte runs — callers slice on "\n" (0x0A), + # which is never a trailing byte of a GBK or UTF-8 multibyte sequence, so + # a character is never split across the boundary. + # + # @param data [String, nil] raw PTY bytes (binary/ASCII-8BIT) + # @return [String] valid UTF-8 string + def self.pty_to_utf8(data) + return "" if data.nil? || data.empty? + + s = data.dup.force_encoding("UTF-8") + return s if s.valid_encoding? + + data.dup + .force_encoding("GBK") + .encode("UTF-8", invalid: :replace, undef: :replace, replace: "?") + rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError + to_utf8(data) + end + + # Return an ASCII-safe UTF-8 copy of *str* suitable for security regex + # pattern matching. Any byte that is not valid in the source encoding, or + # that cannot be represented in UTF-8, is replaced with '?'. The + # original string is never mutated. + # + # @param str [String, nil] + # @return [String] UTF-8 string safe for regex matching + def self.safe_check(str) + return "" if str.nil? || str.empty? + + str.encode("UTF-8", invalid: :replace, undef: :replace, replace: "?") + end + end + end +end diff --git a/lib/clacky/utils/environment_detector.rb b/lib/clacky/utils/environment_detector.rb new file mode 100644 index 0000000..fa9671d --- /dev/null +++ b/lib/clacky/utils/environment_detector.rb @@ -0,0 +1,156 @@ +# frozen_string_literal: true + +module Clacky + module Utils + # Detects the current operating system environment and desktop path. + module EnvironmentDetector + # Detect OS type. + # @return [Symbol] :wsl, :linux, :macos, or :unknown + def self.os_type + return @os_type if defined?(@os_type) + + @os_type = if wsl? + :wsl + elsif RUBY_PLATFORM.include?("darwin") + :macos + elsif RUBY_PLATFORM.include?("linux") + :linux + else + :unknown + end + end + + # Open a file with the OS-default application. + # On WSL, uses "cmd.exe /c start" instead of explorer.exe so the opened + # window receives foreground focus even when called from a background + # thread (e.g. WEBrick request handler). + # @param path [String] Linux-side file path + # @return [Boolean, nil] true/false from system(), or nil on unsupported OS + def self.open_file(path) + case os_type + when :macos then system("open", path) + when :linux then system("xdg-open", path) + when :wsl + win_path = linux_to_win_path(path) + system("cmd.exe", "/c", "start", "", win_path) + end + end + + # Reveal a file in the OS file manager (select/highlight it). + # macOS: open -R; Linux: xdg-open on parent dir; WSL: explorer /select + # @param path [String] Linux-side file path + # @return [Boolean, nil] true/false from system(), or nil on unsupported OS + def self.reveal_file(path) + case os_type + when :macos then system("open", "-R", path) + when :linux then system("xdg-open", File.dirname(path)) + when :wsl + win_path = linux_to_win_path(path) + system("explorer.exe", "/select,#{win_path}") + else + nil + end + end + + # Convert a Windows-style path to a WSL/Linux-side path. + # e.g. "C:/Users/foo/file.txt" → "/mnt/c/Users/foo/file.txt" + # Returns the original path unchanged on non-WSL or if already a Linux path. + # @param path [String] + # @return [String] + def self.win_to_linux_path(path) + return path unless os_type == :wsl && path.match?(/\A[A-Za-z]:[\/\\]/) + + drive = path[0].downcase + rest = path[2..].gsub("\\", "/") + "/mnt/#{drive}#{rest}" + end + + # Convert a Linux-side path to a Windows-style path via wslpath. + # e.g. "/mnt/c/Users/foo/file.txt" → "C:\Users\foo\file.txt" + # Returns the original path unchanged on non-WSL. + # @param path [String] + # @return [String] + def self.linux_to_win_path(path) + return path unless os_type == :wsl + + Clacky::Utils::Encoding.cmd_to_utf8( + `wslpath -w '#{path.gsub("'", "'\''")}'`, + source_encoding: "UTF-8" + ).strip + end + + # Human-readable OS label for injection into session context. + def self.os_label + case os_type + when :wsl then "WSL/Windows" + when :macos then "macOS" + when :linux then "Linux" + else "Unknown" + end + end + + # Detect the desktop directory path for the current environment. + # @return [String, nil] absolute path to desktop, or nil if not found + def self.desktop_path + return @desktop_path if defined?(@desktop_path) + + @desktop_path = case os_type + when :wsl + wsl_desktop_path + when :macos + macos_desktop_path + when :linux + linux_desktop_path + else + fallback_desktop_path + end + end + + def self.wsl? + File.exist?("/proc/version") && + File.read("/proc/version").downcase.include?("microsoft") + rescue + false + end + + private_class_method def self.wsl_desktop_path + if Utils::Encoding.cmd_to_utf8(`which powershell.exe 2>/dev/null`).strip.empty? + return fallback_desktop_path + end + + # powershell.exe on Chinese Windows outputs GBK bytes; decode explicitly + win_path = Utils::Encoding.cmd_to_utf8( + `powershell.exe -NoProfile -Command '[Environment]::GetFolderPath("Desktop")' 2>/dev/null` + ).strip.tr("\r\n", "") + return fallback_desktop_path if win_path.empty? + + # wslpath output is UTF-8 (Linux side) + linux_path = Utils::Encoding.cmd_to_utf8(`wslpath '#{win_path}' 2>/dev/null`, source_encoding: "UTF-8").strip + return linux_path if !linux_path.empty? && Dir.exist?(linux_path) + + fallback_desktop_path + end + + private_class_method def self.linux_desktop_path + path = Utils::Encoding.cmd_to_utf8(`xdg-user-dir DESKTOP 2>/dev/null`, source_encoding: "UTF-8").strip + return path if !path.empty? && path != Dir.home && Dir.exist?(path) + + fallback_desktop_path + end + + private_class_method def self.macos_desktop_path + path = Utils::Encoding.cmd_to_utf8(`osascript -e 'POSIX path of (path to desktop)' 2>/dev/null`, source_encoding: "UTF-8").strip.chomp("/") + return path if !path.empty? && Dir.exist?(path) + + fallback_desktop_path + end + + private_class_method def self.fallback_desktop_path + [ + File.join(Dir.home, "Desktop"), + File.join(Dir.home, "桌面"), + ].find { |p| Dir.exist?(p) } + end + end + end +end diff --git a/lib/clacky/utils/file_ignore_helper.rb b/lib/clacky/utils/file_ignore_helper.rb new file mode 100644 index 0000000..363b5f5 --- /dev/null +++ b/lib/clacky/utils/file_ignore_helper.rb @@ -0,0 +1,243 @@ +# frozen_string_literal: true + +module Clacky + module Utils + # Helper module for file ignoring functionality shared between tools + module FileIgnoreHelper + # Default patterns to ignore when .gitignore is not available + DEFAULT_IGNORED_PATTERNS = [ + 'node_modules', + 'vendor/bundle', + '.git', + '.svn', + 'tmp', + 'log', + 'coverage', + 'dist', + 'build', + '.bundle', + '.sass-cache', + '.DS_Store', + '*.log' + ].freeze + + # Config file patterns that should always be searchable/visible + CONFIG_FILE_PATTERNS = [ + /\.env/, + /\.ya?ml$/, + /\.json$/, + /\.toml$/, + /\.ini$/, + /\.conf$/, + /\.config$/, + ].freeze + + # Find .gitignore file in the search path or parent directories + # Only searches within the search path and up to the current working directory + def self.find_gitignore(path) + search_path = File.directory?(path) ? path : File.dirname(path) + + # Look for .gitignore in current and parent directories + current = File.expand_path(search_path) + cwd = File.expand_path(Dir.pwd) # intentional: gitignore boundary uses process cwd as fallback + root = File.expand_path('/') + + # Limit search: only go up to current working directory + # This prevents finding .gitignore files from unrelated parent directories + # when searching in temporary directories (like /tmp in tests) + search_limit = if current.start_with?(cwd) + cwd + else + current + end + + loop do + gitignore = File.join(current, '.gitignore') + return gitignore if File.exist?(gitignore) + + # Stop if we've reached the search limit or root + break if current == search_limit || current == root + current = File.dirname(current) + end + + nil + end + + # Directories that are always ignored regardless of .gitignore rules + ALWAYS_IGNORED_DIRS = ['.git', '.svn', '.hg'].freeze + + # Check if file should be ignored based on .gitignore or default patterns + def self.should_ignore_file?(file, base_path, gitignore) + # Always calculate path relative to base_path for consistency + # Expand both paths to handle symlinks and relative paths correctly + expanded_file = File.expand_path(file) + expanded_base = File.expand_path(base_path) + + # For files, use the directory as base + expanded_base = File.dirname(expanded_base) if File.file?(expanded_base) + + # Calculate relative path + if expanded_file.start_with?(expanded_base) + relative_path = expanded_file[(expanded_base.length + 1)..-1] || File.basename(expanded_file) + else + # File is outside base path - use just the filename + relative_path = File.basename(expanded_file) + end + + # Clean up relative path + relative_path = relative_path.sub(/^\.\//, '') if relative_path + + # Always ignore version control directories regardless of .gitignore rules + return true if ALWAYS_IGNORED_DIRS.any? do |dir| + relative_path.start_with?("#{dir}/") || relative_path == dir + end + + if gitignore + # Use .gitignore rules + gitignore.ignored?(relative_path) + else + # Use default ignore patterns - only match against relative path components + DEFAULT_IGNORED_PATTERNS.any? do |pattern| + if pattern.include?('*') + File.fnmatch(pattern, relative_path, File::FNM_PATHNAME | File::FNM_DOTMATCH) + else + # Match pattern as a path component (not substring of absolute path) + relative_path.start_with?("#{pattern}/") || + relative_path.include?("/#{pattern}/") || + relative_path == pattern || + File.basename(relative_path) == pattern + end + end + end + end + + # Check if file is a config file (should not be ignored even if in .gitignore) + def self.is_config_file?(file) + CONFIG_FILE_PATTERNS.any? { |pattern| file.match?(pattern) } + end + + # Paths considered too broad to recursively walk by default. Searching from + # these would commonly traverse millions of files (system roots, $HOME with + # many workspaces, WSL Windows mounts). Tools should refuse such requests + # and ask for a narrower base_path. + def self.dangerous_root?(path) + return false if path.nil? || path.empty? + + expanded = File.expand_path(path) + return true if expanded == "/" + + system_roots = ["/root", "/home", "/Users", "/mnt", "/media", "/var", "/etc", "/usr", "/opt"] + return true if system_roots.include?(expanded) + + ["/Users/", "/home/"].each do |prefix| + next unless expanded.start_with?(prefix) + tail = expanded[prefix.length..] + return true if tail && !tail.empty? && !tail.include?("/") + end + + return true if expanded =~ %r{\A/mnt/[a-zA-Z]\z} + + home = ENV["HOME"] + return true if home && !home.empty? && expanded == File.expand_path(home) + + false + end + + # Hard ceiling on directories visited in a single walk. Prevents indefinite + # traversal across huge trees (e.g. /root, $HOME, /mnt/c on WSL). + MAX_DIRS_VISITED = 20_000 + + # Wall-clock budget for a single walk, in seconds. + WALK_TIMEOUT_SECONDS = 15 + + # Raised internally to abort a walk when a budget is exhausted. + class WalkBudgetExceeded < StandardError + attr_reader :reason + def initialize(reason) + @reason = reason + super(reason.to_s) + end + end + + # Walk a directory tree, pruning ignored directories early. + # Yields each non-ignored file path. Supports nested .gitignore files. + # @param skipped [Hash, nil] If provided, increments :ignored for each gitignore-skipped entry. + # @param status [Hash, nil] If provided, populated with :truncated and :truncation_reason + # when the walk is aborted due to dir-count or wall-clock budget. + def self.walk_files(base_path, gitignore: nil, skipped: nil, status: nil, + max_dirs_visited: MAX_DIRS_VISITED, + timeout_seconds: WALK_TIMEOUT_SECONDS, + &block) + unless block_given? + return enum_for(:walk_files, base_path, + gitignore: gitignore, skipped: skipped, status: status, + max_dirs_visited: max_dirs_visited, timeout_seconds: timeout_seconds) + end + + root_gitignore = gitignore || begin + gi_path = find_gitignore(base_path) + gi_path ? Clacky::GitignoreParser.new(gi_path) : nil + end + + budget = { + dirs_visited: 0, + max_dirs: max_dirs_visited, + deadline: timeout_seconds ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout_seconds) : nil + } + + begin + _walk_recursive(base_path, base_path, root_gitignore, skipped, budget, &block) + rescue WalkBudgetExceeded => e + if status + status[:truncated] = true + status[:truncation_reason] = e.reason.to_s + end + end + end + + def self._walk_recursive(dir, base_path, gitignore, skipped, budget, &block) + budget[:dirs_visited] += 1 + if budget[:dirs_visited] > budget[:max_dirs] + raise WalkBudgetExceeded.new(:max_dirs_visited) + end + if budget[:deadline] && Process.clock_gettime(Process::CLOCK_MONOTONIC) > budget[:deadline] + raise WalkBudgetExceeded.new(:timeout) + end + + child_gitignore_path = File.join(dir, ".gitignore") + if dir != base_path && File.exist?(child_gitignore_path) + gitignore ||= Clacky::GitignoreParser.new(nil) + relative_dir = dir[(base_path.length + 1)..] + gitignore.merge!(child_gitignore_path, prefix: relative_dir) + end + + begin + entries = Dir.children(dir) + rescue Errno::EACCES, Errno::ENOENT + return + end + + entries.sort.each do |name| + full = File.join(dir, name) + relative = full[(base_path.length + 1)..] + + if File.directory?(full) + next if ALWAYS_IGNORED_DIRS.include?(name) + if gitignore&.ignored?("#{relative}/") || should_ignore_file?(full, base_path, gitignore) + next + end + _walk_recursive(full, base_path, gitignore, skipped, budget, &block) + else + if !is_config_file?(full) && should_ignore_file?(full, base_path, gitignore) + skipped[:ignored] += 1 if skipped + next + end + yield full + end + end + end + private_class_method :_walk_recursive + + end + end +end diff --git a/lib/clacky/utils/file_processor.rb b/lib/clacky/utils/file_processor.rb new file mode 100644 index 0000000..4e75cbb --- /dev/null +++ b/lib/clacky/utils/file_processor.rb @@ -0,0 +1,675 @@ +# frozen_string_literal: true + +require "tmpdir" +require "fileutils" +require "securerandom" +require "stringio" + +require_relative "parser_manager" +require "zip" + +module Clacky + module Utils + # File processing pipeline. + # + # Two entry points: + # FileProcessor.save(body:, filename:) + # → Store raw bytes to disk only. Returns { name:, path: }. + # Used by http_server and channel adapters — no parsing here. + # + # FileProcessor.process_path(path, name: nil) + # → Parse an already-saved file. Returns FileRef (with preview_path or parse_error). + # Used by agent.run when building the file prompt. + # + # (FileProcessor.process = save + process_path in one call, for convenience.) + module FileProcessor + UPLOAD_DIR = File.join(Dir.tmpdir, "clacky-uploads").freeze + MAX_FILE_BYTES = 32 * 1024 * 1024 # 32 MB + MAX_IMAGE_BYTES = 5 * 1024 * 1024 # 5 MB + + # Alias used by FileReader tool + MAX_FILE_SIZE = MAX_FILE_BYTES + + # Images wider than this will be downscaled before sending to LLM (pixels) + IMAGE_MAX_WIDTH = 800 + # Hard limit for images that can't be resized: Anthropic/Bedrock vision API supports up to 5MB + IMAGE_MAX_BASE64_BYTES = 5_000_000 + + BINARY_EXTENSIONS = %w[ + .png .jpg .jpeg .gif .webp .bmp .tiff .ico .svg + .pdf + .zip .gz .tgz .tar .rar .7z + .exe .dll .so .dylib + .mp3 .mp4 .avi .mov .mkv .wav .flac + .ttf .otf .woff .woff2 + .db .sqlite .bin .dat + .wps .et .dps + ].freeze + + GLOB_ALLOWED_BINARY_EXTENSIONS = %w[ + .pdf .doc .docx .ppt .pptx .xls .xlsx .odt .odp .ods + .wps .et .dps + ].freeze + + LLM_BINARY_EXTENSIONS = %w[.png .jpg .jpeg .gif .webp .pdf].freeze + + MIME_TYPES = { + ".png" => "image/png", + ".jpg" => "image/jpeg", + ".jpeg" => "image/jpeg", + ".gif" => "image/gif", + ".webp" => "image/webp", + ".mp4" => "video/mp4", + ".webm" => "video/webm", + ".mov" => "video/quicktime", + ".wav" => "audio/wav", + ".mp3" => "audio/mpeg", + ".ogg" => "audio/ogg", + ".aac" => "audio/aac", + ".flac" => "audio/flac", + ".m4a" => "audio/mp4", + ".pdf" => "application/pdf" + }.freeze + + FILE_TYPES = { + ".docx" => :document, ".doc" => :document, + ".xlsx" => :spreadsheet, ".xls" => :spreadsheet, + ".pptx" => :presentation, ".ppt" => :presentation, + ".wps" => :document, ".et" => :spreadsheet, ".dps" => :presentation, + ".pdf" => :pdf, + ".zip" => :zip, ".gz" => :zip, ".tgz" => :zip, ".tar" => :zip, ".rar" => :zip, ".7z" => :zip, + ".png" => :image, ".jpg" => :image, ".jpeg" => :image, + ".gif" => :image, ".webp" => :image, + ".csv" => :csv, + ".md" => :text, ".markdown" => :text, ".txt" => :text, ".log" => :text + }.freeze + + # Plain-text extensions whose raw content can be embedded directly as the + # preview (no external parser needed). Kept conservative to avoid pulling + # in huge source files by mistake. + TEXT_PREVIEW_EXTENSIONS = %w[.md .markdown .txt .log].freeze + + # FileRef: result of process / process_path. + FileRef = Struct.new(:name, :type, :original_path, :preview_path, :parse_error, :parser_path, keyword_init: true) do + def parse_failed? + preview_path.nil? && !parse_error.nil? + end + end + + # --------------------------------------------------------------------------- + # Public API + # --------------------------------------------------------------------------- + + # Store raw bytes to disk — no parsing. + # Used by http_server upload endpoint and channel adapters. + # + # @return [Hash] { name: String, path: String } + def self.save(body:, filename:) + FileUtils.mkdir_p(UPLOAD_DIR) + safe_name = sanitize_filename(filename) + dest = File.join(UPLOAD_DIR, "#{SecureRandom.hex(8)}_#{safe_name}") + File.binwrite(dest, body) + { name: safe_name, path: dest } + end + + # Parse an already-saved file and return a FileRef. + # Called by agent.run for each disk file before building the prompt. + # + # @param path [String] Path to the file on disk + # @param name [String] Display name (defaults to basename) + # @return [FileRef] + def self.process_path(path, name: nil) + name ||= File.basename(path.to_s) + # Use compound extension for .tar.gz so it's treated as a tarball, not gzip. + basename_lower = name.to_s.downcase + ext = + if basename_lower.end_with?(".tar.gz") + ".tar.gz" + else + File.extname(path.to_s).downcase + end + type = FILE_TYPES[ext] || :file + + case ext + when ".zip" + body = File.binread(path) + preview_content = parse_zip_listing(body) + preview_path = save_preview(preview_content, path) + FileRef.new(name: name, type: :zip, original_path: path, preview_path: preview_path) + + when ".tar", ".tar.gz", ".tgz", ".gz" + # Archive listing for tarballs and gzip'd files. Provides the LLM a + # file-tree preview so it can decide whether to ask the user to + # extract them (via the shell tool). + begin + preview_content = parse_tar_listing(path, ext) + preview_path = save_preview(preview_content, path) + FileRef.new(name: name, type: :zip, original_path: path, preview_path: preview_path) + rescue => e + FileRef.new(name: name, type: :zip, original_path: path, parse_error: e.message) + end + + when ".png", ".jpg", ".jpeg", ".gif", ".webp" + FileRef.new(name: name, type: :image, original_path: path) + + when ".csv" + # CSV is plain text — the file itself IS the preview. No parser, no copy. + # FileReader handles encoding fallback via safe_utf8 when it reads the file. + FileRef.new(name: name, type: :csv, original_path: path, preview_path: path) + + when *TEXT_PREVIEW_EXTENSIONS + # Markdown / plain text / log: the file itself IS the preview. + # No parser needed, no tmpdir copy — just point preview_path at the original. + FileRef.new(name: name, type: :text, original_path: path, preview_path: path) + + else + result = Utils::ParserManager.parse(path) + if result[:success] + preview_path = save_preview(result[:text], path) + FileRef.new(name: name, type: type, original_path: path, preview_path: preview_path) + else + FileRef.new(name: name, type: type, original_path: path, + parse_error: result[:error], parser_path: result[:parser_path]) + end + end + end + + # Save + parse in one call (convenience method). + # + # @return [FileRef] + def self.process(body:, filename:) + saved = save(body: body, filename: filename) + process_path(saved[:path], name: saved[:name]) + end + + # Save raw image bytes to disk and return a FileRef. + # Used by agent when an image exceeds MAX_IMAGE_BYTES and must be downgraded to disk. + def self.save_image_to_disk(body:, mime_type:, filename: "image.jpg") + FileUtils.mkdir_p(UPLOAD_DIR) + safe_name = sanitize_filename(filename) + dest = File.join(UPLOAD_DIR, "#{SecureRandom.hex(8)}_#{safe_name}") + File.binwrite(dest, body) + FileRef.new(name: safe_name, type: :image, original_path: dest) + end + + # --------------------------------------------------------------------------- + # File type helpers (used by tools and agent) + # --------------------------------------------------------------------------- + + def self.binary_file_path?(path) + ext = File.extname(path).downcase + return true if BINARY_EXTENSIONS.include?(ext) + File.binread(path, 512).to_s.include?("\x00") + rescue + false + end + + def self.glob_allowed_binary?(path) + GLOB_ALLOWED_BINARY_EXTENSIONS.include?(File.extname(path).downcase) + end + + def self.supported_binary_file?(path) + LLM_BINARY_EXTENSIONS.include?(File.extname(path).downcase) + end + + def self.detect_mime_type(path, _data = nil) + MIME_TYPES[File.extname(path).downcase] || "application/octet-stream" + end + + # Downscale a base64-encoded image so its width is at most max_width pixels. + # + # Strategy: + # PNG → chunky_png (pure Ruby, always available as gem dependency) + # other formats (JPG/WEBP/GIF) → sips on macOS, `convert` (ImageMagick) on Linux + # fallback (no CLI tool) → return as-is, but raise if larger than IMAGE_MAX_BASE64_BYTES + # + # @param b64 [String] base64-encoded image data + # @param mime_type [String] e.g. "image/png", "image/jpeg", "image/webp" + # @param max_width [Integer] maximum output width in pixels (default: IMAGE_MAX_WIDTH) + # @return [String] base64-encoded (possibly downscaled) image data + def self.downscale_image_base64(b64, mime_type, max_width: IMAGE_MAX_WIDTH) + require "base64" + + result = if mime_type == "image/png" + downscale_png_chunky(b64, max_width) + else + downscale_via_cli(b64, mime_type, max_width) + end + + return result if result + + # No resize tool available — enforce API hard size limit (5MB) + if b64.bytesize > IMAGE_MAX_BASE64_BYTES + size_kb = b64.bytesize / 1024 + limit_mb = IMAGE_MAX_BASE64_BYTES / 1_000_000 + raise ArgumentError, + "Image too large to send (#{size_kb}KB > #{limit_mb}MB). " \ + "Install ImageMagick (`brew install imagemagick`) to enable automatic resizing." + end + b64 + end + + def self.file_to_base64(path) + require "base64" + ext = File.extname(path).downcase + size = File.size(path) + raise ArgumentError, "File too large: #{path}" if size > MAX_FILE_BYTES + ext_mime = MIME_TYPES[ext] || "application/octet-stream" + raw_data = File.binread(path) + # Detect actual image format from magic bytes (ignore misleading extensions) + mime = ext_mime.start_with?("image/") ? detect_image_mime_type(raw_data, ext_mime) : ext_mime + data = Base64.strict_encode64(raw_data) + # Downscale images before sending to LLM to reduce token cost + data = downscale_image_base64(data, mime) if mime.start_with?("image/") + { format: ext[1..], mime_type: mime, size_bytes: size, base64_data: data } + end + + def self.image_path_to_data_url(path) + raise ArgumentError, "Image file not found: #{path}" unless File.exist?(path) + size = File.size(path) + if size > MAX_IMAGE_BYTES + raise ArgumentError, "Image too large (#{size / 1024}KB > #{MAX_IMAGE_BYTES / 1024}KB): #{path}" + end + require "base64" + # Extension-based guess as fallback only + ext = File.extname(path).downcase.delete(".") + ext_mime = case ext + when "jpg", "jpeg" then "image/jpeg" + when "png" then "image/png" + when "gif" then "image/gif" + when "webp" then "image/webp" + else "image/#{ext}" + end + raw_data = File.binread(path) + # Detect actual image format from magic bytes (ignore misleading extensions) + mime = detect_image_mime_type(raw_data, ext_mime) + b64 = Base64.strict_encode64(raw_data) + # Downscale images before sending to LLM to reduce token cost + b64 = downscale_image_base64(b64, mime) + "data:#{mime};base64,#{b64}" + end + + # --------------------------------------------------------------------------- + # Private helpers + # --------------------------------------------------------------------------- + + def self.parse_zip_listing(body) + lines = ["# ZIP Contents\n"] + Zip::InputStream.open(StringIO.new(body)) do |zis| + while (entry = zis.get_next_entry) + size = entry.size ? " (#{entry.size} bytes)" : "" + lines << "- #{entry.name}#{size}" + end + end + lines.join("\n") + rescue => e + "# ZIP Contents\n(could not list entries: #{e.message})" + end + + # List entries in a tarball or gzip file. + # + # Handles: + # .tar → raw tar reader + # .tar.gz/.tgz → gunzip stream + tar reader + # .gz → single gzipped file → show original filename + uncompressed size + def self.parse_tar_listing(path, ext) + require "rubygems/package" + require "zlib" + + case ext + when ".tar" + lines = ["# TAR Contents\n"] + File.open(path, "rb") do |file| + Gem::Package::TarReader.new(file) do |tar| + tar.each do |entry| + kind = entry.directory? ? "[dir] " : "" + size = entry.header.size ? " (#{entry.header.size} bytes)" : "" + lines << "- #{kind}#{entry.full_name}#{size}" + end + end + end + lines.join("\n") + + when ".tar.gz", ".tgz" + lines = ["# TAR.GZ Contents\n"] + File.open(path, "rb") do |file| + Zlib::GzipReader.wrap(file) do |gz| + Gem::Package::TarReader.new(gz) do |tar| + tar.each do |entry| + kind = entry.directory? ? "[dir] " : "" + size = entry.header.size ? " (#{entry.header.size} bytes)" : "" + lines << "- #{kind}#{entry.full_name}#{size}" + end + end + end + end + lines.join("\n") + + when ".gz" + # Could be gzipped-tar with a misleading extension, or a single-file gzip. + # Try tar first; on failure, fall back to single-file metadata. + begin + lines = ["# TAR.GZ Contents\n"] + found_tar = false + File.open(path, "rb") do |file| + Zlib::GzipReader.wrap(file) do |gz| + Gem::Package::TarReader.new(gz) do |tar| + tar.each do |entry| + found_tar = true + kind = entry.directory? ? "[dir] " : "" + size = entry.header.size ? " (#{entry.header.size} bytes)" : "" + lines << "- #{kind}#{entry.full_name}#{size}" + end + end + end + end + return lines.join("\n") if found_tar + rescue StandardError + # fall through to single-file gzip handling + end + + # Single-file gzip: report the original filename (if recorded) and compressed/uncompressed sizes. + original_name = nil + uncompressed = nil + File.open(path, "rb") do |file| + Zlib::GzipReader.wrap(file) do |gz| + original_name = gz.orig_name + # Read fully to get the uncompressed size. Guarded: stop after 64MB + # to avoid blowing memory on pathological inputs — the preview only + # needs a size estimate, not the content. + limit = 64 * 1024 * 1024 + total = 0 + while (chunk = gz.read(1024 * 1024)) + total += chunk.bytesize + break if total > limit + end + uncompressed = total + end + end + lines = ["# GZIP Contents\n"] + lines << "- Original filename: #{original_name || "(not recorded)"}" + lines << "- Compressed size: #{File.size(path)} bytes" + lines << "- Uncompressed size: #{uncompressed} bytes#{uncompressed && uncompressed > 64 * 1024 * 1024 ? " (truncated)" : ""}" + lines.join("\n") + end + rescue => e + "# Archive Contents\n(could not list entries: #{e.message})" + end + + def self.save_preview(content, original_path) + # Always write previews to a tmpdir-based path to avoid polluting the + # user's working directory with .preview.md sidecar files. + # Use the same UPLOAD_DIR that uploaded files live in; for on-disk files + # outside that dir (e.g. project files opened by file_reader), we still + # land in UPLOAD_DIR so the user's tree stays clean. + FileUtils.mkdir_p(UPLOAD_DIR) + safe_name = File.basename(original_path.to_s).gsub(/[\/\:\*?"<>|\x00]/, "_") + dest = File.join(UPLOAD_DIR, "#{SecureRandom.hex(8)}_#{safe_name}.preview.md") + File.write(dest, content) + dest + end + + def self.sanitize_filename(name) + # Keep Unicode letters/digits (including CJK), ASCII word chars, dots, hyphens, spaces. + # Only strip characters that are unsafe on common filesystems: / \ : * ? " < > | \0 + # to_utf8 first: HTTP multipart headers arrive as ASCII-8BIT on Ruby 2.6, + # and regex matching against ASCII-8BIT raises "invalid byte sequence in UTF-8". + base = File.basename(Clacky::Utils::Encoding.to_utf8(name.to_s)) + .gsub(/[\/\\:\*?"<>|\x00]/, '_') + .strip + base.empty? ? 'upload' : base + end + + # Detect the actual image MIME type from raw binary data by inspecting + # magic bytes, ignoring the file extension. Falls back to extension-based + # detection when magic bytes don't match any known format. + # + # Handles: PNG, JPEG, GIF, WEBP, BMP, TIFF + # + # @param data [String] raw binary data (first 12 bytes is sufficient) + # @param fallback_mime [String] MIME type from extension, used as fallback + # @return [String] detected MIME type (e.g. "image/png", "image/jpeg") + def self.detect_image_mime_type(data, fallback_mime = "image/png") + return fallback_mime if data.nil? || data.bytesize < 4 + + bytes = data.bytes + + case + # PNG: \x89 P N G \r \n \x1a \n + when bytes[0] == 0x89 && bytes[1] == 0x50 && bytes[2] == 0x4E && bytes[3] == 0x47 + "image/png" + # JPEG: \xFF \xD8 \xFF + when bytes[0] == 0xFF && bytes[1] == 0xD8 && bytes[2] == 0xFF + "image/jpeg" + # GIF: GIF87a or GIF89a + when bytes[0] == 0x47 && bytes[1] == 0x49 && bytes[2] == 0x46 && bytes[3] == 0x38 + "image/gif" + # WEBP: RIFF .... WEBP + when bytes[0] == 0x52 && bytes[1] == 0x49 && bytes[2] == 0x46 && bytes[3] == 0x46 && + data.bytesize >= 12 && data[8, 4] == "WEBP" + "image/webp" + # BMP: BM + when bytes[0] == 0x42 && bytes[1] == 0x4D + "image/bmp" + # TIFF: II*\x00 (little-endian) or MM\x00* (big-endian) + when (bytes[0] == 0x49 && bytes[1] == 0x49 && bytes[2] == 0x2A && bytes[3] == 0x00) || + (bytes[0] == 0x4D && bytes[1] == 0x4D && bytes[2] == 0x00 && bytes[3] == 0x2A) + "image/tiff" + else + fallback_mime + end + end + + # --------------------------------------------------------------------------- + # Image downscale helpers (private) + # --------------------------------------------------------------------------- + + # Downscale a PNG using chunky_png (pure Ruby — always available). + # Returns downscaled base64, or original base64 if already within max_width. + def self.downscale_png_chunky(b64, max_width) + require "chunky_png" + require "base64" + image = ChunkyPNG::Image.from_blob(Base64.strict_decode64(b64)) + return b64 if image.width <= max_width + + src_w, src_h = image.width, image.height + dst_h = (src_h * max_width.to_f / src_w).round + image.resample_nearest_neighbor!(max_width, dst_h) + before_kb = b64.bytesize / 1024 + result = Base64.strict_encode64(image.to_blob) + after_kb = result.bytesize / 1024 + Clacky::Logger.debug("image_downscaled", + format: "png", + from: "#{src_w}x#{src_h} (#{before_kb}KB)", + to: "#{max_width}x#{dst_h} (#{after_kb}KB)") + result + rescue => e + Clacky::Logger.debug("image_downscale_skipped", format: "png", reason: e.message) + nil + end + + # Downscale a non-PNG image using CLI tools: + # macOS → sips (built-in, no extra deps) + # Linux → convert (ImageMagick, must be installed) + # Returns downscaled base64, or nil if no tool is available. + def self.downscale_via_cli(b64, mime_type, max_width) + require "base64" + require "tmpdir" + + ext = mime_type.split("/").last + ext = "jpg" if ext == "jpeg" + + # Write input to a temp file + Dir.mktmpdir("clacky-img") do |dir| + input = File.join(dir, "input.#{ext}") + output = File.join(dir, "output.#{ext}") + File.binwrite(input, Base64.strict_decode64(b64)) + + before_kb = b64.bytesize / 1024 + success = false + + if RUBY_PLATFORM.include?("darwin") + # macOS: sips is always available + success = system("sips", "-Z", max_width.to_s, input, "--out", output, + out: File::NULL, err: File::NULL) + else + # Linux/other: try ImageMagick convert + if system("which convert > /dev/null 2>&1") + success = system("convert", input, "-resize", "#{max_width}x>", + output, out: File::NULL, err: File::NULL) + end + end + + return nil unless success && File.exist?(output) && File.size(output) > 0 + + result = Base64.strict_encode64(File.binread(output)) + after_kb = result.bytesize / 1024 + Clacky::Logger.debug("image_downscaled", + format: ext, + from: "#{before_kb}KB", + to: "#{after_kb}KB (max #{max_width}px wide)") + result + end + rescue => e + Clacky::Logger.debug("image_downscale_skipped", mime: mime_type, reason: e.message) + nil + end + + # Image extensions that can be inlined as data URLs in markdown content. + LOCAL_IMAGE_EXTENSIONS = %w[.png .jpg .jpeg .gif .webp].freeze + LOCAL_VIDEO_EXTENSIONS = %w[.mp4 .webm .mov].freeze + LOCAL_AUDIO_EXTENSIONS = %w[.wav .mp3 .ogg .aac .flac .m4a].freeze + LOCAL_MEDIA_EXTENSIONS = (LOCAL_IMAGE_EXTENSIONS + LOCAL_VIDEO_EXTENSIONS + LOCAL_AUDIO_EXTENSIONS).freeze + + # Replace local image paths in markdown content with base64 data URLs. + # + # Handles both `file:///path/to/img.png` and bare `/path/to/img.png` in + # markdown image syntax `![alt](src)`. + # + # @param content [String] markdown text potentially containing local image references + # @return [String] content with local images replaced by data URLs + def self.inline_local_images(content) + return content if content.nil? || content.empty? + + content.gsub(%r{(!\[[^\]]*\])$(file://)?(/[^)]+)$}) do + prefix = $1 + _scheme = $2 + raw_path = $3 + path = CGI.unescape(raw_path) + ext = File.extname(path).downcase + full_match = $& + + unless LOCAL_IMAGE_EXTENSIONS.include?(ext) && File.exist?(path) + next full_match + end + + begin + data_url = image_path_to_data_url(path) + Clacky::Logger.info("file_processor.inline_local_images", path: path, size: File.size(path)) + "#{prefix}(#{data_url})" + rescue StandardError => e + Clacky::Logger.warn("file_processor.inline_local_images.failed", path: path, error: e.message) + full_match + end + end + end + + private_class_method :parse_zip_listing, :parse_tar_listing, :save_preview, :sanitize_filename, + :downscale_png_chunky, :downscale_via_cli + + # ------------------------------------------------------------------------- + # Local image URL rewriting + # ------------------------------------------------------------------------- + + # Rewrite local image paths in markdown content to use the /api/local-image proxy. + # + # Matches two patterns inside `![alt](url)`: + # 1. file:// URLs → ![alt](/api/local-image?path=file:///abs/path.png) + # 2. bare absolute paths → ![alt](/api/local-image?path=/abs/path.png) + # + # https:// URLs and non-image files are left untouched. + # + # @param content [String, nil] markdown text + # @return [String, nil] rewritten content (or original if nothing matched) + def self.rewrite_local_image_urls(content) + return content if content.nil? || content.empty? + + # Rewrite markdown image syntax ![alt](file:///path) → proxy URL + content = content.gsub(/!\[([^\]]*)\]$((?:file:\/\/)?\/[^)]+)$/) do |_match| + alt = Regexp.last_match(1) + href = Regexp.last_match(2) + + path = href.sub(%r{\Afile://}, "") + path = CGI.unescape(path) + + ext = File.extname(path).downcase + if LOCAL_MEDIA_EXTENSIONS.include?(ext) && File.exist?(path) + encoded = CGI.escape(href) + "![#{alt}](/api/local-image?path=#{encoded})" + else + _match + end + end + + # Rewrite