mindwire 0.1.0 → 0.1.2

package/dist/target/ssh.d.ts

@@ -0,0 +1,139 @@
+import { type EnsureEvent } from "./host.js";
+import type { Target, TargetHandle } from "./index.js";
+/** Options for the {@link ssh} target. */
+export interface SshOptions {
+    /** Host to connect to. */
+    host: string;
+    /** SSH port. Defaults to 22. */
+    port?: number;
+    /** SSH username. */
+    username: string;
+    /** Private key material (PEM). Highest-precedence auth. */
+    privateKey?: string | Buffer;
+    /** Path to a private key file (read at connect time). */
+    privateKeyPath?: string;
+    /** Passphrase for an encrypted private key. */
+    passphrase?: string;
+    /** Password auth. */
+    password?: string;
+    /** ssh-agent socket path. Defaults to `$SSH_AUTH_SOCK`. Used when no key/password is given. */
+    agent?: string;
+    /** Handshake timeout (ms). Defaults to 20000. */
+    readyTimeoutMs?: number;
+    /** Port the daemon listens on, on the REMOTE loopback. Defaults to 8790. */
+    daemonPort?: number;
+    /** `AGENT_TYPE` for the remote daemon. Defaults to the client's agent, then `claude-code`. */
+    agentType?: string;
+    /** `AGENT_CWD` — working directory agents run in, on the remote. Defaults to `/root`. */
+    agentCwd?: string;
+    /** Explicit path to a Linux `mindwired` to deploy (else resolved from the platform package). */
+    daemonBin?: string;
+    /** Redeploy when the running daemon's version differs from the SDK's bundled binary. */
+    autoUpdate?: boolean;
+    /** On `close()`, tear the tunnel down and end the SSH connection. Defaults to `true`. */
+    stopOnExit?: boolean;
+    /**
+     * Run the daemon **inside a Docker container** on the remote host instead of natively — a clean,
+     * reproducible, isolated environment per instance. mindwire ensures Docker is present, spins the
+     * container, deploys `mindwired` into it, and tunnels to its published loopback port. Docker is
+     * detected, never installed, unless you opt in with `install: "ifMissing"`.
+     */
+    docker?: {
+        /** Create + own a container from this image. */
+        image?: string;
+        /** Attach to an existing container (id or name) instead of creating one. */
+        container?: string;
+        /** Name for a container we create. */
+        name?: string;
+        /** Docker-on-host policy. `"never"` (default) detects and fails; `"ifMissing"` installs + starts it. */
+        install?: "never" | "ifMissing";
+        /** Extra args spliced into `docker run` (before the image), e.g. `["-e", "FOO=bar"]`. */
+        createArgs?: string[];
+    };
+}
+/**
+ * The SSH target. Returns a {@link Target} whose `connect()` opens an SSH connection, ensures
+ * `mindwired` runs on the remote, and points the SDK at a local tunnel to it.
+ *
+ * ```ts
+ * const mw = new Mindwire({ target: ssh({ host: "box.example.com", username: "root" }) });
+ * ```
+ */
+export declare function ssh(opts: SshOptions): Target;
+interface Ssh2Stream {
+    on(event: string, listener: (...args: any[]) => void): Ssh2Stream;
+    stderr?: {
+        on(event: string, listener: (...args: any[]) => void): unknown;
+    };
+    pipe(dest: any): any;
+    write?(chunk: unknown): unknown;
+    end?(chunk?: unknown): unknown;
+    close?(): unknown;
+    destroy?(): unknown;
+}
+interface Ssh2Sftp {
+    createWriteStream(path: string, opts?: {
+        mode?: number;
+    }): Ssh2Stream;
+}
+interface Ssh2Client {
+    on(event: string, listener: (...args: any[]) => void): Ssh2Client;
+    connect(cfg: Record<string, unknown>): void;
+    exec(command: string, cb: (err: Error | undefined, channel: Ssh2Stream) => void): void;
+    forwardOut(srcIP: string, srcPort: number, dstIP: string, dstPort: number, cb: (err: Error | undefined, channel: Ssh2Stream) => void): void;
+    sftp(cb: (err: Error | undefined, sftp: Ssh2Sftp) => void): void;
+    end(): void;
+}
+interface SshTunnel {
+    baseUrl: string;
+    close(): Promise<void>;
+}
+type MakeTunnel = (client: Ssh2Client, daemonPort: number) => Promise<SshTunnel>;
+/** The resolved inputs {@link provisionSsh} needs — decoupled from `SshOptions` and the lazy import. */
+export interface SshProvisionConfig {
+    /** Stable id for the handle (for logging). */
+    id: string;
+    /** Daemon port on the remote loopback. */
+    daemonPort: number;
+    /** `AGENT_TYPE` for the remote daemon. */
+    agent: string;
+    /** `AGENT_CWD` on the remote. */
+    agentCwd: string;
+    daemonBin?: string;
+    autoUpdate?: boolean;
+    /** Close the tunnel + end the SSH connection on `stop()`. */
+    stopOnExit?: boolean;
+    onLog?: (e: EnsureEvent) => void;
+}
+/**
+ * The provisioning flow, decoupled from the `ssh2` import and the tunnel implementation so it can be
+ * driven by an injected fake client + `makeTunnel` in tests. Ensures the daemon over the SSH
+ * connection, brings up the tunnel, and returns a handle pointed at `http://127.0.0.1:<localPort>`.
+ */
+export declare function provisionSsh(client: Ssh2Client, makeTunnel: MakeTunnel, cfg: SshProvisionConfig): Promise<TargetHandle>;
+/** The resolved inputs {@link provisionSshContainer} needs — the shared daemon knobs plus `docker`. */
+export interface SshContainerProvisionConfig {
+    /** Stable id for the handle (for logging). */
+    id: string;
+    /** Port the daemon binds *inside* the container. */
+    daemonPort: number;
+    /** `AGENT_TYPE` for the in-container daemon. */
+    agent: string;
+    /** `AGENT_CWD` inside the container. */
+    agentCwd: string;
+    daemonBin?: string;
+    autoUpdate?: boolean;
+    /** Close the tunnel, `docker rm -f` a created container, and end the SSH connection on `stop()`. */
+    stopOnExit?: boolean;
+    onLog?: (e: EnsureEvent) => void;
+    /** Container knobs (image/attach/name/install/createArgs). */
+    docker: NonNullable<SshOptions["docker"]>;
+}
+/**
+ * Provision the daemon **in a container** on the remote host over SSH: bridge the SSH connection into a
+ * {@link SandboxHost}, hand it to the generic {@link provisionContainer} (ensure Docker → run container
+ * → deploy the daemon inside), then tunnel to the container's published loopback host port. Decoupled
+ * from the `ssh2` import + tunnel like {@link provisionSsh}, so tests drive it with a fake client.
+ */
+export declare function provisionSshContainer(client: Ssh2Client, makeTunnel: MakeTunnel, cfg: SshContainerProvisionConfig): Promise<TargetHandle>;
+export {};