filetree-cli 0.1.0__tar.gz

filetree_cli-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+.env
+.vercel

filetree_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcus
+
+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.

filetree_cli-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: filetree-cli
+Version: 0.1.0
+Summary: Generate ASCII or Markdown directory trees with smart filtering
+Project-URL: Homepage, https://github.com/marcusbuildsthings-droid/filetree
+Project-URL: Repository, https://github.com/marcusbuildsthings-droid/filetree
+Project-URL: Issues, https://github.com/marcusbuildsthings-droid/filetree/issues
+Author-email: Marcus <marcus.builds.things@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ascii,cli,directory,file,markdown,structure,tree
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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 :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Requires-Dist: click>=8.0.0
+Description-Content-Type: text/markdown
+
+# filetree
+
+Generate ASCII or Markdown directory trees with smart filtering.
+
+## Installation
+
+```bash
+pip install filetree-cli
+```
+
+## Usage
+
+```bash
+# Basic usage - current directory
+filetree
+
+# Specific path with depth limit
+filetree ~/projects -d 2
+
+# Markdown output for documentation
+filetree . --md
+
+# Ignore additional patterns
+filetree . -I "*.log" -I "tmp"
+
+# Show only directories
+filetree . -D
+
+# Show hidden files with sizes and stats
+filetree . -a --size --stats
+
+# JSON output for programmatic use
+filetree . --json
+```
+
+## Features
+
+- **Smart defaults**: Ignores common cruft (.git, node_modules, __pycache__, etc.)
+- **Depth limiting**: Control how deep the tree goes
+- **Pattern ignoring**: Glob patterns to exclude files/directories
+- **Multiple formats**: ASCII (default), Markdown, or JSON
+- **Size display**: Optional file size annotations
+- **Statistics**: File/directory counts and total size
+- **Hidden files**: Toggle visibility of dotfiles
+
+## Default Ignored Patterns
+
+These patterns are ignored by default (use `--no-default-ignore` to include them):
+
+- `.git`, `.svn`, `.hg`
+- `__pycache__`, `*.pyc`
+- `node_modules`
+- `.venv`, `venv`, `.env`
+- `*.egg-info`, `.pytest_cache`, `.mypy_cache`
+- `dist`, `build`
+- `.idea`, `.vscode`
+- `.DS_Store`
+
+## Examples
+
+### Basic Tree
+```
+$ filetree
+myproject/
+├── README.md
+├── pyproject.toml
+└── src/
+    ├── __init__.py
+    └── main.py
+```
+
+### Markdown Output
+```
+$ filetree --md
+```
+```
+myproject/
+├── README.md
+├── pyproject.toml
+└── src/
+    ├── __init__.py
+    └── main.py
+```
+
+### With Stats
+```
+$ filetree --stats --size
+myproject/
+├── README.md (1.2KB)
+├── pyproject.toml (856B)
+└── src/
+    ├── __init__.py (45B)
+    └── main.py (2.3KB)
+
+1 directories, 4 files
+Total size: 4.4KB
+```
+
+### JSON Output
+```
+$ filetree --json
+{
+  "root": "/path/to/myproject",
+  "tree": [
+    "myproject/",
+    "├── README.md",
+    "├── pyproject.toml",
+    "└── src/",
+    "    ├── __init__.py",
+    "    └── main.py"
+  ],
+  "stats": {
+    "directories": 1,
+    "files": 4,
+    "total_size": 4501,
+    "total_size_human": "4.4KB"
+  }
+}
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-d, --depth N` | Maximum depth (-1 for unlimited) |
+| `-I, --ignore PATTERN` | Patterns to ignore (repeatable) |
+| `--no-default-ignore` | Don't use default ignore patterns |
+| `-a, --all` | Show hidden files/directories |
+| `-D, --dirs-only` | Show only directories |
+| `-s, --size` | Show file sizes |
+| `--stats` | Show summary statistics |
+| `--md, --markdown` | Output as markdown code block |
+| `--json` | Output as JSON |
+| `--version` | Show version |
+
+## For AI Agents
+
+See [SKILL.md](SKILL.md) for agent-optimized documentation.
+
+## License
+
+MIT

filetree_cli-0.1.0/README.md

