Skip to content
reaatechREAATECH
Book a conversation

@reaatech/agent-runbook

npm v0.1.0

Provides a shared library of TypeScript interfaces, Zod schemas, and utility functions for defining and validating service runbooks, incident workflows, and alert configurations. It serves as the core type and validation layer for the Agent Runbook ecosystem, requiring only `zod` as a runtime dependency.

npm →source →

@reaatech/agent-runbook

npm version License: MIT CI

Core types, Zod schemas, utilities, and error classes for the Agent Runbook Generator ecosystem. This package is the single source of truth for all domain types used throughout the @reaatech/agent-runbook-* monorepo.

Installation

terminal
npm install @reaatech/agent-runbook
# or
pnpm add @reaatech/agent-runbook

Feature Overview

  • 68+ domain types — ServiceDefinition, Runbook, AlertDefinition, DashboardConfig, FailureMode, RollbackProcedure, IncidentWorkflow, ServiceDependency, HealthCheck, and more
  • 70+ Zod schemas — runtime validation for every domain type, used at API boundaries and in the MCP server
  • 25 utility functions — file I/O, ID generation, markdown helpers, secret redaction, retry with exponential backoff, duration parsing
  • 8 error classes — AppError, ValidationError, NotFoundError, AnalysisError, GenerationError, ConfigurationError, LLMError with type guards and user-facing formatters
  • Zero runtime dependencies beyond zod — lightweight and tree-shakeable
  • Dual ESM/CJS output — works with import and require

Quick Start

typescript
import {
  type AnalysisContext,
  type Runbook,
  AlertSeverity,
  generateId,
  readFile,
  validateInput,
  AnalysisContextSchema,
} from "@reaatech/agent-runbook";
 
// Generate a unique runbook ID
const id = generateId("rb");
 
// Validate an analysis context at the boundary
const raw = JSON.parse(incomingJson);
const context = AnalysisContextSchema.parse(raw);
 
// Read a file with automatic error handling
const content = readFile("./some-file.json");

API Reference

Domain Types

ExportKindDescription
ServiceDefinitioninterfaceService metadata — name, team, repository, version
AnalysisContextinterfaceContext passed between analysis and generation phases
RunbookinterfaceComplete runbook with sections, metadata, and cross-references
RunbookSectioninterfaceIndividual runbook section with content and subsections
RunbookMetadatainterfaceSummary metadata about a generated runbook
GenerationConfiginterfaceConfiguration for the generation process
AlertDefinitioninterfaceAlert with name, type, severity, expression, annotations
DashboardConfiginterfaceDashboard with title, platform, panels, variables
DashboardPanelinterfaceDashboard panel with query, thresholds, legend
FailureModeinterfaceFailure mode with category, severity, detection, mitigation
RollbackProcedureinterfaceRollback procedure with steps, checks, verification
RollbackStepinterfaceIndividual step with commands, timeout, automation
VerificationStepinterfacePost-rollback verification with success criteria
IncidentWorkflowinterfaceIncident response workflow with severity, triggers, escalation
EscalationPolicyinterfaceEscalation policy with levels, repeat policy
CommunicationTemplateinterfaceIncident communication template with variables
ServiceDependencyinterfaceService dependency with direction, protocol, criticality
ServiceMapinterfaceService map graph with nodes, edges, critical paths
HealthCheckinterfaceHealth check with endpoint, interval, timeout, criteria

Enum Types

TypeValues
ServiceTypeweb-api, worker, lambda, function, unknown
ProgrammingLanguagetypescript, javascript, python, go, java, ruby, rust, unknown
Frameworkexpress, fastify, koa, flask, django, fastapi, gin, echo, chi, spring, rails, none, unknown
DeploymentPlatformkubernetes, ecs, cloud-run, lambda, app-engine, heroku, vm, unknown
MonitoringPlatformprometheus, datadog, cloudwatch, grafana, new-relic, unknown
AlertSeveritycritical, warning, info
FailureCategorydependency, resource, application, network, security, infrastructure, database, cache, queue, external
FailureSeveritycritical, high, medium, low
ExportFormatmarkdown, html, pdf, json

Utilities

FunctionSignature
generateId(prefix?: string) => string
fileExists(filePath: string) => boolean
directoryExists(dirPath: string) => boolean
readFile(filePath: string) => string | undefined
readJsonFile<T>(filePath: string) => T | undefined
listFiles(dirPath: string, recursive?: boolean) => string[]
writeFile(filePath: string, content: string) => void
writeJsonFile<T>(filePath: string, data: T) => void
ensureDirectory(dirPath: string) => void
sanitizeAnchor(text: string) => string
escapeMarkdown(text: string) => string
truncate(str: string, maxLength: number) => string
sleep(ms: number) => Promise<void>
retry<T>(fn: () => Promise<T>, maxAttempts?: number, baseDelay?: number) => Promise<T>
looksLikeSecret(value: string) => boolean
redactSecrets(text: string) => string
parseDuration(duration: string) => number
formatDuration(seconds: number) => string
simpleHash(str: string) => number
groupBy<T, K>(items: T[], keyFn: (item: T) => K) => Record<K, T[]>
flatten<T>(arrays: T[][]) => T[]
unique<T>(arr: T[]) => T[]
isPathWithinBase(targetPath: string, basePath: string) => boolean
getRelativePath(from: string, to: string) => string

Validation

FunctionSignature
validateInput<T>(schema: ZodSchema<T>, data: unknown) => InputValidationResult<T>
parseList(value: unknown, separator?: string) => string[]
parseIntOptional(value: unknown, defaultValue: number) => number
parseBool(value: unknown, defaultValue?: boolean) => boolean

Error Classes

ClassError CodeHTTP Status
AppError(custom)500
ValidationErrorVALIDATION_ERROR400
NotFoundErrorNOT_FOUND404
AnalysisErrorANALYSIS_ERROR500
GenerationErrorGENERATION_ERROR500
ConfigurationErrorCONFIGURATION_ERROR500
LLMErrorLLM_ERROR500

Helper functions: isAppError, getErrorMessage, getErrorStack, formatErrorForUser.

Related Packages

License

MIT

All packagesagent-runbook-generator overview