@zdravoai/state-engine

Zdravo runtime state engine with checkpoint/rollback for CLI operations.

Installation

npm install @zdravoai/state-engine

Quick Start

import { createStateEngine } from '@zdravoai/state-engine'

const engine = createStateEngine({
  stateDir: '/path/to/state',
  stateFile: '/path/to/state/zdravo.json',
})

// Record progress through setup checkpoints
engine.advance('ollama_installed')
engine.advance('qdrant_started')

// Mark a failure (keeps completed checkpoints)
engine.fail('configured', new Error('embedding test failed'))

// Roll everything back to a clean slate
engine.rollback()

API

createStateEngine(config): StateEngine

Creates a state engine persisted to config.stateFile. The state directory is created on construction (best effort).

engine.load(): StateRecord

Loads the current state; returns a fresh init state if none exists.

engine.save(state: StateRecord): void

Persists state with a fresh updated_at timestamp using an atomic write-then-rename (0600 permissions).

engine.advance(checkpoint: Checkpoint): StateRecord

Sets currentCheckpoint, appends to completed (deduplicated), clears any failure, and persists.

engine.fail(checkpoint: Checkpoint, error: Error): StateRecord

Records the failed checkpoint in failed and persists.

engine.rollback(): StateRecord

Resets completed to [], sets currentCheckpoint to 'init', and persists.

Types

• Checkpoint: 'init' | 'ollama_installed' | 'qdrant_started' | 'configured' | 'verified'
• StateRecord: { mode, currentCheckpoint, completed, failed?, updated_at }

License

MIT