Adding new CLIs

Author: joaopauloschuler

docs/CLI.md

@@ -236,6 +236,247 @@ Priority (highest to lowest):
 3. Config file (`~/.bpsa.yaml`)
 4. Built-in defaults
 
+## Utility CLIs
+
+Beyond the main `bpsa` REPL, the project ships lightweight CLI wrappers around commonly used tools from `bp_tools.py`. All are installed automatically via `pip install` and support `--help`.
+
+### Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `bptree` | Directory tree with line counts and optional function signatures |
+| `bpgrep` | Search for text patterns in files with extension filtering |
+| `bppack` | Pack a folder's source code into a single tagged string |
+| `bpunpack` | Reconstruct source files from a packed string |
+| `bploc` | Lines-of-code summary broken down by file type |
+| `bpdiff` | Compare two files or two folders (unified diff) |
+| `bpsig` | Extract function/class signatures from a source file |
+| `bppas` | Extract Pascal unit interface sections from a folder |
+
+Entry points in `pyproject.toml`:
+```toml
+[project.scripts]
+bptree  = "smolagents.bp_tree_cli:main"
+bpgrep  = "smolagents.bp_grep_cli:main"
+bppack  = "smolagents.bp_pack_cli:main"
+bpunpack = "smolagents.bp_unpack_cli:main"
+bploc   = "smolagents.bp_loc_cli:main"
+bpdiff  = "smolagents.bp_diff_cli:main"
+bpsig   = "smolagents.bp_sig_cli:main"
+bppas   = "smolagents.bp_pas_cli:main"
+```
+
+---
+
+### `bptree` — Directory Tree
+
+Displays a tree view of a directory with source-file line counts and optional function signatures. Skips common build/artifact folders by default.
+
+```bash
+bptree [FOLDER] [-d DEPTH] [--no-files] [-s] [--skip-dirs DIRS]
+```
+
+| Flag | Description |
+|------|-------------|
+| `FOLDER` | Root folder (default: `.`) |
+| `-d`, `--depth N` | Max depth to traverse (default: 6) |
+| `--no-files` | Show only directories, hide files |
+| `-s`, `--signatures` | Show function/class signatures inline |
+| `--skip-dirs d1,d2` | Comma-separated dirs to show but not traverse |
+
+```bash
+# Basic tree of src/ with depth 2
+bptree src/ -d 2
+
+# Tree with function signatures
+bptree . -s
+
+# Directories only, skip vendor
+bptree . --no-files --skip-dirs vendor,tmp
+```
+
+---
+
+### `bpgrep` — Search in Files
+
+Searches for a text pattern in files within a folder (or a single file). Returns matching lines with file paths and line numbers.
+
+```bash
+bpgrep PATTERN [PATH] [-e EXTS] [-c] [-m MAX]
+```
+
+| Flag | Description |
+|------|-------------|
+| `PATTERN` | Text pattern to search for |
+| `PATH` | Folder or file to search (default: `.`) |
+| `-e`, `--extensions` | Comma-separated extensions to filter (e.g. `py,js,ts`) |
+| `-c`, `--case-sensitive` | Case-sensitive search (default: case-insensitive) |
+| `-m`, `--max-results N` | Maximum results to return (default: 50) |
+
+```bash
+# Search for "def main" in Python files
+bpgrep "def main" src/ -e py
+
+# Case-sensitive search with limit
+bpgrep "TODO" . -c -m 20
+```
+
+---
+
+### `bppack` — Pack Source Code
+
+Packs all source files in a folder into a single string with `<file filename="...">...</file>` XML-like tags. Useful for feeding entire projects to LLMs or creating context dumps.
+
+```bash
+bppack FOLDER [-e EXTS] [--strip-pascal-comments] [--exclude ITEMS] [-o FILE]
+```
+
+| Flag | Description |
+|------|-------------|
+| `FOLDER` | Root folder to scan |
+| `-e`, `--extensions` | Comma-separated extensions to include (default: common source extensions) |
+| `--strip-pascal-comments` | Remove Pascal comments from `.pas`/`.inc` files |
+| `--exclude` | Comma-separated files/folders to exclude |
+| `-o`, `--output FILE` | Write to a file instead of stdout |
+
+```bash
+# Pack src/ to a file
+bppack src/ -o context.txt
+
+# Pack only Python and JS files
+bppack . -e py,js --exclude __pycache__,node_modules
+```
+
+---
+
+### `bpunpack` — Unpack Source Code
+
+Reconstructs source files from a packed string produced by `bppack`. Reads from a file or stdin.
+
+```bash
+bpunpack [INPUT] [-o DIR] [--no-overwrite] [-q]
+```
+
+| Flag | Description |
+|------|-------------|
+| `INPUT` | Packed file to read (default: stdin) |
+| `-o`, `--output-dir DIR` | Base directory to write into (default: `.`) |
+| `--no-overwrite` | Skip files that already exist |
+| `-q`, `--quiet` | Suppress status messages |
+
+```bash
+# Unpack from file into output/
+bpunpack context.txt -o output/
+
+# Pipe from bppack
+bppack src/ | bpunpack -o copy/
+
+# Unpack without overwriting existing files
+bpunpack context.txt --no-overwrite
+```
+
+---
+
+### `bploc` — Lines of Code
+
+Counts lines of code broken down by file extension. Skips hidden files and directories.
+
+```bash
+bploc [FOLDER] [-e EXTS]
+```
+
+| Flag | Description |
+|------|-------------|
+| `FOLDER` | Root folder to analyze (default: `.`) |
+| `-e`, `--extensions` | Comma-separated extensions to count (default: `py,js,java,cpp,c,php,rb`) |
+
+```bash
+# Count lines in current project
+bploc
+
+# Count only Python and TypeScript
+bploc src/ -e py,ts
+```
+
+Example output:
+```
+  .py     23985 lines
+  total   23985 lines
+```
+
+---
+
+### `bpdiff` — Compare Files or Folders
+
+Compares two files or two folders and shows differences in unified diff format. For folders, only source code files are compared.
+
+```bash
+bpdiff PATH1 PATH2 [-c CONTEXT]
+```
+
+| Flag | Description |
+|------|-------------|
+| `PATH1` | First file or folder |
+| `PATH2` | Second file or folder |
+| `-c`, `--context N` | Context lines around differences (default: 3) |
+
+```bash
+# Compare two files
+bpdiff old_version.py new_version.py
+
+# Compare two folders with more context
+bpdiff project_v1/ project_v2/ -c 5
+```
+
+---
+
+### `bpsig` — Function Signatures
+
+Extracts function and class signatures from a source file without showing the implementation. Supports Python, JavaScript/TypeScript, Java, PHP, Pascal, C/C++, Markdown (section headers), and a generic fallback.
+
+```bash
+bpsig FILE [-l LANGUAGE]
+```
+
+| Flag | Description |
+|------|-------------|
+| `FILE` | Source file to extract signatures from |
+| `-l`, `--language` | Programming language (auto-detected from extension if omitted) |
+
+```bash
+# Auto-detect language
+bpsig src/main.py
+
+# Explicit language
+bpsig utils.inc -l pascal
+```
+
+---
+
+### `bppas` — Pascal Interfaces
+
+Extracts the interface sections (between `interface` and `implementation` keywords) from Pascal source files in a folder. Output uses `<pascal_interface filename="...">` tags.
+
+```bash
+bppas FOLDER [--strip-comments] [-o FILE]
+```
+
+| Flag | Description |
+|------|-------------|
+| `FOLDER` | Root folder to scan for `.pas`, `.inc`, `.pp`, `.lpr`, `.dpr` files |
+| `--strip-comments` | Remove Pascal comments from extracted interfaces |
+| `-o`, `--output FILE` | Write to a file instead of stdout |
+
+```bash
+# Extract interfaces
+bppas pascal_src/
+
+# Strip comments and save to file
+bppas lib/ --strip-comments -o interfaces.txt
+```
+
+---
+
 ## Dependencies
 
 - `prompt_toolkit` - REPL input handling (optional, falls back to basic `input()`)

