spec-kit-contracts 1.0.0
Plugin interface contracts for Spec-Kit - Pure interfaces with zero dependencies
License: MIT
Requires Python: >=3.11
Keywords: contracts, interfaces, plugins, protocols, spec-kit

# spec-kit-contracts

Pure interface contracts for the Spec-Kit plugin system.

## Overview

This package contains **only interfaces and contracts** that define the communication between the Spec-Kit core and plugins. It has **zero dependencies** to ensure maximum portability.

Plugin developers should depend only on this package to create plugins that are compatible with the Spec-Kit ecosystem.

## Installation

```bash
pip install spec-kit-contracts
```

## Usage

### Creating a Plugin

```python
from spec_kit_contracts import (
    IPlugin,
    IPluginMetadata,
    PluginBase,
    PluginStatus,
    PluginCapability,
)

class MyPlugin(PluginBase):
    """Example plugin implementation."""

    def _create_metadata(self) -> IPluginMetadata:
        return IPluginMetadata(
            name="my-plugin",
            version="1.0.0",
            author="Your Name",
            description="My awesome plugin",
            capabilities=[PluginCapability.COMMAND, PluginCapability.HOOK],
        )

    def handle_message(self, message):
        """Handle incoming messages."""
        if hasattr(message, 'command_name'):
            if message.command_name == "my-plugin:hello":
                return {"message": "Hello from my plugin!"}
        return None

    def get_config_schema(self):
        """Return configuration schema."""
        return {
            "type": "object",
            "properties": {
                "enabled": {"type": "boolean", "default": True},
            },
        }
```

### Using Service Interfaces

```python
from spec_kit_contracts import (
    IServiceRegistry,
    IFileSystemService,
    IConfigService,
)

class MyPlugin(PluginBase):
    def register_services(self, registry: IServiceRegistry) -> None:
        """Register plugin services with the runtime."""
        registry.register_command("my-plugin:hello", self._handle_hello)
        registry.register_hook("post_save", self._on_file_saved, priority=50)

    def set_services(self, services: dict) -> None:
        """Receive injected services."""
        self.fs: IFileSystemService = services.get("filesystem")
        self.config: IConfigService = services.get("config")
```

### Working with Messages

```python
from spec_kit_contracts import (
    Message,
    Request,
    Response,
    Event,
    Command,
    MessageBuilder,
)

# Create a command message
command = MessageBuilder.command(
    name="design:generate",
    arguments=["my-feature"],
    options={"force": True},
)

# Create an event
event = MessageBuilder.event(
    name="file:saved",
    data={"path": "/path/to/file.py"},
)

# Create a request
request = MessageBuilder.request(
    method="get_config",
    params={"key": "max_lines"},
)
```

## Available Contracts

### Plugin Interfaces

| Interface | Description |
|-----------|-------------|
| `IPlugin` | Core plugin protocol (duck typing) |
| `IPluginMetadata` | Plugin identity and capabilities |
| `PluginBase` | Convenience base class with defaults |
| `PluginStatus` | Lifecycle states (INACTIVE, ACTIVE, etc.) |
| `PluginCapability` | Declared capabilities (COMMAND, HOOK, etc.) |

### Service Interfaces

| Interface | Description |
|-----------|-------------|
| `IServiceRegistry` | Register commands, hooks, services |
| `IConfigService` | Read/write configuration |
| `IFileSystemService` | File operations with safety |
| `ITemplateService` | Template rendering |
| `ILoggingService` | Structured logging |
| `IEventService` | Pub/sub events |
| `IStateService` | Persistent state |

### Message Types

| Type | Description |
|------|-------------|
| `Message` | Base message class |
| `Request` | Method call expecting response |
| `Response` | Response to a request |
| `Event` | Notification/broadcast |
| `Command` | Direct execution |
| `Query` | Information request |

### Exceptions

| Exception | Description |
|-----------|-------------|
| `ContractError` | Base contract error |
| `PluginContractError` | Plugin contract violation |
| `MessageContractError` | Message contract violation |
| `ServiceContractError` | Service contract violation |

## Design Principles

1. **Zero Dependencies**: This package has no external dependencies
2. **Protocol-Based**: Uses Python Protocols for duck typing
3. **Type Safe**: Full type annotations for IDE support
4. **Minimal**: Only interfaces, no implementations
5. **Stable API**: Semantic versioning for breaking changes

## Version Compatibility

| spec-kit-contracts | spec-kit-runtime | spec-kit-core |
|-------------------|------------------|---------------|
| 1.x | 1.x | 1.x |

## License

MIT License - see LICENSE file for details.