completion-ai 0.1.0__tar.gz

completion_ai-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.DS_Store
+
+# generated completion artifacts (not source)
+_*
+!compgen_ai/

completion_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yangwb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

completion_ai-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: completion-ai
+Version: 0.1.0
+Summary: LLM-powered zsh completion scaffolding for arbitrary CLIs
+Project-URL: Homepage, https://github.com/Yangeyu/completion-ai
+Project-URL: Repository, https://github.com/Yangeyu/completion-ai
+Project-URL: Issues, https://github.com/Yangeyu/completion-ai/issues
+Author-email: yangwb <binyang617@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,completion,dashscope,llm,qwen,zsh
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: httpx[socks]>=0.27.0
+Requires-Dist: openai>=1.40.0
+Description-Content-Type: text/markdown
+
+# completion-ai
+
+LLM-powered zsh completion scaffolding for arbitrary CLIs. Point it at any
+command on your `PATH` and it will:
+
+1. Recursively run `<cmd> --help` (and discovered subcommand `--help`s).
+   Subcommand discovery is done by the LLM, not regex — so `install [options]`,
+   `plugin|plugins`, and other oddly-formatted entries are picked up.
+2. Ask Qwen (via DashScope OpenAI-compatible API) to extract a structured
+   schema of flags, subcommands, and positional arguments.
+3. Render a `#compdef` zsh completion script using a deterministic template
+   (the LLM never writes shell directly).
+4. Run `zsh -n` against the result and warn on syntax errors.
+
+The output is meant to be **reviewed by a human** before installation — it's
+a scaffold, not a runtime completion engine.
+
+## Install
+
+Recommended (global CLI, isolated venv managed by uv):
+
+```sh
+uv tool install -e .
+```
+
+Other options:
+
+```sh
+uv pip install -e .       # into the current uv venv
+pip install -e .          # into the active python (conda, system, ...)
+```
+
+Requires `DASHSCOPE_API_KEY` in the environment.
+
+## Usage
+
+```sh
+completion-ai claude                     # writes ./_claude
+completion-ai claude --install           # install straight into oh-my-zsh
+completion-ai claude -o ~/.zsh/completions/_claude
+completion-ai docker --depth 3 -v        # crawl deeper, verbose
+completion-ai gh --dump-schema gh.json   # also save intermediate schema
+```
+
+### Options
+
+| Flag | Default | Notes |
+|---|---|---|
+| `-o, --output PATH` | `./_<cmd>` | Where to write the completion script |
+| `-d, --depth N` | `2` | How deep to crawl subcommand help |
+| `--model ID` | `qwen-plus` | Override via `COMPLETION_AI_MODEL` too |
+| `--dump-schema PATH` | — | Also save the JSON the LLM produced |
+| `--no-syntax-check` | off | Skip `zsh -n` validation |
+| `--install` | off | Install into `$ZSH/custom/plugins/completion-ai/` |
+| `-v, --verbose` | off | Progress logs to stderr |
+
+### Environment
+
+- `DASHSCOPE_API_KEY` — required
+- `COMPLETION_AI_MODEL` — defaults to `qwen-plus`
+- `COMPLETION_AI_BASE_URL` — defaults to DashScope OpenAI-compatible endpoint
+- `ZSH` — oh-my-zsh root, used by `--install` (defaults to `~/.oh-my-zsh`)
+
+## Installing the generated completion
+
+### Option A — oh-my-zsh users (recommended)
+
+```sh
+completion-ai claude --install
+```
+
+This creates `$ZSH/custom/plugins/completion-ai/_claude` plus a
+plugin stub. **First time only**, add the plugin to `~/.zshrc`:
+
+```zsh
+plugins=(git ... completion-ai)
+```
+
+Then refresh:
+
+```sh
+rm -f ~/.zcompdump* && exec zsh
+```
+
+Subsequent `completion-ai <cmd> --install` calls drop new completions into the
+same plugin directory — no zshrc edits needed.
+
+### Option B — plain zsh
+
+```sh
+completion-ai claude -o ~/.zsh/completions/_claude
+
+# in ~/.zshrc (one-time):
+fpath=(~/.zsh/completions $fpath)
+autoload -U compinit && compinit
+```
+
+## How it works
+
+```
+[crawler]   run `<cmd> --help`
+    ↓
+[llm]       discover subcommand names from help text  (1 call per node)
+    ↓
+[crawler]   recursively run discovered subcommands' --help
+    ↓
+[llm]       extract structured JSON schema from all help texts  (1 call)
+    ↓
+[renderer]  JSON → #compdef zsh template (deterministic, not LLM)
+    ↓
+[validator] zsh -n syntax check
+```
+
+For `depth=2`, that's **2 LLM calls** total (1 discover + 1 extract).
+
+## Limitations
+
+- Static only: dynamic completions (e.g. `git checkout <branch>`) are not
+  generated — the script may suggest a hint type (`branch`, `host`, ...) but
+  won't query live state.
+- The LLM may miss hidden flags or mislabel value hints. Always diff against
+  `<cmd> --help` before trusting.
+- Only zsh for now.
+
+## Development
+
+```sh
+git clone <repo> && cd completion-ai
+uv venv && source .venv/bin/activate
+uv pip install -e .
+```
+
+## License
+
+MIT

