trls-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{trls_cli-0.4.0 → trls_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trls-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: A modern tree-style CLI for humans and AI prompts.
 Author: Yonglin and Yuanben
 License: MIT
@@ -41,6 +41,7 @@ Classic `tree` output is useful, but `trls` focuses on modern developer workflow
 - `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
+- `--skill` output for agent workflows, with automatic clipboard copy
 - always-on progress feedback during scans in interactive terminals
 - richer colors for common media, office, and data files
 - `text` output for universal shell compatibility
@@ -77,6 +78,12 @@ Copy a compact LLM-friendly version to the clipboard while keeping the normal te
 trls . -c
 ```
 
+Print the built-in agent skill text and copy it to the clipboard:
+
+```bash
+trls --skill
+```
+
 In interactive terminals, `trls` also shows live scan progress so large trees do not feel stuck.
 
 Snapshots are saved automatically after each run. If you want to refresh the baseline without showing any diff markers, force-save it explicitly:
@@ -206,7 +213,7 @@ Diff markers:
 - `-` removed file or directory
 - `~` modified file or directory
 
-Current behavior in `v0.4.0`:
+Current behavior in `v0.5.0`:
 
 - every successful run updates the latest snapshot for that path
 - default `trls` output compares against the previous run for that path
@@ -228,6 +235,38 @@ Clipboard behavior:
 - the clipboard payload is intentionally different from the terminal render to save tokens
 - WSL-aware clipboard fallbacks are attempted before reporting an error
 
+## Agent Skill Output
+
+Use `trls -skill` or `trls --skill` to print a built-in English skill block for Cursor-style agents and copy it to the clipboard automatically.
+
+Skill behavior:
+
+- prints a ready-to-paste agent instruction block to stdout
+- copies the same text to the clipboard automatically
+- tells agents to prefer `trls` for file structure analysis before broad manual exploration
+- suggests `--format prompt`, `--depth`, `--ignore`, and `-diff` as the primary workflow
+
+Recommended agent command order:
+
+1. Run `trls <path> --format prompt` for the first structure pass.
+2. Add `--depth <n>` if the repository is too large.
+3. Add repeated `--ignore <pattern>` options to remove noisy folders such as `.git`, `node_modules`, `dist`, or build output.
+4. Add `--hidden` only when hidden files are likely relevant.
+5. Use `-diff` when you want to compare against the previous snapshot.
+6. Use `-c` when you want a compact clipboard-oriented summary.
+
+Common agent examples:
+
+```bash
+trls . --format prompt
+trls . --format prompt --depth 2
+trls . --format prompt --ignore .git --ignore node_modules --ignore dist
+trls src --format prompt --depth 3
+trls . -diff --format prompt
+trls . -c
+trls --skill
+```
+
 ## Progress And Color UX
 
 - interactive runs show a transient progress indicator while scanning
@@ -236,7 +275,7 @@ Clipboard behavior:
 - spreadsheet and office files such as `.xlsx`, `.csv`, `.docx`, and `.pptx` have their own color family
 - data-oriented files such as `.parquet` and `.ipynb` are also colorized
 
-## CLI contract for `v0.4.0`
+## CLI contract for `v0.5.0`
 
 The first public release guarantees:
 
@@ -249,6 +288,7 @@ The first public release guarantees:
 - 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`
+- agent skill output is available via `-skill`/`--skill`
 - interactive scans show live progress feedback
 - directories are listed before files and names are sorted case-insensitively
 - unreadable directories are reported in the output instead of crashing the renderers
@@ -290,6 +330,7 @@ Recommended flow:
 2. Verify `pip install`, `trls --version`, and one real CLI example.
 3. Publish the tagged release to PyPI with Trusted Publishing.
 
+.venv\Scripts\Activate.ps1
 Remove-Item -Recurse -Force .\dist
 python -m pytest
 python -m build

{trls_cli-0.4.0 → trls_cli-0.5.0}/README.md

@@ -15,6 +15,7 @@ Classic `tree` output is useful, but `trls` focuses on modern developer workflow
 - `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
+- `--skill` output for agent workflows, with automatic clipboard copy
 - always-on progress feedback during scans in interactive terminals
 - richer colors for common media, office, and data files
 - `text` output for universal shell compatibility
@@ -51,6 +52,12 @@ Copy a compact LLM-friendly version to the clipboard while keeping the normal te
 trls . -c
 ```
 
+Print the built-in agent skill text and copy it to the clipboard:
+
+```bash
+trls --skill
+```
+
 In interactive terminals, `trls` also shows live scan progress so large trees do not feel stuck.
 
 Snapshots are saved automatically after each run. If you want to refresh the baseline without showing any diff markers, force-save it explicitly:
@@ -180,7 +187,7 @@ Diff markers:
 - `-` removed file or directory
 - `~` modified file or directory
 
-Current behavior in `v0.4.0`:
+Current behavior in `v0.5.0`:
 
 - every successful run updates the latest snapshot for that path
 - default `trls` output compares against the previous run for that path
@@ -202,6 +209,38 @@ Clipboard behavior:
 - the clipboard payload is intentionally different from the terminal render to save tokens
 - WSL-aware clipboard fallbacks are attempted before reporting an error
 
+## Agent Skill Output
+
+Use `trls -skill` or `trls --skill` to print a built-in English skill block for Cursor-style agents and copy it to the clipboard automatically.
+
+Skill behavior:
+
+- prints a ready-to-paste agent instruction block to stdout
+- copies the same text to the clipboard automatically
+- tells agents to prefer `trls` for file structure analysis before broad manual exploration
+- suggests `--format prompt`, `--depth`, `--ignore`, and `-diff` as the primary workflow
+
+Recommended agent command order:
+
+1. Run `trls <path> --format prompt` for the first structure pass.
+2. Add `--depth <n>` if the repository is too large.
+3. Add repeated `--ignore <pattern>` options to remove noisy folders such as `.git`, `node_modules`, `dist`, or build output.
+4. Add `--hidden` only when hidden files are likely relevant.
+5. Use `-diff` when you want to compare against the previous snapshot.
+6. Use `-c` when you want a compact clipboard-oriented summary.
+
+Common agent examples:
+
+```bash
+trls . --format prompt
+trls . --format prompt --depth 2
+trls . --format prompt --ignore .git --ignore node_modules --ignore dist
+trls src --format prompt --depth 3
+trls . -diff --format prompt
+trls . -c
+trls --skill
+```
+
 ## Progress And Color UX
 
 - interactive runs show a transient progress indicator while scanning
@@ -210,7 +249,7 @@ Clipboard behavior:
 - spreadsheet and office files such as `.xlsx`, `.csv`, `.docx`, and `.pptx` have their own color family
 - data-oriented files such as `.parquet` and `.ipynb` are also colorized
 
-## CLI contract for `v0.4.0`
+## CLI contract for `v0.5.0`
 
 The first public release guarantees:
 
@@ -223,6 +262,7 @@ The first public release guarantees:
 - 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`
+- agent skill output is available via `-skill`/`--skill`
 - interactive scans show live progress feedback
 - directories are listed before files and names are sorted case-insensitively
 - unreadable directories are reported in the output instead of crashing the renderers
@@ -264,6 +304,7 @@ Recommended flow:
 2. Verify `pip install`, `trls --version`, and one real CLI example.
 3. Publish the tagged release to PyPI with Trusted Publishing.
 
+.venv\Scripts\Activate.ps1
 Remove-Item -Recurse -Force .\dist
 python -m pytest
 python -m build

{trls_cli-0.4.0 → trls_cli-0.5.0}/RELEASING.md

@@ -6,7 +6,7 @@ This repository is prepared for a CLI-first PyPI release.
 
 - distribution name: `trls-cli`
 - import package: `trls`
-- version: `0.4.0`
+- version: `0.5.0`
 - release channel: TestPyPI first, then PyPI
 
 At the time of preparation, `https://pypi.org/project/trls-cli/` should be re-checked right before uploading.
@@ -79,8 +79,8 @@ The workflow already expects the `pypi` environment in GitHub Actions.
 After Trusted Publishing is configured:
 
 ```bash
-git tag v0.4.0
-git push origin v0.4.0
+git tag v0.5.0
+git push origin v0.5.0
 ```
 
 The GitHub Actions workflow will:
@@ -97,4 +97,4 @@ The GitHub Actions workflow will:
 3. Add the real repository URLs to `pyproject.toml`.
 4. Ensure README examples still match current CLI behavior.
 5. Upload to TestPyPI and validate installation.
-6. Push the `v0.4.0` tag to trigger the production release.
+6. Push the `v0.5.0` tag to trigger the production release.

{trls_cli-0.4.0 → trls_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "trls-cli"
-version = "0.4.0"
+version = "0.5.0"
 description = "A modern tree-style CLI for humans and AI prompts."
 readme = "README.md"
 license = { text = "MIT" }

{trls_cli-0.4.0 → trls_cli-0.5.0}/src/trls/__init__.py

@@ -8,7 +8,7 @@ from trls.renderers import (
 )
 from trls.tree import TreeNode, scan_tree
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"
 
 __all__ = [
     "TreeNode",

{trls_cli-0.4.0 → trls_cli-0.5.0}/src/trls/cli.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 import argparse
 import sys
-from pathlib import Path
 from typing import Sequence
 
 from rich.console import Console
@@ -10,6 +9,7 @@ from rich.progress import Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
 
 from trls import __version__
 from trls.clipboard import copy_text
+from trls.paths import normalize_input_path
 from trls.renderers import (
     build_rich_tree,
     render_compact_copy,
@@ -18,6 +18,7 @@ from trls.renderers import (
     render_prompt,
     render_text,
 )
+from trls.skill import AGENT_SKILL_TEXT
 from trls.snapshot import load_last_snapshot, load_snapshot, save_last_snapshot
 from trls.tree import DEFAULT_IGNORE_PATTERNS, diff_trees, scan_tree
 
@@ -90,6 +91,12 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Copy a compact LLM-friendly version to the clipboard after rendering.",
     )
+    parser.add_argument(
+        "-skill",
+        "--skill",
+        action="store_true",
+        help="Print the built-in agent skill text and copy it to the clipboard.",
+    )
     parser.add_argument(
         "--version",
         action="version",
@@ -102,6 +109,15 @@ def main(argv: Sequence[str] | None = None) -> int:
     parser = build_parser()
     args = parser.parse_args(argv)
 
+    if args.skill:
+        print(AGENT_SKILL_TEXT)
+        try:
+            copy_text(AGENT_SKILL_TEXT)
+        except RuntimeError as exc:
+            print(f"Failed to copy to clipboard: {exc}", file=sys.stderr)
+            return 1
+        return 0
+
     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:
@@ -114,7 +130,7 @@ def main(argv: Sequence[str] | None = None) -> int:
     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()
+    root_path = normalize_input_path(args.path)
     needs_fingerprints = True
 
     current_tree = _scan_tree_with_progress(

{trls_cli-0.4.0 → trls_cli-0.5.0}/src/trls/clipboard.py

@@ -1,108 +1,98 @@
-from __future__ import annotations
-
-import os
-import platform
-import shutil
-import subprocess
-from pathlib import Path
-
-
-def copy_text(text: str) -> None:
-    backends = _clipboard_backends()
-    if not backends:
-        raise RuntimeError(
-            "No supported clipboard command was found. "
-            "On Linux/WSL, install wl-clipboard, xclip, or xsel."
-        )
-
-    errors: list[str] = []
-    for backend_name, command in backends:
-        try:
-            _run_clipboard_command(command, text)
-            return
-        except RuntimeError as exc:
-            errors.append(f"{backend_name}: {exc}")
-
-    attempted_names = ", ".join(name for name, _ in backends)
-    error_details = "; ".join(errors)
-    raise RuntimeError(
-        f"No clipboard backend succeeded. Tried: {attempted_names}. {error_details}"
-    )
-
-
-def _clipboard_backends() -> list[tuple[str, list[str]]]:
-    system = platform.system()
-    backends: list[tuple[str, list[str]]] = []
-
-    if system == "Windows":
-        command = _resolve_command("clip")
-        if command:
-            backends.append(("clip", [command]))
-        return backends
-
-    if system == "Darwin":
-        command = _resolve_command("pbcopy")
-        if command:
-            backends.append(("pbcopy", [command]))
-        return backends
-
-    if _is_wsl():
-        clip_exe = _resolve_command("clip.exe") or _resolve_windows_clip_path()
-        if clip_exe:
-            backends.append(("clip.exe", [clip_exe]))
-        powershell_exe = _resolve_command("powershell.exe")
-        if powershell_exe:
-            backends.append(
-                (
-                    "powershell.exe Set-Clipboard",
-                    [powershell_exe, "-NoProfile", "-Command", "Set-Clipboard"],
-                )
-            )
-
-    wl_copy = _resolve_command("wl-copy")
-    if wl_copy:
-        backends.append(("wl-copy", [wl_copy]))
-
-    xclip = _resolve_command("xclip")
-    if xclip:
-        backends.append(("xclip", [xclip, "-selection", "clipboard"]))
-
-    xsel = _resolve_command("xsel")
-    if xsel:
-        backends.append(("xsel", [xsel, "--clipboard", "--input"]))
-
-    return backends
-
-
-def _resolve_command(name: str) -> str | None:
-    return shutil.which(name)
-
-
-def _resolve_windows_clip_path() -> str | None:
-    candidate = Path("/mnt/c/Windows/System32/clip.exe")
-    return str(candidate) if candidate.exists() else None
-
-
-def _is_wsl() -> bool:
-    if os.environ.get("WSL_DISTRO_NAME"):
-        return True
-    try:
-        return "microsoft" in Path("/proc/version").read_text(encoding="utf-8").lower()
-    except OSError:
-        return False
-
-
-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
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+from pathlib import Path
+
+from trls.paths import is_wsl
+
+
+def copy_text(text: str) -> None:
+    backends = _clipboard_backends()
+    if not backends:
+        raise RuntimeError(
+            "No supported clipboard command was found. "
+            "On Linux/WSL, install wl-clipboard, xclip, or xsel."
+        )
+
+    errors: list[str] = []
+    for backend_name, command in backends:
+        try:
+            _run_clipboard_command(command, text)
+            return
+        except RuntimeError as exc:
+            errors.append(f"{backend_name}: {exc}")
+
+    attempted_names = ", ".join(name for name, _ in backends)
+    error_details = "; ".join(errors)
+    raise RuntimeError(
+        f"No clipboard backend succeeded. Tried: {attempted_names}. {error_details}"
+    )
+
+
+def _clipboard_backends() -> list[tuple[str, list[str]]]:
+    system = platform.system()
+    backends: list[tuple[str, list[str]]] = []
+
+    if system == "Windows":
+        command = _resolve_command("clip")
+        if command:
+            backends.append(("clip", [command]))
+        return backends
+
+    if system == "Darwin":
+        command = _resolve_command("pbcopy")
+        if command:
+            backends.append(("pbcopy", [command]))
+        return backends
+
+    if is_wsl():
+        clip_exe = _resolve_command("clip.exe") or _resolve_windows_clip_path()
+        if clip_exe:
+            backends.append(("clip.exe", [clip_exe]))
+        powershell_exe = _resolve_command("powershell.exe")
+        if powershell_exe:
+            backends.append(
+                (
+                    "powershell.exe Set-Clipboard",
+                    [powershell_exe, "-NoProfile", "-Command", "Set-Clipboard"],
+                )
+            )
+
+    wl_copy = _resolve_command("wl-copy")
+    if wl_copy:
+        backends.append(("wl-copy", [wl_copy]))
+
+    xclip = _resolve_command("xclip")
+    if xclip:
+        backends.append(("xclip", [xclip, "-selection", "clipboard"]))
+
+    xsel = _resolve_command("xsel")
+    if xsel:
+        backends.append(("xsel", [xsel, "--clipboard", "--input"]))
+
+    return backends
+
+
+def _resolve_command(name: str) -> str | None:
+    return shutil.which(name)
+
+
+def _resolve_windows_clip_path() -> str | None:
+    candidate = Path("/mnt/c/Windows/System32/clip.exe")
+    return str(candidate) if candidate.exists() else None
+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_cli-0.5.0/src/trls/paths.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import os
+import platform
+import re
+from pathlib import Path, PureWindowsPath
+
+_WINDOWS_DRIVE_PATH_RE = re.compile(r"^([a-zA-Z]):(?:[\\/](.*))?$")
+_WSL_MOUNT_PATH_RE = re.compile(r"^/mnt(?:/host)?/([a-zA-Z])(?:/(.*))?$")
+
+
+def is_wsl() -> bool:
+    if os.environ.get("WSL_DISTRO_NAME"):
+        return True
+    try:
+        return "microsoft" in Path("/proc/version").read_text(encoding="utf-8").lower()
+    except OSError:
+        return False
+
+
+def normalize_input_path(path_value: str | Path) -> Path:
+    translated = translate_input_path(path_value)
+    return Path(translated).expanduser().resolve()
+
+
+def translate_input_path(path_value: str | Path) -> str:
+    raw_path = os.fspath(path_value)
+    mounted_windows_path = _parse_wsl_mounted_windows_path(raw_path)
+
+    if platform.system() == "Windows":
+        if mounted_windows_path is not None:
+            drive, parts = mounted_windows_path
+            return _build_windows_path(drive, parts)
+        return raw_path
+
+    if mounted_windows_path is not None:
+        drive, parts = mounted_windows_path
+        translated_path = _build_wsl_mount_path(drive, parts)
+        mount_root = Path("/mnt") / drive.lower()
+        if is_wsl() or mount_root.exists():
+            return translated_path
+        return raw_path
+
+    windows_drive_path = _parse_windows_drive_path(raw_path)
+    if windows_drive_path is None:
+        return raw_path
+
+    drive, parts = windows_drive_path
+    translated_path = _build_wsl_mount_path(drive, parts)
+    mount_root = Path("/mnt") / drive.lower()
+    if is_wsl() or mount_root.exists():
+        return translated_path
+    return raw_path
+
+
+def canonicalize_path_identity(path_value: str | Path) -> str:
+    normalized_path = normalize_input_path(path_value)
+    windows_identity = _windows_identity(normalized_path)
+    if windows_identity is not None:
+        return f"win:{windows_identity}"
+    return f"posix:{normalized_path.as_posix()}"
+
+
+def _parse_windows_drive_path(raw_path: str) -> tuple[str, list[str]] | None:
+    match = _WINDOWS_DRIVE_PATH_RE.match(raw_path)
+    if match is None:
+        return None
+
+    drive = match.group(1)
+    remainder = match.group(2) or ""
+    parts = [part for part in re.split(r"[\\/]+", remainder) if part]
+    return drive, parts
+
+
+def _parse_wsl_mounted_windows_path(raw_path: str) -> tuple[str, list[str]] | None:
+    match = _WSL_MOUNT_PATH_RE.match(raw_path)
+    if match is None:
+        return None
+
+    drive = match.group(1)
+    remainder = match.group(2) or ""
+    parts = [part for part in remainder.split("/") if part]
+    return drive, parts
+
+
+def _build_windows_path(drive: str, parts: list[str]) -> str:
+    return str(PureWindowsPath(f"{drive.upper()}:\\", *parts))
+
+
+def _build_wsl_mount_path(drive: str, parts: list[str]) -> str:
+    mounted_path = Path("/mnt") / drive.lower()
+    for part in parts:
+        mounted_path /= part
+    return mounted_path.as_posix()
+
+
+def _windows_identity(path: Path) -> str | None:
+    windows_drive_path = _parse_windows_drive_path(str(path))
+    if windows_drive_path is not None:
+        drive, parts = windows_drive_path
+        return _build_windows_identity(drive, parts)
+
+    mounted_windows_path = _parse_wsl_mounted_windows_path(path.as_posix())
+    if mounted_windows_path is not None:
+        drive, parts = mounted_windows_path
+        return _build_windows_identity(drive, parts)
+
+    return None
+
+
+def _build_windows_identity(drive: str, parts: list[str]) -> str:
+    if not parts:
+        return drive.lower()
+    return f"{drive.lower()}/{'/'.join(parts)}"

trls_cli-0.5.0/src/trls/skill.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+AGENT_SKILL_TEXT = """Use `trls` first when you need to understand a project's file structure.
+
+Priority rules:
+- Prefer `trls` over ad hoc `ls`, `tree`, or broad recursive file listing when your goal is repository structure analysis.
+- Start with `trls <path> --format prompt` for an AI-friendly directory snapshot.
+- If the tree is too large, rerun with `--depth <n>` before opening files.
+- If the tree is noisy, rerun with repeated `--ignore <pattern>` arguments.
+- Use `--hidden` only when hidden files are likely relevant.
+- Use `-diff` when you need to inspect structure changes between runs.
+- Use `-c` when you want a compact clipboard-friendly summary for prompts.
+- Use `--format json` only when a downstream tool needs machine-readable output.
+
+Recommended workflow:
+1. Run `trls <target> --format prompt`.
+2. If needed, narrow the scope with `trls <target> --format prompt --depth <n>`.
+3. If needed, remove noise with repeated `--ignore` patterns such as `.git`, `node_modules`, `dist`, `build`, or caches.
+4. Review the tree and identify the smallest relevant subdirectory.
+5. Run `trls` again on that narrower path before opening many files.
+6. Only then open specific files or run targeted code searches.
+
+Argument guide:
+- `--format prompt`: default choice for agent-oriented structure inspection
+- `--depth <n>`: limit traversal when the repository is large
+- `--ignore <pattern>`: suppress noisy paths; can be repeated
+- `--hidden`: include hidden files and directories when required
+- `-diff`: compare the current tree with the previous snapshot
+- `-c`: copy a compact prompt-oriented summary to the clipboard
+- `--format json`: use for automation, not for first-pass exploration
+
+Examples:
+- `trls . --format prompt`
+- `trls . --format prompt --depth 2`
+- `trls . --format prompt --ignore .git --ignore node_modules --ignore dist`
+- `trls src --format prompt --depth 3 -diff`
+- `trls . -c`
+
+Goal:
+Use `trls` to reduce noisy exploration, keep structural analysis consistent, and produce prompt-ready project snapshots before deeper file inspection.
+"""

{trls_cli-0.4.0 → trls_cli-0.5.0}/src/trls/snapshot.py

@@ -1,60 +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)
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+from trls.paths import canonicalize_path_identity, normalize_input_path
+from trls.tree import TreeNode
+
+SNAPSHOT_VERSION = 1
+SNAPSHOT_DIR_ENV = "TRLS_SNAPSHOT_DIR"
+
+
+def default_snapshot_path(root: str | Path) -> Path:
+    normalized_root = canonicalize_path_identity(root)
+    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 normalize_input_path(configured_dir)
+    return Path.home() / ".trls" / "snapshots"
+
+
+def save_snapshot(snapshot_path: str | Path, root: str | Path, tree: TreeNode) -> Path:
+    destination = normalize_input_path(snapshot_path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    root_path = normalize_input_path(root)
+    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 = normalize_input_path(snapshot_path)
+    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 {normalize_input_path(root)}. "
+            "Run trls with --save-snapshot first."
+        )
+    return load_snapshot(snapshot_path)

{trls_cli-0.4.0 → trls_cli-0.5.0}/src/trls/tree.py

@@ -6,6 +6,8 @@ from fnmatch import fnmatch
 from pathlib import Path
 from typing import Any, Callable, Literal
 
+from trls.paths import normalize_input_path
+
 DEFAULT_IGNORE_PATTERNS = (".venv", "dist", "__pycache__")
 DiffStatus = Literal["added", "removed", "modified", "unchanged"]
 
@@ -74,7 +76,7 @@ def scan_tree(
     include_fingerprints: bool = False,
     on_visit: Callable[[Path], None] | None = None,
 ) -> TreeNode:
-    root_path = Path(root).expanduser().resolve()
+    root_path = normalize_input_path(root)
     if not root_path.exists():
         raise FileNotFoundError(f"Path does not exist: {root}")
 

{trls_cli-0.4.0 → trls_cli-0.5.0}/tests/test_cli.py

@@ -1,11 +1,14 @@
 import json
+from pathlib import Path
 
 import pytest
 
 from trls import __version__
 import trls.clipboard as clipboard_module
 import trls.cli as cli_module
+import trls.snapshot as snapshot_module
 from trls.cli import main
+from trls.skill import AGENT_SKILL_TEXT
 from trls.snapshot import save_snapshot
 from trls.tree import scan_tree
 
@@ -97,6 +100,111 @@ def test_cli_json_output(capsys, tmp_path):
     assert any(child["name"] == "src" for child in payload["children"])
 
 
+def test_cli_skill_prints_and_copies_without_scanning(capsys, monkeypatch):
+    copied = {}
+
+    def fake_copy_text(text):
+        copied["text"] = text
+
+    monkeypatch.setattr(cli_module, "copy_text", fake_copy_text)
+    monkeypatch.setattr(
+        cli_module,
+        "normalize_input_path",
+        lambda raw_path: (_ for _ in ()).throw(AssertionError("skill mode should not scan")),
+    )
+
+    exit_code = main(["--skill"])
+    captured = capsys.readouterr()
+
+    assert exit_code == 0
+    assert captured.out == AGENT_SKILL_TEXT + "\n"
+    assert copied["text"] == AGENT_SKILL_TEXT
+
+@pytest.mark.parametrize("flag", ["-skill", "--skill"])
+def test_cli_skill_aliases_are_supported(capsys, monkeypatch, flag):
+    monkeypatch.setattr(cli_module, "copy_text", lambda text: None)
+
+    exit_code = main([flag])
+    captured = capsys.readouterr()
+
+    assert exit_code == 0
+    assert "Use `trls` first" in captured.out
+
+
+def test_cli_short_s_is_not_skill_alias(capsys):
+    with pytest.raises(SystemExit):
+        main(["-s"])
+
+    captured = capsys.readouterr()
+
+    assert "ambiguous option: -s" in captured.err
+
+
+def test_cli_skill_reports_clipboard_failure(capsys, monkeypatch):
+    def failing_copy_text(text):
+        raise RuntimeError("clipboard unavailable")
+
+    monkeypatch.setattr(cli_module, "copy_text", failing_copy_text)
+
+    exit_code = main(["--skill"])
+    captured = capsys.readouterr()
+
+    assert exit_code == 1
+    assert captured.out == AGENT_SKILL_TEXT + "\n"
+    assert "Failed to copy to clipboard: clipboard unavailable" in captured.err
+
+
+def test_cli_normalizes_foreign_input_path_before_scan(capsys, monkeypatch, tmp_path):
+    root = create_project(tmp_path)
+    normalized_inputs = []
+
+    def fake_normalize_input_path(raw_path):
+        normalized_inputs.append(raw_path)
+        return root
+
+    monkeypatch.setattr(cli_module, "normalize_input_path", fake_normalize_input_path)
+
+    exit_code = main(["/mnt/host/c/Users/user/Desktop/ZYB/genewa/trls", "--format", "text"])
+    captured = capsys.readouterr()
+
+    assert exit_code == 0
+    assert normalized_inputs == ["/mnt/host/c/Users/user/Desktop/ZYB/genewa/trls"]
+    assert "demo/" in captured.out
+
+
+def test_cli_snapshot_dir_env_uses_normalized_path(capsys, monkeypatch, tmp_path):
+    root = create_project(tmp_path)
+    root_input = "/mnt/c/Users/user/Desktop/ZYB/genewa/demo"
+    snapshot_env = "/mnt/host/c/Users/user/.trls/snapshots"
+    normalized_snapshot_dir = tmp_path / "snapshots"
+    normalized_calls = []
+
+    def fake_cli_normalize_input_path(raw_path):
+        normalized_calls.append(raw_path)
+        if raw_path == root_input:
+            return root
+        return Path(raw_path).resolve()
+
+    def fake_snapshot_normalize_input_path(raw_path):
+        normalized_calls.append(raw_path)
+        if raw_path == snapshot_env:
+            return normalized_snapshot_dir
+        if raw_path == root_input:
+            return root
+        return Path(raw_path).resolve()
+
+    monkeypatch.setenv("TRLS_SNAPSHOT_DIR", snapshot_env)
+    monkeypatch.setattr(cli_module, "normalize_input_path", fake_cli_normalize_input_path)
+    monkeypatch.setattr(snapshot_module, "normalize_input_path", fake_snapshot_normalize_input_path)
+
+    exit_code = main([root_input, "--format", "prompt"])
+    capsys.readouterr()
+
+    assert exit_code == 0
+    assert snapshot_env in normalized_calls
+    assert any(normalized_snapshot_dir.iterdir())
+
+
 def test_cli_copy_writes_compact_clipboard_output(capsys, monkeypatch, tmp_path):
     root = create_project(tmp_path)
     copied = {}
@@ -319,7 +427,7 @@ def test_cli_diff_last_first_run_creates_baseline_without_error(capsys, monkeypa
 def test_copy_text_uses_clip_exe_in_wsl(monkeypatch):
     calls = []
 
-    monkeypatch.setattr(clipboard_module, "_is_wsl", lambda: True)
+    monkeypatch.setattr(clipboard_module, "is_wsl", lambda: True)
     monkeypatch.setattr(clipboard_module.platform, "system", lambda: "Linux")
     monkeypatch.setattr(
         clipboard_module,
@@ -342,7 +450,7 @@ def test_copy_text_uses_clip_exe_in_wsl(monkeypatch):
 def test_copy_text_reports_install_hint_when_no_backend_exists(monkeypatch):
     monkeypatch.delenv("WSL_DISTRO_NAME", raising=False)
     monkeypatch.setattr(clipboard_module.platform, "system", lambda: "Linux")
-    monkeypatch.setattr(clipboard_module, "_is_wsl", lambda: False)
+    monkeypatch.setattr(clipboard_module, "is_wsl", lambda: False)
     monkeypatch.setattr(clipboard_module, "_resolve_command", lambda name: None)
     monkeypatch.setattr(clipboard_module, "_resolve_windows_clip_path", lambda: None)
 

{trls_cli-0.4.0 → trls_cli-0.5.0}/tests/test_tree.py

@@ -1,5 +1,8 @@
 import json
+import os
 
+import trls.paths as paths_module
+import trls.snapshot as snapshot_module
 from trls import (
     build_rich_tree,
     render_compact_copy,
@@ -9,7 +12,8 @@ from trls import (
     render_text,
     scan_tree,
 )
-from trls.snapshot import load_snapshot, save_snapshot
+from trls.paths import canonicalize_path_identity
+from trls.snapshot import default_snapshot_path, load_snapshot, save_snapshot, snapshot_storage_dir
 from trls.tree import diff_trees
 
 
@@ -95,6 +99,88 @@ def test_rich_renderer_applies_styles_by_node_type(tmp_path):
     assert labels["sheet.xlsx"] == "bright_green"
 
 
+def test_translate_input_path_converts_wsl_mount_paths_for_windows_runtime(monkeypatch):
+    monkeypatch.setattr(paths_module.platform, "system", lambda: "Windows")
+
+    assert (
+        paths_module.translate_input_path("/mnt/c/Users/test/project")
+        == r"C:\Users\test\project"
+    )
+    assert (
+        paths_module.translate_input_path("/mnt/host/d/Work/demo")
+        == r"D:\Work\demo"
+    )
+
+
+def test_translate_input_path_converts_windows_paths_for_wsl_runtime(monkeypatch):
+    monkeypatch.setattr(paths_module.platform, "system", lambda: "Linux")
+    monkeypatch.setattr(paths_module, "is_wsl", lambda: True)
+
+    assert (
+        paths_module.translate_input_path(r"C:\Users\test\project")
+        == "/mnt/c/Users/test/project"
+    )
+    assert paths_module.translate_input_path("D:/Work/demo") == "/mnt/d/Work/demo"
+
+
+def test_translate_input_path_normalizes_host_mount_paths_for_wsl_runtime(monkeypatch):
+    monkeypatch.setattr(paths_module.platform, "system", lambda: "Linux")
+    monkeypatch.setattr(paths_module, "is_wsl", lambda: True)
+
+    assert (
+        paths_module.translate_input_path("/mnt/host/c/Users/test/project")
+        == "/mnt/c/Users/test/project"
+    )
+
+
+def test_canonicalize_path_identity_matches_equivalent_aliases(monkeypatch, tmp_path):
+    project = create_sample_tree(tmp_path)
+    alias_map = {
+        os.fspath(project): project,
+        "/mnt/c/Users/test/project": project,
+        r"C:\Users\test\project": project,
+    }
+
+    monkeypatch.setattr(
+        paths_module,
+        "normalize_input_path",
+        lambda raw_path: alias_map[os.fspath(raw_path)],
+    )
+
+    mounted_identity = canonicalize_path_identity("/mnt/c/Users/test/project")
+    windows_identity = canonicalize_path_identity(r"C:\Users\test\project")
+
+    assert mounted_identity == windows_identity
+
+
+def test_snapshot_storage_dir_normalizes_foreign_env_path(monkeypatch, tmp_path):
+    normalized_snapshot_dir = tmp_path / "snapshots"
+    foreign_snapshot_dir = "/mnt/host/c/Users/user/.trls/snapshots"
+
+    monkeypatch.setenv(snapshot_module.SNAPSHOT_DIR_ENV, foreign_snapshot_dir)
+    monkeypatch.setattr(
+        snapshot_module,
+        "normalize_input_path",
+        lambda raw_path: normalized_snapshot_dir,
+    )
+
+    assert snapshot_storage_dir() == normalized_snapshot_dir
+
+
+def test_default_snapshot_path_matches_equivalent_aliases(monkeypatch, tmp_path):
+    monkeypatch.setattr(snapshot_module, "snapshot_storage_dir", lambda: tmp_path)
+    monkeypatch.setattr(
+        snapshot_module,
+        "canonicalize_path_identity",
+        lambda raw_path: "win:c/Users/test/project",
+    )
+
+    mounted_path = default_snapshot_path("/mnt/c/Users/test/project")
+    windows_path = default_snapshot_path(r"C:\Users\test\project")
+
+    assert mounted_path == windows_path
+
+
 def test_snapshot_round_trip_and_diff_statuses(tmp_path):
     project = create_sample_tree(tmp_path)
     snapshot_path = tmp_path / "snapshot.json"