trls-cli 0.2.0__py3-none-any.whl

trls/__init__.py

@@ -0,0 +1,23 @@
+from trls.renderers import (
+    build_rich_tree,
+    render_compact_copy,
+    render_json,
+    render_markdown,
+    render_prompt,
+    render_text,
+)
+from trls.tree import TreeNode, scan_tree
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "TreeNode",
+    "__version__",
+    "build_rich_tree",
+    "render_compact_copy",
+    "render_json",
+    "render_markdown",
+    "render_prompt",
+    "render_text",
+    "scan_tree",
+]

trls/__main__.py

@@ -0,0 +1,5 @@
+from trls.cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

trls/cli.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from rich.console import Console
+
+from trls import __version__
+from trls.clipboard import copy_text
+from trls.renderers import (
+    build_rich_tree,
+    render_compact_copy,
+    render_json,
+    render_markdown,
+    render_prompt,
+    render_text,
+)
+from trls.snapshot import load_last_snapshot, load_snapshot, save_last_snapshot
+from trls.tree import DEFAULT_IGNORE_PATTERNS, diff_trees, scan_tree
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="trls",
+        description="Render directory trees for humans and LLMs.",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        default=".",
+        help="Directory to scan. Defaults to the current directory.",
+    )
+    parser.add_argument(
+        "--depth",
+        type=int,
+        default=None,
+        help="Maximum directory depth to include.",
+    )
+    parser.add_argument(
+        "--hidden",
+        action="store_true",
+        help="Include hidden files and directories.",
+    )
+    parser.add_argument(
+        "--ignore",
+        action="append",
+        default=[],
+        metavar="PATTERN",
+        help=(
+            "Add an extra ignore name or glob pattern. Repeat for multiple "
+            f"patterns. Defaults also ignore: {', '.join(DEFAULT_IGNORE_PATTERNS)}."
+        ),
+    )
+    parser.add_argument(
+        "--format",
+        choices=("prompt", "rich", "text", "markdown", "json"),
+        default="rich",
+        help="Output format. Defaults to rich.",
+    )
+    parser.add_argument(
+        "-diff",
+        "--diff-last",
+        action="store_true",
+        help="Compare the current tree with the previous snapshot for this path.",
+    )
+    parser.add_argument(
+        "-compare",
+        "--compare-with",
+        metavar="SNAPSHOT",
+        help="Compare the current tree with an explicit snapshot file.",
+    )
+    parser.add_argument(
+        "-save",
+        "--save-snapshot",
+        action="store_true",
+        help="Save the current tree as the snapshot baseline for this path without diffing.",
+    )
+    parser.add_argument(
+        "-update",
+        "--update-snapshot",
+        action="store_true",
+        help="After diffing, replace the saved snapshot baseline with the current tree.",
+    )
+    parser.add_argument(
+        "-c",
+        "--copy",
+        action="store_true",
+        help="Copy a compact LLM-friendly version to the clipboard after rendering.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"trls {__version__}",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.depth is not None and args.depth < 0:
+        parser.error("--depth must be greater than or equal to 0")
+    if args.diff_last and args.compare_with:
+        parser.error("Use either --diff-last or --compare-with, not both")
+    if args.save_snapshot and (args.diff_last or args.compare_with):
+        parser.error(
+            "--save-snapshot cannot be combined with diff flags; use --update-snapshot "
+            "after diffing instead"
+        )
+    if args.update_snapshot and not (args.diff_last or args.compare_with):
+        parser.error("--update-snapshot requires -diff/--diff-last or -compare/--compare-with")
+
+    root_path = Path(args.path).expanduser().resolve()
+    needs_fingerprints = True
+
+    current_tree = scan_tree(
+        root_path,
+        max_depth=args.depth,
+        show_hidden=args.hidden,
+        ignore_patterns=args.ignore,
+        include_fingerprints=needs_fingerprints,
+    )
+    output_tree = current_tree
+
+    if args.save_snapshot:
+        output_tree = current_tree
+    elif args.compare_with:
+        try:
+            output_tree = diff_trees(current_tree, load_snapshot(args.compare_with))
+        except FileNotFoundError as exc:
+            parser.error(str(exc))
+    else:
+        try:
+            output_tree = diff_trees(current_tree, load_last_snapshot(root_path))
+        except FileNotFoundError:
+            output_tree = current_tree
+
+    if args.format == "rich":
+        Console().print(build_rich_tree(output_tree))
+    elif args.format == "prompt":
+        print(render_prompt(output_tree))
+    elif args.format == "text":
+        print(render_text(output_tree))
+    elif args.format == "markdown":
+        print(render_markdown(output_tree))
+    else:
+        print(render_json(output_tree))
+
+    save_last_snapshot(root_path, current_tree)
+
+    if args.copy:
+        try:
+            copy_text(render_compact_copy(output_tree))
+        except RuntimeError as exc:
+            print(f"Failed to copy to clipboard: {exc}", file=sys.stderr)
+            return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

trls/clipboard.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+
+
+def copy_text(text: str) -> None:
+    system = platform.system()
+    if system == "Windows":
+        _run_clipboard_command(["clip"], text)
+        return
+    if system == "Darwin":
+        _run_clipboard_command(["pbcopy"], text)
+        return
+    if shutil.which("wl-copy"):
+        _run_clipboard_command(["wl-copy"], text)
+        return
+    if shutil.which("xclip"):
+        _run_clipboard_command(["xclip", "-selection", "clipboard"], text)
+        return
+    if shutil.which("xsel"):
+        _run_clipboard_command(["xsel", "--clipboard", "--input"], text)
+        return
+
+    raise RuntimeError("No supported clipboard command was found on this system.")
+
+
+def _run_clipboard_command(command: list[str], text: str) -> None:
+    try:
+        subprocess.run(
+            command,
+            input=text,
+            text=True,
+            check=True,
+            capture_output=True,
+        )
+    except FileNotFoundError as exc:
+        raise RuntimeError(f"Clipboard command not found: {command[0]}") from exc
+    except subprocess.CalledProcessError as exc:
+        stderr = exc.stderr.strip() if exc.stderr else "unknown clipboard error"
+        raise RuntimeError(f"Clipboard command failed: {stderr}") from exc

trls/renderers.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from rich.text import Text
+from rich.tree import Tree as RichTree
+
+from trls.tree import TreeNode
+
+DIRECTORY_STYLE = "bold cyan"
+DEFAULT_FILE_STYLE = "white"
+
+FILE_STYLES = {
+    ".py": "green",
+    ".md": "magenta",
+    ".rst": "magenta",
+    ".txt": "white",
+    ".toml": "yellow",
+    ".yaml": "yellow",
+    ".yml": "yellow",
+    ".json": "yellow",
+    ".ini": "yellow",
+    ".cfg": "yellow",
+    ".lock": "yellow",
+    ".sh": "bright_green",
+    ".ps1": "bright_green",
+    ".bat": "bright_green",
+    ".exe": "bright_red",
+    ".whl": "bright_red",
+    ".tar": "bright_red",
+    ".gz": "bright_red",
+    ".zip": "bright_red",
+}
+
+SPECIAL_FILE_STYLES = {
+    "license": "bright_white",
+    "readme.md": "bright_magenta",
+    "pyproject.toml": "bright_yellow",
+}
+DIFF_MARKERS = {
+    "added": "+ ",
+    "removed": "- ",
+    "modified": "~ ",
+    "unchanged": "",
+    None: "",
+}
+DIFF_STYLES = {
+    "added": "green",
+    "removed": "red",
+    "modified": "yellow",
+    "unchanged": "",
+    None: "",
+}
+
+
+def build_rich_tree(node: TreeNode) -> RichTree:
+    label = _rich_label(node)
+    tree = RichTree(label, guide_style="bright_black")
+    for child in node.children:
+        _append_rich_branch(tree, child)
+    return tree
+
+
+def render_text(node: TreeNode) -> str:
+    lines = [f"{_diff_marker(node)}{node.display_name}"]
+    lines.extend(_render_text_children(node.children, prefix=""))
+    return "\n".join(lines)
+
+
+def render_prompt(node: TreeNode) -> str:
+    lines: list[str] = []
+    _append_prompt_lines(node, lines, depth=0)
+    return "\n".join(lines)
+
+
+def render_compact_copy(node: TreeNode) -> str:
+    lines = [node.display_name]
+    for child in node.children:
+        _append_compact_copy_lines(child, lines, prefix=node.display_name)
+    return "\n".join(lines)
+
+
+def render_markdown(node: TreeNode) -> str:
+    lines: list[str] = []
+    _append_markdown_lines(node, lines, depth=0)
+    return "\n".join(lines)
+
+
+def render_json(node: TreeNode) -> str:
+    return json.dumps(node.to_dict(), indent=2)
+
+
+def _append_rich_branch(branch: RichTree, node: TreeNode) -> None:
+    child_branch = branch.add(_rich_label(node))
+    for child in node.children:
+        _append_rich_branch(child_branch, child)
+
+
+def _rich_label(node: TreeNode) -> Text:
+    label = Text()
+    marker = _diff_marker(node)
+    if marker:
+        label.append(marker, style=DIFF_STYLES[node.diff_status])
+
+    if node.is_dir:
+        label.append(node.display_name, style=DIRECTORY_STYLE)
+    else:
+        label.append(node.name, style=_style_for_file(node.name))
+
+    if node.error:
+        label.append(f" [unreadable: {node.error}]", style="red")
+
+    return label
+
+
+def _style_for_file(name: str) -> str:
+    normalized_name = name.lower()
+    if normalized_name in SPECIAL_FILE_STYLES:
+        return SPECIAL_FILE_STYLES[normalized_name]
+
+    suffixes = Path(normalized_name).suffixes
+    for suffix in reversed(suffixes):
+        if suffix in FILE_STYLES:
+            return FILE_STYLES[suffix]
+
+    return DEFAULT_FILE_STYLE
+
+
+def _append_prompt_lines(node: TreeNode, lines: list[str], depth: int) -> None:
+    indent = "  " * depth
+    line = f"{indent}{_diff_marker(node)}[{_prompt_tag(node)}] {node.display_name}"
+    if node.error:
+        line = f"{line} (unreadable: {node.error})"
+    lines.append(line)
+
+    for child in node.children:
+        _append_prompt_lines(child, lines, depth + 1)
+
+
+def _append_compact_copy_lines(node: TreeNode, lines: list[str], prefix: str) -> None:
+    marker = _diff_marker(node)
+    full_path = f"{prefix}{node.name}/" if node.is_dir else f"{prefix}{node.name}"
+    lines.append(f"{marker}{full_path}")
+
+    child_prefix = f"{full_path}" if node.is_dir else prefix
+    for child in node.children:
+        _append_compact_copy_lines(child, lines, child_prefix)
+
+
+def _prompt_tag(node: TreeNode) -> str:
+    if node.is_dir:
+        return "dir"
+
+    normalized_name = node.name.lower()
+    if normalized_name == "license":
+        return "license"
+    if normalized_name == "pyproject.toml":
+        return "meta"
+    if normalized_name == "readme.md":
+        return "doc"
+
+    suffixes = Path(normalized_name).suffixes
+    for suffix in reversed(suffixes):
+        if suffix == ".py":
+            return "py"
+        if suffix in {".md", ".rst", ".txt"}:
+            return "doc"
+        if suffix in {".toml", ".yaml", ".yml", ".json", ".ini", ".cfg", ".lock"}:
+            return "meta"
+        if suffix in {".sh", ".ps1", ".bat"}:
+            return "shell"
+        if suffix in {".exe", ".whl", ".tar", ".gz", ".zip"}:
+            return "archive"
+
+    return "file"
+
+
+def _render_text_children(children: list[TreeNode], prefix: str) -> list[str]:
+    lines: list[str] = []
+
+    for index, child in enumerate(children):
+        is_last = index == len(children) - 1
+        connector = "`-- " if is_last else "|-- "
+        lines.append(f"{prefix}{connector}{_diff_marker(child)}{child.display_name}")
+
+        if child.error:
+            error_prefix = "    " if is_last else "|   "
+            lines.append(f"{prefix}{error_prefix}[unreadable: {child.error}]")
+
+        child_prefix = f"{prefix}{'    ' if is_last else '|   '}"
+        lines.extend(_render_text_children(child.children, child_prefix))
+
+    return lines
+
+
+def _append_markdown_lines(node: TreeNode, lines: list[str], depth: int) -> None:
+    indent = "  " * depth
+    marker = _diff_marker(node).strip()
+    prefix = f"{marker} " if marker else ""
+    line = f"{indent}- {prefix}`{node.display_name}`"
+    if node.error:
+        line = f"{line} _(unreadable: {node.error})_"
+    lines.append(line)
+
+    for child in node.children:
+        _append_markdown_lines(child, lines, depth + 1)
+
+
+def _diff_marker(node: TreeNode) -> str:
+    return DIFF_MARKERS[node.diff_status]

trls/snapshot.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from trls.tree import TreeNode
+
+SNAPSHOT_VERSION = 1
+SNAPSHOT_DIR_ENV = "TRLS_SNAPSHOT_DIR"
+
+
+def default_snapshot_path(root: str | Path) -> Path:
+    root_path = Path(root).expanduser().resolve()
+    normalized_root = root_path.as_posix().lower()
+    key = hashlib.sha256(normalized_root.encode("utf-8")).hexdigest()[:16]
+    return snapshot_storage_dir() / f"{key}.json"
+
+
+def snapshot_storage_dir() -> Path:
+    configured_dir = os.environ.get(SNAPSHOT_DIR_ENV)
+    if configured_dir:
+        return Path(configured_dir).expanduser().resolve()
+    return Path.home() / ".trls" / "snapshots"
+
+
+def save_snapshot(snapshot_path: str | Path, root: str | Path, tree: TreeNode) -> Path:
+    destination = Path(snapshot_path).expanduser().resolve()
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    root_path = Path(root).expanduser().resolve()
+    payload = {
+        "snapshot_version": SNAPSHOT_VERSION,
+        "root_path": str(root_path),
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "tree": tree.to_dict(include_fingerprint=True),
+    }
+    destination.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    return destination
+
+
+def save_last_snapshot(root: str | Path, tree: TreeNode) -> Path:
+    return save_snapshot(default_snapshot_path(root), root, tree)
+
+
+def load_snapshot(snapshot_path: str | Path) -> TreeNode:
+    path = Path(snapshot_path).expanduser().resolve()
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return TreeNode.from_dict(payload["tree"])
+
+
+def load_last_snapshot(root: str | Path) -> TreeNode:
+    snapshot_path = default_snapshot_path(root)
+    if not snapshot_path.exists():
+        raise FileNotFoundError(
+            f"No saved snapshot for {Path(root).expanduser().resolve()}. "
+            "Run trls with --save-snapshot first."
+        )
+    return load_snapshot(snapshot_path)

trls/tree.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from fnmatch import fnmatch
+from pathlib import Path
+from typing import Any, Literal
+
+DEFAULT_IGNORE_PATTERNS = (".venv", "dist", "__pycache__")
+DiffStatus = Literal["added", "removed", "modified", "unchanged"]
+
+
+@dataclass
+class TreeNode:
+    name: str
+    path: str
+    kind: str
+    children: list["TreeNode"] = field(default_factory=list)
+    error: str | None = None
+    size: int | None = None
+    sha256: str | None = None
+    diff_status: DiffStatus | None = None
+
+    @property
+    def is_dir(self) -> bool:
+        return self.kind == "directory"
+
+    @property
+    def display_name(self) -> str:
+        return f"{self.name}/" if self.is_dir else self.name
+
+    def to_dict(self, *, include_fingerprint: bool = False) -> dict[str, object]:
+        payload: dict[str, object] = {
+            "name": self.name,
+            "path": self.path,
+            "kind": self.kind,
+        }
+        if self.error:
+            payload["error"] = self.error
+        if self.diff_status:
+            payload["diff_status"] = self.diff_status
+        if include_fingerprint and not self.is_dir:
+            if self.size is not None:
+                payload["size"] = self.size
+            if self.sha256 is not None:
+                payload["sha256"] = self.sha256
+        if self.children:
+            payload["children"] = [
+                child.to_dict(include_fingerprint=include_fingerprint)
+                for child in self.children
+            ]
+        return payload
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any]) -> "TreeNode":
+        return cls(
+            name=payload["name"],
+            path=payload["path"],
+            kind=payload["kind"],
+            children=[cls.from_dict(child) for child in payload.get("children", [])],
+            error=payload.get("error"),
+            size=payload.get("size"),
+            sha256=payload.get("sha256"),
+            diff_status=payload.get("diff_status"),
+        )
+
+
+def scan_tree(
+    root: str | Path = ".",
+    *,
+    max_depth: int | None = None,
+    show_hidden: bool = False,
+    ignore_patterns: list[str] | None = None,
+    include_fingerprints: bool = False,
+) -> TreeNode:
+    root_path = Path(root).expanduser().resolve()
+    if not root_path.exists():
+        raise FileNotFoundError(f"Path does not exist: {root}")
+
+    patterns = (*DEFAULT_IGNORE_PATTERNS, *(ignore_patterns or []))
+    return _scan_path(
+        path=root_path,
+        root=root_path,
+        depth=0,
+        max_depth=max_depth,
+        show_hidden=show_hidden,
+        ignore_patterns=patterns,
+        include_fingerprints=include_fingerprints,
+    )
+
+
+def _scan_path(
+    *,
+    path: Path,
+    root: Path,
+    depth: int,
+    max_depth: int | None,
+    show_hidden: bool,
+    ignore_patterns: tuple[str, ...],
+    include_fingerprints: bool,
+) -> TreeNode:
+    kind = "directory" if path.is_dir() else "file"
+    node = TreeNode(name=path.name or str(path), path=str(path), kind=kind)
+
+    if not path.is_dir():
+        if include_fingerprints:
+            node.size = path.stat().st_size
+            node.sha256 = _sha256_for_file(path)
+        return node
+
+    if max_depth is not None and depth >= max_depth:
+        return node
+
+    try:
+        entries = sorted(
+            path.iterdir(),
+            key=lambda item: (not item.is_dir(), item.name.lower()),
+        )
+    except OSError as exc:
+        node.error = str(exc)
+        return node
+
+    for entry in entries:
+        if not show_hidden and _is_hidden(entry):
+            continue
+
+        relative_path = entry.relative_to(root).as_posix()
+        if _matches_ignore(entry.name, relative_path, ignore_patterns):
+            continue
+
+        node.children.append(
+            _scan_path(
+                path=entry,
+                root=root,
+                depth=depth + 1,
+                max_depth=max_depth,
+                show_hidden=show_hidden,
+                ignore_patterns=ignore_patterns,
+                include_fingerprints=include_fingerprints,
+            )
+        )
+
+    return node
+
+
+def _is_hidden(path: Path) -> bool:
+    return path.name.startswith(".")
+
+
+def _matches_ignore(name: str, relative_path: str, patterns: tuple[str, ...]) -> bool:
+    return any(
+        fnmatch(name, pattern) or fnmatch(relative_path, pattern)
+        for pattern in patterns
+    )
+
+
+def diff_trees(current: TreeNode, previous: TreeNode) -> TreeNode:
+    if current.kind != previous.kind:
+        node = _clone_tree(current)
+        node.diff_status = "modified"
+        if node.is_dir:
+            node.children = [_mark_tree(child, "added") for child in node.children]
+        return node
+
+    if not current.is_dir:
+        node = _clone_tree(current)
+        node.diff_status = (
+            "unchanged"
+            if current.sha256 == previous.sha256 and current.size == previous.size
+            else "modified"
+        )
+        return node
+
+    previous_by_name = {child.name: child for child in previous.children}
+    current_by_name = {child.name: child for child in current.children}
+    merged_children: list[TreeNode] = []
+
+    for name in sorted(set(previous_by_name) | set(current_by_name), key=str.lower):
+        current_child = current_by_name.get(name)
+        previous_child = previous_by_name.get(name)
+
+        if current_child and previous_child:
+            merged_children.append(diff_trees(current_child, previous_child))
+        elif current_child:
+            merged_children.append(_mark_tree(current_child, "added"))
+        elif previous_child:
+            merged_children.append(_mark_tree(previous_child, "removed"))
+
+    merged_children.sort(key=lambda item: (not item.is_dir, item.name.lower()))
+    node = _clone_tree(current)
+    node.children = merged_children
+    node.diff_status = (
+        "modified"
+        if any(child.diff_status != "unchanged" for child in merged_children)
+        else "unchanged"
+    )
+    return node
+
+
+def _mark_tree(node: TreeNode, status: DiffStatus) -> TreeNode:
+    cloned = _clone_tree(node)
+    cloned.diff_status = status
+    cloned.children = [_mark_tree(child, status) for child in cloned.children]
+    return cloned
+
+
+def _clone_tree(node: TreeNode) -> TreeNode:
+    return TreeNode(
+        name=node.name,
+        path=node.path,
+        kind=node.kind,
+        children=[_clone_tree(child) for child in node.children],
+        error=node.error,
+        size=node.size,
+        sha256=node.sha256,
+        diff_status=node.diff_status,
+    )
+
+
+def _sha256_for_file(path: Path) -> str:
+    hasher = hashlib.sha256()
+    with path.open("rb") as handle:
+        while chunk := handle.read(8192):
+            hasher.update(chunk)
+    return hasher.hexdigest()

