trls-cli 0.2.0__tar.gz

trls_cli-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+.pytest_cache/
+.venv/
+build/
+dist/
+*.egg-info/
+__pycache__/
+*.pyc

trls_cli-0.2.0/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.

trls_cli-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,255 @@
+# 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/RELEASING.md

@@ -0,0 +1,100 @@
+# Releasing `trls`
+
+This repository is prepared for a CLI-first PyPI release.
+
+## Current release assumptions
+
+- distribution name: `trls-cli`
+- import package: `trls`
+- version: `0.2.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.
+
+## 1. Prepare the repository metadata
+
+Before publishing, create the public GitHub repository and then add the real URLs back into `pyproject.toml` if you want them shown on PyPI.
+
+Recommended URLs to add:
+
+- homepage: `https://github.com/<owner>/trls`
+- repository: `https://github.com/<owner>/trls`
+- issues: `https://github.com/<owner>/trls/issues`
+
+## 2. Test locally
+
+On Windows PowerShell:
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+pip install -e ".[dev]"
+pytest
+python -m build
+python -m twine check dist/*
+```
+
+On macOS or Linux:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -e ".[dev]"
+pytest
+python -m build
+python -m twine check dist/*
+```
+
+## 3. Publish to TestPyPI
+
+Create a TestPyPI account, then upload manually:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+Verify the release in a clean environment:
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple trls-cli
+trls --version
+trls . --format markdown
+```
+
+## 4. Configure Trusted Publishing
+
+In both PyPI and TestPyPI:
+
+1. Create the project if it does not exist yet.
+2. Open the publishing settings.
+3. Add your GitHub repository.
+4. Register the workflow file `.github/workflows/publish.yml`.
+
+The workflow already expects the `pypi` environment in GitHub Actions.
+
+## 5. Release from a Git tag
+
+After Trusted Publishing is configured:
+
+```bash
+git tag v0.2.0
+git push origin v0.2.0
+```
+
+The GitHub Actions workflow will:
+
+- install the package with dev dependencies
+- run the test suite
+- build wheel and source distributions
+- publish to PyPI for version tags
+
+## First release checklist
+
+1. Confirm `trls-cli` is still available on PyPI.
+2. Create the public GitHub repository.
+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.2.0` tag to trigger the production release.

trls_cli-0.2.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "trls-cli"
+version = "0.2.0"
+description = "A modern tree-style CLI for humans and AI prompts."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+  { name = "Yonglin and Yuanben" }
+]
+requires-python = ">=3.9"
+dependencies = [
+  "rich>=13.9.0",
+]
+keywords = ["tree", "cli", "filesystem", "prompt", "llm"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Utilities",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+  "pytest>=8.3.4",
+  "twine>=6.1.0",
+]
+
+[project.scripts]
+trls = "trls.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/trls"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+  "/README.md",
+  "/RELEASING.md",
+  "/LICENSE",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]