diff --git a/.gitignore b/.gitignore index 9710ea71d..bfeb417e0 100644 --- a/.gitignore +++ b/.gitignore @@ -88,4 +88,5 @@ !/assets/*.jpg assets/gen_typing_gif.py -!README_CN.md \ No newline at end of file +!README_CN.md +!opencode-commands/ \ No newline at end of file diff --git a/README.md b/README.md index 582669dd6..906e2e180 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,8 @@ CLI-Anything: Bridging the Gap Between AI Agents and the World's Software Quick Start - Demos - Tests + Demos + Tests License

@@ -54,11 +54,16 @@ CLI is the universal interface for both humans and AI agents: ### Prerequisites -- **Claude Code** (with plugin support) - **Python 3.10+** - Target software installed (e.g., GIMP, Blender, LibreOffice, or your own application) +- A supported AI coding agent: [Claude Code](#-claude-code) | [OpenCode](#-opencode) | [More Platforms](#-more-platforms-coming-soon) -### Step 1: Add the Marketplace +### Pick Your Platform + +
+

⚡ Claude Code

 + +**Step 1: Add the Marketplace** CLI-Anything is distributed as a Claude Code plugin marketplace hosted on GitHub. @@ -67,7 +72,7 @@ CLI-Anything is distributed as a Claude Code plugin marketplace hosted on GitHub /plugin marketplace add HKUDS/CLI-Anything ``` -### Step 2: Install the Plugin +**Step 2: Install the Plugin** ```bash # Install the cli-anything plugin from the marketplace @@ -76,12 +81,14 @@ CLI-Anything is distributed as a Claude Code plugin marketplace hosted on GitHub That's it. The plugin is now available in your Claude Code session. -### Step 3: Build a CLI in One Command +**Step 3: Build a CLI in One Command** ```bash -# /cli-anything +# /cli-anything:cli-anything # Generate a complete CLI for GIMP (all 7 phases) -/cli-anything ./gimp +/cli-anything:cli-anything ./gimp + +# Note: If your Claude Code is under 2.x, use "/cli-anything" instead. ``` This runs the full pipeline: @@ -93,21 +100,20 @@ This runs the full pipeline: 6. 📝 **Document** — Updates TEST.md with results 7. 📦 **Publish** — Creates `setup.py`, installs to PATH -### Step 4: Use the CLI +**Step 4 (Optional): Refine and Improve the CLI** + +After the initial build, you can iteratively refine the CLI to expand coverage and add missing capabilities: ```bash -# Install to PATH -cd gimp/agent-harness && pip install -e . +# Broad refinement — agent analyzes gaps across all capabilities +/cli-anything:refine ./gimp -# Use from anywhere -cli-anything-gimp --help -cli-anything-gimp project new --width 1920 --height 1080 -o poster.json -cli-anything-gimp --json layer add -n "Background" --type solid --color "#1a1a2e" - -# Enter interactive REPL -cli-anything-gimp +# Focused refinement — target a specific functionality area +/cli-anything:refine ./gimp "I want more CLIs on image batch processing and filters" ``` +The refine command performs gap analysis between the software's full capabilities and current CLI coverage, then implements new commands, tests, and documentation for the identified gaps. You can run it multiple times to steadily expand coverage — each run is incremental and non-destructive. +
Alternative: Manual Installation @@ -126,6 +132,84 @@ cp -r CLI-Anything/cli-anything-plugin ~/.claude/plugins/cli-anything
+
+ +
+

⚡ OpenCode

 + +**Step 1: Install the Commands** + +Copy the CLI-Anything commands **and** `HARNESS.md` to your OpenCode commands directory: + +```bash +# Clone the repo +git clone https://github.com/HKUDS/CLI-Anything.git + +# Global install (available in all projects) +cp CLI-Anything/opencode-commands/*.md ~/.config/opencode/commands/ +cp CLI-Anything/cli-anything-plugin/HARNESS.md ~/.config/opencode/commands/ + +# Or project-level install +cp CLI-Anything/opencode-commands/*.md .opencode/commands/ +cp CLI-Anything/cli-anything-plugin/HARNESS.md .opencode/commands/ +``` + +> **Note:** `HARNESS.md` is the methodology spec that all commands reference. It must be in the same directory as the commands. + +This adds 5 slash commands: `/cli-anything`, `/cli-anything-refine`, `/cli-anything-test`, `/cli-anything-validate`, and `/cli-anything-list`. + +**Step 2: Build a CLI in One Command** + +```bash +# Generate a complete CLI for GIMP (all 7 phases) +/cli-anything ./gimp + +# Build from a GitHub repo +/cli-anything https://github.com/blender/blender +``` + +The command runs as a subtask and follows the same 7-phase methodology as Claude Code. + +**Step 3 (Optional): Refine and Improve the CLI** + +```bash +# Broad refinement — agent analyzes gaps across all capabilities +/cli-anything-refine ./gimp + +# Focused refinement — target a specific functionality area +/cli-anything-refine ./gimp "batch processing and filters" +``` + +
+ +
+

🔮 More Platforms (Coming Soon)

 + +CLI-Anything is designed to be platform-agnostic. Support for more AI coding agents is planned: + +- **Cursor** — coming soon +- **Windsurf** — coming soon +- **Your favorite tool** — contributions welcome! See the `opencode-commands/` directory for a reference implementation. + +
+ +### Use the Generated CLI + +Regardless of which platform you used to build it, the generated CLI works the same way: + +```bash +# Install to PATH +cd gimp/agent-harness && pip install -e . + +# Use from anywhere +cli-anything-gimp --help +cli-anything-gimp project new --width 1920 --height 1080 -o poster.json +cli-anything-gimp --json layer add -n "Background" --type solid --color "#1a1a2e" + +# Enter interactive REPL +cli-anything-gimp +``` + --- ## 💡 CLI-Anything's Vision: Building Agent-Native Software @@ -168,7 +252,7 @@ AI agents are great at reasoning but terrible at using real professional softwar | 💸 "UI automation breaks constantly" | No screenshots, no clicking, no RPA fragility. Pure command-line reliability with structured interfaces | | 📊 "Agents need structured data" | Built-in JSON output for seamless agent consumption + human-readable formats for debugging | | 🔧 "Custom integrations are expensive" | One Claude plugin auto-generates CLIs for ANY codebase through proven 7-phase pipeline | -| ⚡ "Prototype vs Production gap" | 1,458+ tests with real software validation. Battle-tested across 10 major applications | +| ⚡ "Prototype vs Production gap" | 1,508+ tests with real software validation. Battle-tested across 11 major applications | --- @@ -257,7 +341,7 @@ All CLIs organized under cli_anything.* namespace — conflict-free, pip-install CLI-Anything works on any software with a codebase — no domain restrictions or architectural limitations. ### 🏭 Professional-Grade Testing -Tested across 10 diverse, complex applications spanning creative, productivity, communication, and diagramming domains previously inaccessible to AI agents. +Tested across 11 diverse, complex applications spanning creative, productivity, communication, diagramming, and AI content generation domains previously inaccessible to AI agents. ### 🎨 Diverse Domain Coverage From creative workflows (image editing, 3D modeling, vector graphics) to production tools (audio, office, live streaming, video editing). @@ -344,12 +428,19 @@ Each application received complete, production-ready CLI interfaces — not demo ✅ 138 +✨ AnyGen +AI Content Generation +cli-anything-anygen +AnyGen REST API (anygen.io) +✅ 50 + + Total -✅ 1,458 +✅ 1,508 -> **100% pass rate** across all 1,458 tests — 1,033 unit tests + 425 end-to-end tests. +> **100% pass rate** across all 1,508 tests — 1,073 unit tests + 435 end-to-end tests. --- @@ -376,8 +467,9 @@ kdenlive 155 passed ✅ (111 unit + 44 e2e) shotcut 154 passed ✅ (110 unit + 44 e2e) zoom 22 passed ✅ (22 unit + 0 e2e) drawio 138 passed ✅ (116 unit + 22 e2e) +anygen 50 passed ✅ (40 unit + 10 e2e) ────────────────────────────────────────────────────────────────────────────── -TOTAL 1,458 passed ✅ 100% pass rate +TOTAL 1,508 passed ✅ 100% pass rate ``` --- @@ -434,7 +526,8 @@ cli-anything/ ├── 🎞️ kdenlive/agent-harness/ # Kdenlive CLI (155 tests) ├── 🎬 shotcut/agent-harness/ # Shotcut CLI (154 tests) ├── 📞 zoom/agent-harness/ # Zoom CLI (22 tests) -└── 📐 drawio/agent-harness/ # Draw.io CLI (138 tests) +├── 📐 drawio/agent-harness/ # Draw.io CLI (138 tests) +└── ✨ anygen/agent-harness/ # AnyGen CLI (50 tests) ``` Each `agent-harness/` contains an installable Python package under `cli_anything./` with Click CLI, core modules, utils (including `repl_skin.py` and backend wrapper), and comprehensive tests. @@ -535,7 +628,7 @@ HARNESS.md is our definitive SOP for making any software agent-accessible via au It encodes proven patterns and methodologies refined through automated generation processes. -The playbook distills key insights from successfully building all 9 diverse, production-ready harnesses. +The playbook distills key insights from successfully building all 11 diverse, production-ready harnesses. ### Critical Lessons @@ -654,7 +747,7 @@ MIT License — free to use, modify, and distribute. **CLI-Anything** — *Make any software with a codebase Agent-native.* -A methodology for the age of AI agents | 10 professional software demos | 1,458 passing tests +A methodology for the age of AI agents | 11 professional software demos | 1,508 passing tests
diff --git a/README_CN.md b/README_CN.md index 2f720c45f..09cef2fc1 100644 --- a/README_CN.md +++ b/README_CN.md @@ -7,8 +7,8 @@ CLI-Anything：连接 AI Agent 与全世界软件的桥梁

Quick Start - Demos - Tests + Demos + Tests License

@@ -54,11 +54,16 @@ CLI 是人类和 AI Agent 共通的万能接口： ### 环境要求 -- **Claude Code**（需支持插件） - **Python 3.10+** - 目标软件已安装（如 GIMP、Blender、LibreOffice 或你自己的应用） +- 支持的 AI 编程工具之一：[Claude Code](#-claude-code) | [OpenCode](#-opencode) | [更多平台](#-更多平台即将支持) -### 第一步：添加插件市场 +### 选择你的平台 + +
+

⚡ Claude Code

 + +**第一步：添加插件市场** CLI-Anything 以 Claude Code 插件市场的形式托管在 GitHub 上。 @@ -67,7 +72,7 @@ CLI-Anything 以 Claude Code 插件市场的形式托管在 GitHub 上。 /plugin marketplace add HKUDS/CLI-Anything ``` -### 第二步：安装插件 +**第二步：安装插件** ```bash # 从市场安装 cli-anything 插件 @@ -76,16 +81,17 @@ CLI-Anything 以 Claude Code 插件市场的形式托管在 GitHub 上。 搞定。插件已经在你的 Claude Code 会话中可用了。 -### 第三步：一行命令生成 CLI +**第三步：一行命令生成 CLI** ```bash -# /cli-anything <软件路径或仓库地址> +# /cli-anything:cli-anything <软件路径或仓库地址> # 为 GIMP 生成完整的 CLI（7 个阶段全自动） -/cli-anything ./gimp +/cli-anything:cli-anything ./gimp + +# 注意：如果你的 Claude Code 版本低于 2.x，请使用 "/cli-anything"。 ``` 完整流水线自动执行： - 1. 🔍 **分析** — 扫描源码，将 GUI 操作映射到 API 2. 📐 **设计** — 规划命令分组、状态模型、输出格式 3. 🔨 **实现** — 构建 Click CLI，包含 REPL、JSON 输出、撤销/重做 @@ -94,21 +100,20 @@ CLI-Anything 以 Claude Code 插件市场的形式托管在 GitHub 上。 6. 📝 **文档** — 更新 TEST.md，写入测试结果 7. 📦 **发布** — 生成 `setup.py`，安装到 PATH -### 第四步：开始使用 +**第四步（可选）：优化和扩展 CLI** + +初始构建完成后，你可以迭代优化 CLI，扩展覆盖面并补充缺失的功能： ```bash -# 安装到 PATH -cd gimp/agent-harness && pip install -e . +# 全面优化 — Agent 分析所有功能的覆盖差距 +/cli-anything:refine ./gimp -# 随处可用 -cli-anything-gimp --help -cli-anything-gimp project new --width 1920 --height 1080 -o poster.json -cli-anything-gimp --json layer add -n "Background" --type solid --color "#1a1a2e" - -# 进入交互式 REPL -cli-anything-gimp +# 定向优化 — 指定特定功能领域 +/cli-anything:refine ./gimp "我需要更多图像批处理和滤镜相关的 CLI" ``` +优化命令会对软件的完整功能与当前 CLI 覆盖范围进行差距分析，然后为识别到的差距实现新命令、测试和文档。你可以多次运行以逐步扩展覆盖 — 每次运行都是增量的、非破坏性的。 +
备选方案：手动安装 @@ -127,6 +132,84 @@ cp -r CLI-Anything/cli-anything-plugin ~/.claude/plugins/cli-anything
+
+ +
+

⚡ OpenCode

 + +**第一步：安装命令** + +将 CLI-Anything 命令**和** `HARNESS.md` 复制到 OpenCode 命令目录： + +```bash +# 克隆仓库 +git clone https://github.com/HKUDS/CLI-Anything.git + +# 全局安装（所有项目可用） +cp CLI-Anything/opencode-commands/*.md ~/.config/opencode/commands/ +cp CLI-Anything/cli-anything-plugin/HARNESS.md ~/.config/opencode/commands/ + +# 或项目级安装 +cp CLI-Anything/opencode-commands/*.md .opencode/commands/ +cp CLI-Anything/cli-anything-plugin/HARNESS.md .opencode/commands/ +``` + +> **注意：** `HARNESS.md` 是所有命令引用的方法论规范，必须和命令文件放在同一目录下。 + +安装后获得 5 个斜杠命令：`/cli-anything`、`/cli-anything-refine`、`/cli-anything-test`、`/cli-anything-validate` 和 `/cli-anything-list`。 + +**第二步：一行命令生成 CLI** + +```bash +# 为 GIMP 生成完整的 CLI（7 个阶段全自动） +/cli-anything ./gimp + +# 从 GitHub 仓库构建 +/cli-anything https://github.com/blender/blender +``` + +命令以子任务方式运行，遵循与 Claude Code 相同的 7 阶段方法论。 + +**第三步（可选）：优化和扩展 CLI** + +```bash +# 全面优化 — Agent 分析所有功能的覆盖差距 +/cli-anything-refine ./gimp + +# 定向优化 — 指定特定功能领域 +/cli-anything-refine ./gimp "批处理和滤镜" +``` + +
+ +
+

🔮 更多平台（即将支持）

 + +CLI-Anything 的设计是平台无关的，计划支持更多 AI 编程工具： + +- **Cursor** — 即将支持 +- **Windsurf** — 即将支持 +- **你喜欢的工具** — 欢迎贡献！参考 `opencode-commands/` 目录的实现。 + +
+ +### 开始使用生成的 CLI + +无论你用哪个平台构建，生成的 CLI 使用方式完全一样： + +```bash +# 安装到 PATH +cd gimp/agent-harness && pip install -e . + +# 随处可用 +cli-anything-gimp --help +cli-anything-gimp project new --width 1920 --height 1080 -o poster.json +cli-anything-gimp --json layer add -n "Background" --type solid --color "#1a1a2e" + +# 进入交互式 REPL +cli-anything-gimp +``` + --- ## 💡 CLI-Anything 的愿景：构建 Agent 原生的软件生态 @@ -169,7 +252,7 @@ AI Agent 推理能力很强，但操控真实专业软件的能力很弱。现 | 💸 "GUI 自动化三天两头崩" | 告别截图、点击和 RPA 的脆弱性，纯命令行操控，结构化接口 | | 📊 "Agent 需要结构化数据" | 内置 JSON 输出供 Agent 直接消费，同时保留可读格式方便调试 | | 🔧 "定制集成太贵了" | 一个插件就能为任意代码库自动生成 CLI，经过验证的 7 阶段流水线 | -| ⚡ "原型和生产之间差十万八千里" | 1,458+ 测试用例，全部在真实软件上验证通过，覆盖 10 款主流应用 | +| ⚡ "原型和生产之间差十万八千里" | 1,508+ 测试用例，全部在真实软件上验证通过，覆盖 11 款主流应用 | --- @@ -266,7 +349,7 @@ CLI-Anything 适用于任何有代码库的软件 —— 不限领域，不限 ### 🏭 专业级测试 -在 9 款复杂的开源应用上进行了实测，涵盖创意、生产力、通信和图表领域 —— 这些软件此前对 AI Agent 来说几乎不可触及。 +在 11 款复杂应用上进行了实测，涵盖创意、生产力、通信、图表和 AI 内容生成领域 —— 这些软件此前对 AI Agent 来说几乎不可触及。 ### 🎨 覆盖多元领域 @@ -355,12 +438,19 @@ CLI-Anything 适用于任何有代码库的软件 —— 不限领域，不限 ✅ 138 +✨ AnyGen +AI 内容生成 +cli-anything-anygen +AnyGen REST API (anygen.io) +✅ 50 + + 合计 -✅ 1,458 +✅ 1,508 -> 全部 1,458 项测试 **100% 通过** —— 1,033 项单元测试 + 425 项端到端测试。 +> 全部 1,508 项测试 **100% 通过** —— 1,073 项单元测试 + 435 项端到端测试。 --- @@ -387,8 +477,9 @@ kdenlive 155 passed ✅ (111 unit + 44 e2e) shotcut 154 passed ✅ (110 unit + 44 e2e) zoom 22 passed ✅ (22 unit + 0 e2e) drawio 138 passed ✅ (116 unit + 22 e2e) +anygen 50 passed ✅ (40 unit + 10 e2e) ────────────────────────────────────────────────────────────────────────────── -TOTAL 1,458 passed ✅ 100% pass rate +TOTAL 1,508 passed ✅ 100% pass rate ``` --- @@ -427,12 +518,20 @@ cli-anything/ │ ├── repl_skin.py # 统一 REPL 界面 │ ├── commands/ # 插件命令定义 │ │ ├── cli-anything.md # 主构建命令 -│ │ ├── build.md # 扩展已有 harness 覆盖面 +│ │ ├── refine.md # 扩展已有 harness 覆盖面 │ │ ├── test.md # 测试运行器 -│ │ └── validate.md # 标准验证 +│ │ ├── validate.md # 标准验证 +│ │ └── list.md # 列出所有 CLI 工具 │ └── scripts/ │ └── setup-cli-anything.sh # 安装脚本 │ +├── 📋 opencode-commands/ # OpenCode 命令 +│ ├── cli-anything.md # 主构建命令 +│ ├── cli-anything-refine.md # 优化扩展命令 +│ ├── cli-anything-test.md # 测试运行器 +│ ├── cli-anything-validate.md # 标准验证 +│ └── cli-anything-list.md # 列出所有 CLI 工具 +│ ├── 🎨 gimp/agent-harness/ # GIMP CLI（107 项测试） ├── 🧊 blender/agent-harness/ # Blender CLI（208 项测试） ├── ✏️ inkscape/agent-harness/ # Inkscape CLI（202 项测试） @@ -442,7 +541,8 @@ cli-anything/ ├── 🎞️ kdenlive/agent-harness/ # Kdenlive CLI（155 项测试） ├── 🎬 shotcut/agent-harness/ # Shotcut CLI（154 项测试） ├── 📞 zoom/agent-harness/ # Zoom CLI（22 项测试） -└── 📐 drawio/agent-harness/ # Draw.io CLI（138 项测试） +├── 📐 drawio/agent-harness/ # Draw.io CLI（138 项测试） +└── ✨ anygen/agent-harness/ # AnyGen CLI（50 项测试） ``` 每个 `agent-harness/` 包含一个可安装的 Python 包，位于 `cli_anything.<软件名>/` 下，包含 Click CLI、核心模块、工具类（含 `repl_skin.py` 和后端适配器）以及完整的测试。 @@ -457,6 +557,7 @@ cli-anything/ | `/cli-anything:refine <软件路径> [聚焦方向]` | 优化已有的 CLI —— 通过差距分析扩展覆盖面 | | `/cli-anything:test <软件路径或仓库>` | 运行测试并更新 TEST.md | | `/cli-anything:validate <软件路径或仓库>` | 按照 HARNESS.md 标准进行验证 | +| `/cli-anything:list` | 列出所有已安装和已生成的 CLI 工具 | ### 使用示例 @@ -543,7 +644,7 @@ HARNESS.md 是我们通过自动化 CLI 生成让任意软件变得 Agent 可用 它记录了在自动化生成过程中验证和沉淀下来的模式与方法论。 -这本手册提炼了成功构建全部 9 套生产级 CLI 的关键经验。 +这本手册提炼了成功构建全部 11 套生产级 CLI 的关键经验。 ### 核心经验 @@ -561,7 +662,7 @@ HARNESS.md 是我们通过自动化 CLI 生成让任意软件变得 Agent 可用 ## 📦 安装与使用 -### 插件用户（Claude Code） +### Claude Code 用户 ```bash # 添加市场并安装（推荐） @@ -569,7 +670,21 @@ HARNESS.md 是我们通过自动化 CLI 生成让任意软件变得 Agent 可用 /plugin install cli-anything # 为任何有代码库的软件生成 CLI -/cli-anything <软件名> +/cli-anything:cli-anything <软件路径或仓库> +``` + +### OpenCode 用户 + +```bash +# 克隆仓库 +git clone https://github.com/HKUDS/CLI-Anything.git + +# 复制命令和 HARNESS.md 到 OpenCode 命令目录 +cp CLI-Anything/opencode-commands/*.md ~/.config/opencode/commands/ +cp CLI-Anything/cli-anything-plugin/HARNESS.md ~/.config/opencode/commands/ + +# 为任何有代码库的软件生成 CLI +/cli-anything <软件路径或仓库> ``` ### 使用生成的 CLI @@ -656,7 +771,7 @@ MIT License — 可自由使用、修改和分发。 **CLI-Anything** — *一行命令，让任何软件成为 Agent 的原生工具。* -为 AI Agent 时代而生 | 10 款专业软件实测 | 1,458 项测试全部通过 +为 AI Agent 时代而生 | 11 款专业软件实测 | 1,508 项测试全部通过
diff --git a/opencode-commands/cli-anything-list.md b/opencode-commands/cli-anything-list.md new file mode 100644 index 000000000..cfd31a5cc --- /dev/null +++ b/opencode-commands/cli-anything-list.md @@ -0,0 +1,188 @@ +--- +description: List all available CLI-Anything tools (installed and generated) +--- +# cli-anything-list Command + +List all available CLI-Anything tools (installed and generated). + +**Arguments**: $ARGUMENTS + +## Options + +- `--path ` - Directory to search for generated CLIs (default: current directory) +- `--depth ` - Maximum recursion depth for scanning (default: unlimited). Use `0` for current directory only, `1` for one level deep, etc. +- `--json` - Output in JSON format for machine parsing + +## What This Command Does + +Displays all CLI-Anything tools available in the system: + +### 1. Installed CLIs + +Uses `importlib.metadata` to find installed `cli-anything-*` packages: +- Pattern: package name starts with `cli-anything-` +- Extracts: software name, version, entry point + +```python +from importlib.metadata import distributions + +installed = {} +for dist in distributions(): + name = dist.metadata.get("Name", "") + if name.startswith("cli-anything-"): + software = name.replace("cli-anything-", "") + version = dist.version + # Find executable via entry points or shutil.which + executable = shutil.which(f"cli-anything-{software}") + installed[software] = { + "status": "installed", + "version": version, + "executable": executable + } +``` + +### 2. Generated CLIs + +Uses `glob` to find local CLI directories: +- Pattern: `**/agent-harness/cli_anything/*/__init__.py` (or depth-limited variant) +- Extracts: software name, version (from setup.py), source path +- Status: `generated` + +```python +from pathlib import Path +import glob +import re + +search_path = args.get("path", ".") +max_depth = args.get("depth", None) # None means unlimited +generated = {} + +def extract_version_from_setup(setup_path): + """Extract version from setup.py using regex.""" + try: + content = Path(setup_path).read_text() + match = re.search(r'version\s*=\s*["\']([^"\']+)["\']', content) + return match.group(1) if match else None + except: + return None + +def build_glob_patterns(base_path, depth): + """Build list of glob patterns for depths 0 through max_depth.""" + base = Path(base_path) + suffix = "agent-harness/cli_anything/*/__init__.py" + + if depth is None: + return [str(base / "**" / suffix)] + + patterns = [] + for d in range(depth + 1): + if d == 0: + patterns.append(str(base / suffix)) + else: + prefix = "/".join(["*"] * d) + patterns.append(str(base / prefix / suffix)) + return patterns + +patterns = build_glob_patterns(search_path, max_depth) +for pattern in patterns: + for init_file in glob.glob(pattern, recursive=True): + parts = Path(init_file).parts + for i, p in enumerate(parts): + if p == "cli_anything" and i + 1 < len(parts): + software = parts[i + 1] + agent_harness_idx = parts.index("agent-harness") if "agent-harness" in parts else i - 1 + source = str(Path(*parts[:agent_harness_idx + 2])) + setup_path = Path(*parts[:agent_harness_idx + 1]) / "setup.py" + version = extract_version_from_setup(setup_path) + generated[software] = { + "status": "generated", + "version": version, + "executable": None, + "source": source + } + break +``` + +### 3. Merge Results + +- Deduplicate by software name +- If both installed and generated: show `installed` status with both paths +- The `source` field shows where the generated code is (even for installed) + +## Output Formats + +### Table Format (default) + +``` +CLI-Anything Tools (found 5) + +Name Status Version Source +────────────────────────────────────────────────────────────── +gimp installed 1.0.0 ./gimp/agent-harness +blender installed 1.0.0 ./blender/agent-harness +inkscape generated 1.0.0 ./inkscape/agent-harness +audacity generated 1.0.0 ./audacity/agent-harness +libreoffice generated 1.0.0 ./libreoffice/agent-harness +``` + +### JSON Format (--json) + +```json +{ + "tools": [ + { + "name": "gimp", + "status": "installed", + "version": "1.0.0", + "executable": "/usr/local/bin/cli-anything-gimp", + "source": "./gimp/agent-harness" + }, + { + "name": "inkscape", + "status": "generated", + "version": "1.0.0", + "executable": null, + "source": "./inkscape/agent-harness" + } + ], + "total": 2, + "installed": 1, + "generated_only": 1 +} +``` + +## Implementation Steps + +When this command is invoked, the agent should: + +1. **Parse arguments** from `$ARGUMENTS` + - Extract `--path` value (default: `.`) + - Extract `--depth` value (default: `None` for unlimited recursion) + - Extract `--json` flag (default: false) + +2. **Validate path exists** + - If `--path` specified and doesn't exist, show error and exit + +3. **Scan installed CLIs** + - Use `importlib.metadata.distributions()` to find all packages + - Filter for packages starting with `cli-anything-` + - Extract name, version, find executable path + +4. **Scan generated CLIs** + - Build glob pattern based on depth parameter + - Use `glob.glob(pattern, recursive=True)` + - Parse directory structure to extract software name + - Calculate relative path from current directory + +5. **Merge results** + - Create dict keyed by software name + - Prefer installed data when both exist + - Keep source path from generated if available + +6. **Format output** + - If `--json`: output JSON to stdout + - Otherwise: format as table with proper alignment + +7. **Print results** + - Show summary line with count + - Show table or JSON diff --git a/opencode-commands/cli-anything-refine.md b/opencode-commands/cli-anything-refine.md new file mode 100644 index 000000000..e5061d6b0 --- /dev/null +++ b/opencode-commands/cli-anything-refine.md @@ -0,0 +1,92 @@ +--- +description: Refine an existing CLI harness to expand coverage and add missing capabilities +subtask: true +--- +# cli-anything-refine Command + +Refine an existing CLI harness to improve coverage of the software's functions and usage patterns. + +**Target software**: $1 +**Focus area**: $2 + +## CRITICAL: Read HARNESS.md First + +**Before refining, read `./HARNESS.md` (located alongside this command).** All new commands and tests must follow the same standards as the original build. HARNESS.md is the single source of truth for architecture, patterns, and quality requirements. + +## Arguments + +- `$1` is the **software path** (required). Local path to the software source code (e.g., `/home/user/gimp`, `./blender`). Must be the same source tree used during the original build. + + **Note:** Only local paths are accepted. If you need to work from a GitHub repo, clone it first with `/cli-anything`, then refine. + +- `$2` is the **focus area** (optional). A natural-language description of the functionality area to focus on. When provided, skip broad gap analysis and instead target the specified capability area. + + Examples: + - `"vid-in-vid and picture-in-picture features"` + - `"all batch processing and scripting filters"` + - `"particle systems and physics simulation"` + - `"path boolean operations and clipping"` + + When focus is provided: + - Step 2 (Analyze Software Capabilities) narrows to only the specified area + - Step 3 (Gap Analysis) compares only the focused capabilities against current coverage + - The agent should still present findings before implementing, but scoped to the focus area + +## What This Command Does + +This command is used **after** a CLI harness has already been built with `/cli-anything`. It analyzes gaps between the software's full capabilities and what the current CLI covers, then iteratively expands coverage. If a focus is given, the agent narrows its analysis and implementation to that specific functionality area. + +### Step 1: Inventory Current Coverage +- Read the existing CLI entry point (`_cli.py`) and all core modules +- List every command, subcommand, and option currently implemented +- Read the existing test suite to understand what's tested +- Build a coverage map: `{ function_name: covered | not_covered }` + +### Step 2: Analyze Software Capabilities +- Re-scan the software source at the software path +- Identify all public APIs, CLI tools, scripting interfaces, and batch-mode operations +- Focus on functions that produce observable output (renders, exports, transforms, conversions) +- Categorize by domain (e.g., for GIMP: filters, color adjustments, layer ops, selection tools) + +### Step 3: Gap Analysis +- Compare current CLI coverage against the software's full capability set +- Prioritize gaps by: + 1. **High impact** — commonly used functions missing from the CLI + 2. **Easy wins** — functions with simple APIs that can be wrapped quickly + 3. **Composability** — functions that unlock new workflows when combined with existing commands +- Present the gap report to the user and confirm which gaps to address + +### Step 4: Implement New Commands +- Add new commands/subcommands to the CLI for the selected gaps +- Follow the same patterns as existing commands (as defined in HARNESS.md): + - Click command groups + - `--json` output support + - Session state integration + - Error handling with `handle_error` +- Add corresponding core module functions in `core/` or `utils/` + +### Step 5: Expand Tests +- Add unit tests for every new function in `test_core.py` +- Add E2E tests for new commands in `test_full_e2e.py` +- Add workflow tests that combine new commands with existing ones +- Run all tests (old + new) to ensure no regressions + +### Step 6: Update Documentation +- Update `README.md` with new commands and usage examples +- Update `TEST.md` with new test results +- Update the SOP document (`.md`) with new coverage notes + +## Success Criteria + +- All existing tests still pass (no regressions) +- New commands follow the same architectural patterns (per HARNESS.md) +- New tests achieve 100% pass rate +- Coverage meaningfully improved (new functions exposed via CLI) +- Documentation updated to reflect changes + +## Notes + +- Refine is incremental — run it multiple times to steadily expand coverage +- Each run should focus on a coherent set of related functions rather than trying to cover everything at once +- The agent should present the gap analysis before implementing, so the user can steer priorities +- Refine never removes existing commands — it only adds or enhances diff --git a/opencode-commands/cli-anything-test.md b/opencode-commands/cli-anything-test.md new file mode 100644 index 000000000..680484d63 --- /dev/null +++ b/opencode-commands/cli-anything-test.md @@ -0,0 +1,62 @@ +--- +description: Run tests for a CLI harness and update TEST.md with results +--- +# cli-anything-test Command + +Run tests for a CLI harness and update TEST.md with results. + +**Target software**: $1 + +## CRITICAL: Read HARNESS.md First + +**Before running tests, read `./HARNESS.md` (located alongside this command).** It defines the test standards, expected structure, and what constitutes a passing test suite. + +## Arguments + +- `$1` is the **software path or repo URL** (required). Either: + - A **local path** to the software source code (e.g., `/home/user/gimp`, `./blender`) + - A **GitHub repository URL** (e.g., `https://github.com/GNOME/gimp`, `github.com/blender/blender`) + + If a GitHub URL is provided, clone the repo locally first, then work on the local copy. + + The software name is derived from the directory name. The agent locates the CLI harness at `/root/cli-anything//agent-harness/`. + +## What This Command Does + +1. **Locates the CLI** - Finds the CLI harness based on the software path +2. **Runs pytest** - Executes tests with `-v -s --tb=short` +3. **Captures output** - Saves full test results +4. **Verifies subprocess backend** - Confirms `[_resolve_cli] Using installed command:` appears in output +5. **Updates TEST.md** - Appends results to the Test Results section +6. **Reports status** - Shows pass/fail summary + +## Test Output Format + +The command appends to TEST.md: + +```markdown +## Test Results + +Last run: 2024-03-05 14:30:00 + +``` +[full pytest -v --tb=no output] +``` + +**Summary**: 103 passed in 3.05s +``` + +## Success Criteria + +- All tests pass (100% pass rate) +- TEST.md is updated with full results +- No test failures or errors +- `[_resolve_cli]` output confirms installed command path + +## Failure Handling + +If tests fail: +1. Shows which tests failed +2. Does NOT update TEST.md (keeps previous passing results) +3. Suggests fixes based on error messages +4. Offers to re-run after fixes diff --git a/opencode-commands/cli-anything-validate.md b/opencode-commands/cli-anything-validate.md new file mode 100644 index 000000000..1326187bb --- /dev/null +++ b/opencode-commands/cli-anything-validate.md @@ -0,0 +1,112 @@ +--- +description: Validate a CLI harness against HARNESS.md standards and best practices +--- +# cli-anything-validate Command + +Validate a CLI harness against HARNESS.md standards and best practices. + +**Target software**: $1 + +## CRITICAL: Read HARNESS.md First + +**Before validating, read `./HARNESS.md` (located alongside this command).** It is the single source of truth for all validation checks below. Every check in this command maps to a requirement in HARNESS.md. + +## Arguments + +- `$1` is the **software path or repo URL** (required). Either: + - A **local path** to the software source code (e.g., `/home/user/gimp`, `./blender`) + - A **GitHub repository URL** (e.g., `https://github.com/GNOME/gimp`, `github.com/blender/blender`) + + If a GitHub URL is provided, clone the repo locally first, then work on the local copy. + + The software name is derived from the directory name. The agent locates the CLI harness at `/root/cli-anything//agent-harness/`. + +## What This Command Validates + +### 1. Directory Structure +- `agent-harness/cli_anything//` exists (namespace sub-package) +- `cli_anything/` has NO `__init__.py` (PEP 420 namespace package) +- `/` HAS `__init__.py` (regular sub-package) +- `core/`, `utils/`, `tests/` subdirectories present +- `setup.py` in agent-harness/ uses `find_namespace_packages` + +### 2. Required Files +- `README.md` - Installation and usage guide +- `_cli.py` - Main CLI entry point +- `core/project.py` - Project management +- `core/session.py` - Undo/redo +- `core/export.py` - Rendering/export +- `tests/TEST.md` - Test plan and results +- `tests/test_core.py` - Unit tests +- `tests/test_full_e2e.py` - E2E tests +- `../.md` - Software-specific SOP + +### 3. CLI Implementation Standards +- Uses Click framework +- Has command groups (not flat commands) +- Implements `--json` flag for machine-readable output +- Implements `--project` flag for project file +- Has `handle_error` decorator for consistent error handling +- Has REPL mode +- Has global session state + +### 4. Core Module Standards +- `project.py` has: create, open, save, info, list_profiles +- `session.py` has: Session class with undo/redo/snapshot +- `export.py` has: render function and EXPORT_PRESETS +- All modules have proper docstrings +- All functions have type hints + +### 5. Test Standards +- `TEST.md` has both plan (Part 1) and results (Part 2) +- Unit tests use synthetic data only +- E2E tests use real files +- Workflow tests simulate real-world scenarios +- `test_full_e2e.py` has a `TestCLISubprocess` class +- `TestCLISubprocess` uses `_resolve_cli("cli-anything-")` (no hardcoded paths) +- `_resolve_cli` prints which backend is used and supports `CLI_ANYTHING_FORCE_INSTALLED` +- Subprocess `_run` does NOT set `cwd` (installed commands work from any directory) +- All tests pass (100% pass rate) + +### 6. Documentation Standards +- `README.md` has: installation, usage, command reference, examples +- `.md` has: architecture analysis, command map, rendering gap assessment +- No duplicate `HARNESS.md` (should reference plugin's HARNESS.md) +- All commands documented with examples + +### 7. PyPI Packaging Standards +- `setup.py` uses `find_namespace_packages(include=["cli_anything.*"])` +- Package name follows `cli-anything-` convention +- Entry point: `cli-anything-=cli_anything.._cli:main` +- `cli_anything/` has NO `__init__.py` (namespace package rule) +- All imports use `cli_anything..*` prefix +- Dependencies listed in install_requires +- Python version requirement specified (>=3.10) + +### 8. Code Quality +- No syntax errors +- No import errors +- Follows PEP 8 style +- No hardcoded paths (uses relative paths or config) +- Proper error handling (no bare `except:`) + +## Validation Report + +The command generates a detailed report: + +``` +CLI Harness Validation Report +Software: gimp +Path: /root/cli-anything/gimp/agent-harness/cli_anything/gimp + +Directory Structure (5/5 checks passed) +Required Files (9/9 files present) +CLI Implementation (7/7 standards met) +Core Modules (5/5 standards met) +Test Standards (10/10 standards met) +Documentation (4/4 standards met) +PyPI Packaging (7/7 standards met) +Code Quality (5/5 checks passed) + +Overall: PASS (52/52 checks) +``` diff --git a/opencode-commands/cli-anything.md b/opencode-commands/cli-anything.md new file mode 100644 index 000000000..00d0227c7 --- /dev/null +++ b/opencode-commands/cli-anything.md @@ -0,0 +1,114 @@ +--- +description: Build a complete CLI harness for any GUI application (all 7 phases) +subtask: true +--- +# cli-anything Command + +Build a complete, stateful CLI harness for any GUI application. + +**Target software**: $1 + +## CRITICAL: Read HARNESS.md First + +**Before doing anything else, you MUST read `./HARNESS.md` (located alongside this command).** It defines the complete methodology, architecture standards, and implementation patterns. Every phase below follows HARNESS.md. Do not improvise — follow the harness specification. + +## Arguments + +- `$1` is the **software path or repo URL**. Either: + - A **local path** to the software source code (e.g., `/home/user/gimp`, `./blender`) + - A **GitHub repository URL** (e.g., `https://github.com/GNOME/gimp`, `github.com/blender/blender`) + + If a GitHub URL is provided, clone the repo locally first, then work on the local copy. + + **Note:** Software names alone (e.g., "gimp") are NOT accepted. You must provide the actual source code path or repository URL so the agent can analyze the codebase. + +## What This Command Does + +This command implements the complete cli-anything methodology to build a production-ready CLI harness for any GUI application. **All phases follow the standards defined in HARNESS.md.** + +### Phase 0: Source Acquisition +- If `$1` is a GitHub URL, clone it to a local working directory +- Verify the local path exists and contains source code +- Derive the software name from the directory name (e.g., `/home/user/gimp` -> `gimp`) + +### Phase 1: Codebase Analysis +- Analyzes the local source code +- Analyzes the backend engine and data model +- Maps GUI actions to API calls +- Identifies existing CLI tools +- Documents the architecture + +### Phase 2: CLI Architecture Design +- Designs command groups matching the app's domains +- Plans the state model and output formats +- Creates the software-specific SOP document (e.g., GIMP.md) + +### Phase 3: Implementation +- Creates the directory structure: `agent-harness/cli_anything//core`, `utils`, `tests` +- Implements core modules (project, session, export, etc.) +- Builds the Click-based CLI with REPL support +- Implements `--json` output mode for agent consumption +- All imports use `cli_anything..*` namespace + +### Phase 4: Test Planning +- Creates `TEST.md` with comprehensive test plan +- Plans unit tests for all core modules +- Plans E2E tests with real files +- Designs realistic workflow scenarios + +### Phase 5: Test Implementation +- Writes unit tests (`test_core.py`) - synthetic data, no external deps +- Writes E2E tests (`test_full_e2e.py`) - real files, full pipeline +- Implements workflow tests simulating real-world usage +- Adds output verification (pixel analysis, format validation, etc.) +- Adds `TestCLISubprocess` class with `_resolve_cli("cli-anything-")` + that tests the installed command via subprocess (no hardcoded paths or CWD) + +### Phase 6: Test Documentation +- Runs all tests with `pytest -v --tb=no` +- Appends full test results to `TEST.md` +- Documents test coverage and any gaps + +### Phase 7: PyPI Publishing and Installation +- Creates `setup.py` with `find_namespace_packages(include=["cli_anything.*"])` +- Package name: `cli-anything-`, namespace: `cli_anything.` +- `cli_anything/` has NO `__init__.py` (PEP 420 namespace package) +- Configures console_scripts entry point for PATH installation +- Tests local installation with `pip install -e .` +- Verifies CLI is available in PATH: `which cli-anything-` + +## Output Structure + +``` +/ +└── agent-harness/ + ├── .md # Software-specific SOP + ├── setup.py # PyPI package config (find_namespace_packages) + └── cli_anything/ # Namespace package (NO __init__.py) + └── / # Sub-package (HAS __init__.py) + ├── README.md # Installation and usage guide + ├── _cli.py # Main CLI entry point + ├── core/ # Core modules + │ ├── project.py + │ ├── session.py + │ ├── export.py + │ └── ... + ├── utils/ # Utilities + └── tests/ + ├── TEST.md # Test plan and results + ├── test_core.py # Unit tests + └── test_full_e2e.py # E2E tests +``` + +## Success Criteria + +The command succeeds when: +1. All core modules are implemented and functional +2. CLI supports both one-shot commands and REPL mode +3. `--json` output mode works for all commands +4. All tests pass (100% pass rate) +5. Subprocess tests use `_resolve_cli()` and pass with `CLI_ANYTHING_FORCE_INSTALLED=1` +6. TEST.md contains both plan and results +7. README.md documents installation and usage +8. setup.py is created and local installation works +9. CLI is available in PATH as `cli-anything-`