repocxt 0.1.0__tar.gz

repocxt-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-11-15
+
+### Added
+
+- `ctx` CLI with a `root` argument (defaults to the current directory) and an
+  `-o/--output` flag for writing the context file instead of stdout.
+- Repository walker that honors `.gitignore` and `.ctxignore` at every level of
+  the tree, following git semantics, and always skips `.git`, `.svn`, `.hg`,
+  `.ctx`, `__pycache__`, and `.mypy_cache`.
+- `--include` and `--exclude` filter flags using pathspec glob syntax
+  (`exclude` wins over `include`), plus `--max-size` to skip large files.
+- Binary-file detection via NUL-byte sniffing; binary files are listed in the
+  context document but their content is omitted.
+- Token estimation with no external tokenizer dependency; accurate enough to
+  budget context window fits and slightly conservative.
+- Markdown renderer emitting a directory tree, a files/bytes/tokens summary,
+  and one fenced block per source file with a language hint.
+- `--max-tokens` to stop early once the running token estimate exceeds a limit,
+  `--no-tree` to omit the ASCII tree, and `--json` for a machine-readable
+  summary.
+- `python -m ctx` support, `ctx --version`, and a `py.typed` marker.

repocxt-0.1.0/LICENSE

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

repocxt-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+recursive-include tests *.py

