gwc-pybundle 0.4.2__py3-none-any.whl

gwc_pybundle-0.4.2.dist-info/METADATA

@@ -0,0 +1,476 @@
+Metadata-Version: 2.4
+Name: gwc-pybundle
+Version: 0.4.2
+Summary: Deterministic Python project context bundling for humans, automation, and AI
+Author: Jessica Brown
+License: The MIT License (MIT)
+        =====================
+        
+        Copyright © 2025 Jessica Brown
+        
+        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.
+Project-URL: Homepage, https://github.com/girls-whocode/pybundle
+Project-URL: Repository, https://github.com/girls-whocode/pybundle
+Project-URL: Issues, https://github.com/girls-whocode/pybundle/issues
+Classifier: Development Status :: 4 - Beta
+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 :: Build Tools
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Dynamic: license-file
+
+# 🧳 pybundle
+ 
+**pybundle** is a deterministic, automation-friendly tool for collecting Python project context into a single, shareable bundle - ideal for debugging, audits, AI assistance, CI artifacts, or handoff between engineers.
+
+It produces **machine-readable outputs first**, with optional human-readable summaries layered on top.
+
+> Think “`git archive` + diagnostics + metadata”, without guessing or heuristics.  
+
+> **Note:** The PyPI package name is `gwc-pybundle`, but the tool is installed and used as `pybundle`.
+---
+
+## 🧠 Why pybundle exists
+
+Modern software development compresses what used to be entire teams into a single role.
+
+Today, one developer is often responsible for:
+- application code
+- build systems
+- test tooling
+- deployment logic
+- CI/CD behavior
+- environment differences
+- security implications
+- and increasingly, AI-assisted workflows
+
+The problem is no longer *how* to write code.
+
+It’s answering:
+
+> **“Why is this system behaving the way it is?”**
+
+That question is hard to answer when:
+- context is scattered
+- tooling output is ephemeral
+- environment details are lost
+- source snapshots are incomplete or noisy
+
+AI didn’t create this problem - it exposed it.
+
+Large language models don’t fail because they lack intelligence.
+They fail because we give them **uncurated context**.
+
+Humans don’t fail because they can’t debug.
+They fail because the **cost of reconstructing context** exceeds the time they have.
+
+**pybundle exists to reduce context debt.**
+
+It captures *what matters*, ignores what doesn’t, and produces a deterministic artifact that explains:
+- what code exists
+- what tools ran
+- what environment was used
+- and why the outputs exist
+
+For humans, automation, and AI alike.
+
+---
+
+## ✨ Features
+
+* 📦 **Single archive output** (`.zip` or `.tar.gz`)
+* 🧠 **Machine-readable manifest** (`MANIFEST.json`) for automation
+* 🧾 **Structured summaries** (`SUMMARY.json`)
+* 🧭 **Respects `.gitignore`** exactly when available
+* 🛑 **Safely ignores virtualenvs and caches** (even with non-standard names)
+* 🔍 Optional tooling checks (ruff, mypy, pytest, ripgrep scans)
+* 🧪 Deterministic output (stable paths, timestamps, schemas)
+* 🔒 Secret-safe (optional redaction)
+
+---
+
+## 📂 What’s in a pybundle archive?
+
+At minimum, a bundle contains:
+
+```text
+MANIFEST.json        # stable, machine-readable metadata
+SUMMARY.json         # structured summary of collected data
+src/                 # filtered project source snapshot
+logs/                # tool outputs (ruff, mypy, etc.)
+meta/                # environment + tool detection
+```
+
+### `MANIFEST.json` (automation fuel)
+
+Includes:
+
+* tool paths detected
+* options used
+* archive name + format
+* git commit hash (if available)
+* UTC timestamp
+* schema version (stable)
+
+Another script can fully understand a bundle **without reading markdown**.
+
+---
+
+## 🚀 Installation
+
+We recommend using a Python virtual environment for development tooling.
+
+### Quick installation (pybundle tooling) - RECOMMENDED
+
+Create a dedicated requirements file in the root of your project:
+
+```txt
+# requirements-pybundle.txt
+ruff
+mypy
+pytest
+gwc-pybundle==0.4.2
+```
+
+Then install:
+
+```bash
+pip install -r requirements-pybundle.txt
+```
+
+> **System dependency:**
+> pybundle uses `ripgrep (rg)` for source scanning and expects the system binary.
+>
+> * macOS: `brew install ripgrep`
+> * Ubuntu/Debian: `sudo apt install ripgrep`
+> * Fedora: `sudo dnf install ripgrep`
+
+After installation, run:
+
+```bash
+pybundle run analysis
+```
+
+A new `artifacts/` directory will be created containing:
+
+* the compressed bundle
+* an extracted working directory
+* machine-readable metadata (`MANIFEST.json`, `SUMMARY.json`)
+
+See **Usage** for more details.
+
+---
+
+### Advanced installation
+
+#### From GitHub
+
+```bash
+pip install "gwc-pybundle @ git+https://github.com/girls-whocode/pybundle.git@v0.4.2"
+```
+
+Pinning to a tag ensures reproducible behavior.
+
+#### Editable install (for development)
+
+```bash
+pip install -e .
+```
+
+---
+
+## 🧪 Usage
+
+From the root of a Python project, run a profile using the `run` command:
+
+```bash
+pybundle run analysis
+```
+
+This builds a timestamped diagnostic bundle under the default `artifacts/` directory.
+
+### Profiles
+
+Profiles define *what* pybundle collects and *which tools* are run.
+
+Available profiles include:
+
+* `analysis` - **full diagnostics** (lint, type-check, tests, scans)
+* `debug` - **analysis + additional environment validation**
+* `backup` - **minimal environment snapshot**
+* `ai` - **AI-optimized context bundle** (lean, source-first)
+
+To list all available profiles:
+
+```bash
+pybundle list-profiles
+```
+
+Profiles are always invoked via:
+
+```bash
+pybundle run <profile>
+```
+---
+
+### 🤖 AI profile (NEW)
+
+The `ai` profile is optimized for handing a project to AI tooling
+(ChatGPT, local LLMs, code assistants, etc.).
+
+It prioritizes **source code and reproducible context**, while skipping
+expensive or noisy steps by default.
+
+Run it with:
+
+```bash
+pybundle run ai
+```
+
+#### What `ai` does by default
+
+* ✅ Includes full curated source snapshot (`src/`)
+* ✅ Includes environment + git metadata
+* ✅ Generates `REPRO.md` and `HANDOFF.md`
+* ❌ Skips linting, type-checking, tests
+* ❌ Skips ripgrep scans and error-context expansion
+* ❌ Skips `compileall` unless explicitly enabled
+
+The result is a **small, fast, AI-friendly bundle** that still preserves
+determinism and traceability.
+
+You may selectively re-enable tools:
+
+```bash
+pybundle run ai --ruff --mypy
+pybundle run ai --compileall
+```
+
+This makes `ai` suitable for:
+
+* AI-assisted refactoring
+* Large-context summarization
+* Code review handoff
+* Offline or local LLM workflows
+
+---
+
+### Common options
+
+Most usage customizations are done through flags on `pybundle run`.
+
+Example:
+
+```bash
+pybundle run analysis \
+  --format zip \
+  --outdir ./artifacts \
+  --name myproject-bundle \
+  --strict
+```
+
+Commonly used options:
+
+* `--format {auto,zip,tar.gz}` - archive format
+* `--outdir PATH` - output directory (default: `<project>/artifacts`)
+* `--name NAME` - override archive name prefix
+* `--strict` - fail with non-zero exit code if any step fails
+* `--no-spinner` - disable spinner output (CI-friendly)
+* `--redact / --no-redact` - control secret redaction
+
+Tool execution can be selectively disabled:
+
+```bash
+--no-ruff
+--no-mypy
+--no-pytest
+--no-rg
+--no-error-refs
+--no-context
+```
+
+For the full list of options:
+
+```bash
+pybundle run --help
+```
+
+---
+
+### Doctor mode
+
+To see which tools are available and what *would* run (without creating a bundle):
+
+```bash
+pybundle doctor
+```
+
+You may optionally specify a profile to preview:
+
+```bash
+pybundle doctor analysis
+```
+
+This is useful for validating environment readiness (CI, fresh machines, etc.).
+
+---
+
+### Version
+
+To check the installed version:
+
+```bash
+pybundle version
+```
+
+---
+
+## 🧠 Ignore behavior (important)
+
+### If inside a Git repository
+
+pybundle uses **Git itself** to determine which files are included:
+
+* `.gitignore`
+* `.git/info/exclude`
+* global gitignore rules
+
+This guarantees pybundle sees the project **exactly as Git does**.
+
+### If Git is unavailable
+
+pybundle falls back to safe structural rules:
+
+* ignores `__pycache__`, `.ruff_cache`, `.mypy_cache`, `.pytest_cache`, etc.
+* detects virtual environments by structure (`pyvenv.cfg`, `bin/activate`), not by name
+  → works with `.venv`, `.pybundle-venv`, `env-prod-2025`, etc.
+
+No filename guessing. No surprises.
+
+---
+
+## 📜 Profiles
+
+pybundle is profile-driven. Each profile defines:
+
+* what files are collected
+* which tools run
+* what metadata is emitted
+
+Example profiles:
+
+* `analysis`
+* `source`
+* `minimal`
+
+Profiles are extensible - add your own without modifying core logic.
+
+---
+
+## 🔐 Safety & Redaction
+
+By default, pybundle:
+
+* avoids scanning known secret locations
+* supports optional redaction of sensitive strings in logs
+
+Use `--redact / --no-redact` to control behavior.
+
+---
+
+## 🧩 Why pybundle?
+
+pybundle is designed for:
+
+* handing a project to another engineer
+* attaching context to a bug report
+* feeding a codebase to AI tooling
+* generating CI artifacts
+* preserving “what exactly did we run?”
+* producing **AI-consumable project context** without guesswork
+
+It prioritizes **determinism, traceability, and automation** over clever heuristics.
+
+---
+
+## 🛠 Development Notes
+
+* Python ≥ 3.9
+* Uses modern tooling (ruff, mypy)
+* Fully type-checked
+* Formatter-clean
+* No test suite *yet* (intentional; coming later)
+
+During development, run:
+
+```bash
+python -m pybundle ...
+```
+
+to bypass shell caching.
+
+---
+
+## 📌 Versioning
+
+pybundle follows **Semantic Versioning**.
+
+Pinned Git tags are recommended when used as a dependency:
+
+```txt
+gwc-pybundle @ git+https://github.com/girls-whocode/pybundle.git@v0.4.2
+```
+
+---
+
+## 🧠 Philosophy
+
+> If a tool produces output, it should also produce metadata about **how** and **why** that output exists.
+
+pybundle treats context as a first-class artifact.
+
+---
+
+## 📦 Package naming note
+
+The distribution name on PyPI is **`gwc-pybundle`** to avoid conflicts with existing packages.
+
+The project name, imports, and CLI remain **`pybundle`**.
+
+```bash
+pip install gwc-pybundle
+pybundle run analysis
+```
+ Look in the autocreated `artifacts/` folder
+
+## 📄 License
+
+MIT License

