Metadata-Version: 2.4
Name: cliolens
Version: 0.1.0
Summary: Pack an entire project into one AI-ready context file: directory tree, full file contents, and token estimates.
Project-URL: Homepage, https://github.com/SPARTonScratch/cliolens
Project-URL: Repository, https://github.com/SPARTonScratch/cliolens
Project-URL: Issues, https://github.com/SPARTonScratch/cliolens/issues
Author: ClioLens Authors
License: MIT License
        
        Copyright (c) 2026 ClioLens Authors
        
        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.
License-File: LICENSE
Keywords: ai,cli,context,developer-tools,llm,prompt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: pathspec>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
    <img src="https://raw.githubusercontent.com/SPARTonScratch/cliolens/main/assets/cliolens-logo.png" width="256" alt="ClioLens logo">
</p>

<h1 align="center">ClioLens</h1>

<p align="center"><b>One command. One file. Your whole codebase, ready for any AI.</b></p>

ClioLens packs a project directory into a single markdown *context dump* with
a visual directory tree, the full text of every relevant file, and metadata. It's designed to be attached to free web-based AI models
(Qwen, Kimi, ChatGPT, Claude…) for whole-codebase analysis.

No API keys, local GPU, IDE extensions, or telemetry. Read-only.

---

## Why

Free-tier web models accept file uploads but can't see your repo. Copy-pasting
files one by one is slow and loses structure. ClioLens gives you the
copy-paste workflow in one shot, with guardrails:

- **Zero-config**: `cliolens .` produces something useful immediately.
- **Respects your project**: build artifacts, dependencies, VCS data, and
  `.gitignore` rules are excluded automatically.
- **Transparent**: you always know what was included, what was skipped, and why.
- **Model-aware**: clean headers, syntax-fenced code, token budgets.

## Requirements

