Metadata-Version: 2.4
Name: commitclinic
Version: 0.1.7
Summary: Repository triage CLI for migration readiness and cleanup planning
Author: CommitClinic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: setuptools-scm>=8; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

# CommitClinic

CommitClinic is a repository migration triage CLI. It diagnoses Git repositories (and legacy repos once mirrored to Git), scores migration readiness, and plans safe treatment actions.

## Vibe

CommitClinic uses a medical triage voice:
- Intake: collect repository baseline.
- Diagnosis: identify risk findings.
- Severity: assign A-F readiness grade.
- Treatment Plan: propose cleanup actions.
- Discharge: final migration readiness status.

## Install

**macOS (Homebrew — recommended):**
```bash
brew tap CptPlastic/commitclinic https://github.com/Cptplastic/commitclinic
brew install commitclinic
```

**pip:**
```bash
pip install commitclinic
```

**pipx (isolated install):**
```bash
pipx install commitclinic
```

**From source:**
```bash
git clone https://github.com/your-org/commitclinic
cd commitclinic
pipx install .
```

**Install helper tools (BFG + TruffleHog):**
```bash
commitclinic install-tools
```

## Quick Start

1. Run intake + diagnosis:

```bash
commitclinic intake --repo /path/to/repo --json-out reports/findings.json --csv-out reports/findings.csv
```

3. Print scoring summary:

```bash
commitclinic diagnose --input reports/findings.json
```

## Core Commands

- `commitclinic intake`: scan a repository and generate findings.
- `commitclinic diagnose`: compute score and grade from findings JSON.
- `commitclinic treatment-plan`: generate remediation suggestions.
- `commitclinic treat`: execute approved history cleanup actions.
- `commitclinic install-tools`: install optional helper tools (such as BFG).
- `commitclinic discharge`: produce final readiness summary.
- `commitclinic batch`: scan multiple repositories from a local paths file.
- `commitclinic scan-list`: clone and scan repos from a JSON URL list.
- `commitclinic ui`: launch an interactive terminal dashboard.

`commitclinic treat` is destructive. It requires `--approve` and should be run only after backup.

## BFG Support

CommitClinic supports BFG as a treatment backend.

1. Install BFG jar via CommitClinic:

```bash
commitclinic install-tools --with-bfg
```

2. Run treatment with BFG:

```bash
commitclinic treat --repo /path/to/repo --backend bfg --strip-path secrets.txt --approve
```

Notes:
- BFG deletes by filename pattern; exact path deletions are best handled with `git-filter-repo`.
- You can set `BFG_JAR=/path/to/bfg-1.14.0.jar` in CI/local environments to pin the jar.

## Terminal TUI

Run the interactive terminal dashboard:

```bash
commitclinic ui --repo /path/to/repo
```

Shorter launch options also work:

```bash
commitclinic ui
commitclinic tui
commitclinic dashboard
```

If `--repo` is omitted, CommitClinic uses the current directory.

Keyboard controls:
- `i`: run intake
- `d`: refresh diagnosis
- `p`: preview treatment plan
- `w`: write report JSON to temp directory
- `j`/`k` or arrow keys: move selected finding
- `t`: run treatment for selected finding path (prompts for `y` confirmation)
- `q`: quit

The TUI is intended for local triage sessions. Use standard non-interactive commands in CI and GitHub Actions.

TUI treatment notes:
- The `t` action uses `git-filter-repo` for selected finding paths.
- If selected finding has no path location, treatment is blocked.

## TruffleHog Integration

If `trufflehog` is installed and available in `PATH`, CommitClinic runs it automatically during intake.
If not installed, CommitClinic logs a non-blocking warning finding so you can still run a full pipeline.

## Scanning a List of Remote Repos

Create a JSON file with the repos you want to audit:

```json
{
  "repos": [
    { "url": "https://github.com/org/repo-one", "name": "repo-one" },
    { "url": "https://github.com/org/repo-two", "name": "repo-two" }
  ]
}
```

A flat array of URL strings also works:
```json
["https://github.com/org/repo-one", "https://github.com/org/repo-two"]
```

Run the scan:
```bash
commitclinic scan-list repos.json --work-dir ~/scratch/clones
```

Results are written to `repos.results.json` (alongside the list file) after **each repo**, so if the process is interrupted mid-list you don't lose progress. Re-running skips repos that are already in the results file. Use `--refresh` to re-scan everything.

```bash
# Custom output path:
commitclinic scan-list repos.json --out results/audit.json

# Exit 2 if any repo has blocking findings (useful in CI):
commitclinic scan-list repos.json --strict

# Re-scan all, even previously scanned:
commitclinic scan-list repos.json --refresh
```

## GitHub Actions

Starter workflows for CI are available in the [source repository](https://github.com/your-org/commitclinic).
