juno-cua 0.5.3

package/bin/setup.mjs

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+
+/**
+ * juno-cua setup — configures AI coding agents to use Juno's desktop automation.
+ *
+ * Detects installed agents, checks for the juno-cua binary, and adds MCP config
+ * + skill files so agents can screenshot, click, type, and control your desktop.
+ *
+ * Usage:
+ *   npx juno-cua          # Interactive setup
+ *   npx juno-cua --yes    # Auto-approve all
+ *   npx juno-cua --check  # Just check what's installed, don't modify
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, symlinkSync, copyFileSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const HOME = homedir();
+const AUTO_YES = process.argv.includes("--yes") || process.argv.includes("-y");
+const CHECK_ONLY = process.argv.includes("--check");
+const HELP = process.argv.includes("--help") || process.argv.includes("-h");
+
+// ── Agent definitions ────────────────────────────────────────────────────────
+
+const AGENTS = [
+  {
+    name: "Claude Code",
+    id: "claude-code",
+    mcpConfig: join(HOME, ".claude", "mcp.json"),
+    skillDir: join(HOME, ".claude", "skills"),
+    detected: () => commandExists("claude"),
+  },
+  {
+    name: "Cursor",
+    id: "cursor",
+    mcpConfig: join(HOME, ".cursor", "mcp.json"),
+    skillDir: null,
+    detected: () => existsSync(join(HOME, ".cursor")),
+  },
+  {
+    name: "VS Code (Copilot)",
+    id: "vscode",
+    mcpConfig: join(HOME, ".vscode", "mcp.json"),
+    skillDir: null,
+    detected: () => existsSync(join(HOME, ".vscode")) || commandExists("code"),
+  },
+  {
+    name: "Windsurf",
+    id: "windsurf",
+    mcpConfig: join(HOME, ".codeium", "windsurf", "mcp_config.json"),
+    skillDir: null,
+    detected: () => existsSync(join(HOME, ".codeium", "windsurf")),
+  },
+  {
+    name: "Codex",
+    id: "codex",
+    mcpConfig: join(HOME, ".codex", "mcp.json"),
+    skillDir: null,
+    detected: () => commandExists("codex"),
+  },
+  {
+    name: "Gemini CLI",
+    id: "gemini",
+    mcpConfig: join(HOME, ".gemini", "settings.json"),
+    skillDir: null,
+    detected: () => commandExists("gemini"),
+  },
+];
+
+const MCP_ENTRY = {
+  command: "juno-cua",
+  args: ["serve-mcp"],
+};
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function commandExists(cmd) {
+  try {
+    execSync(`which ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function log(msg) {
+  console.log(msg);
+}
+
+function success(msg) {
+  console.log(`  [ok] ${msg}`);
+}
+
+function warn(msg) {
+  console.log(`  [!!] ${msg}`);
+}
+
+function info(msg) {
+  console.log(`  [..] ${msg}`);
+}
+
+function skip(msg) {
+  console.log(`  [--] ${msg}`);
+}
+
+async function confirm(question) {
+  if (AUTO_YES) return true;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`  ${question} (y/N) `, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === "y");
+    });
+  });
+}
+
+function readJson(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(path, data) {
+  const dir = dirname(path);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
+}
+
+// ── Binary check ─────────────────────────────────────────────────────────────
+
+function checkBinary() {
+  log("\n--- juno-cua binary ---");
+
+  if (commandExists("juno-cua")) {
+    let version = "unknown";
+    try {
+      version = execSync("juno-cua --version", { encoding: "utf8" }).trim();
+    } catch { /* ignore */ }
+    success(`Found: ${version}`);
+    return true;
+  }
+
+  warn("juno-cua not found on PATH");
+  log("");
+  log("  Install via Homebrew:");
+  log("    brew install lacymorrow/tap/juno-cua");
+  log("");
+  log("  Or build from source:");
+  log("    git clone https://github.com/lacymorrow/juno");
+  log("    cd juno && cargo build -p juno-cua --release");
+  log("    cp target/release/juno-cua /usr/local/bin/");
+  log("");
+  return false;
+}
+
+// ── MCP config injection ─────────────────────────────────────────────────────
+
+function hasMcpEntry(config) {
+  const servers = config?.mcpServers || {};
+  return "juno" in servers || "juno-cua" in servers;
+}
+
+function injectMcpEntry(config) {
+  if (!config) config = {};
+  if (!config.mcpServers) config.mcpServers = {};
+  config.mcpServers["juno"] = MCP_ENTRY;
+  return config;
+}
+
+async function configureMcp(agent) {
+  const existing = readJson(agent.mcpConfig);
+
+  if (existing && hasMcpEntry(existing)) {
+    skip(`${agent.name}: MCP already configured`);
+    return;
+  }
+
+  if (CHECK_ONLY) {
+    info(`${agent.name}: MCP not configured (would add)`);
+    return;
+  }
+
+  const yes = await confirm(`Add juno MCP server to ${agent.name}?`);
+  if (!yes) {
+    skip(`${agent.name}: skipped`);
+    return;
+  }
+
+  // For Gemini, the MCP config lives under a different key
+  if (agent.id === "gemini") {
+    let settings = existing || {};
+    if (!settings.mcpServers) settings.mcpServers = {};
+    settings.mcpServers["juno"] = MCP_ENTRY;
+    writeJson(agent.mcpConfig, settings);
+  } else {
+    const config = injectMcpEntry(existing);
+    writeJson(agent.mcpConfig, config);
+  }
+
+  success(`${agent.name}: MCP configured at ${agent.mcpConfig}`);
+}
+
+// ── Skill installation (Claude Code only) ────────────────────────────────────
+
+async function installSkill(agent) {
+  if (!agent.skillDir) return;
+
+  const skillTarget = join(agent.skillDir, "juno");
+  const skillSource = resolve(join(__dirname, "..", "skill"));
+
+  if (existsSync(skillTarget)) {
+    skip(`${agent.name}: Skill already installed`);
+    return;
+  }
+
+  if (CHECK_ONLY) {
+    info(`${agent.name}: Skill not installed (would add)`);
+    return;
+  }
+
+  const yes = await confirm(`Install juno skill for ${agent.name}?`);
+  if (!yes) {
+    skip(`${agent.name}: skill skipped`);
+    return;
+  }
+
+  if (!existsSync(agent.skillDir)) {
+    mkdirSync(agent.skillDir, { recursive: true });
+  }
+
+  // Copy SKILL.md into the skill directory
+  mkdirSync(skillTarget, { recursive: true });
+  const srcSkill = join(skillSource, "SKILL.md");
+  const dstSkill = join(skillTarget, "SKILL.md");
+
+  if (existsSync(srcSkill)) {
+    copyFileSync(srcSkill, dstSkill);
+    success(`${agent.name}: Skill installed at ${skillTarget}`);
+  } else {
+    warn(`Skill source not found at ${srcSkill}`);
+  }
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  if (HELP) {
+    log("juno-cua — Setup desktop automation for AI coding agents");
+    log("");
+    log("Usage:");
+    log("  npx juno-cua          Interactive setup");
+    log("  npx juno-cua --yes    Auto-approve all changes");
+    log("  npx juno-cua --check  Check status without modifying anything");
+    log("  npx juno-cua --help   Show this help");
+    log("");
+    log("What it does:");
+    log("  1. Checks for juno-cua binary on PATH");
+    log("  2. Detects installed AI coding agents");
+    log("  3. Adds MCP server config so agents can use desktop automation");
+    log("  4. Installs the juno skill (Claude Code only)");
+    process.exit(0);
+  }
+
+  log("juno-cua setup — Desktop automation for AI agents");
+  log("==================================================");
+
+  // 1. Check binary
+  const hasBinary = checkBinary();
+
+  // 2. Detect agents
+  log("\n--- Detected agents ---");
+  const detected = AGENTS.filter((a) => a.detected());
+
+  if (detected.length === 0) {
+    warn("No supported agents detected");
+    log("  Supported: Claude Code, Cursor, VS Code, Windsurf, Codex, Gemini CLI");
+    process.exit(0);
+  }
+
+  for (const agent of detected) {
+    success(agent.name);
+  }
+
+  const notDetected = AGENTS.filter((a) => !a.detected());
+  for (const agent of notDetected) {
+    skip(`${agent.name} (not found)`);
+  }
+
+  if (!hasBinary && !CHECK_ONLY) {
+    warn("juno-cua binary not found — MCP server won't work until installed");
+    const proceed = await confirm("Continue with config setup anyway?");
+    if (!proceed) {
+      log("\nInstall juno-cua first, then re-run: npx juno-cua");
+      process.exit(0);
+    }
+  }
+
+  // 3. Configure MCP for detected agents
+  log("\n--- MCP configuration ---");
+  for (const agent of detected) {
+    await configureMcp(agent);
+  }
+
+  // 4. Install skills (Claude Code only)
+  const skillAgents = detected.filter((a) => a.skillDir);
+  if (skillAgents.length > 0) {
+    log("\n--- Skill installation ---");
+    for (const agent of skillAgents) {
+      await installSkill(agent);
+    }
+  }
+
+  // 5. Summary
+  log("\n--- Done ---");
+  if (hasBinary) {
+    log("  juno-cua is ready. Your agents can now:");
+    log("    - Take screenshots and analyze your screen");
+    log("    - Click, type, and scroll in any application");
+    log("    - Read accessibility trees for precise element targeting");
+    log("    - Open apps and URLs, manage the clipboard");
+  } else {
+    log("  Config written. Install the binary to activate:");
+    log("    brew install lacymorrow/tap/juno-cua");
+  }
+  log("");
+}
+
+main().catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "juno-cua",
+  "version": "0.5.3",
+  "description": "Setup juno-cua desktop automation for AI coding agents (Claude Code, Cursor, Codex, Gemini CLI, etc.)",
+  "keywords": [
+    "juno",
+    "computer-use",
+    "desktop-automation",
+    "mcp",
+    "ai-agent",
+    "claude-code",
+    "cursor",
+    "codex"
+  ],
+  "author": "Lacy Morrow <me@lacymorrow.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lacymorrow/juno",
+    "directory": "packages/juno-cua"
+  },
+  "bin": {
+    "juno-cua": "./bin/setup.mjs"
+  },
+  "files": [
+    "bin/",
+    "skill/"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,282 @@
+# juno-cua — Desktop Automation for AI Agents
+
+You have access to `juno-cua`, a CLI tool for macOS desktop automation. It lets you take screenshots, click, type, scroll, read accessibility trees, and control applications — all from the command line with JSON output.
+
+## Quick Check
+
+```bash
+which juno-cua || echo "Not installed — run: brew install lacymorrow/tap/juno-cua"
+```
+
+## Installation
+
+```bash
+brew install lacymorrow/tap/juno-cua
+```
+
+Requires macOS accessibility permissions (System Settings → Privacy & Security → Accessibility).
+
+## When to Use juno-cua
+
+**USE juno-cua when you need to:**
+- See what's on screen (screenshot, UI tree)
+- Click buttons, menus, or UI elements
+- Type into GUI applications (not terminal)
+- Fill forms in native apps
+- Navigate between applications
+- Automate repetitive GUI tasks
+- Read or set the clipboard
+
+**DON'T use juno-cua when:**
+- You can accomplish the task with shell commands, file I/O, or APIs
+- You're working in a terminal-only context with no GUI needed
+- The task involves web scraping (use curl/fetch instead)
+
+## Tool Reference
+
+### Screenshot & Vision
+
+```bash
+# Take a screenshot — returns {"screenshot_base64": "..."}
+juno-cua screenshot
+
+# Get the accessibility tree (structured UI representation)
+juno-cua ui-tree
+juno-cua ui-tree --app "Safari"
+
+# Find specific UI elements
+juno-cua find-elements --selector "AXButton"
+
+# Get info about the currently focused element
+juno-cua focused-element
+```
+
+### Mouse
+
+```bash
+# Click at screen coordinates
+juno-cua click --x 500 --y 300
+juno-cua click --x 500 --y 300 --button right
+juno-cua click --x 500 --y 300 --button double
+
+# Move mouse without clicking
+juno-cua mouse-move --x 500 --y 300
+
+# Get current cursor position
+juno-cua cursor-position
+
+# Scroll at a position
+juno-cua scroll --x 500 --y 300 --direction down
+juno-cua scroll --x 500 --y 300 --direction down --amount 5
+```
+
+### Keyboard
+
+```bash
+# Type text (simulates keystrokes)
+juno-cua type-text --text "Hello, world!"
+
+# Press a key with optional modifier
+juno-cua press-key --key Return
+juno-cua press-key --key c --modifier cmd    # Cmd+C (copy)
+juno-cua press-key --key Tab
+juno-cua press-key --key space
+
+# Hold and release keys
+juno-cua hold-key --key shift --duration-ms 500
+juno-cua release-key --key shift
+```
+
+### System
+
+```bash
+# Clipboard
+juno-cua get-clipboard
+juno-cua set-clipboard --content "copied text"
+
+# Launch apps / open URLs
+juno-cua open-app --name "Safari"
+juno-cua open-url --url "https://example.com"
+
+# Wait (useful between UI actions)
+juno-cua wait --ms 1000
+```
+
+### Advanced
+
+```bash
+# List all tools with full JSON schemas
+juno-cua list-tools
+
+# Generic tool call (for tools not exposed as subcommands)
+juno-cua call --tool leftClick --args '{"x": 100, "y": 200}'
+
+# Print capabilities catalog
+juno-cua capabilities
+```
+
+## Output
+
+All commands return JSON by default. Use `--format pretty` for human-readable output, or `--format quiet` for silent execution (exit code only).
+
+```bash
+# JSON (default)
+juno-cua cursor-position
+# → {"x":512,"y":384}
+
+# Pretty-printed
+juno-cua cursor-position --format pretty
+
+# Silent — just check exit code
+juno-cua click --x 100 --y 200 --format quiet && echo "clicked"
+```
+
+## Patterns
+
+### Screenshot → Analyze → Act Loop
+
+The most common pattern for GUI automation:
+
+```bash
+# 1. See what's on screen
+juno-cua screenshot
+# (analyze the base64 image to find UI elements)
+
+# 2. Act on what you see
+juno-cua click --x 340 --y 220
+
+# 3. Wait for UI to update
+juno-cua wait --ms 500
+
+# 4. Verify the result
+juno-cua screenshot
+```
+
+### Accessibility-First (Preferred)
+
+When possible, use the accessibility tree instead of screenshots — it's faster and more reliable:
+
+```bash
+# Get structured UI info
+juno-cua ui-tree --app "System Settings"
+
+# Find specific elements
+juno-cua find-elements --selector "AXButton"
+
+# Check focused element after an action
+juno-cua focused-element
+```
+
+### Form Filling
+
+```bash
+# Click the first field
+juno-cua click --x 300 --y 200
+juno-cua wait --ms 200
+
+# Type and tab to next field
+juno-cua type-text --text "John Doe"
+juno-cua press-key --key Tab
+juno-cua type-text --text "john@example.com"
+juno-cua press-key --key Tab
+juno-cua type-text --text "password123"
+
+# Submit
+juno-cua press-key --key Return
+```
+
+### App Navigation
+
+```bash
+# Open an app
+juno-cua open-app --name "Finder"
+juno-cua wait --ms 1000
+
+# Use keyboard shortcuts
+juno-cua press-key --key n --modifier cmd    # New window
+juno-cua press-key --key g --modifier cmd    # Go to folder
+juno-cua wait --ms 500
+juno-cua type-text --text "/tmp"
+juno-cua press-key --key Return
+```
+
+### Copy Text from GUI
+
+```bash
+# Select all and copy
+juno-cua press-key --key a --modifier cmd
+juno-cua press-key --key c --modifier cmd
+juno-cua wait --ms 200
+
+# Read clipboard
+juno-cua get-clipboard
+```
+
+## Error Handling
+
+All errors are returned as JSON on stderr with a non-zero exit code:
+
+```json
+{"error": "Screenshot failed: Check accessibility permissions."}
+```
+
+Common issues:
+- **Accessibility permissions**: Grant in System Settings → Privacy & Security → Accessibility
+- **App not found**: Check exact app name with `open-app`
+- **Coordinates out of bounds**: Use `screenshot` first to find valid coordinates
+
+## MCP Server (Alternative to CLI)
+
+For agents that support MCP (Model Context Protocol), `juno-cua` can run as a structured tool server instead of being called via Bash. This gives typed tool schemas and native image content blocks for screenshots.
+
+### Setup
+
+Add to your `.mcp.json` (works in Claude Code, Cursor, Codex, Gemini CLI, etc.):
+
+```json
+{
+  "mcpServers": {
+    "juno": {
+      "command": "juno-cua",
+      "args": ["serve-mcp"]
+    }
+  }
+}
+```
+
+The MCP server exposes the same tools as the CLI — screenshots return as MCP image content blocks automatically.
+
+### When to use MCP vs CLI
+
+- **MCP**: Best when your agent natively supports MCP tools. Gives typed schemas, streaming-friendly output, and image content blocks.
+- **CLI (Bash)**: Works with any agent that can run shell commands. Zero config, universal compatibility.
+
+Both use the same `juno-cua` binary and the same underlying `Desktop` engine.
+
+## Full Juno Orchestrator
+
+If Juno.app is installed, you also have access to the full multi-agent orchestrator:
+
+```bash
+# Natural language desktop automation (requires Juno.app)
+juno query "Open Safari, navigate to github.com, and take a screenshot"
+```
+
+This routes through Juno's hierarchical agent system (Desktop Agent, Browser Agent, File Agent) for complex multi-step tasks. Install from https://github.com/lacymorrow/juno/releases.
+
+### Full Juno MCP Server
+
+The full Juno binary can also run as an MCP server, exposing everything `juno-cua` has PLUS the `query` tool:
+
+```json
+{
+  "mcpServers": {
+    "juno": {
+      "command": "juno",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+The `query` tool is the key difference — it delegates to the multi-agent orchestrator. No other MCP server offers a full AI orchestrator as a single tool call.