Metadata-Version: 2.4
Name: gitgrow
Version: 0.1.0a1
Summary: AI developer agent for clean commits, docs, changelogs, and GitHub progress.
Author: GitGrow
License-Expression: MIT
Keywords: ai,automation,commits,developer-tools,git
Requires-Python: >=3.10
Requires-Dist: gitpython>=3.1
Requires-Dist: openai>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# GitGrow

> **Build daily. Commit cleanly. Grow visibly.**

GitGrow is a Python-first AI developer CLI agent that converts real coding work into clean commits, updated documentation, changelogs, dev logs, and meaningful GitHub activity.

**Status: v0.1.0-alpha — Python CLI MVP**

---

## Why GitGrow?

Most developers do real work but lose track of it. Commit messages are vague, documentation falls behind, and progress feels invisible. GitGrow fixes this by sitting between your editor and Git — scanning what changed, generating professional commit messages, keeping docs in sync, and creating daily progress records.

This is not a fake activity bot. GitGrow only commits real changes you approve.

---

## Installation

```bash
pip install gitgrow
```

**Requirements:**

- Python 3.10 or higher
- Git
- Optional: [GitHub CLI](https://cli.github.com) for GitHub authentication
- Optional: OpenAI API key for AI-powered commit messages (fallback works without it)

---

## Quick Start

```bash
cd my-project
gitgrow init
gitgrow auth github
gitgrow scan
gitgrow commit
```

---

## Commands

| Command | Description |
|---|---|
| `gitgrow init` | Initialize GitGrow inside any git repository |
| `gitgrow auth github` | Connect to GitHub using the GitHub CLI |
| `gitgrow scan` | Scan current changes and classify their impact |
| `gitgrow commit` | Generate a commit message, preview it, and commit |
| `gitgrow docs` | Sync README, CHANGELOG, and docs with changes |
| `gitgrow daily` | Create a dated daily progress devlog |
| `gitgrow sync` | Run docs and daily together |

---

## Example Workflow

```bash
# One-time setup
cd my-project
gitgrow init
gitgrow auth github

# Daily workflow
# ... make some code changes ...
gitgrow scan        # see what changed and how it's classified
gitgrow commit      # generate → preview → approve → commit
gitgrow daily       # create today's progress log
```

### What `gitgrow commit` does

```
Scan git diff
    ↓
Classify change type (feat / fix / docs / test / refactor / ...)
    ↓
Run safety checks (tests, linters, secret scan)
    ↓
Generate commit message (AI or deterministic fallback)
    ↓
Show preview for review
    ↓
Confirm → stage → commit
    ↓
Optional push
```

---

## Commit Messages

GitGrow generates [Conventional Commit](https://www.conventionalcommits.org) style messages:

```
feat(auth): add JWT authentication flow
fix(api): handle missing token errors
docs(readme): update setup instructions
test(auth): add login validation tests
```

Messages are always shown for review before commit. You can edit or cancel at any point.

---

<!-- GITGROW:FEATURES:START -->
<!-- GITGROW:FEATURES:END -->

## AI and Fallback Mode

GitGrow works in two modes:

**AI mode** (requires `OPENAI_API_KEY`):

```bash
export OPENAI_API_KEY=sk-...
gitgrow commit
```

Uses GPT-4o-mini to generate context-aware commit messages, doc updates, changelog entries, and devlogs.

**Fallback mode** (no API key needed):

```bash
gitgrow commit  # works without OPENAI_API_KEY
```

Uses deterministic, rule-based generation from the diff. Always produces valid Conventional Commit messages. No API calls, no network required.

---

## DocSync

When GitGrow detects significant changes (new features, API routes, env vars, dependencies), `gitgrow docs` updates your documentation safely using controlled blocks:

```md
<!-- GITGROW:FEATURES:START -->
(GitGrow updates only this section)
<!-- GITGROW:FEATURES:END -->

<!-- GITGROW:SETUP:START -->
<!-- GITGROW:SETUP:END -->

<!-- GITGROW:API:START -->
<!-- GITGROW:API:END -->
```

Content outside these blocks is never touched unless you use `--no-safe-only`.

---

## Safety Principles

- **Nothing commits without your approval.** Every commit requires explicit confirmation by default.
- **No secrets committed.** GitGrow scans diffs for API keys, tokens, and credentials and blocks them.
- **No empty commits.** Blocked at the pre-commit stage.
- **No token storage.** GitHub authentication uses the GitHub CLI — no raw tokens are saved anywhere.
- **Tests run first.** Configure check commands in `.gitgrow/config.yml` and they run before every commit.
- **You can always skip checks** with `gitgrow commit --skip-checks` but you will be warned.

---

## GitHub Authentication

GitGrow uses the [GitHub CLI](https://cli.github.com) for MVP authentication:

```bash
gitgrow auth github
```

This runs `gh auth login` if needed, reads your username, and stores only connection metadata (no tokens) in `.gitgrow/config.yml`.

---

<!-- GITGROW:SETUP:START -->
<!-- GITGROW:SETUP:END -->

## Configuration

After `gitgrow init`, a config file is created at `.gitgrow/config.yml`:

```yaml
project:
  name: my-project
  type: python

git:
  remote: origin
  default_branch: main
  auto_push: false

checks:
  enabled: true
  before_commit:
    - pytest
    - ruff check .

safety:
  require_confirmation: true
  block_secrets: true
  allow_empty_commits: false

ai:
  enabled: true
  provider: openai
  model: gpt-4o-mini
```

---

## DevLog

`gitgrow daily` creates a dated progress log at `devlog/YYYY/MM/YYYY-MM-DD.md`:

```md
# Progress Log - 2025-01-15

## Today's Momentum
Implemented JWT authentication and added test coverage for login flow.

## What Changed
- src/auth/login.py
- tests/test_auth.py

## What I Learned
JWT expiry handling needs to account for clock skew.

## Next Small Step
Add refresh token support.
```

---

## Files Created by `gitgrow init`

```
gitgrow.md              # human-readable project instructions for GitGrow
.gitgrow/config.yml     # machine config (YAML)
.gitgrowignore          # files GitGrow won't scan
devlog/                 # dated progress logs
```

---

<!-- GITGROW:API:START -->
<!-- GITGROW:API:END -->

## Current Status

**v0.1.0-alpha** — Python CLI MVP

This is the first alpha release. The local CLI workflow is fully functional. The following are not yet implemented:

- GitHub App (planned for Phase 10)
- npm wrapper (planned for later)
- Hosted dashboard or team mode
- PyPI distribution (TestPyPI verification in progress)

---

## Roadmap

| Phase | Status | Description |
|---|---|---|
| Phase 0 | Done | Product definition |
| Phase 1 | Done | Python CLI foundation |
| Phase 2 | Done | `gitgrow init` |
| Phase 3 | Done | `gitgrow auth github` |
| Phase 4 | Done | Project scanner |
| Phase 5 | Done | Smart commit writer |
| Phase 6 | Done | DocSync |
| Phase 7 | Done | Safety checks |
| Phase 8 | Done | DevLog |
| Phase 9 | Done | Git executor |
| Phase 10 | Planned | GitHub App |
| Phase 11 | In progress | PyPI release |
| Phase 12 | Planned | Public launch |

---

## Contributing

Issues and pull requests are welcome. See [docs/security.md](docs/security.md) for security notes.

---

## License

MIT
