git-reaper 0.1.0__tar.gz

git_reaper-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs needs tags to derive the version
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync
+      - run: uv run ruff check src tests
+      - run: uv run ruff format --check src tests
+      - run: uv run mypy
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync
+      - run: uv run pytest
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --group docs
+      - run: uv run --group docs mkdocs build --strict

git_reaper-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,37 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs needs tags to derive the version
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync --group docs
+      - run: uv run --group docs mkdocs build --strict
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@v4

git_reaper-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: publish
+
+# Publishes to PyPI via trusted publishing (OIDC) when a GitHub release is
+# published. One-time setup on PyPI: add a trusted publisher for this repo
+# with workflow "publish.yml" and environment "pypi".
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs derives the version from the release tag
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv sync
+      - run: uv run pytest
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/git-reaper
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

git_reaper-0.1.0/.gitignore

@@ -0,0 +1,223 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+/dev-data
+
+# generated by the hatch-vcs build hook
+src/git_reaper/_version.py

git_reaper-0.1.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to `git-reaper` are recorded here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-02
+
+The First Harvest. Initial release: the flagship gather-and-concatenate
+workflow, folder trees, a health check, and cache management, on top of a
+library-first core.
+
+### Added
+
+#### Commands
+
+- `reaper harvest` - gather files matching a pattern (default `*.md`) from a
+  local path or remote repo URL and concatenate them into a single artifact
+  with a provenance header and per-file dividers.
+- `reaper tree` - hierarchical file listing as markdown or JSON, with depth
+  limits, dirs-only mode, sizes, line counts, and ignore rules. Works on any
+  folder, git or not.
+- `reaper pulse` - signs-of-life check: git presence and version, optional
+  extras, tty/color detection, cache health.
+- `reaper banish` - clear the catacombs (the clone cache), with
+  `--older-than 7d` for partial exorcisms.
+- `reaper boo` - hidden. You did not read this.
+
+#### Core behavior
+
+- Library-first architecture: all real work lives in `git_reaper.core` and
+  returns typed result models; the CLI is a thin presentation layer.
+- The catacombs: remote clones cache under
+  `~/.cache/git-reaper/catacombs/<host>/<owner>/<repo>`, shallow by default
+  and reused across runs. Local `file://` sources are buried flat as
+  `localhost/<name>-<digest>` so deep source paths stay inside Windows
+  path limits.
+- Provenance by default: every artifact opens with source, ref and SHA,
+  timestamp, tool version, and the exact invocation used to produce it.
+- Deterministic output: same repo state plus same flags yields a
+  byte-identical artifact (only the provenance timestamp moves).
+- Ignore rules honored: `.gitignore`, `.reaperignore`, and `--exclude` globs;
+  `.git` is never reaped.
+- Binary detection and per-file size caps, with receipts: skipped files are
+  reported loudly, never silently.
+- Artifacts go to stdout or `--out`; all themed narration and warnings go to
+  stderr, so piping is always safe.
+
+#### Output and formats
+
+- Markdown and JSON formatters.
+- Published JSON schemas: every JSON-emitting command prints its schema with
+  `--schema`.
+- Spooky Rich theming with a shared palette, plus `--plain` / `--no-theme`,
+  `NO_COLOR` support, and automatic degradation on non-tty output.
+
+#### Packaging and tooling
+
+- `src/` layout with hatchling build backend and uv lockfile; VCS-derived
+  versioning.
+- Both `reaper` and `git-reaper` console entry points (the long form is the
+  fallback if the REAPER DAW owns the short one).
+- Test suite covering the CLI, harvest, tree, ignore matching, cache, and
+  schema export; CI workflow; mkdocs documentation site; Makefile.
+
+[Unreleased]: https://github.com/jmcmeen/git-reaper/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jmcmeen/git-reaper/releases/tag/v0.1.0

git_reaper-0.1.0/LICENSE

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

git_reaper-0.1.0/Makefile

@@ -0,0 +1,51 @@
+# git-reaper dev rituals. Everything runs through uv.
+
+UV ?= uv
+
+.DEFAULT_GOAL := help
+
+.PHONY: help setup fmt lint typecheck test cov check build clean run pulse docs docs-build
+
+help: ## List the available rituals
+	@grep -E '^[a-zA-Z_-]+:.*## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf "  \033[35m%-12s\033[0m %s\n", $$1, $$2}'
+
+setup: ## Create the venv and install all deps (incl. dev group)
+	$(UV) sync
+
+fmt: ## Auto-format and fix lint findings
+	$(UV) run ruff format src tests
+	$(UV) run ruff check --fix src tests
+
+lint: ## Lint and check formatting (no changes)
+	$(UV) run ruff check src tests
+	$(UV) run ruff format --check src tests
+
+typecheck: ## mypy over the typed core
+	$(UV) run mypy
+
+test: ## Run the test suite
+	$(UV) run pytest
+
+cov: ## Tests with coverage report
+	$(UV) run pytest --cov=git_reaper --cov-report=term-missing
+
+check: lint typecheck test ## The full gauntlet: lint + types + tests
+
+docs: ## Serve the docs locally with live reload
+	$(UV) run --group docs mkdocs serve
+
+docs-build: ## Build the docs strictly (what CI runs)
+	$(UV) run --group docs mkdocs build --strict
+
+build: ## Build sdist and wheel into dist/
+	$(UV) build
+
+clean: ## Sweep build artifacts and caches
+	rm -rf dist build site .pytest_cache .mypy_cache .ruff_cache .coverage htmlcov
+	find . -type d -name __pycache__ -not -path './.venv/*' -exec rm -rf {} +
+
+run: ## Run the CLI (ARGS="tree ." to pass arguments)
+	$(UV) run reaper $(ARGS)
+
+pulse: ## Signs-of-life check via the CLI
+	$(UV) run reaper pulse