completion_ai-0.1.0/README.md

@@ -0,0 +1,135 @@
+# completion-ai
+
+LLM-powered zsh completion scaffolding for arbitrary CLIs. Point it at any
+command on your `PATH` and it will:
+
+1. Recursively run `<cmd> --help` (and discovered subcommand `--help`s).
+   Subcommand discovery is done by the LLM, not regex — so `install [options]`,
+   `plugin|plugins`, and other oddly-formatted entries are picked up.
+2. Ask Qwen (via DashScope OpenAI-compatible API) to extract a structured
+   schema of flags, subcommands, and positional arguments.
+3. Render a `#compdef` zsh completion script using a deterministic template
+   (the LLM never writes shell directly).
+4. Run `zsh -n` against the result and warn on syntax errors.
+
+The output is meant to be **reviewed by a human** before installation — it's
+a scaffold, not a runtime completion engine.
+
+## Install
+
+Recommended (global CLI, isolated venv managed by uv):
+
+```sh
+uv tool install -e .
+```
+
+Other options:
+
+```sh
+uv pip install -e .       # into the current uv venv
+pip install -e .          # into the active python (conda, system, ...)
+```
+
+Requires `DASHSCOPE_API_KEY` in the environment.
+
+## Usage
+
+```sh
+completion-ai claude                     # writes ./_claude
+completion-ai claude --install           # install straight into oh-my-zsh
+completion-ai claude -o ~/.zsh/completions/_claude
+completion-ai docker --depth 3 -v        # crawl deeper, verbose
+completion-ai gh --dump-schema gh.json   # also save intermediate schema
+```
+
+### Options
+
+| Flag | Default | Notes |
+|---|---|---|
+| `-o, --output PATH` | `./_<cmd>` | Where to write the completion script |
+| `-d, --depth N` | `2` | How deep to crawl subcommand help |
+| `--model ID` | `qwen-plus` | Override via `COMPLETION_AI_MODEL` too |
+| `--dump-schema PATH` | — | Also save the JSON the LLM produced |
+| `--no-syntax-check` | off | Skip `zsh -n` validation |
+| `--install` | off | Install into `$ZSH/custom/plugins/completion-ai/` |
+| `-v, --verbose` | off | Progress logs to stderr |
+
+### Environment
+
+- `DASHSCOPE_API_KEY` — required
+- `COMPLETION_AI_MODEL` — defaults to `qwen-plus`
+- `COMPLETION_AI_BASE_URL` — defaults to DashScope OpenAI-compatible endpoint
+- `ZSH` — oh-my-zsh root, used by `--install` (defaults to `~/.oh-my-zsh`)
+
+## Installing the generated completion
+
+### Option A — oh-my-zsh users (recommended)
+
+```sh
+completion-ai claude --install
+```
+
+This creates `$ZSH/custom/plugins/completion-ai/_claude` plus a
+plugin stub. **First time only**, add the plugin to `~/.zshrc`:
+
+```zsh
+plugins=(git ... completion-ai)
+```
+
+Then refresh:
+
+```sh
+rm -f ~/.zcompdump* && exec zsh
+```
+
+Subsequent `completion-ai <cmd> --install` calls drop new completions into the
+same plugin directory — no zshrc edits needed.
+
+### Option B — plain zsh
+
+```sh
+completion-ai claude -o ~/.zsh/completions/_claude
+
+# in ~/.zshrc (one-time):
+fpath=(~/.zsh/completions $fpath)
+autoload -U compinit && compinit
+```
+
+## How it works
+
+```
+[crawler]   run `<cmd> --help`
+    ↓
+[llm]       discover subcommand names from help text  (1 call per node)
+    ↓
+[crawler]   recursively run discovered subcommands' --help
+    ↓
+[llm]       extract structured JSON schema from all help texts  (1 call)
+    ↓
+[renderer]  JSON → #compdef zsh template (deterministic, not LLM)
+    ↓
+[validator] zsh -n syntax check
+```
+
+For `depth=2`, that's **2 LLM calls** total (1 discover + 1 extract).
+
+## Limitations
+
+- Static only: dynamic completions (e.g. `git checkout <branch>`) are not
+  generated — the script may suggest a hint type (`branch`, `host`, ...) but
+  won't query live state.
+- The LLM may miss hidden flags or mislabel value hints. Always diff against
+  `<cmd> --help` before trusting.
+- Only zsh for now.
+
+## Development
+
+```sh
+git clone <repo> && cd completion-ai
+uv venv && source .venv/bin/activate
+uv pip install -e .
+```
+
+## License
+
+MIT

