Metadata-Version: 2.4
Name: cursor-dungeon-master
Version: 0.3.1
Summary: Context-tracking pre-commit tool for Cursor AI integration
Home-page: https://github.com/yourusername/dungeon-master
Author: Dungeon Master Team
Author-email: Dungeon Master Team <contact@dungeonmaster.dev>
Maintainer-email: Dungeon Master Team <contact@dungeonmaster.dev>
License: MIT License
        
        Copyright (c) 2024 Dungeon Master Contributors
        
        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.
        
Project-URL: Homepage, https://github.com/yourusername/dungeon-master
Project-URL: Documentation, https://github.com/yourusername/dungeon-master#readme
Project-URL: Repository, https://github.com/yourusername/dungeon-master.git
Project-URL: Bug Reports, https://github.com/yourusername/dungeon-master/issues
Project-URL: Changelog, https://github.com/yourusername/dungeon-master/releases
Keywords: documentation,git,pre-commit,context,tracking,cursor,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Requires-Dist: mypy>=0.800; extra == "dev"
Requires-Dist: pre-commit>=2.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 🏰 Dungeon Master

**A context-tracking pre-commit tool for Cursor AI integration.**

Blocks commits until meaningful documentation exists. Creates structured templates that Cursor fills with intelligent content. Enforces quality through automated validation.

```bash
pip install cursor-dungeon-master
dm init
```

---

## ⚔️ How It Works

### 1. **Track Important Files**

Add a simple decorator to mark files for documentation:

```python
# @track_context("auth_service.md")
class AuthService:
    def authenticate(self, token: str) -> bool:
        pass
```

### 2. **Commit Triggers Template Creation**

When you commit, Dungeon Master creates a structured template:

```markdown
# auth_service.py - Context Documentation

## Purpose

<Describe the overall intent and responsibility>

## Key Functions

- **authenticate(token)**: <Explain purpose and usage>
- **generate_token(user_id)**: <Explain purpose and usage>

## Dependencies

- `jwt`: <Why this dependency is needed>
```

### 3. **🛡️ Commit Blocked Until Complete**

```
⚔️ COMMIT BLOCKED: Documentation Required
📜 Templates created: lore/auth_service.md
🧙‍♂️ Use Cursor to complete documentation
```

### 4. **🧙‍♂️ Cursor Fills Templates**

Use Cursor to replace placeholders with meaningful content:

```markdown
## Purpose

Provides JWT-based authentication with secure password hashing
and session management for user login workflows.

## Key Functions

- **authenticate(token)**: Validates JWT tokens and returns user data
- **generate_token(user_id)**: Creates signed JWT tokens for authenticated users
```

### 5. **✅ Validation Passes, Commit Proceeds**

```
🏰 Dungeon Master: All validations passed
📜 Documentation complete and validated
⚡ Commit proceeding...
```

---

## 🎯 Quick Start

```bash
# Install
pip install cursor-dungeon-master

# Initialize in your repo
dm init
pre-commit install

# Mark files for tracking
echo '# @track_context("my_feature.md")' >> src/my_feature.py

# Commit triggers the workflow
git add . && git commit -m "Add new feature"
```

**That's it!** Dungeon Master will guide you through the rest.

---

## 🗡️ Commands

| Command         | Purpose                                      |
| --------------- | -------------------------------------------- |
| `dm init`       | 🏰 Initialize Dungeon Master in repository   |
| `dm update`     | 📜 Create/update templates for tracked files |
| `dm list --all` | 🗺️ Show all tracked files and status         |
| `dm validate`   | 🛡️ Check what would block commits            |
| `dm review`     | 🔮 Manage significant changes                |

---

## 📜 Template Example

**Generated Template:**

```markdown
# auth_service.py - Context Documentation

## Purpose

<Describe the overall intent and responsibility of this file>

## Usage Summary

**File Location**: `src/auth_service.py`

**Key Dependencies**:

- `jwt`: <explain why needed>
- `hashlib`: <explain why needed>

## Key Functions

- **authenticate(self, token)**: <Explain purpose>
- **generate_token(self, user_id)**: <Explain purpose>

## Integration Notes

<How this integrates with the broader system>
```

**After Cursor Completion:**

```markdown
# auth_service.py - Context Documentation

## Purpose

Comprehensive authentication service handling user login, JWT token
management, and secure session tracking. Core security component
for all user authentication workflows.

## Usage Summary

**File Location**: `src/auth_service.py`

**Key Dependencies**:

- `jwt`: Provides JWT encoding/decoding for stateless authentication
- `hashlib`: SHA-256 password hashing for secure credential storage

## Key Functions

- **authenticate(self, token)**: Validates JWT tokens, returns user data or raises AuthError
- **generate_token(self, user_id)**: Creates signed JWT with user claims and expiration

## Integration Notes

Used by API middleware for request authentication. Integrates with
user service for credential validation and session management.
```

---

## 🏺 Project Structure

```
your_project/
├── 📜 lore/                    # Generated documentation
│   ├── auth_service.md         # ✅ Complete
│   ├── api_client.md          # ⚠️ Needs completion
│   └── utils.md               # ✅ Complete
├── 🏹 src/
│   ├── auth.py                # @track_context("auth_service.md")
│   ├── client.js              # @track_context("api_client.md")
│   └── utils.py               # @track_context("utils.md")
└── ⚔️ hooks/
    └── pre_commit_hook.py     # Enforcement engine
```

---

## 🛡️ Validation Rules

| Status         | Rule                           | Action                          |
| -------------- | ------------------------------ | ------------------------------- |
| ⚔️ **BLOCKED** | Template missing               | Creates template, blocks commit |
| ⚔️ **BLOCKED** | Contains `<placeholders>`      | Must complete with Cursor       |
| ⚔️ **BLOCKED** | Significant changes unreviewed | Run `dm review --mark-reviewed` |
| ✅ **PASSES**  | All documentation complete     | Commit proceeds                 |

---

## 🔮 Advanced Features

### 🎲 Change Detection

Automatically detects significant code changes:

```bash
🔮 Significant changes detected:
   📄 auth_service.py
      • New function: validate_permissions()
      • Modified function: authenticate()

💎 Use 'dm review --mark-reviewed' if changes are minor
⚔️ Update documentation if changes affect core functionality
```

### 🧙‍♂️ Language Support

- **🐍 Python**: Full AST analysis with intelligent templates
- **⚡ JavaScript/TypeScript**: Advanced regex parsing
- **🗡️ Other Languages**: Basic analysis with manual completion

### 🏰 Pre-commit Integration

```yaml
repos:
  - repo: local
    hooks:
      - id: dungeon-master
        name: "🏰 Dungeon Master"
        entry: dm validate
        language: python
        always_run: true
```

---

## 🌟 Philosophy

**This isn't auto-documentation.** It's a **structured collaboration** between:

- 🧙‍♂️ **AI (Cursor)** - Provides intelligence and content
- 🏰 **Dungeon Master** - Enforces structure and consistency
- ⚔️ **Developers** - Maintain control and oversight
- 📜 **Documentation** - Stays current through commit-time enforcement

**Result**: Documentation that's meaningful, current, consistent, and enforced.

---

## 🗺️ Development

```bash
git clone https://github.com/yourusername/dungeon-master.git
cd dungeon-master
pip install -e .[dev]
python tests/verify_installation.py
```

---

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

---

**💎 Remember**: This creates a structured way for AI assistants like Cursor to help you maintain accurate, meaningful documentation as part of your development workflow.

🏰 _"In the dungeon of development, proper documentation is your most powerful spell."_