pyproject.toml

@@ -165,5 +165,12 @@ lines-after-imports = 2
 smolagent = "smolagents.cli:main"
 bpsa = "smolagents.bp_cli:main"
 bptree = "smolagents.bp_tree_cli:main"
+bpgrep = "smolagents.bp_grep_cli:main"
+bppack = "smolagents.bp_pack_cli:main"
+bpunpack = "smolagents.bp_unpack_cli:main"
+bploc = "smolagents.bp_loc_cli:main"
+bpdiff = "smolagents.bp_diff_cli:main"
+bpsig = "smolagents.bp_sig_cli:main"
+bppas = "smolagents.bp_pas_cli:main"
 webagent = "smolagents.vision_web_browser:main"
 ad-infinitum = "smolagents.bp_ad_infinitum:main"

src/smolagents/bp_diff_cli.py

@@ -0,0 +1,36 @@
+"""CLI wrapper for compare_files and compare_folders."""
+
+import argparse
+import os
+
+from smolagents.bp_tools import compare_files, compare_folders
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="bpdiff",
+        description="Compare two files or two folders and show differences in unified diff format.",
+    )
+    parser.add_argument("path1", help="first file or folder")
+    parser.add_argument("path2", help="second file or folder")
+    parser.add_argument(
+        "-c", "--context",
+        type=int,
+        default=3,
+        help="number of context lines around differences (default: 3)",
+    )
+
+    args = parser.parse_args()
+
+    if os.path.isfile(args.path1) and os.path.isfile(args.path2):
+        result = compare_files(args.path1, args.path2, context_lines=args.context)
+    elif os.path.isdir(args.path1) and os.path.isdir(args.path2):
+        result = compare_folders(args.path1, args.path2, context_lines=args.context)
+    else:
+        result = "Error: both paths must be files or both must be directories"
+
+    print(result)
+
+
+if __name__ == "__main__":
+    main()

src/smolagents/bp_grep_cli.py

@@ -0,0 +1,51 @@
+"""CLI wrapper for search_in_files."""
+
+import argparse
+
+from smolagents.bp_tools import search_in_files
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="bpgrep",
+        description="Search for a text pattern in files within a folder or a single file.",
+    )
+    parser.add_argument("pattern", help="text pattern to search for")
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="folder or file to search in (default: current directory)",
+    )
+    parser.add_argument(
+        "-e", "--extensions",
+        type=lambda s: tuple(ext if ext.startswith(".") else f".{ext}" for ext in s.split(",")),
+        default=None,
+        help="comma-separated file extensions to search (e.g. py,js,ts)",
+    )
+    parser.add_argument(
+        "-c", "--case-sensitive",
+        action="store_true",
+        help="make the search case-sensitive (default: case-insensitive)",
+    )
+    parser.add_argument(
+        "-m", "--max-results",
+        type=int,
+        default=50,
+        help="maximum number of results (default: 50)",
+    )
+
+    args = parser.parse_args()
+
+    result = search_in_files(
+        folder_path=args.path,
+        search_pattern=args.pattern,
+        file_extensions=args.extensions,
+        case_sensitive=args.case_sensitive,
+        max_results=args.max_results,
+    )
+    print(result)
+
+
+if __name__ == "__main__":
+    main()