"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/
Python
upgrade to v0.2.0 with a series of updates
yuhao3c2b7fd09f9e
diff --git a/README.md b/README.mdindex 3293af939..84a461776 100644--- a/README.md+++ b/README.md@@ -41,9 +41,26 @@ CLI-Anything: Bridging the Gap Between AI Agents and the World's Software</stron> Thanks to all invaluable efforts from the community! More updates continuously on the way everyday..-- **2026-03-23** ๐ค Launched **CLI-Hub meta-skill** โ agents can now discover and install CLIs autonomously via [`cli-hub-meta-skill/SKILL.md`](cli-hub-meta-skill/SKILL.md). The catalog auto-updates from `registry.json` via GitHub Actions, making the entire marketplace agent-native.+- **2026-03-30** ๐๏ธ **CLI-Anything v0.2.0** โ HARNESS.md progressive disclosure redesign. Detailed guides (MCP backend, filter translation, timecode, session locking, PyPI publishing, SKILL.md generation) extracted into `guides/` for on-demand loading. Phases 1โ7 now contiguous. Key Principles and Rules merged into a single authoritative section. Added Guides Reference routing table. Renamed "Critical Lessons Learned" to "Architecture Patterns & Pitfalls."-- **2026-03-22** ๐ต **MuseScore CLI** merged with transpose, export, and instrument management. Community contributions continue expanding domain coverage.+- **2026-03-29** ๐ Blender skill docs updated โ enforce absolute render paths and correct prerequisites.++- **2026-03-28** ๐ **CLIBrowser** added to CLI-Hub registry for agent-accessible browser automation.++- **2026-03-27** ๐ Zotero SKILL.md enhanced with agent-facing constraints; REPL config and executable resolution fixes.++- **2026-03-26** ๐ **Zotero CLI** harness landed for Zotero desktop (library management, collections, citations). Draw.io custom ID bugfix (#132) and registry.json syntax fix.++- **2026-03-25** ๐ฎ **RenderDoc CLI** merged for GPU frame capture analysis (PSO compute, REPL capture cache). FreeCAD updated for v1.1 (new datum system, tapping, simulation). Blender EEVEE engine name corrected. Zoom token permissions hardened.++- **2026-03-24** ๐ญ **FreeCAD CLI** added with 258 commands across 17 groups. **iTerm2** and **Teltonika RMS** harnesses added to registry. CLI-Hub frontend and README install URLs updated.++- **2026-03-23** ๐ค Launched **CLI-Hub meta-skill** โ agents can now discover and install CLIs autonomously via [`cli-hub-meta-skill/SKILL.md`](cli-hub-meta-skill/SKILL.md). **Krita CLI** harness merged for digital painting. DOMShell MCP parameter mismatches and connection model fixed.++<details>+<summary>Earlier news (Mar 17โ22)</summary>++- **2026-03-22** ๐ต **MuseScore CLI** merged with transpose, export, and instrument management.- **2026-03-21** ๐ง Infrastructure improvements โ refined test harnesses and documentation across multiple CLIs. Enhanced Windows compatibility for several backends.@@ -53,22 +70,24 @@ CLI-Anything: Bridging the Gap Between AI Agents and the World's Software</stron- **2026-03-18** ๐งช Test coverage expansion โ additional E2E scenarios and edge case validation across multiple CLIs.-- **2026-03-17** ๐ Launched the **[CLI-Hub](https://hkuds.github.io/CLI-Anything/)** โ a central registry where you can browse, search, and install any CLI with a single `pip` command. Contributors can add new CLIs or update existing ones by simply opening a PR with a `registry.json` entry. The hub updates automatically on merge.+- **2026-03-17** ๐ Launched the **[CLI-Hub](https://hkuds.github.io/CLI-Anything/)** โ a central registry where you can browse, search, and install any CLI with a single `pip` command.++</details><details>-<summary>Earlier news</summary>+<summary>Earlier news (Mar 11โ16)</summary>-- **2026-03-16** ๐ค Added **SKILL.md generation** (Phase 6.5) โ every generated CLI now ships with an AI-discoverable skill definition inside the Python package. ReplSkin auto-detects the skill file after `pip install`, and the REPL banner displays the absolute path for agents. Includes `skill_generator.py`, Jinja2 template, `package_data` in all setup.py files, and 51 new tests.+- **2026-03-16** ๐ค Added **SKILL.md generation** (Phase 6.5) โ every generated CLI now ships with an AI-discoverable skill definition. Includes `skill_generator.py`, Jinja2 template, and 51 new tests.-- **2026-03-15** ๐พ Support for **OpenClaw** from the community! Merged Windows `cygpath` guard to ensure CLI-Anything works reliably in Windows bash environments. Community contributions continue to strengthen cross-platform support.+- **2026-03-15** ๐พ Support for **OpenClaw** from the community! Merged Windows `cygpath` guard for cross-platform support.-- **2026-03-14** ๐ Fixed a GIMP Script-Fu path injection vulnerability and added **Japanese README** translation. OpenCode version requirements documented alongside several Windows compatibility improvements.+- **2026-03-14** ๐ Fixed a GIMP Script-Fu path injection vulnerability and added **Japanese README** translation.-- **2026-03-13** ๐ **Qodercli** plugin officially merged as a community contribution with dedicated setup scripts. Codex skill gained a Windows install script, and placeholder URLs were cleaned up across the project.+- **2026-03-13** ๐ **Qodercli** plugin officially merged as a community contribution with dedicated setup scripts.-- **2026-03-12** ๐ฆ **Codex skill** integration landed, bringing CLI-Anything to yet another AI coding platform. Qodercli support was also introduced, and documentation was updated with limitations and experimental labels.+- **2026-03-12** ๐ฆ **Codex skill** integration landed, bringing CLI-Anything to yet another AI coding platform.-- **2026-03-11** ๐ **Zoom** video conferencing harness added as the 11th supported application. Multiple community fixes shipped for Shotcut auto-save, LibreOffice Windows/macOS backend, and OpenCode support.+- **2026-03-11** ๐ **Zoom** video conferencing harness added as the 11th supported application.</details>diff --git a/cli-anything-plugin/HARNESS.md b/cli-anything-plugin/HARNESS.mdindex acd12fe8d..1a08bea0d 100644--- a/cli-anything-plugin/HARNESS.md+++ b/cli-anything-plugin/HARNESS.md@@ -68,35 +68,9 @@ designed for humans, without needing a display or mouse.Generate valid intermediate files, then invoke the real software for conversion.6. **Add session management** โ State persistence, undo/redo- **Session file locking** โ When saving session JSON, use exclusive file locking- to prevent concurrent writes from corrupting data. Never use bare- `open("w") + json.dump()` โ `open("w")` truncates the file before any lock- can be acquired. Instead, open with `"r+"`, lock, then truncate inside the lock:- ```python- def _locked_save_json(path, data, **dump_kwargs) -> None:- """Atomically write JSON with exclusive file locking."""- try:- f = open(path, "r+") # no truncation on open- except FileNotFoundError:- os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)- f = open(path, "w") # first save โ file doesn't exist yet- with f:- _locked = False- try:- import fcntl- fcntl.flock(f.fileno(), fcntl.LOCK_EX)- _locked = True- except (ImportError, OSError):- pass # Windows / unsupported FS โ proceed unlocked- try:- f.seek(0)- f.truncate() # truncate INSIDE the lock- json.dump(data, f, **dump_kwargs)- f.flush()- finally:- if _locked:- fcntl.flock(f.fileno(), fcntl.LOCK_UN)- ```+ **Session file locking** โ Use exclusive file locking for session JSON saves+ to prevent concurrent write corruption. See [`guides/session-locking.md`](guides/session-locking.md)+ for the `_locked_save_json` pattern (open `"r+"`, lock, then truncate inside the lock).7. **Add the REPL with unified skin** โ Interactive mode wrapping the subcommands.- Copy `repl_skin.py` from the plugin (`cli-anything-plugin/repl_skin.py`) into`utils/repl_skin.py` in your CLI package@@ -275,60 +249,16 @@ definition that can be loaded by Claude Code or other AI assistants.---```-2. **Markdown Body** โ Usage instructions including:- - Installation prerequisites- - Basic command syntax- - Command groups and their functions- - Usage examples- - Agent-specific guidance (JSON output, error handling)--**Generation Process:**--1. **Extract CLI metadata** using `skill_generator.py`:- ```python- from skill_generator import generate_skill_file-- skill_path = generate_skill_file(- harness_path="/path/to/agent-harness"- )- # Default output: cli_anything/<software>/skills/SKILL.md- ```--2. **The generator automatically extracts:**- - Software name and version from setup.py- - Command groups from the CLI file (Click decorators)- - Documentation from README.md- - System package requirements--3. **Customize the template** (optional):- - Default template: `templates/SKILL.md.template`- - Uses Jinja2 placeholders for dynamic content- - Can be extended for software-specific sections--**Output Location:**+2. **Markdown Body** โ Installation prerequisites, command syntax, command groups,+ usage examples, and agent-specific guidance (JSON output, error handling).-SKILL.md is generated inside the Python package so it is installed with `pip install`:-```-<software>/-โโโ agent-harness/- โโโ cli_anything/- โโโ <software>/- โโโ skills/- โโโ SKILL.md-```--**Manual Generation:**+**Generation & Customization:** Use `skill_generator.py` to extract CLI metadata+automatically, or customize via the Jinja2 template at `templates/SKILL.md.template`.+See [`guides/skill-generation.md`](guides/skill-generation.md) for the full generation+process, template customization options, and manual generation commands.-```bash-cd cli-anything-plugin-python skill_generator.py /path/to/software/agent-harness-```--**Integration with CLI Build:**--The SKILL.md generation should be run after Phase 6 (Test Documentation) completes-successfully, ensuring the CLI is fully documented and tested before creating the-skill definition.+**Output Location:** SKILL.md lives inside the Python package at+`cli_anything/<software>/skills/SKILL.md` so it is installed with `pip install`.**Key Principles:**@@ -340,20 +270,11 @@ skill definition.**Skill Path in CLI Banner:**-ReplSkin auto-detects `skills/SKILL.md` inside the package and displays the absolute-path in the startup banner. AI agents can read the file at the displayed path:+ReplSkin auto-detects `skills/SKILL.md` inside the package directory and displays+the absolute path in the startup banner. AI agents can read the skill file at the+displayed path to learn the CLI's full capabilities.-```python-# In the REPL initialization (e.g., shotcut_cli.py)-from cli_anything.<software>.utils.repl_skin import ReplSkin--skin = ReplSkin("<software>", version="1.0.0")-skin.print_banner() # Auto-detects and displays: โ Skill: /path/to/cli_anything/<software>/skills/SKILL.md-```--**Package Data:**--Ensure `setup.py` includes the skill file as package data so it is installed with pip:+**Package Data:** Ensure `setup.py` includes the skill file so it ships with pip:```pythonpackage_data={@@ -361,7 +282,18 @@ package_data={},```-## Critical Lessons Learned+### Phase 7: PyPI Publishing and Installation++After building and testing the CLI, make it installable and discoverable using+**PEP 420 namespace packages** under the shared `cli_anything` namespace.++See [`guides/pypi-publishing.md`](guides/pypi-publishing.md) for the full setup.py template,+namespace package structure, import conventions, and verification steps.++**Key rule:** `cli_anything/` has **no** `__init__.py` (namespace package). Each+sub-package (`gimp/`, `blender/`, etc.) **does** have `__init__.py`.++## Architecture Patterns & Pitfalls### Use the Real Software โ Don't Reimplement It@@ -426,89 +358,23 @@ the input. Users can't tell anything happened.### MCP Backend Pattern-For services that expose an MCP (Model Context Protocol) server:+For software that exposes an MCP (Model Context Protocol) server instead of a traditional+CLI (e.g., DOMShell for browser automation). See [`guides/mcp-backend.md`](guides/mcp-backend.md)+for the full backend wrapper pattern, session management, daemon mode, and example implementations.-**Use case:** When the software provides an MCP server instead of a traditional CLI.-Example: DOMShell provides browser automation via MCP tools.--**When to use:**-- The software has an official or community MCP server-- No native CLI exists, or MCP provides better functionality-- You want to integrate AI/agent tools that speak MCP protocol--**Backend wrapper** (`utils/<service>_backend.py`):-```python-import asyncio-from typing import Any-from mcp import ClientSession, StdioServerParameters-from mcp.client.stdio import stdio_client--async def _call_tool(tool_name: str, arguments: dict) -> Any:- """Call an MCP tool."""- server_params = StdioServerParameters(- command="npx",- args=["@apireno/domshell"]- )- async with stdio_client(server_params) as (read, write):- async with ClientSession(read, write) as session:- await session.initialize()- result = await session.call_tool(tool_name, arguments)- return result--def is_available() -> bool:- """Check if MCP server is available."""- # Try to spawn and verify- ...--# Sync wrappers for each tool-def ls(path: str = "/") -> dict:- """List directory contents."""- return asyncio.run(_call_tool("domshell_ls", {"path": path}))-```--**Session management:**-- MCP server spawns per command (stateless from server perspective)-- CLI maintains state (URL, working directory, navigation history)-- Each command re-spawns the MCP server process--**Daemon mode (optional):**-- Spawn MCP server once, reuse connection for multiple commands-- Reduces latency for interactive use-- Requires explicit start/stop or `--daemon` flag--**Dependencies:** Add `mcp>=0.1.0` to install_requires--**Example implementations:**-- `browser/agent-harness` โ DOMShell MCP server for browser automation-- See: https://github.com/HKUDS/CLI-Anything/tree/main/browser/agent-harness+**Use when:** no native CLI exists, software has an MCP server, or you need agent-native tool integration.### Filter Translation Pitfalls-When translating effects between formats (e.g., MLT โ ffmpeg), watch for:--- **Duplicate filter types:** Some tools (ffmpeg) don't allow the same filter twice- in a chain. If your project has both `brightness` and `saturation` filters, and- both map to ffmpeg's `eq=`, you must **merge** them into a single `eq=brightness=X:saturation=Y`.-- **Ordering constraints:** ffmpeg's `concat` filter requires **interleaved** stream- ordering: `[v0][a0][v1][a1][v2][a2]`, NOT grouped `[v0][v1][v2][a0][a1][a2]`.- The error message ("media type mismatch") is cryptic if you don't know this.-- **Parameter space differences:** Effect parameters often use different scales.- MLT brightness `1.15` = +15%, but ffmpeg `eq=brightness=0.06` on a -1..1 scale.- Document every mapping explicitly.-- **Unmappable effects:** Some effects have no equivalent in the render tool. Handle- gracefully (warn, skip) rather than crash.+When translating effects between formats (e.g., MLT โ ffmpeg), watch for duplicate filter+merging, interleaved stream ordering, parameter scale differences, and unmappable effects.+See [`guides/filter-translation.md`](guides/filter-translation.md) for detailed rules and examples.### Timecode Precision-Non-integer frame rates (29.97fps = 30000/1001) cause cumulative rounding errors:--- **Use `round()`, not `int()`** for float-to-frame conversion. `int(9000 * 29.97)`- truncates and loses frames; `round()` gets the right answer.-- **Use integer arithmetic for timecode display.** Convert frames โ total milliseconds- via `round(frames * fps_den * 1000 / fps_num)`, then decompose with integer- division. Avoid intermediate floats that drift over long durations.-- **Accept ยฑ1 frame tolerance** in roundtrip tests at non-integer FPS. Exact equality- is mathematically impossible.+Non-integer frame rates (29.97fps) cause cumulative rounding errors. Key rules: use+`round()` not `int()`, use integer arithmetic for display, accept ยฑ1 frame tolerance.+See [`guides/timecode-precision.md`](guides/timecode-precision.md) for the full approach.### Output Verification Methodology@@ -602,53 +468,52 @@ Real-world workflow test scenarios should include:- Save/load round-trips of complex projects- Iterative refinement (add, modify, remove, re-add)-## Key Principles+## Principles & Rules++These are non-negotiable. Every harness MUST follow all of them.-- **Use the real software** โ The CLI MUST invoke the actual application for rendering- and export. Generate valid intermediate files (ODF, MLT XML, .blend, SVG), then hand- them to the real software. Never reimplement the rendering engine in Python.-- **The software is a hard dependency** โ Not optional, not gracefully degraded. If- LibreOffice isn't installed, `cli-anything-libreoffice` must error clearly, not- silently produce inferior output with a fallback library.+**Backend & Rendering:**+- **The real software is a hard dependency.** The CLI MUST invoke the actual application+ (LibreOffice, Blender, GIMP, etc.) for rendering and export. Do NOT reimplement+ rendering in Python. Do NOT gracefully degrade to a fallback library. If the software+ is not installed, error with clear install instructions.- **Manipulate the native format directly** โ Parse and modify the app's native projectfiles (MLT XML, ODF, SVG, etc.) as the data layer.- **Leverage existing CLI tools** โ Use `libreoffice --headless`, `blender --background`,`melt`, `ffmpeg`, `inkscape --actions`, `sox` as subprocesses for rendering.-- **Verify rendering produces correct output** โ See "The Rendering Gap" above.-- **E2E tests must produce real artifacts** โ PDF, DOCX, rendered images, videos.- Print output paths so users can inspect. Never test only the intermediate format.+- **Verify rendering produces correct output** โ See "The Rendering Gap" in+ Architecture Patterns & Pitfalls above.+- **Every filter/effect in the registry MUST have a corresponding render mapping**+ or be explicitly documented as "project-only (not rendered)".++**CLI Design:**- **Fail loudly and clearly** โ Agents need unambiguous error messages to self-correct.- **Be idempotent where possible** โ Running the same command twice should be safe.- **Provide introspection** โ `info`, `list`, `status` commands are critical for agentsto understand current state before acting.-- **JSON output mode** โ Every command should support `--json` for machine parsing.+- **JSON output mode** โ Every command MUST support `--json` for machine parsing.+- **Use the unified REPL skin** โ Copy `cli-anything-plugin/repl_skin.py` to+ `utils/repl_skin.py` and use `ReplSkin` for banner, prompt, help, and messages.+ REPL MUST be the default behavior (`invoke_without_command=True`).-## Rules--- **The real software MUST be a hard dependency.** The CLI must invoke the actual- software (LibreOffice, Blender, GIMP, etc.) for rendering and export. Do NOT- reimplement rendering in Python. Do NOT gracefully degrade to a fallback library.- If the software is not installed, the CLI must error with clear install instructions.-- **Every `cli_anything/<software>/` directory MUST contain a `README.md`** that explains how to- install the software dependency, install the CLI, run tests, and shows basic usage.+**Testing:**- **E2E tests MUST invoke the real software** and produce real output files (PDF, DOCX,- rendered images, videos). Tests must verify output exists, has correct format, and- print artifact paths so users can inspect results. Never test only intermediate files.-- **Every export/render function MUST be verified** with programmatic output analysis- before being marked as working. "It ran without errors" is not sufficient.-- **Every filter/effect in the registry MUST have a corresponding render mapping**- or be explicitly documented as "project-only (not rendered)".-- **Test suites MUST include real-file E2E tests**, not just unit tests with synthetic- data. Format assumptions break constantly with real media.+ rendered images, videos). Verify output exists, has correct format (magic bytes, ZIP+ structure), and print artifact paths for manual inspection. Never test only+ intermediate files.+- **Every export/render function MUST be verified** with programmatic output analysis.+ "It ran without errors" is not sufficient.- **E2E tests MUST include subprocess tests** that invoke the installed`cli-anything-<software>` command via `_resolve_cli()`. Tests must work againstthe actual installed package, not just source imports.-- **Every `cli_anything/<software>/tests/` directory MUST contain a `TEST.md`** documenting what the tests- cover, what realistic workflows are tested, and the full test results output.-- **Every CLI MUST use the unified REPL skin** (`repl_skin.py`) for the interactive mode.- Copy `cli-anything-plugin/repl_skin.py` to `utils/repl_skin.py` and use `ReplSkin`- for the banner, prompt, help, messages, and goodbye. REPL MUST be the default behavior- when the CLI is invoked without a subcommand (`invoke_without_command=True`).+- **Test suites MUST include real-file E2E tests**, not just unit tests with synthetic+ data. Format assumptions break constantly with real media.++**Documentation:**+- **Every `cli_anything/<software>/` directory MUST contain a `README.md`** explaining+ how to install the software dependency, install the CLI, run tests, and basic usage.+- **Every `cli_anything/<software>/tests/` directory MUST contain a `TEST.md`**+ documenting test coverage, realistic workflows tested, and full test results output.## Directory Structure@@ -712,110 +577,16 @@ command-line interface TO the software, not a replacement for it.The pattern is always the same: **build the data โ call the real software โ verifythe output**.-### Phase 7: PyPI Publishing and Installation--After building and testing the CLI, make it installable and discoverable.--All cli-anything CLIs use **PEP 420 namespace packages** under the shared-`cli_anything` namespace. This allows multiple CLI packages to be installed-side-by-side in the same Python environment without conflicts.--1. **Structure the package** as a namespace package:- ```- agent-harness/- โโโ setup.py- โโโ cli_anything/ # NO __init__.py here (namespace package)- โโโ <software>/ # e.g., gimp, blender, audacity- โโโ __init__.py # HAS __init__.py (regular sub-package)- โโโ <software>_cli.py- โโโ core/- โโโ utils/- โโโ tests/- ```-- The key rule: `cli_anything/` has **no** `__init__.py`. Each sub-package- (`gimp/`, `blender/`, etc.) **does** have `__init__.py`. This is what- enables multiple packages to contribute to the same namespace.+## Guides Reference-2. **Create setup.py** in the `agent-harness/` directory:- ```python- from setuptools import setup, find_namespace_packages-- setup(- name="cli-anything-<software>",- version="1.0.0",- packages=find_namespace_packages(include=["cli_anything.*"]),- install_requires=[- "click>=8.0.0",- "prompt-toolkit>=3.0.0",- # Add Python library dependencies here- ],- entry_points={- "console_scripts": [- "cli-anything-<software>=cli_anything.<software>.<software>_cli:main",- ],- },- python_requires=">=3.10",- )- ```-- **Important details:**- - Use `find_namespace_packages`, NOT `find_packages`- - Use `include=["cli_anything.*"]` to scope discovery- - Entry point format: `cli_anything.<software>.<software>_cli:main`- - The **system package** (LibreOffice, Blender, etc.) is a **hard dependency**- that cannot be expressed in `install_requires`. Document it in README.md and- have the backend module raise a clear error with install instructions:- ```python- # In utils/<software>_backend.py- def find_<software>():- path = shutil.which("<software>")- if path:- return path- raise RuntimeError(- "<Software> is not installed. Install it with:\n"- " apt install <software> # Debian/Ubuntu\n"- " brew install <software> # macOS"- )- ```--3. **All imports** use the `cli_anything.<software>` prefix:- ```python- from cli_anything.gimp.core.project import create_project- from cli_anything.gimp.core.session import Session- from cli_anything.blender.core.scene import create_scene- ```--4. **Test local installation**:- ```bash- cd /root/cli-anything/<software>/agent-harness- pip install -e .- ```--5. **Verify PATH installation**:- ```bash- which cli-anything-<software>- cli-anything-<software> --help- ```--6. **Run tests against the installed command**:- ```bash- cd /root/cli-anything/<software>/agent-harness- CLI_ANYTHING_FORCE_INSTALLED=1 python3 -m pytest cli_anything/<software>/tests/ -v -s- ```- The output must show `[_resolve_cli] Using installed command: /path/to/cli-anything-<software>`- confirming subprocess tests ran against the real installed binary, not a module fallback.--7. **Verify namespace works across packages** (when multiple CLIs installed):- ```python- import cli_anything.gimp- import cli_anything.blender- # Both resolve to their respective source directories- ```+Detailed guides live in `guides/`. Use this table to decide which ones to read+based on the software you're building a harness for.-**Why namespace packages:**-- Multiple CLIs coexist in the same Python environment without conflicts-- Clean, organized imports under a single `cli_anything` namespace-- Each CLI is independently installable/uninstallable via pip-- Agents can discover all installed CLIs via `cli_anything.*`-- Standard Python packaging โ no hacks or workarounds+| Guide | Read when... | Phase |+|-------|-------------|-------|+| [`session-locking.md`](guides/session-locking.md) | Implementing session save (all harnesses) | Phase 3 |+| [`skill-generation.md`](guides/skill-generation.md) | Generating the SKILL.md file | Phase 6.5 |+| [`pypi-publishing.md`](guides/pypi-publishing.md) | Packaging and installing the CLI | Phase 7 |+| [`mcp-backend.md`](guides/mcp-backend.md) | Software has an MCP server, no native CLI | Phase 3 |+| [`filter-translation.md`](guides/filter-translation.md) | Video/audio CLI with effects that need render-time translation | Phase 3 |+| [`timecode-precision.md`](guides/timecode-precision.md) | Video/audio CLI with non-integer frame rates (29.97fps, etc.) | Phase 3, 5 |diff --git a/cli-anything-plugin/guides/filter-translation.md b/cli-anything-plugin/guides/filter-translation.mdnew file mode 100644index 000000000..5e32fc8ef--- /dev/null+++ b/cli-anything-plugin/guides/filter-translation.md@@ -0,0 +1,26 @@+# Filter Translation Pitfalls++When translating effects between formats (e.g., MLT โ ffmpeg), watch for these common issues.++## Duplicate Filter Types++Some tools (ffmpeg) don't allow the same filter twice in a chain. If your project has both `brightness` and `saturation` filters, and both map to ffmpeg's `eq=`, you must **merge** them into a single `eq=brightness=X:saturation=Y`.++## Ordering Constraints++ffmpeg's `concat` filter requires **interleaved** stream ordering:+`[v0][a0][v1][a1][v2][a2]`, NOT grouped `[v0][v1][v2][a0][a1][a2]`.++The error message ("media type mismatch") is cryptic if you don't know this.++## Parameter Space Differences++Effect parameters often use different scales:+- MLT brightness `1.15` = +15%+- ffmpeg `eq=brightness=0.06` on a -1..1 scale++Document every mapping explicitly.++## Unmappable Effects++Some effects have no equivalent in the render tool. Handle gracefully (warn, skip) rather than crash.diff --git a/cli-anything-plugin/guides/mcp-backend.md b/cli-anything-plugin/guides/mcp-backend.mdnew file mode 100644index 000000000..0db45a45e--- /dev/null+++ b/cli-anything-plugin/guides/mcp-backend.md@@ -0,0 +1,64 @@+# MCP Backend Pattern++For services that expose an MCP (Model Context Protocol) server instead of a traditional CLI.++## When to Use++- The software has an official or community MCP server+- No native CLI exists, or MCP provides better functionality+- You want to integrate AI/agent tools that speak MCP protocol++**Use case:** When the software provides an MCP server instead of a traditional CLI.+Example: DOMShell provides browser automation via MCP tools.++## Backend Wrapper (`utils/<service>_backend.py`)++```python+import asyncio+from typing import Any+from mcp import ClientSession, StdioServerParameters+from mcp.client.stdio import stdio_client++async def _call_tool(tool_name: str, arguments: dict) -> Any:+ """Call an MCP tool."""+ server_params = StdioServerParameters(+ command="npx",+ args=["@apireno/domshell"]+ )+ async with stdio_client(server_params) as (read, write):+ async with ClientSession(read, write) as session:+ await session.initialize()+ result = await session.call_tool(tool_name, arguments)+ return result++def is_available() -> bool:+ """Check if MCP server is available."""+ # Try to spawn and verify+ ...++# Sync wrappers for each tool+def ls(path: str = "/") -> dict:+ """List directory contents."""+ return asyncio.run(_call_tool("domshell_ls", {"path": path}))+```++## Session Management++- MCP server spawns per command (stateless from server perspective)+- CLI maintains state (URL, working directory, navigation history)+- Each command re-spawns the MCP server process++## Daemon Mode (Optional)++- Spawn MCP server once, reuse connection for multiple commands+- Reduces latency for interactive use+- Requires explicit start/stop or `--daemon` flag++## Dependencies++Add `mcp>=0.1.0` to `install_requires`.++## Example Implementations++- `browser/agent-harness` โ DOMShell MCP server for browser automation+- See: https://github.com/HKUDS/CLI-Anything/tree/main/browser/agent-harnessdiff --git a/cli-anything-plugin/guides/pypi-publishing.md b/cli-anything-plugin/guides/pypi-publishing.mdnew file mode 100644index 000000000..7c8b72cc5--- /dev/null+++ b/cli-anything-plugin/guides/pypi-publishing.md@@ -0,0 +1,117 @@+# PyPI Publishing and Installation (Phase 7)++After building and testing the CLI, make it installable and discoverable.++All cli-anything CLIs use **PEP 420 namespace packages** under the shared+`cli_anything` namespace. This allows multiple CLI packages to be installed+side-by-side in the same Python environment without conflicts.++## 1. Package Structure++```+agent-harness/+โโโ setup.py+โโโ cli_anything/ # NO __init__.py here (namespace package)+ โโโ <software>/ # e.g., gimp, blender, audacity+ โโโ __init__.py # HAS __init__.py (regular sub-package)+ โโโ <software>_cli.py+ โโโ core/+ โโโ utils/+ โโโ tests/+```++The key rule: `cli_anything/` has **no** `__init__.py`. Each sub-package+(`gimp/`, `blender/`, etc.) **does** have `__init__.py`. This is what+enables multiple packages to contribute to the same namespace.++## 2. setup.py Template++Create `setup.py` in the `agent-harness/` directory:++```python+from setuptools import setup, find_namespace_packages++setup(+ name="cli-anything-<software>",+ version="1.0.0",+ packages=find_namespace_packages(include=["cli_anything.*"]),+ install_requires=[+ "click>=8.0.0",+ "prompt-toolkit>=3.0.0",+ # Add Python library dependencies here+ ],+ entry_points={+ "console_scripts": [+ "cli-anything-<software>=cli_anything.<software>.<software>_cli:main",+ ],+ },+ python_requires=">=3.10",+)+```++**Important details:**+- Use `find_namespace_packages`, NOT `find_packages`+- Use `include=["cli_anything.*"]` to scope discovery+- Entry point format: `cli_anything.<software>.<software>_cli:main`+- The **system package** (LibreOffice, Blender, etc.) is a **hard dependency**+ that cannot be expressed in `install_requires`. Document it in README.md and+ have the backend module raise a clear error with install instructions:+ ```python+ # In utils/<software>_backend.py+ def find_<software>():+ path = shutil.which("<software>")+ if path:+ return path+ raise RuntimeError(+ "<Software> is not installed. Install it with:\n"+ " apt install <software> # Debian/Ubuntu\n"+ " brew install <software> # macOS"+ )+ ```++## 3. Import Convention++All imports use the `cli_anything.<software>` prefix:++```python+from cli_anything.gimp.core.project import create_project+from cli_anything.gimp.core.session import Session+from cli_anything.blender.core.scene import create_scene+```++## 4. Verification Steps++**Test local installation:**+```bash+cd /root/cli-anything/<software>/agent-harness+pip install -e .+```++**Verify PATH installation:**+```bash+which cli-anything-<software>+cli-anything-<software> --help+```++**Run tests against the installed command:**+```bash+cd /root/cli-anything/<software>/agent-harness+CLI_ANYTHING_FORCE_INSTALLED=1 python3 -m pytest cli_anything/<software>/tests/ -v -s+```+The output must show `[_resolve_cli] Using installed command: /path/to/cli-anything-<software>`+confirming subprocess tests ran against the real installed binary, not a module fallback.++**Verify namespace works across packages** (when multiple CLIs installed):+```python+import cli_anything.gimp+import cli_anything.blender+# Both resolve to their respective source directories+```++## Why Namespace Packages++- Multiple CLIs coexist in the same Python environment without conflicts+- Clean, organized imports under a single `cli_anything` namespace+- Each CLI is independently installable/uninstallable via pip+- Agents can discover all installed CLIs via `cli_anything.*`+- Standard Python packaging โ no hacks or workaroundsdiff --git a/cli-anything-plugin/guides/session-locking.md b/cli-anything-plugin/guides/session-locking.mdnew file mode 100644index 000000000..3c3f50e6f--- /dev/null+++ b/cli-anything-plugin/guides/session-locking.md@@ -0,0 +1,39 @@+# Session File Locking++When saving session JSON, use exclusive file locking to prevent concurrent writes from corrupting data.++## The Problem++Never use bare `open("w") + json.dump()` โ `open("w")` truncates the file before any lock can be acquired.++## The Solution: `_locked_save_json`++Open with `"r+"`, lock, then truncate inside the lock:++```python+def _locked_save_json(path, data, **dump_kwargs) -> None:+ """Atomically write JSON with exclusive file locking."""+ try:+ f = open(path, "r+") # no truncation on open+ except FileNotFoundError:+ os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)+ f = open(path, "w") # first save โ file doesn't exist yet+ with f:+ _locked = False+ try:+ import fcntl+ fcntl.flock(f.fileno(), fcntl.LOCK_EX)+ _locked = True+ except (ImportError, OSError):+ pass # Windows / unsupported FS โ proceed unlocked+ try:+ f.seek(0)+ f.truncate() # truncate INSIDE the lock+ json.dump(data, f, **dump_kwargs)+ f.flush()+ finally:+ if _locked:+ fcntl.flock(f.fileno(), fcntl.LOCK_UN)+```++Copy this pattern into `core/session.py` for all session saves.diff --git a/cli-anything-plugin/guides/skill-generation.md b/cli-anything-plugin/guides/skill-generation.mdnew file mode 100644index 000000000..ea3f02a77--- /dev/null+++ b/cli-anything-plugin/guides/skill-generation.md@@ -0,0 +1,115 @@+# SKILL.md Generation (Phase 6.5)++Generate a SKILL.md file that makes the CLI discoverable and usable by AI agents+through the skill-creator methodology. This file serves as a self-contained skill+definition that can be loaded by Claude Code or other AI assistants.++## Purpose++SKILL.md files follow a standard format that enables AI agents to:+- Discover the CLI's capabilities+- Understand command structure and usage+- Generate correct command invocations+- Handle output programmatically++## SKILL.md Structure++### 1. YAML Frontmatter โ Triggering metadata for skill discovery:++```yaml+---+name: "cli-anything-<software>"+description: "Brief description of what the CLI does"+---+```++### 2. Markdown Body โ Usage instructions including:++- Installation prerequisites+- Basic command syntax+- Command groups and their functions+- Usage examples+- Agent-specific guidance (JSON output, error handling)++## Generation Process++### 1. Extract CLI metadata using `skill_generator.py`:++```python+from skill_generator import generate_skill_file++skill_path = generate_skill_file(+ harness_path="/path/to/agent-harness"+)+# Default output: cli_anything/<software>/skills/SKILL.md+```++### 2. The generator automatically extracts:++- Software name and version from setup.py+- Command groups from the CLI file (Click decorators)+- Documentation from README.md+- System package requirements++### 3. Customize the template (optional):++- Default template: `templates/SKILL.md.template`+- Uses Jinja2 placeholders for dynamic content+- Can be extended for software-specific sections++## Output Location++SKILL.md is generated inside the Python package so it is installed with `pip install`:++```+<software>/+โโโ agent-harness/+ โโโ cli_anything/+ โโโ <software>/+ โโโ skills/+ โโโ SKILL.md+```++## Manual Generation++```bash+cd cli-anything-plugin+python skill_generator.py /path/to/software/agent-harness+```++## Integration with CLI Build++The SKILL.md generation should be run after Phase 6 (Test Documentation) completes+successfully, ensuring the CLI is fully documented and tested before creating the+skill definition.++## Key Principles++- SKILL.md must be self-contained (no external dependencies for understanding)+- Include agent-specific guidance for programmatic usage+- Document `--json` flag usage for machine-readable output+- List all command groups with brief descriptions+- Provide realistic examples that demonstrate common workflows++## Skill Path in CLI Banner++ReplSkin auto-detects `skills/SKILL.md` inside the package and displays the absolute+path in the startup banner. AI agents can read the file at the displayed path:++```python+# In the REPL initialization (e.g., shotcut_cli.py)+from cli_anything.<software>.utils.repl_skin import ReplSkin++skin = ReplSkin("<software>", version="1.0.0")+skin.print_banner() # Auto-detects and displays: โ Skill: /path/to/cli_anything/<software>/skills/SKILL.md+```++## Package Data++Ensure `setup.py` includes the skill file as package data so it is installed with pip:++```python+package_data={+ "cli_anything.<software>": ["skills/*.md"],+},+```diff --git a/cli-anything-plugin/guides/timecode-precision.md b/cli-anything-plugin/guides/timecode-precision.mdnew file mode 100644index 000000000..6fc50345e--- /dev/null+++ b/cli-anything-plugin/guides/timecode-precision.md@@ -0,0 +1,22 @@+# Timecode Precision++Non-integer frame rates (29.97fps = 30000/1001) cause cumulative rounding errors. Follow these rules to avoid drift.++## Use `round()`, Not `int()`++For float-to-frame conversion:+- `int(9000 * 29.97)` โ **wrong**, truncates and loses frames+- `round(9000 * 29.97)` โ **correct**, gets the right answer++## Use Integer Arithmetic for Timecode Display++Convert frames โ total milliseconds via:+```python+total_ms = round(frames * fps_den * 1000 / fps_num)+```++Then decompose with integer division. Avoid intermediate floats that drift over long durations.++## Accept ยฑ1 Frame Tolerance++In roundtrip tests at non-integer FPS, exact equality is mathematically impossible. Accept ยฑ1 frame tolerance.