Core Functions

start()

Entry point for all SysopKit scripts. Creates a root execution context, sets up a reporter and abort handling, and runs the provided function.

import { start } from 'sysopkit/start';

async function start<R>(
  fn: (ctx: ExecutionContext) => Promise<R>,
  options?: StartOptions,
): Promise<StartResult<R>>;

Options

Option	Type	Default	Description
reporter	Reporter	ConsoleReporter	Custom reporter for output
dryRun	boolean	SYSOPKIT_DRY_RUN env var	Prevent actual changes
signal	AbortSignal	—	External signal for cancellation
vars	Record<symbol | string, any>	—	Initial context variables

Return Value

type StartResult<T> =
  | { success: true; result: T; duration: number }
  | { success: false; error: unknown; duration: number };

Always returns a result — never throws. Check result.success to determine outcome.

main()

CLI script entry point. Same as start() but also sets process.exitCode (1 on failure, 0 on success when no exit code is set yet) and returns the StartResult unchanged. Never calls process.exit(), so reporter output flushes and await using cleanup completes. At debug verbosity it rethrows the failure after setting the exit code, so bugs surface with a full stack trace.

import { main } from 'sysopkit/start';

async function main<R>(
  fn: (ctx: ExecutionContext) => Promise<R>,
  options?: StartOptions,
): Promise<StartResult<R>>;

await main(async () => {
  // ... automation logic ...
});

---

task()

Creates a named child context for a user-facing operation. Task output appears at normal verbosity.

import { task } from 'sysopkit';

async function task<R>(
  name: string,
  fn: (ctx: ExecutionContext) => Promise<R>,
  opts?: TaskOptions,
): Promise<R>;

Options

Option	Type	Description
details	string | (() => string | Record)	Additional context info for reporter
verbosity	Verbosity	Override verbosity for this task
vars	Record<string, any>	Scoped context variables
signal	AbortSignal	Scoped abort signal

---

utility()

Creates a named child context for internal helper operations. Output is suppressed at normal verbosity (shown at debug level).

import { utility } from 'sysopkit';

async function utility<R>(
  name: string,
  fn: (ctx: ExecutionContext) => Promise<R>,
  options?: UtilityOptions,
): Promise<R>;

Options

Option	Type	Description
vars	Record<symbol | string, any>	Scoped context variables
signal	AbortSignal	Scoped abort signal

---

context()

Returns the current ExecutionContext. Throws if called outside a start() scope.

import { context } from 'sysopkit';

function context(): ExecutionContext;

ExecutionContext Properties

Property	Type	Description
type	ContextType	'root' | 'apply' | 'connector' | 'middleware' | 'utility' | 'task'
parent	ExecutionContext | null	Parent context in the tree
reporter	Reporter	Shared reporter instance
conn	Connector | null	Active connector (null in root)
dryRun	boolean	Dry-run mode flag
name	string	Context name
vars	Record<symbol | string, any> | undefined	Context variables
signal	AbortSignal	Abort signal for cancellation
verbosity	Verbosity	Current verbosity level

Methods

Method	Description
tryGet(key)	Get variable by key, returns undefined if absent
get(key)	Get variable by key, throws if absent
abort(reason?)	Abort execution with optional reason
on(event, handler)	Register event handler for this context
info(msg)	Log at info level
warn(msg)	Log at warning level
error(msg)	Log at error level

---

emit()

Dispatches an event that propagates up the context chain. Registered handlers at each level are called.

import { emit } from 'sysopkit';

function emit<T>(event: Event<T>, data: T): void;

---

emitChanged()

Convenience function for operations to report infrastructure modifications. Emits a CHANGE_EVENT with the provided entry or entries.

import { emitChanged } from 'sysopkit';

function emitChanged(entries: ChangeEntry | ChangeEntry[]): void;

---

onChange()

Registers a change listener for the duration of a function. The handler is called whenever a CHANGE_EVENT is emitted within the scope.

import { onChange } from 'sysopkit';

async function onChange<R>(
  handler: (event: ChangeEntry | ChangeEntry[]) => void,
  fn: () => R | Promise<R>,
): Promise<R>;

---

latch()

Returns a closure that starts false and flips to true on the first truthy call. Used with onChange() to detect whether changes occurred.

import { latch } from 'sysopkit';

function latch<T>(): (value?: T) => boolean;

const changed = latch();

// onChange will call changed(true) on any change
await onChange(changed, async () => {
  await createFile({ path: '/etc/conf', content: 'data' });
});

if (changed()) {
  // React to changes
}

---

middleware()

Wraps a connector with middleware for the duration of a function. The middleware factory receives the current connector and context, and returns a new connector.

import { middleware } from 'sysopkit';

function middleware<R>(
  name: string,
  fn: (ctx: ExecutionContext) => Promise<R>,
  wrap: (next: Connector, ctx: ExecutionContext) => Connector,
  options?: MiddlewareContextOptions,
): Promise<R>;