diff --git a/WARP.md b/WARP.md new file mode 100644 index 0000000..4195703 --- /dev/null +++ b/WARP.md @@ -0,0 +1,492 @@ +# WARP.md - STRUCT Project Guide + +> This file serves as a comprehensive guide for developers working with the STRUCT project. It contains project-specific conventions, development workflows, and institutional knowledge. + +## ๐Ÿ“‹ Table of Contents + +- [Project Overview](#project-overview) +- [Development Environment](#development-environment) +- [Code Structure](#code-structure) +- [Development Workflow](#development-workflow) +- [Testing Guidelines](#testing-guidelines) +- [Code Style & Standards](#code-style--standards) +- [Release Process](#release-process) +- [Common Tasks](#common-tasks) +- [Troubleshooting](#troubleshooting) +- [Architecture Decisions](#architecture-decisions) +- [Performance Considerations](#performance-considerations) +- [Security Guidelines](#security-guidelines) +- [Documentation Standards](#documentation-standards) +- [Dependencies & Tools](#dependencies--tools) +- [Monitoring & Observability](#monitoring--observability) +- [Issue & Work Management](#issue--work-management) + +## ๐ŸŽฏ Project Overview + +### Mission +STRUCT simplifies project organization by creating consistent file and folder structures tailored to specific needs. It enhances productivity and maintains uniformity across projects through YAML-based configuration files. + +### Key Features +- **YAML-Based Configuration**: Simple, readable project structure definitions +- **Template Variables**: Dynamic content with Jinja2 templating and interactive prompts +- **Remote Content Fetching**: Support for GitHub, HTTP/HTTPS, S3, and Google Cloud Storage +- **Smart File Handling**: Multiple strategies for managing existing files +- **Automation Hooks**: Pre and post-generation shell commands +- **MCP Integration**: Model Context Protocol support for AI-assisted workflows + +### Technology Stack +- **Language**: Python 3.12+ +- **CLI Framework**: argparse with custom command pattern +- **Templating**: Jinja2 with custom delimiters +- **Testing**: pytest with coverage reporting +- **Documentation**: MkDocs with Material theme +- **CI/CD**: GitHub Actions +- **Package Management**: pip with requirements.txt + +## ๐Ÿ›  Development Environment + +### Prerequisites +```bash +# Python 3.12 or higher +python --version + +# Virtual environment (recommended) +python -m venv .venv +source .venv/bin/activate # Linux/macOS +# or +.venv\Scripts\activate # Windows + +# Install dependencies +pip install -r requirements.txt +pip install -r requirements.dev.txt +``` + +### Environment Variables +```bash +# Optional: OpenAI API key for AI features +export OPENAI_API_KEY="your-api-key-here" + +# Optional: GitHub token for private repo access +export GITHUB_TOKEN="your-github-token" + +# Optional: Logging level +export STRUCT_LOG_LEVEL="DEBUG" +``` + +### IDE Configuration +- **VS Code**: Recommended extensions in `.vscode/extensions.json` +- **PyCharm**: Python interpreter should point to `.venv/bin/python` +- **Pre-commit hooks**: Run `pre-commit install` after setup + +## ๐Ÿ— Code Structure + +### Directory Layout +``` +struct_module/ +โ”œโ”€โ”€ commands/ # CLI command implementations +โ”‚ โ”œโ”€โ”€ generate.py # Main generation command +โ”‚ โ”œโ”€โ”€ validate.py # YAML validation +โ”‚ โ”œโ”€โ”€ list.py # List available structures +โ”‚ โ””โ”€โ”€ ... +โ”œโ”€โ”€ contribs/ # Built-in structure templates +โ”œโ”€โ”€ filters.py # Jinja2 custom filters +โ”œโ”€โ”€ template_renderer.py # Core templating logic +โ”œโ”€โ”€ file_item.py # File handling and processing +โ”œโ”€โ”€ input_store.py # User input persistence +โ”œโ”€โ”€ utils.py # Utility functions +โ””โ”€โ”€ main.py # Entry point + +tests/ # Test suite +docs/ # Documentation source +examples/ # Example configurations +``` + +### Key Modules + +#### `template_renderer.py` +- Handles Jinja2 templating with custom delimiters +- Interactive variable prompting with descriptions +- Type coercion and validation +- Icon-based user interface + +#### `file_item.py` +- Represents files to be created/modified +- Handles different content sources (inline, remote, etc.) +- Implements file creation strategies (overwrite, skip, backup, etc.) + +#### `commands/` +- Each command is a separate class inheriting from `Command` +- Self-contained argument parsing and execution logic +- Consistent error handling and logging + +## ๐Ÿ”„ Development Workflow + +### Branch Strategy +- `main`: Production-ready code +- `feature/*`: New features (e.g., `feature/display-variable-descriptions-116`) +- `bugfix/*`: Bug fixes +- `hotfix/*`: Critical production fixes +- `docs/*`: Documentation updates + +### Commit Message Convention +``` +(): + + + +