completion_ai-0.1.0/completion_ai/cli.py

@@ -0,0 +1,198 @@
+"""completion-ai CLI entry point."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+OMZ_PLUGIN_NAME = "completion-ai"
+
+from . import __version__
+from .crawler import crawl
+from .llm import DEFAULT_MODEL, discover_subcommands, extract_schema
+from .renderer import render_zsh
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="completion-ai",
+        description="Generate zsh completion scaffolding for any CLI using an LLM.",
+    )
+    p.add_argument("command", help="Target CLI command (must be on PATH)")
+    p.add_argument(
+        "-o", "--output", type=Path, default=None,
+        help="Output path (default: ./_<command>)",
+    )
+    p.add_argument(
+        "-d", "--depth", type=int, default=2,
+        help="Max subcommand crawl depth (default: 2)",
+    )
+    p.add_argument(
+        "--model", default=DEFAULT_MODEL,
+        help=f"LLM model id (default: {DEFAULT_MODEL}; env COMPLETION_AI_MODEL)",
+    )
+    p.add_argument(
+        "--dump-schema", type=Path, default=None,
+        help="Also write the intermediate JSON schema here",
+    )
+    p.add_argument(
+        "--no-syntax-check", action="store_true",
+        help="Skip the zsh -n syntax validation",
+    )
+    p.add_argument(
+        "--install", action="store_true",
+        help=(
+            "Install the generated completion into the oh-my-zsh plugin "
+            f"'{OMZ_PLUGIN_NAME}' (overrides --output)."
+        ),
+    )
+    p.add_argument("-v", "--verbose", action="store_true")
+    p.add_argument("--version", action="version", version=f"completion-ai {__version__}")
+    return p
+
+
+def _syntax_check(script: str) -> tuple[bool, str]:
+    with tempfile.NamedTemporaryFile("w", suffix=".zsh", delete=False) as f:
+        f.write(script)
+        path = f.name
+    try:
+        r = subprocess.run(
+            ["zsh", "-n", path],
+            capture_output=True, text=True, timeout=5,
+        )
+        return r.returncode == 0, (r.stderr or r.stdout).strip()
+    except FileNotFoundError:
+        return True, "zsh not found, skipping syntax check"
+    finally:
+        Path(path).unlink(missing_ok=True)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    cmd = args.command
+
+    def log(msg: str) -> None:
+        if args.verbose:
+            print(f"[completion-ai] {msg}", file=sys.stderr)
+
+    discover_calls = [0]
+
+    def _discover(help_text: str) -> list[str]:
+        discover_calls[0] += 1
+        subs = discover_subcommands(help_text, model=args.model)
+        log(f"discover #{discover_calls[0]}: {subs}")
+        return subs
+
+    try:
+        log(f"crawling `{cmd} --help` (depth={args.depth}, model={args.model})")
+        root = crawl(cmd, max_depth=args.depth, discover=_discover)
+    except FileNotFoundError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    except Exception as e:
+        print(f"error: crawl failed: {e}", file=sys.stderr)
+        return 3
+
+    n_nodes = len(root.flatten())
+    log(f"collected {n_nodes} help section(s) via {discover_calls[0]} discover call(s)")
+
+    try:
+        log("extracting schema")
+        schema = extract_schema(root, model=args.model, verbose=args.verbose)
+    except Exception as e:
+        print(f"error: LLM call failed: {e}", file=sys.stderr)
+        return 3
+
+    if not schema.get("name"):
+        schema["name"] = cmd
+
+    if args.dump_schema:
+        args.dump_schema.write_text(json.dumps(schema, indent=2, ensure_ascii=False))
+        log(f"wrote schema -> {args.dump_schema}")
+
+    script = render_zsh(schema)
+
+    if not args.no_syntax_check:
+        ok, msg = _syntax_check(script)
+        if not ok:
+            print("warning: generated script failed `zsh -n` check:", file=sys.stderr)
+            print(msg, file=sys.stderr)
+            print("output still written; please review.", file=sys.stderr)
+        else:
+            log("zsh -n syntax check passed")
+
+    if args.install:
+        return _install_to_omz(cmd, script, log)
+
+    out = args.output or Path.cwd() / f"_{cmd}"
+    out.write_text(script)
+    print(f"wrote {out}")
+    print(
+        "next steps:\n"
+        f"  1. review {out}\n"
+        f"  2. move to a directory on $fpath, e.g.:\n"
+        f"       mkdir -p ~/.zsh/completions && mv {out} ~/.zsh/completions/\n"
+        f"       # add to ~/.zshrc if not already:  fpath=(~/.zsh/completions $fpath)\n"
+        f"  3. reload completions:  autoload -U compinit && compinit\n"
+        "tip: use --install to drop it straight into oh-my-zsh."
+    )
+    return 0
+
+
+def _omz_root() -> Path:
+    return Path(os.environ.get("ZSH") or Path.home() / ".oh-my-zsh")
+
+
+def _install_to_omz(cmd: str, script: str, log) -> int:
+    omz = _omz_root()
+    if not omz.is_dir():
+        print(
+            f"error: oh-my-zsh not found at {omz}. "
+            "Set $ZSH or install oh-my-zsh first.",
+            file=sys.stderr,
+        )
+        return 4
+
+    plugin_dir = omz / "custom" / "plugins" / OMZ_PLUGIN_NAME
+    plugin_dir.mkdir(parents=True, exist_ok=True)
+    target = plugin_dir / f"_{cmd}"
+    target.write_text(script)
+    log(f"installed -> {target}")
+
+    # Ensure the plugin has an entrypoint file so oh-my-zsh recognizes it.
+    stub = plugin_dir / f"{OMZ_PLUGIN_NAME}.plugin.zsh"
+    if not stub.exists():
+        stub.write_text(
+            "# Auto-generated by completion-ai.\n"
+            "# Adds this directory to fpath so the _<cmd> files here are picked up.\n"
+            "fpath=(${0:A:h} $fpath)\n"
+        )
+        log(f"created plugin stub -> {stub}")
+
+    zshrc = Path.home() / ".zshrc"
+    plugin_listed = False
+    if zshrc.exists():
+        try:
+            plugin_listed = OMZ_PLUGIN_NAME in zshrc.read_text()
+        except OSError:
+            pass
+
+    print(f"installed completion for `{cmd}` -> {target}")
+    if not plugin_listed:
+        print(
+            "\nOne more step: add the plugin to ~/.zshrc, e.g.:\n"
+            f"    plugins=(... {OMZ_PLUGIN_NAME})\n"
+        )
+    print(
+        "Then reload:\n"
+        "    rm -f ~/.zcompdump* && exec zsh"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

completion_ai-0.1.0/completion_ai/crawler.py

@@ -0,0 +1,61 @@
+"""Recursively collect --help text for a target CLI.
+
+Subcommand discovery is delegated to a caller-supplied callback (typically an
+LLM call) so this module doesn't need to understand help-format dialects.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from typing import Callable
+
+
+@dataclass
+class HelpNode:
+    path: list[str]
+    help_text: str
+    children: list["HelpNode"] = field(default_factory=list)
+
+    def flatten(self) -> list["HelpNode"]:
+        out = [self]
+        for c in self.children:
+            out.extend(c.flatten())
+        return out
+
+
+DiscoverFn = Callable[[str], list[str]]
+
+
+def run_help(argv: list[str], timeout: float = 8.0) -> str:
+    try:
+        r = subprocess.run(
+            argv + ["--help"],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError, PermissionError) as e:
+        return f"[completion-ai: failed to run {' '.join(argv)} --help: {e}]"
+    return (r.stdout or "") + (("\n" + r.stderr) if r.stderr else "")
+
+
+def crawl(cmd: str, max_depth: int, discover: DiscoverFn) -> HelpNode:
+    if shutil.which(cmd) is None:
+        raise FileNotFoundError(f"command not found on PATH: {cmd}")
+    root = HelpNode(path=[cmd], help_text=run_help([cmd]))
+    if max_depth > 1:
+        _expand(root, max_depth, 1, discover)
+    return root
+
+
+def _expand(node: HelpNode, max_depth: int, depth: int, discover: DiscoverFn) -> None:
+    if depth >= max_depth:
+        return
+    for sub in discover(node.help_text):
+        if not sub or not isinstance(sub, str):
+            continue
+        child_path = node.path + [sub]
+        child = HelpNode(path=child_path, help_text=run_help(child_path))
+        node.children.append(child)
+        _expand(child, max_depth, depth + 1, discover)