gwc_pybundle-0.4.2.dist-info/RECORD

@@ -0,0 +1,34 @@
+gwc_pybundle-0.4.2.dist-info/licenses/LICENSE.md,sha256=ZmD484KG9hysmSMFT824y7aIc8lhFBnjkN-3DJNjXCc,1108
+pybundle/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pybundle/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+pybundle/cli.py,sha256=q9RkFbAK1YDcD-q1kgU8NPfKpLKAOTtbRzJuXwfwyO8,8132
+pybundle/context.py,sha256=_gStOHLCWDr_-ricMHnls1uzuW-8nSb2drkkm03AP0c,6714
+pybundle/doctor.py,sha256=P-WaokOGHWLiiQRN1gk7XveOz5CF_rraETvswbXmRw8,3149
+pybundle/manifest.py,sha256=hH5EMho9an-85uVy-JVeRs62UoDHSBTAc_UrvP2h1FY,2250
+pybundle/packaging.py,sha256=h1SmDj32EwLBGUgTI19IzaClC6k0r3irxM429iouAkg,1134
+pybundle/policy.py,sha256=HCSL8LcfbuAtmRqIS5TTQv38Wdsn-5ES-Yz6DtfFmss,4943
+pybundle/profiles.py,sha256=hl7BeNf9xibH7esm3T8VvfwM31qLDv6Q2UYdePF-R9M,4964
+pybundle/roadmap_model.py,sha256=27kfsQATbMZ8GNsblnNzspdeSVmzES5EJOGoLSwyHPM,1125
+pybundle/roadmap_scan.py,sha256=fJVuwmAOkAGELLzfmM0PCRjx3D9ufKw48WmSxsQXQ-E,9325
+pybundle/root_detect.py,sha256=d_HdA_usPxK1orc9cnNTY_fZrvdScQnI_f1XvvlHSFA,361
+pybundle/runner.py,sha256=WuTsZLJb1n43dMpDwKcEBthKHMSE2n59r1h0xcpxiLA,2060
+pybundle/tools.py,sha256=TNlMVodj1mcdjzaTlfwyZbjQ49ZVGqvd7KcQuEEgV2Q,116
+pybundle/steps/base.py,sha256=9LZwPYlGAWfnIe5DRbfP89ZmMLhbmOm9SQ-vWmQANHA,356
+pybundle/steps/compileall.py,sha256=ZbaIAPVG6pflqPaVfn5jSHcEC7qWncm_HIWUHokYdXg,2371
+pybundle/steps/context_expand.py,sha256=pG1-59RqQFIdTlMj5CJ65b8Or9qNk8LgudntdT10m7M,7986
+pybundle/steps/copy_pack.py,sha256=6M0_yToyLqkbe93qLRN0Cly0qGRoB4iZrSA5_mnLYQU,9284
+pybundle/steps/error_refs.py,sha256=mq1DGXREQRudycyPb7H0obkHmv3HvO-QPPbf2zoZDu0,5640
+pybundle/steps/handoff_md.py,sha256=fZGOQ5EdOz8vJfcwSYOiwPLJpO8CWrACIP3060RtUwY,6215
+pybundle/steps/mypy.py,sha256=x3df4BiJe0X47u-bw_JAC4IE1cgymAVhwagvWClWiPg,1916
+pybundle/steps/pytest.py,sha256=Bi89ZW1F1EEPGII2wlDLlXahvaHEflXD9q8rTJMSLs0,2102
+pybundle/steps/repro_md.py,sha256=EvoNVKaHFelfrv_jfBLpbkORTiDSjah3GgWXW3NvEXY,4856
+pybundle/steps/rg_scans.py,sha256=TT7PkxJSRszIzgN23VkEbX94ReGRJ1SQARLB__xBS2M,2436
+pybundle/steps/roadmap.py,sha256=wticWSzqw4EZqI7lOeSRqbBSW19FAjG8ijln8d_CUXM,5865
+pybundle/steps/ruff.py,sha256=iI_c8Q0cGsul2oOvyzA7BLA2kV4C8EtmsuL-L3MHHx8,3726
+pybundle/steps/shell.py,sha256=N5uH5CRro2UP1oya1eP5J8IXvwPuOimbHkC1_Ua-sa8,2143
+pybundle/steps/tree.py,sha256=sgRleTPgjAb9PnSAletpnybd5BirLNqauuEaTRidcWQ,4147
+gwc_pybundle-0.4.2.dist-info/METADATA,sha256=UY0Z174jEU1cLUcIpWMECg0fjzVLD004AhpYP537RHo,11695
+gwc_pybundle-0.4.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+gwc_pybundle-0.4.2.dist-info/entry_points.txt,sha256=xgXfIvyx9ZI6jd9MscFWNMzQrcX4scTVJ9L7WwksUHg,47
+gwc_pybundle-0.4.2.dist-info/top_level.txt,sha256=N5x3QutDUtHQn3HwkFmH5PeM9uPY-E5wOKUJSE8PBKM,9
+gwc_pybundle-0.4.2.dist-info/RECORD,,

gwc_pybundle-0.4.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gwc_pybundle-0.4.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pybundle = pybundle.cli:main

gwc_pybundle-0.4.2.dist-info/licenses/LICENSE.md

@@ -0,0 +1,25 @@
+The MIT License (MIT)
+=====================
+
+Copyright © 2025 Jessica Brown
+
+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.

gwc_pybundle-0.4.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+pybundle

pybundle/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())