@hstm-labs/forge-common

Shared foundation for the Forge monorepo — core type definitions, structured error model, JSON logger, configuration validation, SQLite persistence, and LLM adapter abstractions.

Installation

npm install @hstm-labs/forge-common

Public API

Types

• RunStatus, StageStatus, StageName — run lifecycle enums
• ForgeConfig — workspace configuration shape
• GenerationRun, PipelineStageRecord, Artifact — run tracking
• LLMUsageRecord, RunSummary, Workspace, InitOptions — operational types
• BenchmarkStageEntry, BenchmarkReport, BenchmarkRunSummary, BenchmarkComparison — benchmarking
• CodeReviewFinding, CodeReviewReport, ReviewDimension — code review

Error Model

• ForgeError — structured error class with codes (FORGE-{CATEGORY}-{NUMBER})
• ErrorCodes — predefined error code constants across 9 categories

Logger

• StructuredLogger — JSON-formatted structured logger with child context support

Configuration

• validateConfig() — Ajv-based config validation
• loadConfig() — load and validate forge.config.json
• resolveEnvVars() — environment variable interpolation
• discoverWorkspace() — walk up from cwd to find .forge/ directory

LLM Adapters

• LLMRegistry — provider registry for adapter lookup
• MockAdapter — deterministic mock for testing
• OpenAIAdapter — OpenAI API (supports baseURL for Ollama/local models)
• AnthropicAdapter — Anthropic Claude API
• GeminiAdapter — Google Gemini API

Persistence

• SqliteRunStore — SQLite-backed run metadata, stage tracking, artifact manifest, benchmarks

Usage

import {
  ForgeError,
  ErrorCodes,
  StructuredLogger,
  loadConfig,
  discoverWorkspace,
  LLMRegistry,
  OpenAIAdapter,
  SqliteRunStore,
} from '@hstm-labs/forge-common';

const logger = new StructuredLogger({ level: 'info' });
const workspace = discoverWorkspace(process.cwd());
const config = loadConfig(workspace.configPath);

License

MIT