winterforge-dx-tools 0.1.0

Developer experience tools for WinterForge - OpenAPI, GraphQL, testing utilities, and CLI formatting

winterforge-dx-tools

Developer Experience Tools for WinterForge

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)

pip install winterforge[dx]

Standalone

pip install winterforge-dx-tools

---

Quick Start

OpenAPI Generation

Generate OpenAPI 3.1 specifications from your WinterForge CLI commands:

# 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:

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:

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", "[e-mail]", "Admin"],
        ["Bob", "[e-mail]", "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:

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:

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:

@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

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:

# 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:

# 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

# 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:

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:

FormatterManager.register('custom', CustomFormatter)

Creating Custom Elements

Create scoped elements:

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:

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