@hstm-labs/forge-core

Pipeline orchestration engine for Forge — manages stage execution, dual execution modes (API/Agent), run lifecycle, resume logic, artifact integrity verification, and progress reporting.

Installation

npm install @hstm-labs/forge-core

Public API

Pipeline Runner

• PipelineRunner — central orchestrator for sequential stage execution
• PipelineRunnerConstructorOptions, ContinueResult — runner configuration and results

Stage Executors

• ApiStageExecutor — direct LLM calls with retry logic and output validation
• AgentStageExecutor — prompt export for IDE agents with filesystem validation

Types

• PipelineStage — stage interface contract (name, dependsOn, requiresLLM, execute())
• PipelineContext, PipelineStageInput, PipelineStageOutput — pipeline data flow

Stage author contract (layout)

After the validate stage runs, the runner sets context.layout (from @hstm-labs/forge-common’s ResolvedLayout). Generator stages (Scaffold, ServicesGenerate, AppsGenerate) must:

• Read target paths from context.layout (serverPath, clientPath, or context.layout.stagePaths[stageName]).
• Write only to those layout-resolved paths under the project root (in-place). Do not assume output goes to run-artifact directories for a later merge.
• StageContext, StageResult, StageArtifact — executor-level types
• ExecutionMode, OutputValidator, RetryPolicy — executor configuration
• ProgressEvent, ProgressListener — real-time progress reporting

Utilities

• initWorkspace() — scaffold .forge/ directory and forge.config.json
• ValidateStage — built-in specification validation stage
• isValidTransition(), assertValidTransition() — run state machine
• checkArtifactIntegrity() — verify on-disk artifacts before resume

Usage

import { PipelineRunner, ApiStageExecutor } from '@hstm-labs/forge-core';

const runner = new PipelineRunner({
  config,
  runStore,
  logger,
  llmAdapter,
  executionMode: 'api',
});

runner.registerStage(validateStage);
const result = await runner.run(specPath);

License

MIT