spec-kit-core 1.0.0

Core application services for Spec-Kit - Service implementations and application bridge

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

pip install spec-kit-core

Services Provided

ConfigService

Configuration management with YAML support:

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:

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:

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:

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:

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:

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:

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:

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.