Class SSHKaos

packages/kaos/src/ssh.ts:435–945

 * A KAOS implementation that interacts with a remote machine via SSH and SFTP.
 */
export class SSHKaos implements Kaos {
  readonly name: string = 'ssh';

  private _client: Client;
  private _sftp: SFTPWrapper;
  private _home: string;
  private _cwd: string;
  private readonly _envLayers: readonly Record<string, string>[];

  // Stub: real wiring (probing the remote host via `uname` / `$SHELL` over the
  // SSH transport) is deferred.
  get osEnv(): Environment {
    throw new KaosError(
      'SSHKaos.osEnv is not yet wired — remote environment probing is not implemented.',
    );
  }

  private constructor(
    client: Client,
    sftp: SFTPWrapper,
    home: string,
    cwd: string,
    envLayers: readonly Record<string, string>[] = [],
  ) {
    this._client = client;
    this._sftp = sftp;
    this._home = home;
    this._cwd = cwd;
    this._envLayers = envLayers;
  }

  withCwd(cwd: string): SSHKaos {
    return new SSHKaos(this._client, this._sftp, this._home, cwd, this._envLayers);
  }

  withEnv(env: Record<string, string>): SSHKaos {
    return new SSHKaos(this._client, this._sftp, this._home, this._cwd, [...this._envLayers, env]);
  }

  private _resolvePath(path: string): string {
    if (isAbsolute(path)) return path;
    return join(this._cwd, path);
  }

  /**
   * Factory method to create an SSHKaos instance.
   * Establishes the SSH connection and SFTP session.
   */
  static async create(options: SSHKaosOptions): Promise<SSHKaos> {
    // Start from extraOptions (advanced ssh2 options) so our managed fields
    // below take precedence.
    const config: ConnectConfig = {
      ...options.extraOptions,
      host: options.host,
      port: options.port ?? 22,
      username: options.username,
    };