context-gen-cli 1.0.0__tar.gz → 1.2.4__tar.gz

context_gen_cli-1.2.4/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: context-gen-cli
+Version: 1.2.4
+Summary: A modern CLI tool that scans any project, builds an AST-based dependency graph, and generates structured LLM context (agent.md / agent.json).
+Author: yakkshit
+License-Expression: MIT
+Keywords: llm,context,agent,cli,code-analysis,ast,graph,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: typer[all]>=0.12.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: pathspec>=0.12.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: build>=1.1.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+
+# ⚡ context-gen-cli (Python Edition)
+
+[![PyPI version](https://img.shields.io/pypi/v/context-gen-cli.svg?color=3775a9)](https://pypi.org/project/context-gen-cli/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/context-gen-cli.svg)](https://pypi.org/project/context-gen-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> ⚡ **Fast, AST-powered Python CLI tool that scans any project, extracts architecture models, and generates structured LLM context (`agent.md`, `agent.json`, `agent.yaml`).**
+
+---
+
+## 🌟 Highlights
+
+- **100% Accurate Python Dependency Graphs**: Built using Python's native `ast` (Abstract Syntax Tree) module to resolve imports, relative packages, entry points, and utilities without regex guesswork.
+- **⚡ All-In-One Default Mode (`-d`)**: Auto-generates triple context formats in `context/` and runs a live auto-sync watcher in the background.
+- **`.gitignore` & Multi-Ignore Respect**: Automatically parses rules from `.gitignore`, `.npmignore`, `.dockerignore`, `.contextignore`, `.ignore`, and filters `.env*` secrets.
+- **Triple Format Output**: Generates Markdown (`agent.md`), MCP-compatible structured JSON (`agent.json`), and clean YAML (`agent.yaml`).
+- **🔄 Auto-Sync Watch Mode (`-w`)**: Monitors workspace changes and updates context files automatically on save.
+- **Configuration Parity**: Seamlessly reads `.context-gen.json` if present to maintain unified project settings with the Node.js edition.
+- **Modern CLI**: Styled with `typer` and `rich` for rich terminal output and progress reporting.
+
+---
+
+## 📦 Installation
+
+Install from PyPI using `pip` (or `pipx` / `uv`):
+
+```bash
+pip install context-gen-cli
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. ⚡ All-In-One Default Mode (Recommended)
+Generates all formats in `context/` and starts the live auto-sync watcher in background:
+
+```bash
+context-gen -d
+```
+
+### 2. Generate All Formats (Markdown, JSON, YAML)
+Scans the current directory and outputs `agent.md`, `agent.json`, and `agent.yaml` in `context/`:
+
+```bash
+context-gen .
+```
+
+### 3. Generate Specific Format (JSON / MD / YAML)
+Generate only the format you need:
+
+```bash
+# Generate MCP-ready JSON
+context-gen . --format json
+
+# Generate Markdown
+context-gen . --format md
+
+# Generate YAML
+context-gen . --format yaml
+```
+
+### 4. Watch Mode
+Keep context files fresh automatically on every file edit:
+
+```bash
+context-gen . --watch
+```
+
+### 5. Custom Output Destination & Directory Depth
+```bash
+context-gen ./my-project -o custom/docs/context.md --max-depth 4
+```
+
+---
+
+## 📖 CLI Reference
+
+```text
+Usage: context-gen [OPTIONS] [PATH]
+
+Arguments:
+  [PATH]    Target project directory to analyze  [default: .]
+
+Options:
+  -d, --default             ⚡ Zero-config default mode: generate all formats in context/ and run live auto-sync watcher
+  -f, --format [all|md|json|yaml]  Output format [default: all]
+  -o, --output PATH         Custom output file path (e.g. context/agent.md or custom.json)
+  -w, --watch               Watch directory and auto-regenerate context on file changes
+  --max-depth INTEGER       Maximum directory depth to scan (1-10) [default: 3]
+  --help                    Show this message and exit
+```
+
+---
+
+## 🌐 Node.js & Live MCP Server
+
+Looking for the live MCP server with interactive SSE streaming and public tunnels? Check out the [Node.js edition](https://www.npmjs.com/package/context-gen-cli):
+
+```bash
+npx context-gen-cli -d
+# or
+npx context-gen-cli --mcp
+```
+
+---
+
+## 📄 License
+
+MIT © [yakkshit](https://github.com/yakkshit)

context_gen_cli-1.2.4/README.md

@@ -0,0 +1,110 @@
+# ⚡ context-gen-cli (Python Edition)
+
+[![PyPI version](https://img.shields.io/pypi/v/context-gen-cli.svg?color=3775a9)](https://pypi.org/project/context-gen-cli/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/context-gen-cli.svg)](https://pypi.org/project/context-gen-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+> ⚡ **Fast, AST-powered Python CLI tool that scans any project, extracts architecture models, and generates structured LLM context (`agent.md`, `agent.json`, `agent.yaml`).**
+
+---
+
+## 🌟 Highlights
+
+- **100% Accurate Python Dependency Graphs**: Built using Python's native `ast` (Abstract Syntax Tree) module to resolve imports, relative packages, entry points, and utilities without regex guesswork.
+- **⚡ All-In-One Default Mode (`-d`)**: Auto-generates triple context formats in `context/` and runs a live auto-sync watcher in the background.
+- **`.gitignore` & Multi-Ignore Respect**: Automatically parses rules from `.gitignore`, `.npmignore`, `.dockerignore`, `.contextignore`, `.ignore`, and filters `.env*` secrets.
+- **Triple Format Output**: Generates Markdown (`agent.md`), MCP-compatible structured JSON (`agent.json`), and clean YAML (`agent.yaml`).
+- **🔄 Auto-Sync Watch Mode (`-w`)**: Monitors workspace changes and updates context files automatically on save.
+- **Configuration Parity**: Seamlessly reads `.context-gen.json` if present to maintain unified project settings with the Node.js edition.
+- **Modern CLI**: Styled with `typer` and `rich` for rich terminal output and progress reporting.
+
+---
+
+## 📦 Installation
+
+Install from PyPI using `pip` (or `pipx` / `uv`):
+
+```bash
+pip install context-gen-cli
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. ⚡ All-In-One Default Mode (Recommended)
+Generates all formats in `context/` and starts the live auto-sync watcher in background:
+
+```bash
+context-gen -d
+```
+
+### 2. Generate All Formats (Markdown, JSON, YAML)
+Scans the current directory and outputs `agent.md`, `agent.json`, and `agent.yaml` in `context/`:
+
+```bash
+context-gen .
+```
+
+### 3. Generate Specific Format (JSON / MD / YAML)
+Generate only the format you need:
+
+```bash
+# Generate MCP-ready JSON
+context-gen . --format json
+
+# Generate Markdown
+context-gen . --format md
+
+# Generate YAML
+context-gen . --format yaml
+```
+
+### 4. Watch Mode
+Keep context files fresh automatically on every file edit:
+
+```bash
+context-gen . --watch
+```
+
+### 5. Custom Output Destination & Directory Depth
+```bash
+context-gen ./my-project -o custom/docs/context.md --max-depth 4
+```
+
+---
+
+## 📖 CLI Reference
+
+```text
+Usage: context-gen [OPTIONS] [PATH]
+
+Arguments:
+  [PATH]    Target project directory to analyze  [default: .]
+
+Options:
+  -d, --default             ⚡ Zero-config default mode: generate all formats in context/ and run live auto-sync watcher
+  -f, --format [all|md|json|yaml]  Output format [default: all]
+  -o, --output PATH         Custom output file path (e.g. context/agent.md or custom.json)
+  -w, --watch               Watch directory and auto-regenerate context on file changes
+  --max-depth INTEGER       Maximum directory depth to scan (1-10) [default: 3]
+  --help                    Show this message and exit
+```
+
+---
+
+## 🌐 Node.js & Live MCP Server
+
+Looking for the live MCP server with interactive SSE streaming and public tunnels? Check out the [Node.js edition](https://www.npmjs.com/package/context-gen-cli):
+
+```bash
+npx context-gen-cli -d
+# or
+npx context-gen-cli --mcp
+```
+
+---
+
+## 📄 License
+
+MIT © [yakkshit](https://github.com/yakkshit)

context_gen_cli-1.2.4/context_gen/cli.py

@@ -0,0 +1,287 @@
+"""
+context_gen.cli: Typer-based CLI entry point for context-gen-cli (Python Edition).
+"""
+
+import json
+import time
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import List, Optional
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from context_gen.scanner import scan_project
+from context_gen.extractor import extract_metadata
+from context_gen.graph import build_dependency_graph
+from context_gen.generator import generate_agent_md, generate_agent_json, generate_agent_yaml
+
+app = typer.Typer(
+    name="context-gen",
+    help="⚡ Generate graph-based project context (agent.md, agent.json, agent.yaml) for LLMs.",
+    add_completion=False,
+    no_args_is_help=False
+)
+console = Console()
+
+
+class OutputFormat(str, Enum):
+    """Supported output formats."""
+    ALL = "all"
+    MD = "md"
+    JSON = "json"
+    YAML = "yaml"
+
+
+def execute_generation(
+    target_dir: Path,
+    format_choice: OutputFormat,
+    output_override: Optional[Path] = None,
+    max_depth: int = 3,
+    verbose: bool = True
+) -> dict:
+    """Scans and generates the requested context format files."""
+    scan_result = scan_project(str(target_dir), max_depth=max_depth)
+    files = scan_result["files"]
+    tree = scan_result["tree"]
+
+    metadata = extract_metadata(str(target_dir), files)
+    graph = build_dependency_graph(files, str(target_dir))
+
+    # Read output directory from .context-gen.json if available
+    config_file = target_dir / ".context-gen.json"
+    output_dir_name = "context"
+    if config_file.is_file():
+        try:
+            with open(config_file, "r", encoding="utf-8") as f:
+                cfg = json.load(f)
+                output_dir_name = cfg.get("outputDir", "context")
+        except Exception:
+            pass
+
+    dest_dir = target_dir / output_dir_name
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    generated_files: List[Path] = []
+
+    if output_override:
+        out_file = output_override.resolve()
+        out_file.parent.mkdir(parents=True, exist_ok=True)
+        if format_choice == OutputFormat.JSON:
+            json_data = generate_agent_json(metadata, graph, tree, str(target_dir))
+            out_file.write_text(json.dumps(json_data, indent=2), encoding="utf-8")
+        elif format_choice == OutputFormat.YAML:
+            yaml_text = generate_agent_yaml(metadata, graph, tree, str(target_dir))
+            out_file.write_text(yaml_text, encoding="utf-8")
+        else:
+            md_text = generate_agent_md(metadata, graph, tree)
+            out_file.write_text(md_text, encoding="utf-8")
+        generated_files.append(out_file)
+    else:
+        # Determine formats to generate
+        formats_to_build = ["md", "json", "yaml"] if format_choice == OutputFormat.ALL else [format_choice.value]
+
+        if "md" in formats_to_build:
+            md_file = dest_dir / "agent.md"
+            md_text = generate_agent_md(metadata, graph, tree)
+            md_file.write_text(md_text, encoding="utf-8")
+            generated_files.append(md_file)
+
+        if "json" in formats_to_build:
+            json_file = dest_dir / "agent.json"
+            json_data = generate_agent_json(metadata, graph, tree, str(target_dir))
+            json_file.write_text(json.dumps(json_data, indent=2), encoding="utf-8")
+            generated_files.append(json_file)
+
+        if "yaml" in formats_to_build:
+            yaml_file = dest_dir / "agent.yaml"
+            yaml_text = generate_agent_yaml(metadata, graph, tree, str(target_dir))
+            yaml_file.write_text(yaml_text, encoding="utf-8")
+            generated_files.append(yaml_file)
+
+    return {
+        "files": files,
+        "graph": graph,
+        "metadata": metadata,
+        "generated_files": generated_files,
+        "output_dir": dest_dir
+    }
+
+
+def run_watch_loop(target_dir: Path, format_choice: OutputFormat, max_depth: int = 3) -> None:
+    """Runs a live background file watch loop that regenerates context on changes."""
+    console.print(
+        Panel(
+            f"[bold cyan]👀 Watch Mode Active[/bold cyan]\n"
+            f"[dim]Monitoring workspace:[/dim] [green]{target_dir}[/green]\n"
+            f"[dim]Auto-updating context files on save. Press [bold]Ctrl+C[/bold] to exit.[/dim]",
+            border_style="cyan"
+        )
+    )
+
+    last_snapshot = {}
+
+    def get_snapshot():
+        snap = {}
+        for p in target_dir.rglob("*"):
+            if p.is_file():
+                rel = p.relative_to(target_dir).as_posix()
+                if not any(token in rel for token in ["context/", "node_modules/", ".git/", "__pycache__/", ".venv/", "agent."]):
+                    try:
+                        snap[rel] = p.stat().st_mtime
+                    except Exception:
+                        pass
+        return snap
+
+    last_snapshot = get_snapshot()
+
+    try:
+        while True:
+            time.sleep(1.0)
+            current_snapshot = get_snapshot()
+
+            changed = False
+            for f, mtime in current_snapshot.items():
+                if f not in last_snapshot or last_snapshot[f] != mtime:
+                    changed = True
+                    break
+
+            if not changed and set(last_snapshot.keys()) != set(current_snapshot.keys()):
+                changed = True
+
+            if changed:
+                last_snapshot = current_snapshot
+                time_str = datetime.now().strftime("%H:%M:%S")
+                console.print(f"[dim][{time_str}][/dim] [bold green]🔄 Project changed. Regenerating context files...[/bold green]")
+                execute_generation(target_dir, format_choice, max_depth=max_depth, verbose=False)
+                console.print(f"[dim][{time_str}][/dim] [bold cyan]✓ Context files updated & synced in context/![/bold cyan]")
+    except KeyboardInterrupt:
+        console.print("\n[bold yellow]👋 Stopping watch mode...[/bold yellow]")
+
+
+@app.command()
+def main(
+    path: Path = typer.Argument(
+        default=Path("."),
+        help="Target project directory to analyze.",
+        file_okay=False,
+        dir_okay=True,
+        readable=True,
+        resolve_path=True,
+    ),
+    project: Optional[Path] = typer.Option(
+        None,
+        "--project",
+        "-p",
+        help="Target project directory to analyze.",
+        file_okay=False,
+        dir_okay=True,
+        readable=True,
+        resolve_path=True,
+    ),
+    default_mode: bool = typer.Option(
+        False,
+        "--default",
+        "-d",
+        help="⚡ Zero-config default mode: generate all formats in context/ and run live auto-sync watcher.",
+    ),
+    format: OutputFormat = typer.Option(
+        OutputFormat.ALL,
+        "--format",
+        "-f",
+        help="Output format: 'all', 'md', 'json', or 'yaml'.",
+        case_sensitive=False,
+    ),
+    mcp: bool = typer.Option(
+        False,
+        "--mcp",
+        "-m",
+        help="Start MCP server mode.",
+    ),
+    interactive: bool = typer.Option(
+        False,
+        "--interactive",
+        "-i",
+        help="Run in interactive mode.",
+    ),
+    output: Optional[Path] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Custom output file path (e.g. context/agent.md or custom.json).",
+    ),
+    watch: bool = typer.Option(
+        False,
+        "--watch",
+        "-w",
+        help="Watch directory and auto-regenerate context on file changes.",
+    ),
+    max_depth: int = typer.Option(
+        3,
+        "--max-depth",
+        help="Maximum directory depth to scan.",
+        min=1,
+        max=10,
+    ),
+) -> None:
+    """
+    Scan a project, build an AST-powered dependency graph, and generate LLM context.
+    """
+    target_dir = (project or path).resolve()
+
+    # If -d / --default is supplied, generate all formats and keep watch running
+    if default_mode:
+        console.print(
+            Panel.fit(
+                f"[bold cyan]⚡ context-gen-cli (Python All-In-One Mode -d)[/bold cyan]\n"
+                f"[dim]Target:[/dim] [green]{target_dir}[/green]\n"
+                f"[dim]Mode:[/dim] [yellow]Auto-Generate All Formats + Live Background Watcher[/yellow]",
+                border_style="cyan"
+            )
+        )
+        res = execute_generation(target_dir, OutputFormat.ALL, max_depth=max_depth)
+        table = Table(show_header=False, box=None)
+        table.add_row("[bold]Scanned Files:[/bold]", f"[cyan]{len(res['files'])}[/cyan]")
+        table.add_row("[bold]AST Graph Edges:[/bold]", f"[cyan]{len(res['graph']['edges'])}[/cyan]")
+        table.add_row("[bold]Tech Stack:[/bold]", f"[green]{', '.join(res['metadata']['techStack'])}[/green]")
+        table.add_row("[bold]Generated Files:[/bold]", f"[yellow]{', '.join(f.name for f in res['generated_files'])}[/yellow]")
+        console.print(Panel(table, title="[bold green]✅ Context Generated in context/[/bold green]", border_style="green"))
+        run_watch_loop(target_dir, OutputFormat.ALL, max_depth=max_depth)
+        return
+
+    console.print(
+        Panel.fit(
+            f"[bold cyan]⚡ context-gen-cli (Python Edition)[/bold cyan]\n"
+            f"[dim]Analyzing target:[/dim] [green]{target_dir}[/green]\n"
+            f"[dim]Format:[/dim] [yellow]{format.value.upper()}[/yellow]",
+            border_style="cyan"
+        )
+    )
+
+    with console.status("[bold green]Scanning directory and parsing AST graph...[/bold green]"):
+        res = execute_generation(target_dir, format, output_override=output, max_depth=max_depth)
+
+    # Display completion summary
+    table = Table(show_header=False, box=None)
+    table.add_row("[bold]Scanned Files:[/bold]", f"[cyan]{len(res['files'])}[/cyan]")
+    table.add_row("[bold]AST Graph Edges:[/bold]", f"[cyan]{len(res['graph']['edges'])}[/cyan]")
+    table.add_row("[bold]Tech Stack:[/bold]", f"[green]{', '.join(res['metadata']['techStack'])}[/green]")
+    table.add_row("[bold]Output Destination:[/bold]", f"[yellow]{res['output_dir']}[/yellow]")
+    table.add_row("[bold]Generated Files:[/bold]", f"[green]{', '.join(f.name for f in res['generated_files'])}[/green]")
+
+    console.print(
+        Panel(
+            table,
+            title="[bold green]✅ Context Generated Successfully[/bold green]",
+            border_style="green"
+        )
+    )
+
+    if watch:
+        run_watch_loop(target_dir, format, max_depth=max_depth)
+
+
+if __name__ == "__main__":
+    app()

{context_gen_cli-1.0.0 → context_gen_cli-1.2.4}/context_gen/generator.py

@@ -151,3 +151,76 @@ def generate_agent_md(
     ])
 
     return "\n".join(lines)
+
+
+def generate_agent_yaml(
+    metadata: Dict[str, Any],
+    graph: Dict[str, Any],
+    tree: str = "",
+    project_path: str = ""
+) -> str:
+    """
+    Generates clean, structured YAML representation of the project context.
+
+    Args:
+        metadata (Dict[str, Any]): Project metadata from extractor.
+        graph (Dict[str, Any]): AST dependency graph.
+        tree (str): Visual directory tree.
+        project_path (str): Root project path.
+
+    Returns:
+        str: Formatted YAML string.
+    """
+    now_iso = datetime.now(timezone.utc).isoformat()
+    path_val = project_path or metadata.get("projectPath", "")
+    overview = metadata.get("overview", "").replace('"', '\\"')
+
+    lines: List[str] = [
+        "# Project Architecture & Context Model (YAML)",
+        "# Generated automatically by context-gen-cli (Python Edition)",
+        "version: \"1.0.0\"",
+        f"generated_at: \"{now_iso}\"",
+        f"project_path: \"{path_val}\"",
+        f"overview: \"{overview}\"",
+        "",
+        "tech_stack:",
+    ]
+
+    for tech in metadata.get("techStack", ["Python"]):
+        lines.append(f"  - \"{tech}\"")
+
+    lines.extend([
+        "",
+        "entry_points:",
+    ])
+    for ep in graph.get("entryPoints", []):
+        lines.append(f"  - \"{ep}\"")
+
+    lines.extend([
+        "",
+        "utilities:",
+    ])
+    for u in graph.get("utilities", []):
+        lines.append(f"  - \"{u}\"")
+
+    lines.extend([
+        "",
+        "key_files:",
+    ])
+    for kf in metadata.get("keyFiles", []):
+        desc = kf['description'].replace('"', '\\"')
+        lines.append(f"  - path: \"{kf['path']}\"")
+        lines.append(f"    description: \"{desc}\"")
+
+    lines.extend([
+        "",
+        "dependency_edges:",
+    ])
+    for edge in graph.get("edges", []):
+        lines.append(f"  - from: \"{edge['from']}\"")
+        lines.append(f"    to: \"{edge['to']}\"")
+        lines.append(f"    type: \"{edge.get('type', 'import')}\"")
+
+    lines.append("")
+    return "\n".join(lines)
+

context_gen_cli-1.2.4/context_gen/mcp/__init__.py

@@ -0,0 +1,3 @@
+"""
+context_gen.mcp: Model Context Protocol tools and server integrations for context-gen-cli.
+"""