trls_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: trls-cli
+Version: 0.2.0
+Summary: A modern tree-style CLI for humans and AI prompts.
+Author: Yonglin and Yuanben
+License: MIT
+License-File: LICENSE
+Keywords: cli,filesystem,llm,prompt,tree
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: rich>=13.9.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: twine>=6.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# trls
+
+`trls` is a modern tree-style CLI that renders file structures for humans and AI prompts.
+
+It is built for two common workflows:
+
+- inspect a project in the terminal with a cleaner, more readable tree view
+- export a stable directory snapshot that can be pasted into prompts, docs, or automation
+
+## Why `trls`
+
+Classic `tree` output is useful, but `trls` focuses on modern developer workflows:
+
+- `rich` tree output by default for a polished terminal experience
+- `prompt` output for AI-friendly, copy-pasteable directory snapshots
+- snapshot diff by default, so each run shows what changed since last time
+- `-c` clipboard copy for a compact, paste-ready LLM format
+- `text` output for universal shell compatibility
+- `markdown` output for docs and prompt sharing
+- `json` output for tooling and automation
+
+The first release keeps the scope intentionally small: one command, predictable output, and formats that are easy to copy into AI conversations.
+
+## Install
+
+```bash
+pip install trls-cli
+```
+
+## Quick start
+
+Show the current directory:
+
+```bash
+trls
+```
+
+By default, this compares the current tree against the previous run for the same path. On first run, it simply prints the current tree and creates the baseline.
+
+Export an AI-friendly directory snapshot:
+
+```bash
+trls . --format prompt
+```
+
+Copy a compact LLM-friendly version to the clipboard while keeping the normal terminal output:
+
+```bash
+trls . -c
+```
+
+Snapshots are saved automatically after each run. If you want to refresh the baseline without showing any diff markers, force-save it explicitly:
+
+```bash
+trls . -save
+```
+
+Compare against the previous run for the same path:
+
+```bash
+trls . -diff
+```
+
+Compare against an explicit snapshot file:
+
+```bash
+trls . -compare snapshot.json --format prompt
+```
+
+Show a specific directory:
+
+```bash
+trls path/to/project
+```
+
+Limit traversal depth:
+
+```bash
+trls . --depth 2
+```
+
+Include hidden files:
+
+```bash
+trls . --hidden
+```
+
+Ignore noisy paths:
+
+```bash
+trls . --ignore ".git" --ignore "__pycache__" --ignore "*.pyc"
+```
+
+Export machine-readable output:
+
+```bash
+trls . --format json
+```
+
+## Example output
+
+Prompt output:
+
+```text
+[dir] project/
+  [doc] README.md
+  [meta] pyproject.toml
+  [dir] src/
+    [dir] trls/
+      [py] cli.py
+      [py] tree.py
+```
+
+Text output:
+
+```text
+project/
+|-- README.md
+|-- pyproject.toml
+`-- src/
+    `-- trls/
+        |-- cli.py
+        `-- tree.py
+```
+
+Markdown output:
+
+```markdown
+- `project/`
+  - `README.md`
+  - `pyproject.toml`
+  - `src/`
+    - `trls/`
+      - `cli.py`
+      - `tree.py`
+```
+
+Prompt diff output:
+
+```text
+[dir] project/
+  ~ [doc] README.md
+  [meta] pyproject.toml
+  [dir] src/
+    - [py] old.py
+    + [py] new.py
+```
+
+Clipboard copy output with `-c`:
+
+```text
+project/
+project/src/
+project/src/trls/
+project/src/trls/cli.py
+~ project/README.md
++ project/src/new_file.py
+- project/src/old_file.py
+```
+
+## Python API
+
+`trls` can also be used as a small Python library:
+
+```python
+from trls import render_prompt, scan_tree
+
+tree = scan_tree("src", max_depth=2, ignore_patterns=["__pycache__", "*.pyc"])
+print(render_prompt(tree))
+```
+
+## Snapshot Diff
+
+`trls` automatically persists a file tree snapshot after each run and can compare future scans against it.
+
+Diff markers:
+
+- `+` added file or directory
+- `-` removed file or directory
+- `~` modified file or directory
+
+Current behavior in `v0.2.0`:
+
+- every successful run updates the latest snapshot for that path
+- default `trls` output compares against the previous run for that path
+- the first `--diff-last` run creates the baseline automatically if none exists yet
+- modification detection is hash-based for files
+- directories are marked modified when any descendant changes
+- explicit snapshots and automatic "last snapshot" comparison are both supported
+
+## Clipboard Copy
+
+Use `trls -c` to keep the normal terminal render while also copying a compact prompt-oriented version to your clipboard.
+
+Clipboard behavior:
+
+- the first line keeps the root directory name
+- every later line uses a full root-prefixed path
+- `+`, `-`, and `~` diff markers are preserved
+- the clipboard payload is intentionally different from the terminal render to save tokens
+
+## CLI contract for `v0.2.0`
+
+The first public release guarantees:
+
+- scan the current directory or a user-provided path
+- five output formats: `rich`, `prompt`, `text`, `markdown`, and `json`
+- `rich` is the default output format
+- default output is also a diff against the previous run when a baseline exists
+- hidden files are excluded by default and included with `--hidden`
+- ignore rules may be repeated with `--ignore`
+- snapshots are automatically updated after successful runs
+- snapshot diffing is available via `-save`/`--save-snapshot`, `-diff`/`--diff-last`, `-compare`/`--compare-with`, and `-update`/`--update-snapshot`
+- clipboard copy is available via `-c`/`--copy`
+- directories are listed before files and names are sorted case-insensitively
+- unreadable directories are reported in the output instead of crashing the renderers
+
+## Development
+
+On macOS or Linux:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -e ".[dev]"
+pytest
+```
+
+On Windows PowerShell:
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+pip install -e ".[dev]"
+pytest
+```
+
+## Release
+
+Build locally:
+
+```bash
+python -m build
+twine check dist/*
+```
+
+Recommended flow:
+
+1. Upload a test release to TestPyPI.
+2. Verify `pip install`, `trls --version`, and one real CLI example.
+3. Publish the tagged release to PyPI with Trusted Publishing.
+
+See `RELEASING.md` and `.github/workflows/publish.yml` for the release checklist.

trls_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+trls/__init__.py,sha256=xSZVUpeVLDrxFB3xc5wTgP1mfKgCgw9wT8e3VU0DaRw,415
+trls/__main__.py,sha256=KEYAlzDhxAiYWK82jQxP__VHf9qkrIn7vfRL_e_Cdus,84
+trls/cli.py,sha256=hRkNQ7TUt9Gh8GB4OxdIDKfswPTXy313zs9hRZc4eLI,4920
+trls/clipboard.py,sha256=Hd8T8xkO8PyfhI89oX1a046fh5fC9hc8_3HKDWicgF4,1353
+trls/renderers.py,sha256=wtK0ceHBOXVIHEz552jLNuJlYxp1RLQ_fVpLxGNbqsk,5858
+trls/snapshot.py,sha256=x8ncrnDETVwfSsAXzdhcM3_FfTStwxBxE_aLmMAhyvg,2083
+trls/tree.py,sha256=rkY6vYXBWpuqqUCfikmI8bBXR2TK3kZrRhu0Ao4f1C4,6775
+trls_cli-0.2.0.dist-info/METADATA,sha256=ji708F_GIx4G90BZ8PLCRd2XvjWoObbtIvNMB7YtGZM,6675
+trls_cli-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+trls_cli-0.2.0.dist-info/entry_points.txt,sha256=WxQnx5xOstjnZgDPcNB0RAL0XbjvYvEPntpfysdk0jQ,39
+trls_cli-0.2.0.dist-info/licenses/LICENSE,sha256=J1usaWY_pV5oRHZpXuBXPTtCBGuq6TCQw_mI0DNXaho,1085
+trls_cli-0.2.0.dist-info/RECORD,,

trls_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

trls_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+trls = trls.cli:main

trls_cli-0.2.0.dist-info/licenses/LICENSE

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