Metadata-Version: 2.4
Name: churn-cli
Version: 0.4.2
Summary: Read your codebase. Generate interview questions or full project docs.
Author: dhawalshankar
Project-URL: Homepage, https://github.com/DhawalShankar/project-churn
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: google-genai
Requires-Dist: click
Requires-Dist: python-dotenv
Requires-Dist: questionary
Requires-Dist: markdown
Provides-Extra: pdf
Requires-Dist: xhtml2pdf; extra == "pdf"
Provides-Extra: groq
Requires-Dist: groq>=0.4.0; extra == "groq"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: all
Requires-Dist: xhtml2pdf; extra == "all"
Requires-Dist: groq>=0.4.0; extra == "all"
Requires-Dist: openai>=1.0.0; extra == "all"

# Churn
> One command. Every doc your project needs. Every question your interview demands.

---

## Install

```bash
pip install churn-cli
```

For PDF export support (`--only pdf`):

```bash
pip install "churn-cli[pdf]"
```

For Groq or OpenAI as your provider:

```bash
pip install "churn-cli[groq]"
pip install "churn-cli[openai]"
```

Requires Python 3.8+. By default Churn uses Gemini — get a free key at [aistudio.google.com](https://aistudio.google.com).

---

## Usage

Churn has two main commands: `interview` for interview prep, and `docs` for documentation generation. Point either at a local folder **or a public/private GitHub repo URL** — Churn clones it to a temp folder, scans it, and deletes the clone automatically when it's done.

```bash
churn interview /path/to/your/project
churn interview https://github.com/owner/repo

churn docs /path/to/your/project
churn docs https://github.com/owner/repo
```

First run pe active provider ka API key maangega — ek baar enter karo, save ho jaata hai globally (`~/.churn/config.json`).

---

## `churn interview`

Generates level-wise interview Q&A from your codebase.

```bash
churn interview /path/to/project
churn interview https://github.com/owner/repo                # works directly on a GitHub repo
churn interview /path/to/project --level senior          # skip interactive prompt
churn interview /path/to/project --questions 15           # custom question count (default: 10)
churn interview /path/to/project --output report.md        # custom output file
churn interview /path/to/project --format json             # json output instead of markdown
churn interview /path/to/project --ignore tests/ --ignore migrations/   # skip folders
```

### Options

```
-q, --questions INTEGER           Number of questions  [default: 10]
-l, --level [fresher|mid|senior]  Skip prompt, set level directly
-o, --output TEXT                 Output file  [default: churn-output.md]
-f, --format [md|json]            Output format  [default: md]
-i, --ignore TEXT                 Extra folders to ignore (repeatable)
```

### Output Example

```markdown
# Churn — MID Level

**Q1: In `matchingService.js`, what are the three criteria for a perfect match?**

The `findMatches` function checks: same campus, userProfile's wantedElectives includes
student's currentElective, and student's wantedElectives includes userProfile's currentElective.

---
```

---

## `churn docs`

Generates complete project documentation from your codebase.

```bash
churn docs /path/to/project
churn docs https://github.com/owner/repo               # works directly on a GitHub repo
churn docs /path/to/project --only readme,prd          # generate only specific docs
churn docs /path/to/project --only readme,prd,arch,pdf # include a combined PDF report
churn docs /path/to/project --output my-docs/           # custom output folder
churn docs /path/to/project --ignore tests/             # skip folders
churn docs /path/to/project --force                     # regenerate even if code is unchanged
```

### Options

```
--only TEXT        Comma separated: readme, prd, arch, pdf  [default: readme,prd,arch]
-o, --output TEXT  Output folder  [default: churn-docs/]
-i, --ignore TEXT  Extra folders to ignore (repeatable)
--force            Regenerate every doc even if the code hasn't changed since the last run
```

### Output

```
churn-docs/
├── README.md       — what it does, setup, usage, tech stack
├── PRD.md          — problem, features, roadmap inferred from code
├── ARCHITECTURE.md — folder structure, data flow, key files
└── REPORT.pdf       — all three combined, shareable (only with --only ...,pdf)
```

Each doc is generated strictly from what's in the code — README, PRD, and ARCHITECTURE
don't invent features, flags, or files that aren't actually there. The PRD's roadmap
section is inferred from real TODOs and unfinished code paths, not guesses.

**Smart caching:** Churn hashes your compressed code on every run. If nothing's changed
since the last `docs` run, unchanged doc types are skipped instead of re-generated — saving
API calls. Use `--force` to regenerate anyway. If a doc already exists, Churn *updates* it
instead of rewriting from scratch, preserving wording that's still accurate. This caching is
stable even for GitHub URLs — re-cloning the same repo produces the same hash.

> PDF export uses `xhtml2pdf` (pure Python) — no native GTK/Cairo dependencies, so it
> works out of the box on Windows, macOS, and Linux. Requires `pip install "churn-cli[pdf]"`.

---

## GitHub URL Support

Both `churn interview` and `churn docs` accept a GitHub repo URL in place of a local path:

```bash
churn interview https://github.com/owner/repo
churn docs https://github.com/owner/repo --only readme,prd
```

What happens under the hood:
1. Churn shallow-clones the repo (`git clone --depth 1`) into a temp directory
2. Scans and compresses it exactly like a local project
3. Deletes the temp clone the moment it's done — success or failure, the clone never survives past the command

Public repos work with no setup. For **private repos** (or to avoid GitHub's low unauthenticated
rate limits), set a token first:

```bash
churn auth github                          # interactive prompt
churn auth github --token ghp_xxxxxxxx     # non-interactive
churn auth github --logout                 # remove the stored token
```

> **Fine-grained PAT scope needed:** if you're using a fine-grained personal access
> token, "Repository access" alone isn't enough — under **Permissions → Repository
> permissions**, set **Contents** to at least **Read-only**, or cloning will fail with
> a `403` / "Write access to repository not granted" error even for private repos you own.

The token is stored the same way as AI provider keys — locally in `~/.churn/config.json`,
masked in `churn auth status` and `churn config show`, never transmitted anywhere except
directly to GitHub during the clone. You can also set it via the `GITHUB_TOKEN` environment
variable instead.

---

## `churn auth`

Manage API key authentication per provider, and your GitHub token.

```bash
churn auth login                       # set/update key for the active provider
churn auth login --provider groq       # set/update key for a specific provider
churn auth logout                      # remove key for the active provider
churn auth logout --provider openai    # remove key for a specific provider
churn auth status                      # show active provider + masked key status for all providers + GitHub
churn auth github                      # set/update your GitHub token (for GitHub URL support)
churn auth github --logout             # remove the stored GitHub token
```

---

## `churn config`

View and edit local Churn configuration.

```bash
churn config show                  # print full config (API keys + GitHub token masked)
churn config set theme dark        # set a non-secret config value
churn config provider              # interactively switch active provider
churn config provider groq         # switch active provider directly
churn config open                  # print (and try to open) the config file location
```

> `api_key`, `providers`, and `active_provider` can't be changed via `config set` —
> use `churn auth login` / `churn auth github` and `churn config provider` for those.

---

## `churn update`

Check PyPI for a newer version and self-update.

```bash
churn update
churn --update   # equivalent global flag
```

---

## Global Flags

```bash
churn --version   # show version
churn --update    # check for and install the latest version from PyPI
churn --help      # show all commands and options
```

---

## What It Does

Churn scans a local project directory (or clones a GitHub URL), identifies the most frequently edited files using `git log`, compresses the code, and sends it to your active AI provider (Gemini by default, Groq or OpenAI as alternatives).

- `churn interview` returns interview questions with detailed answers, saved as markdown or JSON.
- `churn docs` returns a full documentation set (README, PRD, ARCHITECTURE, and an optional combined PDF report).

---

## Providers

Churn supports multiple AI providers — switch anytime with `churn config provider`:

| Provider | Model | Notes |
|---|---|---|
| **Gemini** (default) | `gemini-flash-latest` | Auto-falls back to `gemini-2.5-flash` on 503. Most generous free tier of the three. |
| **Groq** | `llama-3.3-70b-versatile` | Requires `pip install "churn-cli[groq]"`. Free tier has a daily token cap that resets ~24h after it's hit. |
| **OpenAI** | `gpt-4o-mini` | Requires `pip install "churn-cli[openai]"`. No auto-renewing free tier — needs prepaid credits added at platform.openai.com before use. |

Keys can also be set via environment variables instead of `churn auth login`:
`GEMINI_API_KEY`, `GROQ_API_KEY`, `OPENAI_API_KEY` — these take precedence over stored keys.

---

## Files Scanned

**Included:** `.py` `.js` `.ts` `.tsx` `.jsx` `.java` `.go` `.cpp` `.env.example`

**Ignored:** `node_modules/` `.git/` `dist/` `build/` `__pycache__/` `.next/` `venv/` `churn-env/` `.env`

User can pass additional folders to ignore via `-i/--ignore` (repeatable).

---

## Privacy

- No code is stored at any point
- Everything runs locally — no backend server
- Code is sent to your active provider's API for processing only
- `.env` files are never scanned — hardcoded in the ignore list
- API keys and your GitHub token are stored locally at `~/.churn/config.json` (file permissions locked to owner-only where supported), never transmitted anywhere else
- GitHub clones are deleted immediately after scanning, whether the run succeeds or fails

---

## Tech Stack

- Python 3.8+
- `click` — CLI framework
- `questionary` — interactive prompts
- `python-dotenv` — environment variables
- `google-genai` — Gemini API SDK
- `groq` — Groq API SDK (optional)
- `openai` — OpenAI API SDK (optional)
- `markdown` + `xhtml2pdf` — PDF report export (optional)
- `git` (system binary) — repo history scanning and GitHub URL cloning

---

## Local Development

```bash
git clone https://github.com/DhawalShankar/project-churn
cd project-churn
python -m venv venv
venv\Scripts\activate        # Windows
source venv/bin/activate     # Mac/Linux
pip install -e ".[pdf]"
churn interview /path/to/project
churn docs /path/to/project
```

---

## Roadmap

- [x] PyPI publish — `pip install churn-cli`
- [x] Custom question count — `--questions`
- [x] Custom output path — `--output`
- [x] JSON export — `--format json`
- [x] Skip folders — `--ignore`
- [x] `churn docs` — README, PRD, ARCHITECTURE generation
- [x] PDF export — `REPORT.pdf`
- [x] Multi-provider support (Groq, OpenAI) — `churn config provider`
- [x] Self-update — `churn update` / `--update`
- [x] Doc caching — skip unchanged docs, update instead of rewrite
- [x] GitHub public **and private** repo URL support — clone, scan, auto-cleanup + `churn auth github`
- [ ] VS Code Extension
- [ ] Custom focus flag — `--focus security`
- [ ] Rich progress bars (replace plain `click.echo` status lines)

---

## License

Personal project. All rights reserved.
© 2026 dhawalshankar
