Metadata-Version: 2.4
Name: peek-dev
Version: 0.1.0
Summary: AI-powered developer companion for understanding, monitoring, and maintaining AI-generated codebases
License: MIT
Project-URL: Homepage, https://github.com/pramod/peek
Project-URL: Repository, https://github.com/pramod/peek
Project-URL: Issues, https://github.com/pramod/peek/issues
Keywords: developer-tools,cli,code-analysis,ai,debugging,dependency-graph,code-health,prompt-tracking
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer[all]>=0.12.0
Requires-Dist: rich>=13.0.0
Requires-Dist: networkx>=3.2
Requires-Dist: gitpython>=3.1.40
Provides-Extra: graph
Requires-Dist: matplotlib>=3.7.0; extra == "graph"
Provides-Extra: ai
Requires-Dist: openai>=1.0.0; extra == "ai"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"

# Peek

> **AI-powered developer companion** — understand, monitor, and maintain your codebase.

[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Peek sits beside your AI coding tools (Copilot, ChatGPT, Cursor) and builds **contextual intelligence** about your repository. It tracks which prompt generated which code, maps your codebase architecture, and can trace bugs back to the exact prompt that introduced them.

---

## Installation

```bash
pip install peek-dev
```

Or install from source:

```bash
git clone https://github.com/pramod/peek
cd peek
pip install -e .
```

**Requirements**: Python 3.9+, git (optional but recommended)

---

## Quick Start

```bash
# 1. Initialise Peek in your project
cd your-project/
peek init

# 2. See your codebase as a feature map
peek map

# 3. Log the prompt you just used to generate code
peek log "Create the authentication module with JWT support"

# 4. Get a health score for your repo
peek health

# 5. Trace a bug back to its originating prompt
peek debug
```

---

## Commands

### `peek init`
Initialises Peek in the current directory. Creates `.peek/peek.db` for prompt tracking and scaffolds missing project files (`src/`, `tests/`, `docs/`, `README.md`).

```
$ peek init

╭─────── ** Peek Initialized ───────╮
│  Project     my-project            │
│  Type        python                │
│  Files found 12 Python file(s)     │
│                                    │
│  Created                           │
│  + src/                            │
│  + tests/                          │
│  + docs/                           │
╰────────────────────────────────────╯
```

---

### `peek map`
Groups your Python files by folder and displays a feature map — your codebase at a glance.

```
$ peek map

  Feature Map
 ┌──────────────┬─────────────────────────────┬───────┐
 │ Feature      │ Files                       │ Count │
 ├──────────────┼─────────────────────────────┼───────┤
 │ cli          │ · cli/commands.py            │     1 │
 │ core         │ · core/repo_scanner.py       │     3 │
 │              │ · core/git_history.py        │       │
 │              │ · core/dependency_graph.py   │       │
 └──────────────┴─────────────────────────────┴───────┘
```

---

### `peek log "<prompt>"`
Logs the AI prompt you just used and links it to the files that changed. **This is the data that powers `peek debug`.**

```bash
peek log "Add checkout flow with cart integration"
```

Run this immediately after using an AI tool to generate code.

---

### `peek debug`
Peeks signature feature. Diffs recent git commits, finds which logged prompt touched the changed files, and shows the downstream blast radius through your import graph.

```
$ peek debug

Recently Changed Files
└── checkout_service.py

Suspect Prompts
╭─────────────────────────────────────────╮
│  Prompt #4  abc1234                      │
│  "Add checkout flow with cart integration"│
│  Touched: checkout_service.py, cart.py   │
╰─────────────────────────────────────────╯

Downstream Affected Files
  → order_service.py
  → payment_handler.py
```

---

### `peek health`
Scores your repository out of 100 across four dimensions: test coverage, duplicate logic, documentation, and circular dependencies.

```
$ peek health

╭─────── Repository Health ──────────╮
│  Score:  72 / 100   Grade: C       │
│  ████████████████░░░░░░░░░░░░░░░░  │
╰────────────────────────────────────╯

 Category         Severity   Detail
 Test Coverage    MEDIUM     8 of 14 modules have no tests
 Duplicate Logic  LOW        1 duplicate function group detected
```

---

## How It Works

```
peek log "prompt"   →  captures git state + links changed files
peek debug          →  git diff → prompt DB lookup → graph traversal
peek health         →  AST analysis → weighted score (no ML required)
peek map            →  file tree walk → feature grouping
```

All analysis is **local and offline**. No data leaves your machine.

---

## Design Decisions

| Choice | Reason |
|--------|--------|
| Python-only (v1) | AST module is built-in, no extra deps |
| SQLite storage | Built into Python, fast, queryable |
| Git diff + graph traversal | Deterministic debugging without ML |
| Typer + Rich | Beautiful terminal output, auto-generated help |

---

## Roadmap

- **Phase 2**: `peek security`, `peek graph`, `peek clean`, PyPI publishing
- **Phase 3**: `peek architect` (AI suggestions), `peek monitor` (background watcher), VS Code extension

---

## License

MIT