repocxt-0.1.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: repocxt
+Version: 0.1.0
+Summary: Package a repository into a single, LLM-ready context file with a tree, file contents, and a token estimate.
+Author: Kamran
+License-Expression: MIT
+Keywords: llm,context,cli,code,ai,prompt
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pathspec>=1.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: build
+Requires-Dist: build>=1.0; extra == "build"
+Requires-Dist: twine>=4.0; extra == "build"
+Dynamic: license-file
+
+# ctx
+
+Package a repository into a single, LLM-ready context file.
+
+`ctx` walks a directory and emits one markdown file containing an ASCII tree of
+the repo, the contents of every source file (fenced with language hints), and a
+token estimate — so you can paste a whole repository into an LLM prompt, or
+point an agent at it, and the model sees structure and code together.
+
+## What it looks like
+
+Running `ctx` on this repo (tree trimmed for the README; the header counts are real):
+
+````text
+# repo — context
+
+- files: **26** · **67763 bytes** · ~**19876 tokens**
+
+## Tree
+
+```text
+├── .github/
+│   ├── workflows/
+│   │   ├── ci.yml
+│   │   └── release.yml
+│   └── FUNDING.yml
+├── src/
+│   └── ctx/
+│       ├── __init__.py
+│       ├── __main__.py
+│       ├── ...
+│       └── walker.py
+├── tests/
+│   ├── conftest.py
+│   ├── test_cli.py
+│   ├── test_ignore.py
+│   ├── test_render.py
+│   ├── test_tokens.py
+│   └── test_walker.py
+├── .gitignore
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+├── LICENSE
+├── MANIFEST.in
+├── pyproject.toml
+└── README.md
+```
+````
+
+## Features
+
+- **One file out.** Directory tree, file contents, and a token estimate in a
+  single markdown document — ready to paste into a prompt.
+- **Gitignore-aware.** Follows `.gitignore` (and `.ctxignore`) at every level
+  of the tree, with git's semantics: deeper rule files win.
+- **Binary-safe.** Binary files are detected and listed, but their content is
+  omitted instead of corrupting the document.
+- **Token-aware.** `--max-tokens` stops early once the running estimate crosses
+  the limit, so the output fits your context window.
+- **Filterable.** `--include` / `--exclude` with repeatable pathspec globs, and
+  `--max-size` to skip files that are too big.
+- **Offline and light.** The only runtime dependency is `pathspec`.
+
+## Install
+
+Requires Python 3.10+. The package is published on PyPI as `repocxt`; the
+command you run is `ctx`.
+
+```bash
+pipx install repocxt
+```
+
+Or install from a checkout directly:
+
+```bash
+pipx install .
+```
+
+Or with plain pip:
+
+```bash
+pip install repocxt
+```
+
+However you install it, you get a `ctx` command (it also runs as
+`python -m ctx`).
+
+## Usage
+
+```text
+usage: ctx [-h] [-o FILE] [--include GLOB] [--exclude GLOB] [--max-size BYTES]
+           [--max-tokens N] [--no-tree] [--json] [--version]
+           [root]
+```
+
+- `root` — directory to pack. Defaults to the current directory. The header
+  uses the directory's name (or `repo` when the name is empty, e.g. `.`).
+- `-o FILE, --output FILE` — write to a file instead of stdout. `-o -` means
+  stdout explicitly.
+- `--include GLOB` / `--exclude GLOB` — keep or drop paths matching a glob
+  (repeatable; pathspec syntax). Both are applied after ignore filtering, and
+  `--exclude` wins over `--include`.
+- `--max-size BYTES` — skip files larger than this many bytes.
+- `--max-tokens N` — stop once the emitted text reaches N tokens.
+- `--no-tree` — omit the ASCII tree section; just the files.
+- `--json` — print a machine-readable summary (file list, counts, bytes,
+  tokens) instead of the document.
+
+### With LLMs
+
+The output is self-contained, so driving an LLM is two steps:
+
+```bash
+# write it to a file for an agent that can read files
+ctx -o ctx.md
+
+# or just paste stdout straight into the prompt
+ctx | head -c 20000
+```
+
+Point the model at `ctx.md` ("this is my whole repo, read it") or paste it
+directly — the tree tells it the layout, the fenced blocks give it the code,
+and the token estimate tells you whether it fits.
+
+## How it decides what to include
+
+- **Gitignore semantics.** `.gitignore` files are read at every directory and
+  applied to relative paths; a deeper `.gitignore`'s decision wins over a
+  shallower one's, and later lines override earlier ones. A private
+  `.ctxignore` file is honored the same way, for rules you do not want to
+  commit to git.
+- **Always-skipped directories.** `.git`, `.svn`, `.hg`, `.ctx`,
+  `__pycache__`, and `.mypy_cache` are always skipped.
+- **Binary omission.** A file is treated as binary when its first 8 KB contain
+  a NUL byte — images, archives, compiled objects. It is still listed in the
+  document, but with a note instead of content.
+- **Files, not directories.** Only regular files are packed; empty directories
+  and directory symlinks do not appear in the tree.
+
+## Philosophy
+
+Offline-first. There is no telemetry, no network call, and no tokenizer — token
+counts come from a small local heuristic that errs high, which is the safe
+direction for context budgeting. The dependency list stays minimal
+(`pathspec` is the only runtime dependency) and the output is plain markdown
+you can read, diff, and paste anywhere.
+
+## Development
+
+```bash
+git clone <your fork>/ctx
+cd ctx
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+- Run tests: `python -m pytest`
+- Lint: `python -m ruff check .` (config and dev extras live in `pyproject.toml`)
+
+No need to install to poke at the CLI:
+
+```bash
+export PYTHONPATH="$PWD/src"
+python3 -m ctx --help
+```
+
+## Testing & compatibility
+
+Honest status of what is and isn't verified:
+
+- **Tested on:** Linux, Python 3.12 — 106 automated tests pass (`pytest`),
+  `ruff` clean, wheel + sdist build clean, `twine check` passes. Edge cases
+  covered by tests: nested/overriding `.gitignore`, negation, directory-only
+  patterns, filenames with spaces, undecodable and binary files, oversized
+  files, symlinks (not followed for dirs), backtick-fences inside file bodies,
+  and `--max-tokens` / `--json` behavior.
+- **Expected but not yet verified:** macOS and Windows, and Python 3.10–3.11.
+  The code is pure Python + `pathspec` with no OS-specific calls, so it
+  *should* run anywhere, but only Linux/3.12 has been exercised. The GitHub
+  Actions matrix (`ci.yml`) runs 3.10–3.12 on Linux for every push; wider
+  platform testing is welcome via PRs / CI runs.
+- **Not verified at all:** any real PyPI publication (needs a maintainer token).
+
+If you hit a platform you use that isn't green, open an issue with your OS,
+Python version, and the error — that's the fastest way this list gets shorter.
+
+## License
+
+[MIT](LICENSE) © 2026 Kamran

repocxt-0.1.0/README.md

@@ -0,0 +1,189 @@
+# ctx
+
+Package a repository into a single, LLM-ready context file.
+
+`ctx` walks a directory and emits one markdown file containing an ASCII tree of
+the repo, the contents of every source file (fenced with language hints), and a
+token estimate — so you can paste a whole repository into an LLM prompt, or
+point an agent at it, and the model sees structure and code together.
+
+## What it looks like
+
+Running `ctx` on this repo (tree trimmed for the README; the header counts are real):
+
+````text
+# repo — context
+
+- files: **26** · **67763 bytes** · ~**19876 tokens**
+
+## Tree
+
+```text
+├── .github/
+│   ├── workflows/
+│   │   ├── ci.yml
+│   │   └── release.yml
+│   └── FUNDING.yml
+├── src/
+│   └── ctx/
+│       ├── __init__.py
+│       ├── __main__.py
+│       ├── ...
+│       └── walker.py
+├── tests/
+│   ├── conftest.py
+│   ├── test_cli.py
+│   ├── test_ignore.py
+│   ├── test_render.py
+│   ├── test_tokens.py
+│   └── test_walker.py
+├── .gitignore
+├── CHANGELOG.md
+├── CONTRIBUTING.md
+├── LICENSE
+├── MANIFEST.in
+├── pyproject.toml
+└── README.md
+```
+````
+
+## Features
+
+- **One file out.** Directory tree, file contents, and a token estimate in a
+  single markdown document — ready to paste into a prompt.
+- **Gitignore-aware.** Follows `.gitignore` (and `.ctxignore`) at every level
+  of the tree, with git's semantics: deeper rule files win.
+- **Binary-safe.** Binary files are detected and listed, but their content is
+  omitted instead of corrupting the document.
+- **Token-aware.** `--max-tokens` stops early once the running estimate crosses
+  the limit, so the output fits your context window.
+- **Filterable.** `--include` / `--exclude` with repeatable pathspec globs, and
+  `--max-size` to skip files that are too big.
+- **Offline and light.** The only runtime dependency is `pathspec`.
+
+## Install
+
+Requires Python 3.10+. The package is published on PyPI as `repocxt`; the
+command you run is `ctx`.
+
+```bash
+pipx install repocxt
+```
+
+Or install from a checkout directly:
+
+```bash
+pipx install .
+```
+
+Or with plain pip:
+
+```bash
+pip install repocxt
+```
+
+However you install it, you get a `ctx` command (it also runs as
+`python -m ctx`).
+
+## Usage
+
+```text
+usage: ctx [-h] [-o FILE] [--include GLOB] [--exclude GLOB] [--max-size BYTES]
+           [--max-tokens N] [--no-tree] [--json] [--version]
+           [root]
+```
+
+- `root` — directory to pack. Defaults to the current directory. The header
+  uses the directory's name (or `repo` when the name is empty, e.g. `.`).
+- `-o FILE, --output FILE` — write to a file instead of stdout. `-o -` means
+  stdout explicitly.
+- `--include GLOB` / `--exclude GLOB` — keep or drop paths matching a glob
+  (repeatable; pathspec syntax). Both are applied after ignore filtering, and
+  `--exclude` wins over `--include`.
+- `--max-size BYTES` — skip files larger than this many bytes.
+- `--max-tokens N` — stop once the emitted text reaches N tokens.
+- `--no-tree` — omit the ASCII tree section; just the files.
+- `--json` — print a machine-readable summary (file list, counts, bytes,
+  tokens) instead of the document.
+
+### With LLMs
+
+The output is self-contained, so driving an LLM is two steps:
+
+```bash
+# write it to a file for an agent that can read files
+ctx -o ctx.md
+
+# or just paste stdout straight into the prompt
+ctx | head -c 20000
+```
+
+Point the model at `ctx.md` ("this is my whole repo, read it") or paste it
+directly — the tree tells it the layout, the fenced blocks give it the code,
+and the token estimate tells you whether it fits.
+
+## How it decides what to include
+
+- **Gitignore semantics.** `.gitignore` files are read at every directory and
+  applied to relative paths; a deeper `.gitignore`'s decision wins over a
+  shallower one's, and later lines override earlier ones. A private
+  `.ctxignore` file is honored the same way, for rules you do not want to
+  commit to git.
+- **Always-skipped directories.** `.git`, `.svn`, `.hg`, `.ctx`,
+  `__pycache__`, and `.mypy_cache` are always skipped.
+- **Binary omission.** A file is treated as binary when its first 8 KB contain
+  a NUL byte — images, archives, compiled objects. It is still listed in the
+  document, but with a note instead of content.
+- **Files, not directories.** Only regular files are packed; empty directories
+  and directory symlinks do not appear in the tree.
+
+## Philosophy
+
+Offline-first. There is no telemetry, no network call, and no tokenizer — token
+counts come from a small local heuristic that errs high, which is the safe
+direction for context budgeting. The dependency list stays minimal
+(`pathspec` is the only runtime dependency) and the output is plain markdown
+you can read, diff, and paste anywhere.
+
+## Development
+
+```bash
+git clone <your fork>/ctx
+cd ctx
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+- Run tests: `python -m pytest`
+- Lint: `python -m ruff check .` (config and dev extras live in `pyproject.toml`)
+
+No need to install to poke at the CLI:
+
+```bash
+export PYTHONPATH="$PWD/src"
+python3 -m ctx --help
+```
+
+## Testing & compatibility
+
+Honest status of what is and isn't verified:
+
+- **Tested on:** Linux, Python 3.12 — 106 automated tests pass (`pytest`),
+  `ruff` clean, wheel + sdist build clean, `twine check` passes. Edge cases
+  covered by tests: nested/overriding `.gitignore`, negation, directory-only
+  patterns, filenames with spaces, undecodable and binary files, oversized
+  files, symlinks (not followed for dirs), backtick-fences inside file bodies,
+  and `--max-tokens` / `--json` behavior.
+- **Expected but not yet verified:** macOS and Windows, and Python 3.10–3.11.
+  The code is pure Python + `pathspec` with no OS-specific calls, so it
+  *should* run anywhere, but only Linux/3.12 has been exercised. The GitHub
+  Actions matrix (`ci.yml`) runs 3.10–3.12 on Linux for every push; wider
+  platform testing is welcome via PRs / CI runs.
+- **Not verified at all:** any real PyPI publication (needs a maintainer token).
+
+If you hit a platform you use that isn't green, open an issue with your OS,
+Python version, and the error — that's the fastest way this list gets shorter.
+
+## License
+
+[MIT](LICENSE) © 2026 Kamran

