Context Variables

Context variables are branded symbols (Var<T>) that provide type-safe access to scoped values.

Var Type

type Var<T> = symbol & {
  readonly __value?: T;
  readonly __type?: 'sysopkit.var';
};

Variables are looked up via parent-chain traversal. A child context can access variables from any ancestor context.

Using Variables

import { task } from 'sysopkit';

task('inner', async (ctx) => {
  const value = ctx.tryGet(MY_VAR); // returns T | undefined
  const guaranteed = ctx.get(MY_VAR); // returns T, throws if absent
});

Built-in Variables

Variable	Type	Description
SUDO_USER	Var<string>	Default sudo user
SUDO_PASSWORD	Var<string>	Default sudo password
SUDO_ROLE	Var<string>	SELinux role for sudo
SUDO_PRESERVE_ENV	Var<boolean | string[]>	Preserved sudo env vars

SSH_AUTH_SOCKET is not a context variable — it is an environment key the SSH connector sets internally from its authSocket option.

Setting Variables

Variables are typically set when creating a context:

import { SUDO_PASSWORD } from 'sysopkit/middleware/sudo';
import { start } from 'sysopkit/start';

await start(
  async () => {
    // sudo middleware will read SUDO_PASSWORD from context
    await sudo(async () => {
      await sh('whoami');
    });
  },
  {
    vars: { [SUDO_PASSWORD]: 'secret' },
  },
);