git_reaper-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: git-reaper
+Version: 0.1.0
+Summary: A spooky utility for data mining git repositories (and any folder foolish enough to hold still).
+Project-URL: Homepage, https://github.com/jmcmeen/git-reaper
+Author: John McMeen
+License: MIT License
+        
+        Copyright (c) 2026 John McMeen
+        
+        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: analysis,cli,git,llm,repository
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Requires-Dist: pathspec>=0.12
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: gitpython>=3.1; extra == 'all'
+Requires-Dist: textual>=0.80; extra == 'all'
+Requires-Dist: tiktoken>=0.7; extra == 'all'
+Provides-Extra: git
+Requires-Dist: gitpython>=3.1; extra == 'git'
+Provides-Extra: tokens
+Requires-Dist: tiktoken>=0.7; extra == 'tokens'
+Provides-Extra: tui
+Requires-Dist: textual>=0.80; extra == 'tui'
+Description-Content-Type: text/markdown
+
+# git-reaper
+
+> A spooky utility for data mining git repositories (and any folder foolish enough to hold still).
+
+`git-reaper` reaps structured knowledge from repositories: it clones, gathers,
+concatenates, and packs the contents of a git repo (or a plain directory) into
+clean, portable artifacts. Library first; the CLI is a thin adapter over
+`git_reaper.core`.
+
+## Install
+
+```sh
+uv tool install git-reaper   # or: pip install git-reaper
+```
+
+Both `reaper` and `git-reaper` land on your PATH (the long form is the
+fallback if the REAPER DAW already owns the short one).
+
+## Commands (v0.1.0)
+
+| Command | What it does |
+| --- | --- |
+| `harvest` | Gather files matching a pattern (default `*.md`) from a path or repo URL and concatenate them into one artifact with a provenance header and per-file dividers. |
+| `tree` | Hierarchical file listing as markdown or JSON. Depth limits, dirs-only, sizes, line counts, ignore rules. |
+| `pulse` | Signs-of-life check: git present, optional extras, cache health. |
+| `banish` | Clear the catacombs (the clone cache). `--older-than 7d` for partial exorcisms. |
+
+```sh
+reaper harvest https://github.com/Textualize/rich --pattern "*.md" -o RICH.md
+reaper tree . --sizes --lines
+reaper tree . --format json | jq .file_count
+reaper pulse
+reaper banish --older-than 7d
+```
+
+## Behavior you can rely on
+
+- **Artifacts to stdout (or `--out`); narration to stderr.** Piping is always safe.
+- **Deterministic output.** Same repo state + same flags = byte-identical
+  artifact (only the provenance timestamp moves).
+- **Provenance by default.** Every artifact opens with source, ref/sha,
+  timestamp, tool version, and the exact invocation.
+- **Ignore rules honored.** `.gitignore` + `.reaperignore` + `--exclude`
+  globs; `.git` is never reaped.
+- **Caps with receipts.** Size caps and binary detection skip files loudly,
+  never silently.
+- **The catacombs.** Remote clones cache under
+  `~/.cache/git-reaper/catacombs/<host>/<owner>/<repo>`, shallow, reused
+  across runs. Local `file://` sources are buried flat
+  (`localhost/<name>-<digest>`) to stay inside Windows path limits.
+- **Published schemas.** Every JSON-emitting command prints its JSON schema
+  with `--schema`.
+- **`--plain` / `NO_COLOR`** produce clean ASCII; non-tty output auto-disables
+  the theatrics.
+- **No telemetry.** The dead tell no tales.
+
+## Library use
+
+```python
+from git_reaper.core.source import resolve_source
+from git_reaper.core.harvest import harvest
+from git_reaper.formatters.markdown import write_harvest
+
+repo = resolve_source("https://github.com/Textualize/rich").repo
+result = harvest(repo, patterns=("*.md",))
+with open("RICH.md", "w") as fh:
+    write_harvest(result, fh)
+```
+
+## Development
+
+Everything runs through `uv` and the Makefile:
+
+```sh
+make setup      # create venv, install deps
+make check      # lint + typecheck + tests (the full gauntlet)
+make fmt        # auto-format and fix lint findings
+make test       # pytest
+make cov        # pytest with coverage
+make docs       # serve the docs locally
+make run ARGS="tree ."
+make build      # sdist + wheel
+```
+
+The version comes from git tags (`hatch-vcs`); there is nothing to bump.
+Publishing a GitHub release for a `vX.Y.Z` tag builds and uploads to PyPI
+via trusted publishing, and docs deploy to GitHub Pages on every push to
+`main`.
+
+## License
+
+MIT. Rest in peace.