@@ -0,0 +1,142 @@
+# filetree
+
+Generate ASCII or Markdown directory trees with smart filtering.
+
+## Installation
+
+```bash
+pip install filetree-cli
+```
+
+## Usage
+
+```bash
+# Basic usage - current directory
+filetree
+
+# Specific path with depth limit
+filetree ~/projects -d 2
+
+# Markdown output for documentation
+filetree . --md
+
+# Ignore additional patterns
+filetree . -I "*.log" -I "tmp"
+
+# Show only directories
+filetree . -D
+
+# Show hidden files with sizes and stats
+filetree . -a --size --stats
+
+# JSON output for programmatic use
+filetree . --json
+```
+
+## Features
+
+- **Smart defaults**: Ignores common cruft (.git, node_modules, __pycache__, etc.)
+- **Depth limiting**: Control how deep the tree goes
+- **Pattern ignoring**: Glob patterns to exclude files/directories
+- **Multiple formats**: ASCII (default), Markdown, or JSON
+- **Size display**: Optional file size annotations
+- **Statistics**: File/directory counts and total size
+- **Hidden files**: Toggle visibility of dotfiles
+
+## Default Ignored Patterns
+
+These patterns are ignored by default (use `--no-default-ignore` to include them):
+
+- `.git`, `.svn`, `.hg`
+- `__pycache__`, `*.pyc`
+- `node_modules`
+- `.venv`, `venv`, `.env`
+- `*.egg-info`, `.pytest_cache`, `.mypy_cache`
+- `dist`, `build`
+- `.idea`, `.vscode`
+- `.DS_Store`
+
+## Examples
+
+### Basic Tree
+```
+$ filetree
+myproject/
+├── README.md
+├── pyproject.toml
+└── src/
+    ├── __init__.py
+    └── main.py
+```
+
+### Markdown Output
+```
+$ filetree --md
+```
+```
+myproject/
+├── README.md
+├── pyproject.toml
+└── src/
+    ├── __init__.py
+    └── main.py
+```
+
+### With Stats
+```
+$ filetree --stats --size
+myproject/
+├── README.md (1.2KB)
+├── pyproject.toml (856B)
+└── src/
+    ├── __init__.py (45B)
+    └── main.py (2.3KB)
+
+1 directories, 4 files
+Total size: 4.4KB
+```
+
+### JSON Output
+```
+$ filetree --json
+{
+  "root": "/path/to/myproject",
+  "tree": [
+    "myproject/",
+    "├── README.md",
+    "├── pyproject.toml",
+    "└── src/",
+    "    ├── __init__.py",
+    "    └── main.py"
+  ],
+  "stats": {
+    "directories": 1,
+    "files": 4,
+    "total_size": 4501,
+    "total_size_human": "4.4KB"
+  }
+}
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-d, --depth N` | Maximum depth (-1 for unlimited) |
+| `-I, --ignore PATTERN` | Patterns to ignore (repeatable) |
+| `--no-default-ignore` | Don't use default ignore patterns |
+| `-a, --all` | Show hidden files/directories |
+| `-D, --dirs-only` | Show only directories |
+| `-s, --size` | Show file sizes |
+| `--stats` | Show summary statistics |
+| `--md, --markdown` | Output as markdown code block |
+| `--json` | Output as JSON |
+| `--version` | Show version |
+
+## For AI Agents
+
+See [SKILL.md](SKILL.md) for agent-optimized documentation.
+
+## License
+
+MIT

filetree_cli-0.1.0/SKILL.md

@@ -0,0 +1,96 @@
+# filetree Skill
+
+Generate directory trees in ASCII, Markdown, or JSON format.
+
+## Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `filetree [PATH]` | Generate tree for directory |
+| `filetree -d N` | Limit depth to N levels |
+| `filetree -D` | Directories only |
+| `filetree --md` | Markdown code block output |
+| `filetree --json` | JSON output with stats |
+| `filetree --stats` | Show file/dir counts |
+
+## Common Patterns
+
+### Basic tree with depth limit
+```bash
+filetree . -d 3
+```
+
+### Documentation-ready markdown
+```bash
+filetree ~/project --md > tree.md
+```
+
+### Directories only for large projects
+```bash
+filetree . -D -d 2
+```
+
+### Full analysis with sizes
+```bash
+filetree . -a --size --stats
+```
+
+### Ignore specific patterns
+```bash
+filetree . -I "*.log" -I "tmp" -I "cache"
+```
+
+### Machine-readable JSON
+```bash
+filetree . --json
+```
+
+## JSON Output Format
+
+```json
+{
+  "root": "/absolute/path",
+  "tree": [
+    "dirname/",
+    "├── file1.txt",
+    "└── subdir/",
+    "    └── file2.txt"
+  ],
+  "stats": {
+    "directories": 1,
+    "files": 2,
+    "total_size": 1234,
+    "total_size_human": "1.2KB"
+  }
+}
+```
+
+## Default Ignored Patterns
+
+These are automatically ignored (use `--no-default-ignore` to include):
+- `.git`, `.svn`, `.hg` (version control)
+- `__pycache__`, `*.pyc` (Python cache)
+- `node_modules` (Node.js)
+- `.venv`, `venv` (virtual environments)
+- `dist`, `build` (build outputs)
+- `.idea`, `.vscode` (IDE configs)
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Path not found or not a directory |
+
+## Integration Tips
+
+1. Use `--json` for programmatic parsing
+2. Use `-D -d 2` for quick project overview
+3. Combine `--md` with documentation generators
+4. Add custom `-I` patterns for project-specific cruft
+
+## Installation
+
+```bash
+pip install filetree-cli
+```