repocxt-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "repocxt"
+version = "0.1.0"
+description = "Package a repository into a single, LLM-ready context file with a tree, file contents, and a token estimate."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kamran" }]
+keywords = ["llm", "context", "cli", "code", "ai", "prompt"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Build Tools",
+]
+dependencies = [
+    "pathspec>=1.1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "pytest-cov>=4.1",
+    "ruff>=0.4",
+]
+build = [
+    "build>=1.0",
+    "twine>=4.0",
+]
+
+[project.scripts]
+ctx = "ctx.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ctx = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "C4"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

repocxt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

repocxt-0.1.0/src/ctx/__init__.py

@@ -0,0 +1,8 @@
+"""ctx — package a repository into a single, LLM-ready context file.
+
+The public surface is the ``ctx`` console command, implemented in
+:mod:`ctx.cli`. Importing the package only exposes metadata.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

repocxt-0.1.0/src/ctx/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m ctx``."""
+
+from ctx.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

repocxt-0.1.0/src/ctx/binary.py

@@ -0,0 +1,37 @@
+"""Heuristic detection of binary files.
+
+No file signature database: a file is treated as binary when its first chunk
+contains a NUL byte, which is reliable for the formats programmers actually
+commit (images, archives, compiled objects, fonts, audio). UTF-16 text and some
+encodings can contain NUL, but they are vanishingly rare in repository trees.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_SNIFF_BYTES = 8192
+_NUL = b"\x00"
+
+
+def is_nul_in_text(text: str) -> bool:
+    """True when decoded ``text`` still contains a NUL character.
+
+    ``is_binary`` sniffs only the first chunk, so a NUL past that window would
+    otherwise slip through; checking the decoded text is the definitive gate.
+    """
+    return _NUL.decode("ascii") in text
+
+
+def is_binary(path: Path) -> bool:
+    """Return True when ``path`` looks like a binary file.
+
+    Reads at most :data:`_SNIFF_BYTES` bytes. Files shorter than that are judged
+    on their whole content. A missing file answers False (the caller handles it).
+    """
+    try:
+        with path.open("rb") as handle:
+            chunk = handle.read(_SNIFF_BYTES)
+    except OSError:
+        return False
+    return _NUL in chunk