paratix 0.10.0 → 0.12.2

package/dist/types-Cl2Muw1x.d.ts

@@ -1,254 +0,0 @@
-/**
- * A scalar env value, or a lazy function that returns one.
- * Functions may be async, allowing secrets to be fetched on demand.
- */
-type EnvironmentValue = (() => boolean | number | string) | (() => Promise<boolean | number | string>) | boolean | number | string;
-/** A key-value map of environment values available to modules and templates. */
-type Environment = Record<string, EnvironmentValue>;
-/** Environment values that can be emitted through the typed meta system. */
-type MetaEnvironmentValue = EnvironmentValue;
-/** Generic meta entry that propagates a value into the downstream environment. */
-type EnvironmentMetaEntry = {
-    kind: "env";
-    name: string;
-    resolve: () => Promise<boolean | number | string>;
-    valueType: "boolean" | "number" | "string";
-};
-/** Runner control-plane meta entry emitted when sshd changed its listen port. */
-type SshdPortMetaEntry = {
-    kind: "sshd.port";
-    port: number;
-};
-/** Runner control-plane meta entry emitted when the target host changed. */
-type SystemHostMetaEntry = {
-    host: string;
-    kind: "system.host";
-};
-/** Runner control-plane meta entry emitted when a reboot should trigger reconnect logic. */
-type SystemRebootMetaEntry = {
-    kind: "system.reboot";
-};
-/** Any meta entry that modules may emit. */
-type ModuleMetaEntry = EnvironmentMetaEntry | SshdPortMetaEntry | SystemHostMetaEntry | SystemRebootMetaEntry;
-/** Check result indicating the module's desired state is not yet present. */
-declare const NEEDS_APPLY: "needs-apply";
-/** Execution status emitted by a module apply step. */
-type ModuleStatus = "changed" | "failed" | "ok" | "skipped";
-/** The outcome of a module's apply step. */
-type ModuleResult = {
-    /**
-     * Optional internal dry-run detail shown instead of the generic `(dry-run)`
-     * suffix when a module performed custom dry-run verification.
-     * @internal
-     */
-    _dryRunDetail?: string;
-    /**
-     * Optional internal control-plane marker that tells the current scope to
-     * execute all pending signals immediately at this point in the run.
-     * @internal
-     */
-    _flushSignals?: true;
-    /**
-     * Optional internal control-plane marker that tells the runner to stop the
-     * current run successfully after this module completed.
-     * @internal
-     */
-    _stopRun?: true;
-    /** Optional short detail appended to the printed module status line. */
-    detail?: string;
-    /** Optional error details consumed by the runner for centralized CLI output. */
-    error?: Error;
-    /** Optional typed meta entries for env propagation and runner control-plane updates. */
-    meta?: ModuleMetaEntry[];
-    /** Execution status of the module. */
-    status: ModuleStatus;
-};
-/**
- * Internal orchestration step shape shared between runner and recipe execution.
- * Contains the merged downstream environment after a single apply step.
- * @internal
- */
-type OrchestrationStep = {
-    /** @internal */
-    _flushSignals?: true;
-    /** @internal */
-    _stopRun?: true;
-    env: Environment;
-    meta?: ModuleMetaEntry[];
-    status: ModuleStatus;
-};
-/**
- * A single idempotent unit of work that can be checked and applied.
- * Modules form the building blocks of a server recipe.
- */
-type Module = {
-    /**
-     * Optional internal dry-run apply hook for modules that need custom dry-run
-     * execution semantics beyond the generic blocker/meta-producer markers.
-     * @internal
-     */
-    _applyDryRun?: (ssh: null | SshConnection, environment: Environment) => Promise<ModuleResult>;
-    /**
-     * Internal marker for modules that must still execute their apply step in dry-run mode
-     * because they act as run blockers rather than mutating state.
-     * @internal
-     */
-    _dryRunBlocker?: true;
-    /**
-     * Internal marker for non-mutating modules whose apply step emits meta that must
-     * still be materialized during dry-run so downstream modules see the same environment.
-     * @internal
-     */
-    _dryRunMetaProducer?: true;
-    /**
-     * Enforce the desired state.
-     * @returns A {@link ModuleResult} describing what happened.
-     */
-    apply: (ssh: null | SshConnection, environment: Environment) => Promise<ModuleResult>;
-    /**
-     * Determine whether the module needs to run.
-     * @returns `"ok"` if the desired state is already present, `"needs-apply"` otherwise.
-     */
-    check: (ssh: null | SshConnection, environment: Environment) => Promise<"needs-apply" | "ok">;
-    /**
-     * When true the module runs locally instead of over SSH.
-     * The `ssh` parameter will be `null` in check/apply.
-     */
-    local?: boolean;
-    /** Human-readable name shown in the run output. */
-    name: string;
-};
-/** Raw output from a remote or local command execution. */
-type ExecResult = {
-    /** Exit code of the process. */
-    code: number;
-    /** Captured standard error. */
-    stderr: string;
-    /** Captured standard output. */
-    stdout: string;
-};
-/** Options that control how a command is executed. */
-type ExecOptions = {
-    /** Additional environment variables to inject into the process. */
-    env?: Record<string, string>;
-    /** Return a result even when the exit code is non-zero instead of throwing. */
-    ignoreExitCode?: boolean;
-    /** Strings to mask in error messages (e.g. tokens, passwords). */
-    secrets?: string[];
-    /** Suppress stdout/stderr from the console while running. */
-    silent?: boolean;
-    /** Abort the command after this many milliseconds. */
-    timeout?: number;
-};
-/**
- * Abstraction over an active SSH session.
- * All methods that accept a `command` string run it on the remote host.
- */
-type SshConnection = {
-    /** Register an additional port that was opened on the remote host. */
-    addPort: (port: number) => void;
-    /** Close the SSH connection and free resources. */
-    disconnect: () => void;
-    /** Download a remote file to the local filesystem. */
-    downloadFile: (remotePath: string, localPath: string) => Promise<void>;
-    /** Run a command and return the full result including exit code and output. */
-    exec: (command: string, options?: ExecOptions) => Promise<ExecResult>;
-    /** Return `true` if the remote path exists. */
-    exists: (remotePath: string) => Promise<boolean>;
-    /**
-     * Return the low-level connection parameters for this session.
-     * `privateKeyPath` and `agentSocket` reflect the authentication method that
-     * was actually used for the current session. `privateKeyPath` is returned as
-     * an expanded filesystem path.
-     */
-    getConnectionInfo: () => {
-        agentSocket?: string;
-        authMethod?: "agent" | "password" | "privateKey";
-        host: string;
-        port: number;
-        privateKeyPath?: string;
-        user: string;
-        verifiedHostPublicKey?: string;
-    };
-    /** Run a command and return stdout split into lines. */
-    lines: (command: string) => Promise<string[]>;
-    /** Run a command and return trimmed stdout. */
-    output: (command: string) => Promise<string>;
-    /** Probe whether passwordless sudo works; prompt interactively if not and cache the password. */
-    probeSudo: () => Promise<void>;
-    /** Read the full contents of a remote file as a string. */
-    readFile: (remotePath: string) => Promise<string>;
-    /** Remove a previously registered port from the reconnect candidate list. */
-    removePort: (port: number) => void;
-    /** Return the SHA-256 hex digest of a remote file, or `null` if not found. */
-    sha256: (remotePath: string) => Promise<null | string>;
-    /** Run a command and return `true` if the exit code is zero. */
-    test: (command: string) => Promise<boolean>;
-    /** Update the target host address (e.g. after a reboot with new IP). */
-    updateHost: (host: string) => void;
-    /** Upload a local file to the remote host via SFTP. */
-    uploadFile: (localPath: string, remotePath: string, options?: {
-        mode?: string;
-    }) => Promise<void>;
-    /** Write a string to a remote file, creating or overwriting it. */
-    writeFile: (remotePath: string, content: string, options: {
-        mode: string;
-    }) => Promise<void>;
-};
-/** SSH connection parameters for a server. */
-type SshConfig = {
-    /** Forward the local SSH agent to the remote host. */
-    agentForward?: boolean;
-    /** Expected SHA256 host fingerprint used as a pinned trust anchor. */
-    expectedHostFingerprint?: string;
-    /** Expected OpenSSH public key (`"<algorithm> <base64>"`) used as a pinned trust anchor. */
-    expectedHostPublicKey?: string;
-    /** Maximum number of reconnection attempts before giving up. */
-    maxReconnectAttempts?: number;
-    /** Fall back to password authentication if key auth fails. */
-    passwordFallback?: boolean;
-    /** Ordered list of candidate ports -- the runner tries each until one connects. */
-    ports: number[];
-    /**
-     * Absolute path to the private key file used for authentication.
-     * When omitted, the SSH agent referenced by `SSH_AUTH_SOCK` is used instead.
-     * Exactly one of `privateKey` or a running SSH agent must be available.
-     */
-    privateKey?: string;
-    /** Maximum time in milliseconds to spend attempting reconnection before giving up. */
-    reconnectTimeout?: number;
-    /**
-     * Host key verification strategy.
-     * - `"accept-new"` — explicit TOFU opt-in: accept unknown keys and append them to `~/.ssh/known_hosts`.
-     * - `"yes"` — reject unknown keys; only connect when the key is already in `known_hosts`.
-     * - `"no"` — skip host key verification entirely.
-     *
-     * When omitted, Paratix now defaults to `"yes"`. To connect to a new host
-     * safely without TOFU, set `expectedHostFingerprint` or `expectedHostPublicKey`.
-     */
-    strictHostKeyChecking?: "accept-new" | "no" | "yes";
-    /** Password used for `sudo` escalation on the remote host. */
-    sudoPassword?: string;
-    /** Username to authenticate as. */
-    user: string;
-};
-/** Top-level definition of a server and the modules to run on it. */
-type ServerDefinition = {
-    /** Server-level env values merged with global env before running modules. */
-    env?: Environment;
-    /** Hostname or IP address. */
-    host: string;
-    /** Display name for the server. */
-    name: string;
-    /** Ordered list of modules (or recipes) to apply. */
-    run: Module[];
-    /**
-     * Modules triggered as signals after the run completes with status `"changed"`.
-     * Typically used for service reloads or notifications.
-     */
-    signals?: Module[];
-    /** SSH connection parameters. */
-    ssh: SshConfig;
-};
-
-export { type Environment as E, type Module as M, NEEDS_APPLY as N, type OrchestrationStep as O, type ServerDefinition as S, type ModuleMetaEntry as a, type MetaEnvironmentValue as b, type EnvironmentMetaEntry as c, type SshdPortMetaEntry as d, type SystemHostMetaEntry as e, type SystemRebootMetaEntry as f, type ModuleResult as g, type ExecResult as h, type ModuleStatus as i, type SshConnection as j, type EnvironmentValue as k, type ExecOptions as l, type SshConfig as m };