wip-cli 0.1.0__tar.gz

wip_cli-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug Report
+about: Report a bug to help us improve wip
+title: "[Bug] "
+labels: bug
+assignees: ""
+---
+
+## Description
+
+A clear and concise description of the bug.
+
+## Steps to Reproduce
+
+1. Run `...`
+2. See error
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include any error messages or output.
+
+## Environment
+
+- **OS:** (e.g., macOS 15.2, Ubuntu 24.04)
+- **Python version:** (e.g., 3.12.1)
+- **wip version:** (output of `wip version`)
+- **Installation method:** (pip install -e ., etc.)
+
+## Additional Context
+
+Any other context, screenshots, or log output.

wip_cli-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement for wip
+title: "[Feature] "
+labels: enhancement
+assignees: ""
+---
+
+## Problem Description
+
+A clear description of the problem or limitation you're experiencing.
+
+## Proposed Solution
+
+Describe the solution you'd like. How should it work?
+
+## Alternatives Considered
+
+Describe any alternative solutions or features you've considered.
+
+## Additional Context
+
+Any other context, mockups, or examples that help explain the request.

wip_cli-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## Summary
+
+Brief description of what this PR does and why.
+
+## Changes
+
+-
+
+## Test Plan
+
+- [ ] Tested manually with `wip` / `wip --verbose` / `wip --json`
+- [ ] Verified no regressions in existing commands
+
+## Checklist
+
+- [ ] All new `.py` files include `from __future__ import annotations`
+- [ ] No new dependencies added without justification
+- [ ] Errors are handled gracefully (no unhandled exceptions)
+- [ ] Docs updated if applicable (`README.md`, `docs/CONTEXT.md`)

wip_cli-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project
+*.db
+.wip/
+
+# Testing / linting
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/

wip_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-02-12
+
+### Added
+
+- **Foundation & Scanner (Phase 0+1):** Config management (TOML read/write, interactive init), repo discovery, git status scanning (branch, dirty, stash, ahead/behind, recent branches/commits), Rich terminal display, CLI wiring (`wip`, `wip scan`, `wip config`, `--json`, `--verbose`)
+- **Interactive Worklist (Phase 2):** `wip add/done/list` commands with repo linking, persistent JSON state, worklist shown in briefing and under linked repos
+- **LLM Integration (Phase 4):** Provider abstraction (Anthropic implemented, OpenAI/Gemini stubs), `wip ai briefing`, `wip ai standup`, `wip ai ask` with streaming, prompt assembly from scan data, config-driven provider/model selection
+- **Passive Agent Detection (Phase 5):** Detect coding agent activity from git signals (author names, branch patterns), agent sessions in terminal/JSON/AI output, configurable patterns with sensible defaults, status tracking (active/recent/stale)
+- **Enriched File-Level Context (Phase 6):** Changed files with diff stats, stash descriptions, commit bodies and per-commit file lists in verbose output and LLM prompts
+
+[0.1.0]: https://github.com/drmnaik/wip/releases/tag/v0.1.0

