Metadata-Version: 2.4
Name: winterforge-dx-tools
Version: 0.1.0
Summary: Developer experience tools for WinterForge - OpenAPI, GraphQL, testing utilities, and CLI formatting
Author-email: WinterForge Team <team@winterforge.dev>
License: MIT
Project-URL: Homepage, https://github.com/winterforge/winterforge-dx-tools
Project-URL: Documentation, https://winterforge-dx-tools.readthedocs.io
Project-URL: Repository, https://github.com/winterforge/winterforge-dx-tools
Project-URL: Issues, https://github.com/winterforge/winterforge-dx-tools/issues
Project-URL: Changelog, https://github.com/winterforge/winterforge-dx-tools/blob/main/CHANGELOG.md
Keywords: winterforge,developer-tools,openapi,graphql,cli,formatting,code-generation,testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Code Generators
Classifier: Topic :: Software Development :: Testing
Classifier: Framework :: AsyncIO
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: winterforge>=0.1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: strawberry-graphql>=0.200.0
Provides-Extra: all
Requires-Dist: uvicorn>=0.23.0; extra == "all"
Requires-Dist: httpx>=0.25.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# winterforge-dx-tools

**Developer Experience Tools for WinterForge**

[![Tests](https://img.shields.io/badge/tests-33%20passing-brightgreen)](tests/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

WinterForge DX Tools provides code generation, testing utilities, and
Rich-based CLI formatting to enhance the developer experience when
building WinterForge applications.

---

## Features

- **OpenAPI Generation** - Generate OpenAPI 3.1 specs from CLI commands
- **GraphQL Schema Generation** - Auto-generate GraphQL schemas
- **REST Endpoint Generation** - Create FastAPI routes from commands
- **Testing Utilities** - Fixtures and helpers for testing
- **CLI Formatting** - Rich-based terminal output (panels, tables,
  trees)
- **Migration System** - Database and schema migration tools
- **Scoped Plugin Architecture** - Demonstrative subsidiary plugin
  system

---

## Installation

### Via WinterForge Extras (Recommended)

```bash
pip install winterforge[dx]
```

### Standalone

```bash
pip install winterforge-dx-tools
```

---

## Quick Start

### OpenAPI Generation

Generate OpenAPI 3.1 specifications from your WinterForge CLI commands:

```bash
# Generate spec to stdout
winterforge dx openapi user

# Save to file
winterforge dx openapi user --output user-api.yaml

# JSON format
winterforge dx openapi user --format json --output api.json

# Custom metadata
winterforge dx openapi user \
  --title "User Management API" \
  --version "2.0.0"
```

**Python API:**

```python
from winterforge_dx_tools.openapi import OpenAPIGenerator

spec = OpenAPIGenerator.generate_spec(
    root_name='user',
    title='User API',
    version='1.0.0'
)
# Returns dict - convert to YAML/JSON as needed
```

### CLI Formatting

Rich-based terminal output with scoped plugins:

```python
from winterforge_dx_tools.formatters import FormatterManager

formatter = FormatterManager.get('prettier')

# Bordered panels
formatter.panel(
    "Hello from WinterForge!",
    title="Welcome",
    border_style="green"
)

# Data tables
formatter.table(
    [
        ["Alice", "alice@example.com", "Admin"],
        ["Bob", "bob@example.com", "User"],
    ],
    headers=["Name", "Email", "Role"],
    title="Users"
)

# Horizontal rules
formatter.rule("Section Divider", style="blue")

# Hierarchical trees
tree_data = {
    'label': 'Project',
    'children': [
        {'label': 'models'},
        {'label': 'views'},
    ]
}
formatter.tree(tree_data)
```

### GraphQL Schema Generation

Generate GraphQL schemas from your Frags:

```python
from winterforge_dx_tools.graphql import SchemaGenerator

schema = SchemaGenerator.generate_schema(
    frag_name='user',
    include_mutations=True
)
# Returns Strawberry GraphQL schema
```

### REST Endpoint Generation

Generate FastAPI routes from CLI commands:

```python
from winterforge_dx_tools.server import EndpointGenerator

app = EndpointGenerator.generate_app(
    root_name='user',
    prefix='/api'
)
# Returns FastAPI app instance
```

---

## What Gets Generated

### From WinterForge Commands

Given this command:

```python
@root('user')
class UserCommands:
    @decorator_provider(
        cli_command=CLICommandConfig()
    )
    async def create(
        self,
        username: str,
        email: str
    ) -> Frag:
        """Create a new user."""
        # Implementation
```

### You Get This OpenAPI Spec

```yaml
openapi: 3.1.0
info:
  title: User API
  version: 1.0.0
paths:
  /api/user/create:
    post:
      summary: Create a new user.
      operationId: user_create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                email:
                  type: string
              required:
                - username
                - email
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  affinities:
                    type: array
                    items:
                      type: string
```

---

## Components

### OpenAPI Generator

- **Automatic Type Mapping** - Python hints → OpenAPI schemas
- **Pydantic Support** - Pydantic models map to components
- **Multiple Formats** - YAML and JSON output
- **Docstring Integration** - Docstrings become descriptions
- **Zero Configuration** - Works out of the box

### GraphQL Generator

- **Schema Generation** - Frags → GraphQL types
- **Resolver Factory** - Auto-generate resolvers
- **Type Mapping** - Python types → GraphQL types
- **Strawberry Integration** - Uses Strawberry GraphQL

### Server Generator

- **FastAPI Routes** - Auto-generate REST endpoints
- **Request Handling** - Parse and validate requests
- **Response Handling** - Format responses consistently
- **Error Handling** - Standardized error responses

### Formatters & Elements

- **FormatterManager** - Pluggable formatting system
- **PrettierFormatter** - Rich-based terminal output
- **ElementManager** - Reusable UI elements
- **Scoped Plugins** - Elements scoped to formatters

### Testing Utilities

- **Test Fixtures** - Common test data and mocks
- **Helper Functions** - Assertion helpers
- **Integration Support** - FastAPI and GraphQL testing

### Migration System

- **Migration Generator** - Create migration templates
- **Migration Executor** - Apply migrations
- **Migration Tracker** - Track applied migrations
- **Rollback Support** - Undo migrations

---

## CLI Commands

All commands are available under `winterforge dx`:

```bash
# OpenAPI generation
winterforge dx openapi <root> [OPTIONS]

# GraphQL generation
winterforge dx graphql <frag> [OPTIONS]

# Server generation
winterforge dx server <root> [OPTIONS]

# Migration commands
winterforge dx migrate create <name>
winterforge dx migrate up
winterforge dx migrate down
winterforge dx migrate status
```

---

## Architecture

### Scoped Plugin System

DX Tools demonstrates WinterForge's scoped plugin architecture:

- **FormatterManager** - Manages formatters (e.g., prettier)
- **ElementManager** - Manages UI elements (panel, table, tree)
- **Cross-Manager Scoping** - Elements scope to formatters via
  `@scope('prettier')`
- **Dependency Resolution** - Topological ordering via
  DependencyResolver
- **Scoped Access** - `ElementManager.with_scope('prettier')` returns
  only scoped elements

**Example:**

```python
# Element scoped to prettier formatter
from winterforge.plugins.decorators import scope

@scope('prettier')
class PanelElement:
    """Panel element for prettier formatter."""
    ...

# Access scoped elements
prettier_elements = ElementManager.with_scope('prettier')
for element in prettier_elements.all():
    print(element.__class__.__name__)
```

---

## Testing

```bash
# Run all tests
pytest tests/dx_tools/

# Run with coverage
pytest tests/dx_tools/ --cov=winterforge_dx_tools

# Run specific test file
pytest tests/dx_tools/test_openapi.py
```

**Current Status:** 33 tests passing

---

## Development

### Creating Custom Formatters

Implement the formatter interface:

```python
class CustomFormatter:
    """Custom formatting implementation."""

    def panel(self, content, **kwargs):
        """Render a panel."""
        # Implementation

    def table(self, data, headers, **kwargs):
        """Render a table."""
        # Implementation
```

Register via entry points or manually:

```python
FormatterManager.register('custom', CustomFormatter)
```

### Creating Custom Elements

Create scoped elements:

```python
from winterforge.plugins.decorators import scope

@scope('custom')
class CustomElement:
    """Element scoped to custom formatter."""
    ...
```

---

## Examples

See `examples/dx_tools_demo.py` for a complete demonstration of:

- Plugin architecture
- Scoped relationships
- Dependency trees
- Rich formatting examples

Run with:

```bash
python examples/dx_tools_demo.py
```

---

## Contributing

Contributions welcome! Please ensure:

- All tests pass
- New features have tests
- Code follows WinterForge mandates
- Line length ≤80 characters

---

## License

MIT License - see LICENSE file for details

---

## Links

- **WinterForge Core:**
  https://github.com/winterforge/winterforge
- **Documentation:**
  https://winterforge-dx-tools.readthedocs.io
- **Issues:**
  https://github.com/winterforge/winterforge-dx-tools/issues

---

Built with ❄️ by the WinterForge team