completion_ai-0.1.0/completion_ai/llm.py

@@ -0,0 +1,130 @@
+"""Call Qwen (DashScope, OpenAI-compatible) for:
+  1. discover_subcommands - given one help text, list direct subcommand names.
+  2. extract_schema - given the full help tree, return structured CLI schema.
+"""
+from __future__ import annotations
+
+import json
+import os
+import textwrap
+
+from openai import OpenAI
+
+from .crawler import HelpNode
+
+DEFAULT_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
+DEFAULT_MODEL = os.environ.get("COMPLETION_AI_MODEL", "qwen-plus")
+
+
+def _client() -> OpenAI:
+    api_key = os.environ.get("DASHSCOPE_API_KEY")
+    if not api_key:
+        raise RuntimeError("DASHSCOPE_API_KEY is not set")
+    base_url = os.environ.get("COMPLETION_AI_BASE_URL", DEFAULT_BASE_URL)
+    return OpenAI(api_key=api_key, base_url=base_url)
+
+
+DISCOVER_SYSTEM = textwrap.dedent(
+    """
+    You read one CLI's --help output and list its direct subcommand names.
+
+    Output JSON exactly like: {"subcommands": ["name1", "name2"]}
+
+    Rules:
+    - Only direct subcommands (not flags, not nested subcommands).
+    - For aliased entries like "plugin|plugins" return the canonical first
+      name only ("plugin").
+    - Strip placeholder tokens like "[options]", "[args]", "<target>", etc.
+    - Skip "help" if listed as a subcommand.
+    - If no subcommand section exists, return {"subcommands": []}.
+    - Be conservative: only what is explicitly listed.
+    - Do not invent commands not present in the help text.
+    """
+).strip()
+
+
+EXTRACT_SYSTEM = textwrap.dedent(
+    """
+    You analyze CLI --help output and produce a JSON schema describing the
+    command tree, flags, and positional arguments. Be conservative: only
+    include things explicitly shown in the help text. Do not invent flags.
+
+    Output JSON with this exact shape (no prose, no markdown fences):
+    {
+      "name": "<root command>",
+      "description": "<one-line summary>",
+      "flags": [
+        {"long": "--foo", "short": "-f", "takes_value": true, "value_hint": "file|dir|enum|string", "choices": ["a","b"], "description": "..."}
+      ],
+      "positionals": [
+        {"name": "PATH", "value_hint": "file|dir|string", "description": "...", "repeatable": false}
+      ],
+      "subcommands": [
+        { ... same shape recursively, omit fields not present ... }
+      ]
+    }
+
+    Rules:
+    - "short" may be omitted if absent. "choices" only when help lists them.
+    - "value_hint" must be one of: file, dir, command, host, user, branch,
+      string, enum, integer. Use "string" when unsure.
+    - Keep descriptions under 80 chars, single line.
+    - Omit any field you are unsure about rather than guessing.
+    - Include every subcommand whose help text appears in the input, even if
+      its own help is sparse.
+    """
+).strip()
+
+
+def discover_subcommands(help_text: str, model: str = DEFAULT_MODEL) -> list[str]:
+    client = _client()
+    resp = client.chat.completions.create(
+        model=model,
+        messages=[
+            {"role": "system", "content": DISCOVER_SYSTEM},
+            {"role": "user", "content": help_text},
+        ],
+        temperature=0,
+        response_format={"type": "json_object"},
+    )
+    data = json.loads(resp.choices[0].message.content or "{}")
+    raw = data.get("subcommands") or []
+    out: list[str] = []
+    seen: set[str] = set()
+    for s in raw:
+        if not isinstance(s, str):
+            continue
+        name = s.strip().split()[0] if s.strip() else ""
+        if name and name not in seen and not name.startswith("-"):
+            seen.add(name)
+            out.append(name)
+    return out
+
+
+def _serialize_tree(node: HelpNode) -> str:
+    parts = []
+    for n in node.flatten():
+        header = "$ " + " ".join(n.path) + " --help"
+        parts.append(f"{header}\n{n.help_text.rstrip()}")
+    return "\n\n---\n\n".join(parts)
+
+
+def extract_schema(root: HelpNode, model: str = DEFAULT_MODEL, verbose: bool = False) -> dict:
+    client = _client()
+    user_content = (
+        f"Root command: {root.path[0]}\n\n"
+        f"Help outputs (root + subcommands):\n\n{_serialize_tree(root)}"
+    )
+    if verbose:
+        print(f"[llm] extract model={model} prompt_chars={len(user_content)}")
+    resp = client.chat.completions.create(
+        model=model,
+        messages=[
+            {"role": "system", "content": EXTRACT_SYSTEM},
+            {"role": "user", "content": user_content},
+        ],
+        temperature=0.1,
+        response_format={"type": "json_object"},
+    )
+    content = resp.choices[0].message.content or "{}"
+    return json.loads(content)

