@helmstack/core

Core orchestrator engine for HelmStack: task management, AI logic, state/memory, command handlers with contract-first validation.

🎯 Overview

HelmStack Core is the orchestration engine that powers all HelmStack commands. It implements:

• Command orchestration via the Heck class
• Runtime policies (timeout, retry, lock, validation)
• Service interfaces for external integrations
• Handler framework for command business logic
• Contract-first validation using @helmstack/schemas

🏗️ Architecture

helmstack-core/
├── src/
│   ├── orchestrator/         # Main Heck class and handler registry
│   ├── runtime/              # Lock, Retry, Timeout, Validation, Logger
│   ├── services/             # Interface definitions for external services
│   ├── usecases/             # Command handlers (business logic)
│   ├── policies/             # Reusable policies and rules
│   └── bootstrap/            # Context setup and dependency injection

🚀 Usage

import { Heck, CoreContext } from '@helmstack/core';

// Create context with service implementations
const context = new CoreContext({
  services: {
    Git: new GitAdapter(),
    GitHub: new GitHubAdapter(),
    ML: new MLAdapter(),
    // ... other services
  }
});

// Create orchestrator
const heck = new Heck(registry, context);

// Execute command
const result = await heck.run('plan', {
  ai: true,
  charter: true
});

console.log(result.payload);

📝 Command Handlers

All command handlers implement the Handler<TInput, TOutput> interface:

export class PlanHandler implements Handler<PlanInput, PlanOutput> {
  async run(input: PlanInput, context: CoreContext): Promise<PlanOutput> {
    // Business logic here
    return {
      strategy: 'ai',
      tasks: [...],
      risks: [...]
    };
  }
}

🔧 Runtime Features

• Envelope: Standard response format for all commands
• Validation: AJV-based schema validation
• Lock: Workspace-level file locking for mutating operations
• Retry: Exponential backoff with jitter
• Timeout: Configurable timeouts with abort support
• Logger: Structured logging with redaction

🤝 Service Integration

Core defines interfaces for external services but doesn't implement them. Implementations come from @helmstack/addons:

• Git - Local git operations
• GitHub - GitHub API integration
• ML - AI/ML service integration
• Secrets - Secret management
• FS - File system operations
• Http - HTTP client with retry/backoff

📋 Contract Validation

All command inputs and outputs are validated against schemas from @helmstack/schemas. This ensures:

• Type safety across the entire ecosystem
• Consistent API contracts
• Breaking change detection

🧪 Testing

# Run all tests
npm test

# Run contract tests (against schemas)
npm run test:contract

# Run unit tests
npm run test:unit

# Run integration tests
npm run test:integration

Part of the HelmStack ecosystem.