diff --git a/README.md b/README.md index ab56df3..beafd7b 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,20 @@ --- +## Start Here (Canonical Docs Route) + +If this is your first visit, **this `README.md` is the canonical onboarding path**. + +Follow this order: + +1. Stay in this file for context + Quick Start. +2. Use [`docs/README.md`](docs/README.md) as the docs index for deeper reading. +3. Open [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) when you are ready to contribute. + +This keeps first-time navigation deterministic and avoids documentation dead-ends. + +--- + ## Why This Exists LLMs are strong at reasoning, but weak on precise, current CLI syntax unless the exact tool/version is in context. diff --git a/docs/README.md b/docs/README.md index 48d917e..88e3b47 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,268 +1,21 @@ -# CLI Plugins +# Documentation Routing -> **OpenAPI for CLIs** -- Automatically crawl any CLI's `--help` output and generate structured Claude Code plugins that give AI agents expert-level command knowledge. +If you're new to this project, start at the repository root: -[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/) -[![Tests](https://img.shields.io/badge/tests-100%20passed-brightgreen.svg)](#running-tests) +- **Canonical first stop:** [`../README.md`](../README.md) ---- +The root README contains the complete first-time path (context, setup, quick start, and core workflow). -## The Problem +## Deep-Dive Docs Index -AI coding assistants lack precise knowledge of CLI tools -- especially newer ones released after training cutoffs. When asked to construct a `docker buildx` command or debug a `claude-flow swarm` invocation, they guess at flag names, invent non-existent options, and miss required arguments. Manual documentation is token-expensive and quickly outdated. +After reading the root README, use this index: -## The Solution +- **Contributing workflow and standards:** [`CONTRIBUTING.md`](CONTRIBUTING.md) -**CLI Plugins** solves this with a two-phase pipeline: +## Recommended Paths -``` -CLI binary --> Crawler --> JSON map --> Generator --> Claude Code Plugin -(git, docker...) (Phase 1) (output/) (Phase 2) (plugins/cli-*) -``` +- **First-time user:** `../README.md` -> Quick Start -> Generated Plugin Layout +- **Contributor:** `../README.md` -> this index -> `CONTRIBUTING.md` +- **Returning user:** jump directly to the doc above as needed -1. **Crawler** executes `--help` recursively across all subcommands, parsing flags, descriptions, examples, env vars, and usage patterns into a structured JSON map. -2. **Generator** transforms that JSON into a self-contained Claude Code plugin with progressive disclosure: a lean SKILL.md overview backed by full reference files. - -The result: Claude Code gains precise, complete, up-to-date knowledge of any CLI tool -- including ones it has never seen. - -## Highlights - -- **Universal parser** -- Handles 7 CLI format families (Go/Cobra, Python/Click, Rich-Click, Node/Commander, Git, POSIX, man pages) without hardcoded format detection -- **691 commands crawled** across 7 CLIs with 5,109 flags and 316 usage examples -- **Progressive disclosure** -- SKILL.md stays lean (~700 words); detailed flag tables and examples load on-demand from `references/` -- **Echoed parent detection** -- Automatically identifies when a CLI returns parent help for subcommands, preventing duplicated data -- **Zero dependencies** -- Crawler and generator use Python stdlib only -- **100% test coverage** -- 100 tests across crawler and generator (66 + 34) -- **Idempotent** -- Re-running overwrites cleanly, no stale files - -## Pre-Built Plugins - -Ready-to-use plugins for popular CLIs: - -| Plugin | Commands | Flags | Examples | Size | -|--------|----------|-------|----------|------| -| `cli-claude-flow` | 51 | 15 | 17 | ~10 KB | -| `cli-docker` | 271 | 1,419 | 7 | ~116 KB | -| `cli-git` | 22 | 441 | 126 | ~128 KB | -| `cli-gh` | 212 | 1,097 | 166 | ~110 KB | -| `cli-npm` | 67 | 411 | 0 | ~30 KB | -| `cli-uv` | 54 | 1,684 | 0 | ~193 KB | -| `cli-langchain` | 14 | 42 | 0 | ~8 KB | - -## Quick Start - -```bash -# Prerequisites: Python 3.11+, uv -git clone https://github.com/nsalvacao/cli-plugins.git -cd cli-plugins -uv sync - -# Crawl a CLI -uv run cli-crawler git -o output/git.json --raw - -# Generate the plugin -uv run generate-plugin output/git.json - -# Plugin ready at plugins/cli-git/ -``` - -## Installing a Plugin - -Copy a generated plugin to Claude Code's plugin directory: - -```bash -cp -r plugins/cli-docker ~/.claude/plugins/cli-docker -``` - -Or test locally without installing: - -```bash -claude --plugin-dir plugins/cli-docker -``` - -The plugin auto-activates when Claude Code detects relevant CLI questions. - -## Creating a Plugin for Any CLI - -### Step 1: Configure (optional) - -Add CLI-specific settings to `config.yaml`: - -```yaml -clis: - my-tool: - max_depth: 5 # Subcommand depth (default: 5) - group: my-category # Grouping label - timeout: 10 # Per-command timeout in seconds - plugins: - discovery_command: my-tool plugin list -``` - -### Step 2: Crawl - -```bash -uv run cli-crawler my-tool -o output/my-tool.json -v --raw -``` - -### Step 3: Generate - -```bash -uv run generate-plugin output/my-tool.json -``` - -### Step 4: Use - -```bash -claude --plugin-dir plugins/cli-my-tool -``` - -## Generated Plugin Structure - -``` -plugins/cli-my-tool/ -├── .claude-plugin/ -│ └── plugin.json # Plugin manifest -├── skills/ -│ └── cli-my-tool/ -│ ├── SKILL.md # Lean overview (~700 words) -│ └── references/ -│ ├── commands.md # Full command tree with flags -│ └── examples.md # Usage examples -├── commands/ -│ └── scan-cli.md # /scan-cli slash command -└── scripts/ - └── rescan.sh # Re-crawl and regenerate -``` - -**Progressive disclosure**: SKILL.md is always loaded when the skill triggers. Reference files load on-demand when Claude needs detailed flag tables or examples, keeping context window usage minimal. - -## Architecture - -### Crawler (`src/crawler/`) - -| Module | Purpose | -|--------|---------| -| `pipeline.py` | Top-level orchestrator | -| `detector.py` | Auto-detect help pattern (`--help`, `-h`, `help`, manpage) | -| `discovery.py` | Recursive subcommand crawl with cycle detection | -| `executor.py` | Safe subprocess execution with timeout | -| `parser.py` | Main parse dispatcher | -| `parsers/sections.py` | Section segmentation (7 format families) | -| `parsers/flags.py` | Flag extraction with type inference | -| `parsers/commands.py` | Subcommand list parsing | -| `parsers/usage.py` | Usage pattern extraction | -| `parsers/examples.py` | Example extraction | -| `parsers/envvars.py` | Environment variable extraction | -| `parsers/manpage.py` | Man page format parser | -| `models.py` | Data structures (`CLIMap`, `Command`, `Flag`, etc.) | -| `config.py` | YAML config loader | -| `formatter.py` | JSON serialization | -| `version.py` | Version detection | - -### Generator (`src/generator/plugin_generator.py`) - -Single-file generator using Python stdlib only. Reads crawler JSON and produces a complete Claude Code plugin directory. - -### Supported CLI Format Families - -| Family | Examples | Detection | -|--------|----------|-----------| -| Go/Cobra | docker, gh, kubectl | `Available Commands:` / `Flags:` | -| Python/Click | uv, pip | `Commands:` / `Options:` | -| Python/Rich-Click | claude-flow, langchain | Box-drawing borders + sections | -| Node/Commander | npm | Man page style | -| Git | git | Man page + porcelain/plumbing groups | -| Generic POSIX | curl, grep | `-flag description` format | -| Man pages | git-commit, npm-install | `.TH` / `NAME` / `SYNOPSIS` | - -## Development - -### Project Layout - -``` -cli-plugins/ -├── pyproject.toml # CLI entrypoints (project.scripts) -├── config.yaml # CLI configurations -├── src/ -│ ├── crawler/ # Crawler modules + cli-crawler entrypoint -│ ├── generator/ # Plugin generator (generate-plugin) -│ ├── config/ # Inventory/config audit (config-audit) -│ └── lib/ # Shared helpers -├── tests/ # Test suite -├── output/ # Crawler JSON output (gitignored) -├── plugins/ # Generated plugins -└── docs/ # Documentation -``` - -### Running Tests - -```bash -# All tests -uv run python -m pytest tests/ -v - -# Crawler tests only -uv run python -m pytest tests/ -v -k "not generate" - -# Generator tests only -uv run python -m pytest tests/test_generate_plugin.py -v -``` - -### Re-scanning a CLI - -Each plugin includes a `scripts/rescan.sh`: - -```bash -bash plugins/cli-docker/scripts/rescan.sh -``` - -Or manually: - -```bash -uv run cli-crawler docker -o output/docker.json --raw -v -uv run generate-plugin output/docker.json -``` - -### Batch Crawl - -```bash -for cli in ; do - uv run cli-crawler "$cli" -o "output/$cli.json" --raw -v -done -``` - -## Design Decisions - -- **Python stdlib only** -- No external dependencies for crawler or generator -- **Idempotent generation** -- Re-running overwrites cleanly, no stale files -- **Echoed parent detection** -- When a CLI returns parent help for a subcommand, the crawler creates a minimal entry using the parent's one-liner description instead of duplicating flags/examples -- **Progressive disclosure** -- SKILL.md stays lean; full details in reference files loaded on-demand -- **Format-agnostic parsing** -- Section-based segmentation handles Go, Python, Node, and POSIX conventions without hardcoded format detection -- **Domain-aware trigger phrases** -- Plugin descriptions use natural language with grouped command areas, not keyword stuffing - -## Requirements - -- Python 3.11+ -- [uv](https://docs.astral.sh/uv/) package manager -- Target CLI tools must be installed and on PATH - -## Contributing - -See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for development setup and guidelines. - -## Author - -**Nuno Salvacao** -- GitHub: [@nsalvacao](https://github.com/nsalvacao) -- LinkedIn: [nsalvacao](https://www.linkedin.com/in/nsalvacao/) -- Email: nuno.salvacao@gmail.com - -## License - -[MIT](LICENSE) - -## References - -- [Claude Code Plugins](https://docs.anthropic.com/en/docs/claude-code/plugins) -- Official plugin documentation -- [Claude Code Skills](https://docs.anthropic.com/en/docs/claude-code/skills) -- Skill authoring guide -- [OpenAPI Specification](https://swagger.io/specification/) -- The inspiration: structured API contracts, but for CLIs +This file intentionally stays short to keep routing unambiguous.