completion_ai-0.1.0/completion_ai/renderer.py

@@ -0,0 +1,141 @@
+"""Render extracted schema into a zsh _compdef completion script."""
+from __future__ import annotations
+
+from typing import Any
+
+VALUE_HINT_TO_ZSH = {
+    "file": "_files",
+    "dir": "_files -/",
+    "directory": "_files -/",
+    "command": "_command_names",
+    "host": "_hosts",
+    "user": "_users",
+    "branch": "__git_branch_names 2>/dev/null || _message branch",
+    "integer": "_message number",
+    "string": "",
+    "enum": "",
+}
+
+
+def _zsh_escape(s: str) -> str:
+    if s is None:
+        return ""
+    return s.replace("\\", "\\\\").replace("'", "''").replace("[", "\\[").replace("]", "\\]").replace(":", "\\:")
+
+
+def _action_for(flag: dict[str, Any]) -> str:
+    if not flag.get("takes_value"):
+        return ""
+    choices = flag.get("choices") or []
+    if choices:
+        joined = " ".join(_zsh_escape(c) for c in choices)
+        return f":value:({joined})"
+    hint = (flag.get("value_hint") or "string").lower()
+    action = VALUE_HINT_TO_ZSH.get(hint, "")
+    label = _zsh_escape(hint or "value")
+    return f":{label}:{action}".rstrip(":")
+
+
+def _flag_spec(flag: dict[str, Any]) -> str:
+    long = flag.get("long") or ""
+    short = flag.get("short") or ""
+    desc = _zsh_escape(flag.get("description") or "")
+    action = _action_for(flag)
+
+    forms = [f for f in (short, long) if f]
+    if not forms:
+        return ""
+    if len(forms) == 2:
+        head = "{" + ",".join(forms) + "}"
+        exclusion = "(" + " ".join(forms) + ")"
+        return f"'{exclusion}'{head}'[{desc}]{action}'"
+    return f"'{forms[0]}[{desc}]{action}'"
+
+
+def _positional_spec(pos: dict[str, Any], idx: int) -> str:
+    name = _zsh_escape(pos.get("name") or f"arg{idx}")
+    hint = (pos.get("value_hint") or "string").lower()
+    action = VALUE_HINT_TO_ZSH.get(hint, "")
+    quantifier = "*" if pos.get("repeatable") else f"{idx}"
+    return f"'{quantifier}:{name}:{action}'".rstrip("'") + "'"
+
+
+def _has_subcommands(node: dict[str, Any]) -> bool:
+    return bool(node.get("subcommands"))
+
+
+def _render_node(node: dict[str, Any], func_name: str, indent: str = "  ") -> tuple[str, list[str]]:
+    """Return (function body, list of child function definitions)."""
+    flags = node.get("flags") or []
+    positionals = node.get("positionals") or []
+    subs = node.get("subcommands") or []
+
+    lines: list[str] = []
+    lines.append(f"{func_name}() {{")
+    lines.append(f"{indent}local curcontext=$curcontext state line ret=1")
+    lines.append(f"{indent}local -a args")
+    lines.append(f"{indent}args=(")
+
+    for f in flags:
+        spec = _flag_spec(f)
+        if spec:
+            lines.append(f"{indent}{indent}{spec}")
+
+    if subs:
+        lines.append(f"{indent}{indent}'1: :->cmds'")
+        lines.append(f"{indent}{indent}'*::arg:->args'")
+    else:
+        for i, p in enumerate(positionals, start=1):
+            lines.append(f"{indent}{indent}{_positional_spec(p, i)}")
+
+    lines.append(f"{indent})")
+    lines.append(f"{indent}_arguments -C $args && ret=0")
+
+    children_defs: list[str] = []
+    if subs:
+        lines.append(f"{indent}case $state in")
+        lines.append(f"{indent}{indent}cmds)")
+        sub_descs = []
+        for s in subs:
+            sname = s.get("name") or ""
+            sdesc = _zsh_escape(s.get("description") or "")
+            if sname:
+                sub_descs.append(f"'{_zsh_escape(sname)}:{sdesc}'")
+        lines.append(f"{indent}{indent}{indent}local -a subcmds")
+        lines.append(f"{indent}{indent}{indent}subcmds=({' '.join(sub_descs)})")
+        lines.append(f"{indent}{indent}{indent}_describe 'command' subcmds && ret=0")
+        lines.append(f"{indent}{indent};;")
+        lines.append(f"{indent}{indent}args)")
+        lines.append(f"{indent}{indent}{indent}case $line[1] in")
+        for s in subs:
+            sname = s.get("name") or ""
+            if not sname:
+                continue
+            child_fn = f"{func_name}_{sname.replace('-', '_')}"
+            lines.append(f"{indent}{indent}{indent}{indent}{sname}) {child_fn} ;;")
+            body, more = _render_node(s, child_fn, indent)
+            children_defs.append(body)
+            children_defs.extend(more)
+        lines.append(f"{indent}{indent}{indent}esac")
+        lines.append(f"{indent}{indent};;")
+        lines.append(f"{indent}esac")
+
+    lines.append(f"{indent}return ret")
+    lines.append("}")
+    return "\n".join(lines), children_defs
+
+
+def render_zsh(schema: dict[str, Any]) -> str:
+    cmd = schema.get("name") or "cmd"
+    safe_cmd = cmd.replace("-", "_")
+    root_fn = f"_{safe_cmd}"
+    body, children = _render_node(schema, root_fn)
+
+    header = (
+        f"#compdef {cmd}\n"
+        f"# Generated by completion-ai. Review before installing.\n"
+        f"# Move to a directory on $fpath (e.g. ~/.zsh/completions/_{cmd}),\n"
+        f"# then run: autoload -U compinit && compinit\n"
+    )
+    parts = [header, body, *children, f"{root_fn} \"$@\""]
+    return "\n\n".join(parts) + "\n"

completion_ai-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "completion-ai"
+version = "0.1.0"
+description = "LLM-powered zsh completion scaffolding for arbitrary CLIs"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "yangwb", email = "binyang617@gmail.com" }]
+keywords = ["cli", "completion", "zsh", "llm", "qwen", "dashscope"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+    "Topic :: System :: Shells",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "openai>=1.40.0",
+    "httpx[socks]>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Yangeyu/completion-ai"
+Repository = "https://github.com/Yangeyu/completion-ai"
+Issues = "https://github.com/Yangeyu/completion-ai/issues"
+
+[project.scripts]
+completion-ai = "completion_ai.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["completion_ai"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "completion_ai",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]