filetree_cli-0.1.0/filetree/__init__.py

@@ -0,0 +1,3 @@
+"""filetree - Generate ASCII or Markdown directory trees."""
+
+__version__ = "0.1.0"

filetree_cli-0.1.0/filetree/cli.py

@@ -0,0 +1,271 @@
+"""CLI for filetree - directory tree generator."""
+
+import json
+import os
+import sys
+from fnmatch import fnmatch
+from pathlib import Path
+from typing import List, Optional, Set, Tuple
+
+import click
+
+from . import __version__
+
+# Default patterns to ignore
+DEFAULT_IGNORES = [
+    ".git",
+    ".svn",
+    ".hg",
+    "__pycache__",
+    "*.pyc",
+    ".DS_Store",
+    "node_modules",
+    ".venv",
+    "venv",
+    ".env",
+    "*.egg-info",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".tox",
+    "dist",
+    "build",
+    ".idea",
+    ".vscode",
+]
+
+# Tree characters
+TREE_BRANCH = "├── "
+TREE_LAST = "└── "
+TREE_PIPE = "│   "
+TREE_SPACE = "    "
+
+
+def should_ignore(name: str, path: Path, patterns: List[str]) -> bool:
+    """Check if a file/dir should be ignored based on patterns."""
+    for pattern in patterns:
+        if fnmatch(name, pattern):
+            return True
+        # Also check full path for patterns with /
+        if "/" in pattern and fnmatch(str(path), pattern):
+            return True
+    return True if name.startswith(".") and ".*" in patterns else False
+
+
+def get_size(path: Path) -> int:
+    """Get file size, 0 for directories."""
+    try:
+        if path.is_file():
+            return path.stat().st_size
+        return 0
+    except (OSError, PermissionError):
+        return 0
+
+
+def format_size(size: int) -> str:
+    """Format bytes to human readable."""
+    for unit in ["B", "KB", "MB", "GB", "TB"]:
+        if size < 1024:
+            return f"{size:.1f}{unit}" if unit != "B" else f"{size}{unit}"
+        size /= 1024
+    return f"{size:.1f}PB"
+
+
+def generate_tree(
+    root: Path,
+    prefix: str = "",
+    depth: int = -1,
+    current_depth: int = 0,
+    ignore_patterns: List[str] = None,
+    dirs_only: bool = False,
+    show_hidden: bool = False,
+    show_size: bool = False,
+    stats: dict = None,
+) -> List[str]:
+    """Generate tree lines for a directory."""
+    if ignore_patterns is None:
+        ignore_patterns = []
+    
+    if stats is None:
+        stats = {"dirs": 0, "files": 0, "size": 0}
+    
+    lines = []
+    
+    # Check depth limit
+    if depth >= 0 and current_depth >= depth:
+        return lines
+    
+    try:
+        entries = sorted(root.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower()))
+    except PermissionError:
+        return lines
+    
+    # Filter entries
+    filtered = []
+    for entry in entries:
+        name = entry.name
+        
+        # Skip hidden unless requested
+        if not show_hidden and name.startswith("."):
+            continue
+        
+        # Skip ignored patterns
+        skip = False
+        for pattern in ignore_patterns:
+            if fnmatch(name, pattern):
+                skip = True
+                break
+        if skip:
+            continue
+        
+        # Skip files if dirs_only
+        if dirs_only and entry.is_file():
+            continue
+        
+        filtered.append(entry)
+    
+    # Generate tree lines
+    for i, entry in enumerate(filtered):
+        is_last = i == len(filtered) - 1
+        connector = TREE_LAST if is_last else TREE_BRANCH
+        
+        # Build the line
+        line = prefix + connector + entry.name
+        
+        if entry.is_dir():
+            line += "/"
+            stats["dirs"] += 1
+        else:
+            stats["files"] += 1
+            size = get_size(entry)
+            stats["size"] += size
+            if show_size:
+                line += f" ({format_size(size)})"
+        
+        lines.append(line)
+        
+        # Recurse into directories
+        if entry.is_dir():
+            extension = TREE_SPACE if is_last else TREE_PIPE
+            lines.extend(
+                generate_tree(
+                    entry,
+                    prefix=prefix + extension,
+                    depth=depth,
+                    current_depth=current_depth + 1,
+                    ignore_patterns=ignore_patterns,
+                    dirs_only=dirs_only,
+                    show_hidden=show_hidden,
+                    show_size=show_size,
+                    stats=stats,
+                )
+            )
+    
+    return lines
+
+
+def tree_to_markdown(root_name: str, lines: List[str]) -> str:
+    """Convert tree lines to markdown code block."""
+    output = f"```\n{root_name}/\n"
+    output += "\n".join(lines)
+    output += "\n```"
+    return output
+
+
+def tree_to_json(root: Path, lines: List[str], stats: dict) -> dict:
+    """Convert tree to JSON structure."""
+    return {
+        "root": str(root.absolute()),
+        "tree": [root.name + "/"] + lines,
+        "stats": {
+            "directories": stats["dirs"],
+            "files": stats["files"],
+            "total_size": stats["size"],
+            "total_size_human": format_size(stats["size"]),
+        },
+    }
+
+
+@click.command()
+@click.argument("path", default=".", type=click.Path(exists=True))
+@click.option("-d", "--depth", default=-1, type=int, help="Maximum depth (-1 for unlimited)")
+@click.option("-I", "--ignore", "ignores", multiple=True, help="Patterns to ignore (can repeat)")
+@click.option("--no-default-ignore", is_flag=True, help="Don't use default ignore patterns")
+@click.option("-a", "--all", "show_hidden", is_flag=True, help="Show hidden files/dirs")
+@click.option("-D", "--dirs-only", is_flag=True, help="Show only directories")
+@click.option("-s", "--size", "show_size", is_flag=True, help="Show file sizes")
+@click.option("--stats", "show_stats", is_flag=True, help="Show summary statistics")
+@click.option("--md", "--markdown", "markdown", is_flag=True, help="Output as markdown code block")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+@click.option("--version", is_flag=True, help="Show version")
+def main(
+    path: str,
+    depth: int,
+    ignores: Tuple[str, ...],
+    no_default_ignore: bool,
+    show_hidden: bool,
+    dirs_only: bool,
+    show_size: bool,
+    show_stats: bool,
+    markdown: bool,
+    as_json: bool,
+    version: bool,
+):
+    """Generate directory tree for PATH.
+    
+    Examples:
+    
+      filetree                      # Current directory
+      filetree ~/projects -d 2      # Max depth 2
+      filetree . --md               # Markdown output
+      filetree . -I "*.log" -I tmp  # Ignore patterns
+      filetree . -D                 # Directories only
+      filetree . -a --size --stats  # Show all with sizes and stats
+    """
+    if version:
+        click.echo(f"filetree {__version__}")
+        return
+    
+    root = Path(path).resolve()
+    
+    if not root.is_dir():
+        click.echo(f"Error: {path} is not a directory", err=True)
+        sys.exit(1)
+    
+    # Build ignore patterns
+    ignore_patterns = []
+    if not no_default_ignore:
+        ignore_patterns.extend(DEFAULT_IGNORES)
+    ignore_patterns.extend(ignores)
+    
+    # Generate tree
+    stats = {"dirs": 0, "files": 0, "size": 0}
+    lines = generate_tree(
+        root,
+        depth=depth,
+        ignore_patterns=ignore_patterns,
+        dirs_only=dirs_only,
+        show_hidden=show_hidden,
+        show_size=show_size,
+        stats=stats,
+    )
+    
+    # Output
+    if as_json:
+        output = tree_to_json(root, lines, stats)
+        click.echo(json.dumps(output, indent=2))
+    elif markdown:
+        click.echo(tree_to_markdown(root.name, lines))
+    else:
+        click.echo(f"{root.name}/")
+        click.echo("\n".join(lines))
+        
+        if show_stats:
+            click.echo()
+            click.echo(f"{stats['dirs']} directories, {stats['files']} files")
+            if stats["size"] > 0:
+                click.echo(f"Total size: {format_size(stats['size'])}")
+
+
+if __name__ == "__main__":
+    main()

filetree_cli-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "filetree-cli"
+version = "0.1.0"
+description = "Generate ASCII or Markdown directory trees with smart filtering"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [
+    { name = "Marcus", email = "marcus.builds.things@gmail.com" }
+]
+keywords = ["directory", "tree", "cli", "file", "structure", "ascii", "markdown"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+    "click>=8.0.0",
+]
+
+[project.scripts]
+filetree = "filetree.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/marcusbuildsthings-droid/filetree"
+Repository = "https://github.com/marcusbuildsthings-droid/filetree"
+Issues = "https://github.com/marcusbuildsthings-droid/filetree/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["filetree"]