spec-kit-core 1.0.0
Core application services for Spec-Kit - Service implementations and application bridge
License: MIT
Requires Python: >=3.11
Keywords: application, core, services, spec-kit

# spec-kit-core

Core application services for the Spec-Kit ecosystem.

## Overview

This package provides concrete implementations of the service interfaces defined in `spec-kit-contracts`. These services are injected into plugins at runtime, providing them with controlled access to system resources.

## Installation

```bash
pip install spec-kit-core
```

## Services Provided

### ConfigService

Configuration management with YAML support:

```python
from spec_kit_core.services import ConfigService

config = ConfigService(config_path=".specify/config.yaml")

# Get configuration values
value = config.get("plugins.design.template_style", default="standard")

# Set configuration
config.set("plugins.design.enabled", True)

# Save changes
config.save()
```

### FileSystemService

Safe file operations with path validation:

```python
from spec_kit_core.services import FileSystemService

fs = FileSystemService(base_path="./project")

# Read file
content = fs.read_file("specs/feature/spec.md")

# Write file (creates directories as needed)
fs.write_file("specs/feature/plan.md", content)

# Check existence
if fs.exists("specs/feature"):
    files = fs.list_directory("specs/feature")
```

### TemplateService

Jinja2 template rendering:

```python
from spec_kit_core.services import TemplateService

templates = TemplateService()

# Register template
templates.register_template("hld", "# HLD: {{ feature_name }}\n...")

# Render
content = templates.render("hld", {
    "feature_name": "User Authentication",
    "version": "1.0",
})
```

### LoggingService

Structured logging:

```python
from spec_kit_core.services import LoggingService

logger = LoggingService(name="my-plugin")

logger.info("Plugin initialized", extra={"config": config})
logger.warning("Deprecated feature used")
logger.error("Operation failed", exc_info=True)
```

### EventService

Pub/sub event system:

```python
from spec_kit_core.services import EventService

events = EventService()

# Subscribe to events
def on_file_saved(data):
    print(f"File saved: {data['path']}")

events.subscribe("file:saved", on_file_saved)

# Emit events
events.emit("file:saved", {"path": "/project/file.py"})
```

### StateService

Persistent state management:

```python
from spec_kit_core.services import StateService

state = StateService(storage_path=".specify/state")

# Save state
state.set("plugin:design:last_run", datetime.now().isoformat())

# Get state
last_run = state.get("plugin:design:last_run")

# Clear state
state.clear("plugin:design:*")
```

## Application Bridge

The `RuntimeBridge` connects core services to the plugin runtime:

```python
from spec_kit_core import RuntimeBridge
from spec_kit_runtime import PluginContainer

# Create bridge with services
bridge = RuntimeBridge(
    config_path=".specify/config.yaml",
    base_path="./project",
)

# Connect to plugin container
container = PluginContainer()
bridge.connect(container)

# Services are now available to plugins
```

## Service Registry

The `ServiceRegistry` manages service registration and lookup:

```python
from spec_kit_core import ServiceRegistry
from spec_kit_contracts import IFileSystemService

registry = ServiceRegistry()

# Register service
registry.register(IFileSystemService, fs_instance)

# Get service
fs = registry.get(IFileSystemService)

# Check availability
if registry.has(IFileSystemService):
    ...
```

## Architecture

```
┌─────────────────────────────────────────────────┐
│                  spec-kit-core                   │
│                                                 │
│  ┌─────────────────────────────────────────┐   │
│  │            RuntimeBridge                 │   │
│  │  Connects services to plugin runtime     │   │
│  └──────────────────┬──────────────────────┘   │
│                     │                          │
│  ┌──────────────────┴──────────────────────┐   │
│  │           ServiceRegistry                │   │
│  │  DI container for service lookup         │   │
│  └──────────────────┬──────────────────────┘   │
│                     │                          │
│  ┌──────────────────┴──────────────────────┐   │
│  │              Services                    │   │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  │   │
│  │  │ Config  │  │   FS    │  │Template │  │   │
│  │  └─────────┘  └─────────┘  └─────────┘  │   │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  │   │
│  │  │ Logging │  │  Event  │  │  State  │  │   │
│  │  └─────────┘  └─────────┘  └─────────┘  │   │
│  └──────────────────────────────────────────┘   │
└─────────────────────────────────────────────────┘
         │                    │
         ▼                    ▼
┌─────────────────┐  ┌─────────────────┐
│ spec-kit-runtime│  │spec-kit-contracts│
│  (plugin mgmt)  │  │  (interfaces)   │
└─────────────────┘  └─────────────────┘
```

## Dependencies

- `spec-kit-contracts>=1.0.0` - Interface contracts
- `spec-kit-runtime>=1.0.0` - Plugin runtime
- `pyyaml>=6.0` - Configuration parsing
- `jinja2>=3.0` - Template rendering

## License

MIT License - see LICENSE file for details.