Architecture
SysopKit is a TypeScript infrastructure automation framework. Its architecture is built around a few core abstractions: contexts, connectors, middleware, operations and reporters.
Core Design Principles
Section titled “Core Design Principles”- TypeScript first: All configuration and logic is written in TypeScript, enabling compile-time validation, refactoring safety and IDE support.
- Composable primitives: Small, focused building blocks (connectors, middleware, operations) compose into complex workflows.
- Context propagation:
AsyncLocalStoragecarries execution state across async boundaries without explicit parameter passing. - Pluggable observability: A pluggable reporting system captures all lifecycle events, changes, and errors.
Execution Model
Section titled “Execution Model”Every operation runs within an ExecutionContext propagated via AsyncLocalStorage. Contexts form a child-parent chain:
root ⇐ connector ⇐ [middleware] ⇐ task / utility ⇐ …Each context carries a reporter, connector, abort signal, typed variables, verbosity level, and dry-run flag. See Execution Model for details.
Connectors
Section titled “Connectors”The Connector interface abstracts command transport — local processes, SSH or podman containers. Every implementation provides connect(), spawn() methods. See Connectors for the guide.
Middleware
Section titled “Middleware”ConnectorMiddleware wraps a connector using decorator pattern. Built-in middlewares add sudo, command tracing, prompt handling and command transformation. See Middleware for the guide.
Apply Engine
Section titled “Apply Engine”apply() orchestrates operations across one or more hosts. Single-host mode connects and runs a function; multi-host mode processes hosts in parallel batches with configurable failure thresholds. See Apply for the guide.
Inventory System
Section titled “Inventory System”The inventory system provides host management with typed variables, tags, and lazy connector creation. Variables merge with precedence: inventory → group → host. See Inventory for the guide.
Events & Changes
Section titled “Events & Changes”Type-safe events use branded symbols. CHANGE_EVENT carries ChangeEntry objects describing infrastructure modifications. Events propagate up the context chain. See Events & Changes for details.
Reporter System
Section titled “Reporter System”The Reporter interface captures all execution lifecycle events. The built-in ConsoleReporter provides:
- Hierarchical context display
- Color-coded output
- Duration
- Buffered output for parallel execution
- Formatting change reports
- Error stack formatting
Custom reporters can implement the Reporter interface to integrate with logging systems, CI pipelines or monitoring tools.