- Python 3.10+ (on Windows 11, [uv](https://astral.sh/uv) manages this for you)
- Any OS; developed and tested against Windows 11 (paths with spaces,
  Unicode, backslashes, and long paths all handled)

## Installation

**Prerequisites (one-time):**

```powershell
# uv — manages Python and packages for you
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Git — needed to fetch from GitHub (skip if you already have it)
winget install Git.Git
```

**Install ClioLens** (open a **new terminal** after the steps above):

```powershell
uv tool install git+https://github.com/SPARTonScratch/cliolens
cliolens --version   # verify
```

To pin a specific release instead of tracking `main`:

```powershell
uv tool install git+https://github.com/SPARTonScratch/cliolens@v0.1.0
```

### From source (for contributors)

```powershell
git clone https://github.com/SPARTonScratch/cliolens
cd cliolens
uv tool install .        # or: uv pip install -e ".[dev]" for editable + test tooling
```

Upgrade / uninstall: `uv tool upgrade cliolens` · `uv tool uninstall cliolens`.
Plain `pip install .` also works from a local clone.

## Quickstart

```powershell
# Dump the current directory, writes 'cliolens project context.md' right here
cliolens .

# Want it on stdout instead (to pipe or copy)?
cliolens . -o -

# Preview exactly what will be included before generating
cliolens . --dry-run

# Check against a 128K-token model window
cliolens . -t 128000
```

## CLI reference

```
cliolens [OPTIONS] [DIRECTORY]
```

| Flag | Default | Description |
|---|---|---|
| `DIRECTORY` | `.` | Root directory to scan |
| `-o, --output PATH` | `cliolens project context.md` | Output file in the current directory (`-o -` for stdout; existing files overwritten) |
| `-m, --max-file-size SIZE` | `100KB` | Larger files are truncated with a notice (`B`/`KB`/`MB`/`GB`) |
| `-e, --exclude GLOB` | — | Extra exclude pattern, repeatable (`*.log`, `temp/`, `src/gen/*.py`) |
| `-n, --no-gitignore` | off | Ignore `.gitignore` files (built-in exclusions still apply) |
| `-f, --follow-symlinks` | off | Follow symlinks (loop-safe via inode tracking) |
| `-d, --dry-run` | off | Report include/skip decisions without generating output |
| `-t, --max-tokens N` | `0` | Warn on stderr if the estimate exceeds N |
| `--show-binary` | off | Dump binary file contents as base64-encoded text in File Contents; without this flag, a placeholder notice (type + size) is shown instead. Binaries always appear in the tree and counts regardless. |
| `--version` | — | Print version and exit |

## What gets excluded

**Always (built-in):** `.git`, `.svn`, `.hg`, `node_modules`, `vendor`,
`__pycache__`, `.mypy_cache`, `.pytest_cache`, `.ruff_cache`, `.venv`,
`venv`, `env`, `ENV`, `dist`, `build`, `target`, `.out`, `.idea`, `.vscode`,
`.DS_Store`, `Thumbs.db`, and files matching `*.pyc *.pyo *.class *.o *.so
*.dll *.exe *.bin *.lock`.

**Then:** every `.gitignore` in the tree (root and nested, including `!`
negations and `**` patterns, via the `pathspec` library).

**Then:** your `--exclude` globs — matched against the full relative path,
the basename (gitignore-style), or a path suffix. `dir/` patterns prune the
whole directory.

**Plus:** the output file itself, as a safety guard so re-runs never dump the
previous dump. On Windows all matching is case-insensitive.

**Binary files** (images, fonts, media, archives, ML artifacts…) are detected
by a built-in extension blacklist (fast path) with content analysis as the
fallback authority. They **always** appear in the directory tree, count toward
included files, and show a placeholder notice in the File Contents section
with their MIME type and size. Use `--show-binary` to replace the placeholder
with the file's full content as base64-encoded text (subject to
`--max-file-size` truncation, measured in bytes).

## Anatomy of the output

````markdown
# Project Context Dump

## Metadata
- **Project Name:** my-app
- **Root Path:** C:\Users\Dev\my-app
- **Generated At:** 2026-08-01 18:40:05 -02:00
- **Files Scanned:** 142
- **Files Included:** 87
- **Files Skipped:** 55
- **Estimated Tokens:** 45,210 (~180,840 characters)
- **Total Source Size:** 312.4KB

---

## Directory Tree

```
my-app/
├── src/
│   └── main.py
└── README.md
```

---

## File Contents

### src/main.py

```python
def main():
    print("hello")
```

End of dump. Generated by cliolens v0.1.0
````

- **Scanned** = every file encountered; **included** = in the dump
  (truncated files and binary files count as included); **skipped** = excluded
  or unreadable.
- Oversized files keep their first 50 lines plus a truncation banner.
- With `--show-binary`, binary placeholders are replaced with base64-encoded
  content in a code fence, truncated at `--max-file-size` if necessary.

## Token estimation

`ceil(characters / 4)` is used to estimate token count, so expect ±20% of a real tokenizer on typical source. Diagnostics and warnings print to **stderr** in color (TTY-only, honors `NO_COLOR`), so piping stdout is always clean markdown.

## Exit codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | Input/runtime error (missing dir, permission denied, bad output path…) |
| `2` | Usage error (unknown flag, malformed `--max-file-size`) |
| `130` | Interrupted (Ctrl+C) |

## Development

```powershell
uv pip install -e ".[dev]"     # editable install + test tooling
pytest                         # unit + integration tests
pytest --cov=cliolens          # with coverage
ruff check src tests           # lint
```

```
src/cliolens/
├── cli.py        # argument parsing, orchestration, error presentation
├── scanner.py    # traversal, filter pipeline, binary detection, metadata
├── formatter.py  # tree rendering, markdown assembly, content wrapping
└── utils.py      # token estimation, size formatting, path helpers
```

## License

MIT License, see [LICENSE](LICENSE).