wip_cli-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a friendly, safe, and welcoming experience for everyone.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Being respectful and considerate
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting, or derogatory comments
+- Personal or political attacks
+- Public or private forms of intimidation
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, including issues,
+pull requests, and discussions, as well as public spaces when an individual
+is representing the project.
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported to the project maintainer:
+
+- **LinkedIn:** [Mahesh Naik](https://www.linkedin.com/in/kamaheshnaik/)
+
+All reports will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

wip_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to wip
+
+Thanks for your interest in contributing to **wip**! This guide will help you get started.
+
+## Prerequisites
+
+- Python 3.9+
+- git
+
+## Dev Setup
+
+```bash
+# Fork and clone
+git clone git@github.com:<your-username>/wip.git
+cd wip
+
+# Create virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Install in editable mode (includes all dependencies)
+pip install -e .
+```
+
+## Code Conventions
+
+Please read `docs/CONTEXT.md` — specifically **Section 5 (Code conventions)** and **Section 10 (Guidelines for contributors)** — for the full picture. Key rules:
+
+- Every `.py` file **must** start with `from __future__ import annotations`
+- Use **dataclasses** for data models, plain functions for logic
+- No new dependencies without clear justification — prefer stdlib
+- Handle errors gracefully — never crash the whole briefing because one repo is broken
+- Follow existing import order: stdlib, third-party, local (`wip.*`)
+- Keep CLI commands thin — delegate logic to modules
+
+## Submitting a Pull Request
+
+1. **Fork** the repo and create a feature branch from `main`:
+   ```bash
+   git checkout -b feat/your-feature main
+   ```
+2. Make your changes following the code conventions above.
+3. **Commit** with a short imperative subject line (e.g., "Add stale branch detection"). Body explains _why_, not _what_.
+4. **Push** to your fork:
+   ```bash
+   git push origin feat/your-feature
+   ```
+5. Open a **Pull Request** against `main` on GitHub.
+
+## Good First Issues
+
+Looking for a place to start? These are great entry points:
+
+- **Implement the OpenAI provider** — `src/wip/llm/openai.py` is scaffolded as a stub
+- **Implement the Gemini provider** — `src/wip/llm/gemini.py` is scaffolded as a stub
+- **Add test coverage** — there are no tests yet; adding tests for any module is valuable
+
+## Contact
+
+- **LinkedIn:** [Mahesh Naik](https://www.linkedin.com/in/kamaheshnaik/)
+- **Issues:** [GitHub Issues](https://github.com/drmnaik/wip/issues)

wip_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mahesh Naik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wip_cli-0.1.0/LLM_CONTEXT.md

@@ -0,0 +1,74 @@
+# LLM_CONTEXT.md — Context for coding agents and bots
+
+> This file provides the context a coding agent or bot needs to understand and contribute to the `wip` project. For full architecture details, data models, and roadmap, see `docs/CONTEXT.md`.
+
+## Quick reference
+
+- **What:** CLI developer briefing tool — scans git repos, shows status, tracks work-in-progress items
+- **Stack:** Python 3.9+, Typer (CLI), GitPython (git), Rich (display), TOML (config), JSON (worklist), Anthropic/OpenAI/Gemini SDK (LLM)
+- **Build:** Hatchling, src-layout (`src/wip/`), entry point `wip = "wip.cli:app"`
+- **Config:** `~/.wip/config.toml`
+- **Worklist:** `~/.wip/worklist.json`
+
+## Rules
+
+1. Every `.py` file MUST start with `from __future__ import annotations`
+2. Python 3.9 minimum — no match/case, no `TypeAlias`, no 3.10+ features
+3. Use dataclasses for data models, plain functions for logic — no service classes
+4. Prefix private helpers with `_` — public API is everything without underscore
+5. Wrap all GitPython calls in try/except — never crash because one repo is broken
+6. No new dependencies without clear justification — prefer stdlib
+7. CLI commands go in `cli.py`, keep them thin, delegate to modules
+8. Errors use `raise typer.Exit(1)`, user messages use `typer.echo()`
+
+## Module map
+
+| Module           | Does what                            | Key exports                                  |
+|------------------|--------------------------------------|----------------------------------------------|
+| `cli.py`         | Commands, flags, orchestration       | `app`                                        |
+| `config.py`      | TOML config read/write               | `WipConfig`, `AgentsConfig`, `load_config()`, `save_config()`|
+| `discovery.py`   | Find git repos on disk               | `discover_repos()`                           |
+| `scanner.py`     | Collect git status + agent detection | `RepoStatus`, `AgentSession`, `FileChange`, `scan_repo()`, `scan_repos()` |
+| `display.py`     | Rich terminal output                 | `render_briefing()`, `render_json()`, `render_worklist()` |
+| `worklist.py`    | WIP task tracker, JSON persist       | `WorkItem`, `add_item()`, `complete_item()`, `get_items()`, `detect_repo()` |
+| `llm/base.py`    | ABC, response type, errors           | `LLMProvider`, `LLMResponse`, `LLMError` |
+| `llm/registry.py`| Provider lookup, key resolution      | `get_provider()`, `list_providers()` |
+| `llm/prompts.py` | Prompt assembly from scan data       | `build_briefing_prompt()`, `build_standup_prompt()`, `build_query_prompt()` |
+| `llm/anthropic.py`| Anthropic Claude (implemented)      | `AnthropicProvider` |
+| `llm/openai.py`  | OpenAI GPT (implemented)             | `OpenAIProvider` |
+| `llm/gemini.py`  | Google Gemini (implemented)          | `GeminiProvider` |
+
+## How to extend
+
+- **New scan data:** Add field to `RepoStatus` → populate in `scan_repo()` → render in `_render_repo()`
+- **New config field:** Add to `WipConfig` with default → update `load_config()`/`save_config()` → optionally add prompt in `config_init()`
+- **New CLI command:** Add `@app.command()` in `cli.py` → delegate to relevant module
+
+### Worklist
+
+- **New worklist field:** Add to `WorkItem` dataclass → update `add_item()` → render in `_render_work_item()`
+- **New worklist command:** Add `@app.command()` in `cli.py` → delegate to `worklist.py`
+
+### LLM
+
+- **New provider:** Create `llm/<name>.py` extending `LLMProvider` → implement `complete()` + `stream()` → register in `llm/registry.py` PROVIDERS dict. Follow the pattern in `anthropic.py`, `openai.py`, or `gemini.py`: lazy `_get_client()`, error mapping to `LLMAuthError`/`LLMRateLimitError`/`LLMError`, import guard for the SDK package.
+- **New AI command:** Add `@ai_app.command()` in `cli.py` → use `_get_llm_provider()` + `_scan_all()` + `_llm_call()`
+- **New prompt type:** Add `build_*_prompt()` to `llm/prompts.py` returning `(system, user)` tuple
+
+## Commands
+
+```bash
+pip install -e .          # Install in dev mode (includes all deps)
+wip                       # Run briefing
+wip --json                # JSON output
+wip --verbose             # Full detail
+wip config init           # Interactive setup
+wip config show           # Show config
+wip add "description"     # Add WIP item (auto-links to current repo)
+wip done <id>             # Mark item as done
+wip list                  # Show open items
+wip list --all            # Include completed items
+wip ai briefing           # AI narrative briefing
+wip ai standup            # Generate standup update
+wip ai ask "question"     # Ask about your work
+```

wip_cli-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: wip-cli
+Version: 0.1.0
+Summary: Where did I leave off? A developer briefing tool.
+Project-URL: Homepage, https://github.com/drmnaik/wip
+Project-URL: Repository, https://github.com/drmnaik/wip
+Project-URL: Issues, https://github.com/drmnaik/wip/issues
+Author: Mahesh Naik
+License: MIT
+License-File: LICENSE
+Keywords: briefing,cli,developer-tools,git,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Version Control :: Git
+Requires-Python: >=3.9
+Requires-Dist: anthropic>=0.79.0
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli>=1.0.0; python_version < '3.11'
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+# wip — Where did I leave off?
+
+A developer briefing tool. **wip** scans your git repositories and shows you what you were working on, what's dirty, what's stashed, and what needs your attention. With optional AI features, it turns raw git data into narrative briefings, standup drafts, and answers to natural language questions about your work.
+
+## Features
+
+- 🔍 **Auto-discover** git repos in configured directories
+- 📊 **Status overview** — dirty files, stashes, ahead/behind tracking
+- 🌿 **Recent branches** — see branches you've touched recently
+- 💬 **Recent commits** — your commits from the last 24 hours
+- 📝 **Work-in-progress tracker** — jot down tasks, link them to repos, see them in your briefing
+- 🎨 **Rich terminal output** — color-coded status with icons
+- 📦 **Multiple output modes** — human-friendly or JSON for scripting
+- 🕵️ **Agent detection** — passively detect coding agent activity (Claude, Copilot, Cursor, Devin) from git signals
+- 📂 **Enriched file-level context** — changed files with diff stats, stash descriptions, commit bodies and file lists in LLM prompts and verbose output
+- 🤖 **AI-powered briefings** — narrative summaries, standup drafts, natural language queries
+- 🧭 **Context-aware git help** — ask how to untangle branches, recover stashes, or fix mistakes — the AI sees your actual repo state
+- 🔌 **Provider abstraction** — Anthropic and OpenAI implemented, Gemini — all implemented
+
+## Installation
+
+```bash
+# Clone the repository
+git clone git@github.com:drmnaik/wip.git
+cd wip
+
+# Install in editable mode (includes all dependencies)
+pip install -e .
+```
+
+**Requirements:** Python 3.9+
+
+## Quick Start
+
+```bash
+# First-time setup (interactive)
+wip config init
+
+# Show your briefing
+wip
+
+# Verbose mode with full details
+wip --verbose
+
+# JSON output for scripting
+wip --json
+```
+
+## Configuration
+
+Config is stored at `~/.wip/config.toml`:
+
+```toml
+directories = ["/Users/you/projects", "/Users/you/work"]
+author = "Your Name"
+scan_depth = 3
+recent_days = 14
+
+[llm]
+provider = "anthropic"
+model = "claude-haiku-4-5-20251001"
+api_key_env = "ANTHROPIC_API_KEY"
+
+# Optional: customize agent detection patterns
+[agents]
+authors = ["claude", "copilot", "cursor", "devin", "codex", "github-actions", "bot"]
+branch_patterns = ["agent/", "claude/", "copilot/", "devin/", "cursor/"]
+```
+
+- **directories** — which directories to scan for git repos
+- **author** — your git author name (filters commits to show only yours)
+- **scan_depth** — how deep to search for repos (default: 3 levels)
+- **recent_days** — how far back to look for recent branches (default: 14 days)
+- **[llm]** — optional LLM configuration for AI features
+  - **provider** — `anthropic`, `openai`, or `gemini`
+  - **model** — model ID (leave empty for provider default)
+  - **api_key_env** — environment variable name holding your API key
+- **[agents]** — optional overrides for agent detection (works out of the box with defaults)
+  - **authors** — substrings matched case-insensitively against commit author names
+  - **branch_patterns** — branch name prefixes that indicate agent activity
+
+## Commands
+
+### Core
+
+```bash
+wip               # Show briefing (default command)
+wip scan          # Alias for wip
+wip --json        # Output as JSON
+wip --verbose     # Show full details
+wip config init   # Interactive setup
+wip config show   # Display current config
+wip version       # Show version
+```
+
+### Work-in-progress tracker
+
+```bash
+wip add "fix auth bug"                     # Add item (auto-links to current repo)
+wip add "read docs" --repo /path/to/repo   # Add item linked to specific repo
+wip done 1                                 # Mark item #1 as done
+wip list                                   # Show open items
+wip list --all                             # Show all items including completed
+```
+
+### AI-powered commands
+
+Requires an LLM provider configured in `~/.wip/config.toml` and the corresponding API key set as an environment variable.
+
+```bash
+wip ai briefing                 # Narrative briefing
+wip ai standup                  # Generate a standup update from git activity
+wip ai ask "what was I working on yesterday?"
+wip ai ask "anything I forgot to push?"
+wip ai ask "summarize my week"
+
+# Context-aware git help — the AI sees your actual branches, dirty files, and stashes
+wip ai ask "I have diverged branches, how do I cleanly get back to main?"
+wip ai ask "how do I recover what I stashed last week?"
+wip ai ask "what git commands do I need to untangle this mess?"
+```
+
+## Example Output
+
+### Standard briefing (`wip`)
+
+```
+ wip — 3 repos scanned
+
+ work-in-progress — 2 items
+
+  #1  fix auth token refresh (auth-service) — 2h ago
+  #3  update API docs (api-gateway) — 1d ago
+
+auth-service (fix/token-refresh) ⚠
+  3 dirty · 1 stash · last commit 14h ago
+  2 ahead, 0 behind origin
+  agents:
+    claude on agent/add-tests — 12 commits, 14 files (23m ago) ● active
+    copilot on copilot/logout — 4 commits, 3 files (7h ago) ○ stale
+  wip:
+    #1 fix auth token refresh (2h ago)
+  recent: main (3d), feat/oauth (5d)
+  commits today:
+    a1b2c3 fix retry logic for token refresh (2h ago)
+
+frontend (main) ✓
+  clean · 2 stashes
+  0 ahead, 0 behind origin
+
+api-gateway (main) ↓
+  clean · 3 behind origin
+  wip:
+    #3 update API docs (1d ago)
+```
+
+### AI briefing (`wip ai briefing`)
+
+```
+## Briefing
+
+You were deep in a token refresh bug in auth-service yesterday evening.
+You changed the retry logic in 3 files but stashed something — probably
+an alternative approach. Your note says the issue is around line 340.
+You might want to start by comparing your stash against your current changes.
+
+The frontend is clean but you left a TODO about form validation on Tuesday.
+api-gateway just needs a pull — 3 commits behind, low priority.
+
+Suggested focus: finish auth-service first (uncommitted work at risk),
+then circle back to the frontend TODO.
+```
+
+### Status Icons
+
+- ✓ — Clean repo, up to date
+- ⚠ — Dirty files (modified, staged, or untracked)
+- ↓ — Behind remote (needs pull)
+
+## Development
+
+```bash
+# Install dependencies
+pip install -e .
+
+# Run from source
+python -m wip.cli
+```
+
+## Roadmap
+
+**Phase 0+1: Foundation + Scanner** ✅
+- Config management, repo discovery, git status scanning, terminal output
+
+**Phase 2: Interactive Worklist** ✅
+- `wip add/done/list` commands with repo linking and persistent state
+
+**Phase 4: LLM Integration** ✅
+- Provider abstraction (Anthropic, OpenAI, and Gemini all implemented)
+- `wip ai briefing`, `wip ai standup`, `wip ai ask` with streaming
+- Prompt assembly from scan data, config-driven provider/model selection
+
+**Phase 5: Passive Agent Detection** ✅
+- Detect coding agent activity from git signals (author names, branch patterns)
+- Agent sessions surface in `wip`, `wip --json`, and all AI commands automatically
+- Configurable author/branch patterns with sensible defaults (zero config required)
+- Status tracking: active (<1h), recent (<24h), stale (>24h)
+
+**Phase 6: Enriched File-Level Context** ✅
+- Changed files with diff stats (insertions/deletions), color-coded by stage in verbose output
+- Stash descriptions surfaced in verbose display and LLM prompts
+- Commit bodies (capped at 3 lines) and per-commit file lists (capped at 10 paths) in LLM context
+
+Ideas and contributions welcome — see `docs/CONTEXT.md` for architecture details.
+
+## Contact
+
+- **LinkedIn:** [Mahesh Naik](https://www.linkedin.com/in/kamaheshnaik/)
+- **Issues:** [GitHub Issues](https://github.com/drmnaik/wip/issues)
+
+## License
+
+MIT
+
+## Author
+
+Built by Mahesh Naik with Claude