Metadata-Version: 2.4
Name: towow-progress
Version: 0.1.1
Summary: AI-native development progress dashboard — turn your git history into a beautiful narrative page.
Project-URL: Homepage, https://towow.net
Project-URL: Repository, https://github.com/NatureBlueee/Towow
Author-email: Towow <hello@towow.net>
License-Expression: MIT
Keywords: ai,dashboard,developer-tools,git,progress
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# towow-progress

Turn your git history into a beautiful, artistic progress page. Not a boring dashboard — a narrative that tells your project's story.

![MIT License](https://img.shields.io/badge/license-MIT-blue)

## Quick Start

```bash
pip install towow-progress
cd your-repo
towow-progress init        # auto-detect modules, create config
towow-progress generate    # build docs/progress.html
open docs/progress.html    # done!
```

## Let Your AI Set It Up

Paste this to Claude, ChatGPT, or any coding AI:

> Install `towow-progress`, run `towow-progress init` on this repo, then customize `.towow-progress.json` — set a good title, subtitle, and adjust module names to be human-readable. Then run `towow-progress generate` and open the result.

Your AI will analyze your repo structure and configure everything.

## What You Get

- **Hero section** — total commits, lines changed, active days, longest streak
- **Live indicator** — latest commit with relative time ("3m ago")
- **Scrollable timeline** — daily commit activity with peak highlights
- **Module trends** — stacked area chart showing strategic focus shifts
- **Distribution** — horizontal bar chart of code by module
- **Weekly velocity** — line chart with acceleration/deceleration analysis
- **Changelog** — expandable recent commits with type badges, file counts, diffs

Single self-contained HTML file. Works offline. Deploy anywhere.

## Configuration

`towow-progress init` creates `.towow-progress.json`:

```json
{
  "title": "My Project Progress",
  "subtitle": "Built by a team of 3 over 120 days",
  "lang": "en",
  "modules": {
    "src": "Core Engine",
    "api": "API Layer",
    "web": "Frontend",
    "tests": "Test Suite",
    "docs": "Documentation"
  },
  "colors": {
    "src": "#1D4ED8",
    "api": "#059669",
    "web": "#EA580C",
    "tests": "#7C3AED",
    "docs": "#0891B2"
  },
  "output": "docs/progress.html",
  "accent_color": "#1D4ED8",
  "accent_secondary": "#EA580C",
  "background": "#F7F4F0",
  "font_family": "",
  "branding": true
}
```

### What you can customize

| Field | What it does | Example |
|-------|-------------|---------|
| `title` | Big hero title | `"Acme Engine"` |
| `subtitle` | Line under the title | `"3 engineers · 200 days"` |
| `modules` | Map directory prefixes to display names | `{"src": "Core"}` |
| `colors` | Hex color per module | `{"src": "#1D4ED8"}` |
| `accent_color` | Primary brand color (borders, links, charts) | `"#8B5CF6"` (purple) |
| `accent_secondary` | Highlight color (peaks, badges) | `"#F59E0B"` (amber) |
| `background` | Page background | `"#FAFAF9"` (stone) |
| `font_family` | Custom font stack | `"'JetBrains Mono', monospace"` |
| `output` | Where to write the HTML | `"public/progress.html"` |
| `branding` | Show "Powered by Towow" footer | `true` / `false` |

### Color presets

**Default (warm ivory + blue)**
```json
{ "accent_color": "#1D4ED8", "accent_secondary": "#EA580C", "background": "#F7F4F0" }
```

**Dark academia**
```json
{ "accent_color": "#78350F", "accent_secondary": "#B45309", "background": "#FEFCE8" }
```

**Cyberpunk**
```json
{ "accent_color": "#7C3AED", "accent_secondary": "#EC4899", "background": "#FAF5FF" }
```

**Forest**
```json
{ "accent_color": "#065F46", "accent_secondary": "#D97706", "background": "#F0FDF4" }
```

## Auto-Update with GitHub Actions

```bash
towow-progress setup-ci
```

This creates `.github/workflows/towow-progress.yml`. On every push to `main`, it regenerates and commits the HTML.

**Deploy to GitHub Pages:**
1. Run `towow-progress setup-ci`
2. Go to repo Settings → Pages → Source: `Deploy from a branch` → Branch: `main`, folder: `/docs`
3. Push. Your progress page is live at `https://username.github.io/repo/progress.html`

## How It Works

1. **Scans git history** — `git log --numstat` to get per-file additions/deletions
2. **Classifies files** — maps file paths to modules using your config
3. **Computes analytics** — daily/weekly/monthly aggregations, velocity, streaks
4. **Renders HTML** — single file with inline CSS + Chart.js from CDN

No database. No server. No API keys. Just git + Python.

---

Powered by [Towow](https://towow.net) — AI-native collaboration protocol
