@builder.io/ai-utils 0.79.2 → 0.79.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.79.2",
+  "version": "0.79.3",
   "description": "Builder.io AI utils",
   "files": [
     "src"

package/src/connectivity/checks/dns-check.d.ts

@@ -4,5 +4,11 @@ export interface DnsCheckOptions {
     source: Source;
     testId: TestId;
     timeout?: number;
+    /**
+     * Resolve against these DNS servers (each "ip" or "ip:port") instead of the
+     * system resolver — e.g. a VPC proxy's dnsmasq at "10.64.0.10:53" to test
+     * customer-internal name resolution.
+     */
+    servers?: string[];
 }
 export declare function dnsCheck(options: DnsCheckOptions): Promise<CheckResult>;

package/src/connectivity/checks/dns-check.js

@@ -1,10 +1,23 @@
 import dns from "node:dns";
 import { mapNodeErrorToConnectivityCode } from "../error-codes.js";
-const { resolve4, resolve6 } = dns.promises;
 const DEFAULT_TIMEOUT_MS = 10000;
 export async function dnsCheck(options) {
-    const { hostname, source, testId, timeout = DEFAULT_TIMEOUT_MS } = options;
+    const { hostname, source, testId, timeout = DEFAULT_TIMEOUT_MS, servers, } = options;
     const startTime = Date.now();
+    // Use a dedicated resolver when custom servers are provided; otherwise fall
+    // back to the process-wide resolver (system DNS). The dedicated resolver is
+    // cancelled on the way out (both paths) so a query left in flight by the
+    // timeout race doesn't keep its c-ares channel/handle alive (~25s) when the
+    // custom DNS server is unreachable.
+    let resolve4 = dns.promises.resolve4;
+    let resolve6 = dns.promises.resolve6;
+    let resolver;
+    if (servers && servers.length > 0) {
+        resolver = new dns.promises.Resolver();
+        resolver.setServers(servers);
+        resolve4 = resolver.resolve4.bind(resolver);
+        resolve6 = resolver.resolve6.bind(resolver);
+    }
     let timeoutId;
     const timeoutPromise = new Promise((_, reject) => {
         timeoutId = setTimeout(() => {
@@ -34,6 +47,7 @@ export async function dnsCheck(options) {
             }
         }
         clearTimeout(timeoutId);
+        resolver === null || resolver === void 0 ? void 0 : resolver.cancel();
         const durationMs = Date.now() - startTime;
         if (addresses.length === 0) {
             return {
@@ -63,6 +77,7 @@ export async function dnsCheck(options) {
     }
     catch (error) {
         clearTimeout(timeoutId);
+        resolver === null || resolver === void 0 ? void 0 : resolver.cancel();
         const durationMs = Date.now() - startTime;
         const err = error;
         if (err.message === "DNS resolution timed out") {

package/src/connectivity/checks/dns-check.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/src/connectivity/checks/dns-check.spec.js

@@ -0,0 +1,54 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import dns from "node:dns";
+import { dnsCheck } from "./dns-check.js";
+describe("dnsCheck", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("uses the system resolver and does NOT construct a custom Resolver", async () => {
+        const resolve4 = vi
+            .spyOn(dns.promises, "resolve4")
+            .mockResolvedValue(["1.2.3.4"]);
+        const setServers = vi.spyOn(dns.promises.Resolver.prototype, "setServers");
+        const result = await dnsCheck({
+            hostname: "git.example.com",
+            source: "cloud",
+            testId: "git-host:dns",
+        });
+        expect(result.passed).toBe(true);
+        expect(resolve4).toHaveBeenCalledWith("git.example.com");
+        expect(setServers).not.toHaveBeenCalled();
+    });
+    it("resolves against the provided servers via a dedicated Resolver", async () => {
+        var _a;
+        const setServers = vi.spyOn(dns.promises.Resolver.prototype, "setServers");
+        const resolve4 = vi
+            .spyOn(dns.promises.Resolver.prototype, "resolve4")
+            .mockResolvedValue(["10.20.30.40"]);
+        const result = await dnsCheck({
+            hostname: "git.internal.customer",
+            source: "vpc",
+            testId: "git-host:dns",
+            servers: ["10.64.0.10:53"],
+        });
+        expect(result.passed).toBe(true);
+        expect(setServers).toHaveBeenCalledWith(["10.64.0.10:53"]);
+        expect(resolve4).toHaveBeenCalledWith("git.internal.customer");
+        expect((_a = result.metadata) === null || _a === void 0 ? void 0 : _a.addresses).toEqual(["10.20.30.40"]);
+    });
+    it("ignores an empty servers array (falls back to the system resolver)", async () => {
+        const resolve4 = vi
+            .spyOn(dns.promises, "resolve4")
+            .mockResolvedValue(["1.2.3.4"]);
+        const setServers = vi.spyOn(dns.promises.Resolver.prototype, "setServers");
+        const result = await dnsCheck({
+            hostname: "git.example.com",
+            source: "vpc",
+            testId: "git-host:dns",
+            servers: [],
+        });
+        expect(result.passed).toBe(true);
+        expect(resolve4).toHaveBeenCalled();
+        expect(setServers).not.toHaveBeenCalled();
+    });
+});

package/src/connectivity/checks/ssh-check.d.ts

@@ -1,3 +1,4 @@
+import net from "net";
 import type { CheckResult, Source, TestId } from "../types.js";
 export interface SshCheckOptions {
     hostname: string;
@@ -5,5 +6,7 @@ export interface SshCheckOptions {
     source: Source;
     testId: TestId;
     timeout?: number;
+    /** Provide a pre-connected socket (e.g. tunneled through a SOCKS5 proxy). */
+    connectFn?: (hostname: string, port: number) => Promise<net.Socket>;
 }
 export declare function sshCheck(options: SshCheckOptions): Promise<CheckResult>;

package/src/connectivity/checks/ssh-check.js

@@ -5,52 +5,81 @@ const DEFAULT_TIMEOUT_MS = 5000;
 const SSH_BANNER_PREFIX = "SSH-";
 export async function sshCheck(options) {
     var _a, _b;
-    const { hostname, port = DEFAULT_PORT, source, testId, timeout = DEFAULT_TIMEOUT_MS, } = options;
+    const { hostname, port = DEFAULT_PORT, source, testId, timeout = DEFAULT_TIMEOUT_MS, connectFn, } = options;
     const target = `${hostname}:${port}`;
     const startTime = Date.now();
     try {
         const result = await new Promise((resolve) => {
-            const socket = new net.Socket();
             let banner = "";
-            socket.setTimeout(timeout);
-            socket.on("connect", () => {
-                // Wait for SSH banner data before closing
-            });
-            socket.on("data", (data) => {
-                banner += data.toString();
-                if (banner.includes("\n") || banner.length > 256) {
-                    socket.destroy();
-                    banner = banner.split("\n")[0].trim();
-                    if (banner.startsWith(SSH_BANNER_PREFIX)) {
-                        resolve({ success: true, banner });
+            // Shared by the direct path (socket we create) and the proxied path
+            // (socket returned already-connected by connectFn).
+            const attachHandlers = (socket) => {
+                socket.setTimeout(timeout);
+                socket.on("data", (data) => {
+                    banner += data.toString();
+                    if (banner.includes("\n") || banner.length > 256) {
+                        socket.destroy();
+                        banner = banner.split("\n")[0].trim();
+                        if (banner.startsWith(SSH_BANNER_PREFIX)) {
+                            resolve({ success: true, banner });
+                        }
+                        else {
+                            resolve({
+                                success: false,
+                                error: new Error(`Unexpected response: not an SSH server`),
+                                banner,
+                            });
+                        }
                     }
-                    else {
+                });
+                socket.on("timeout", () => {
+                    socket.destroy();
+                    const error = new Error("SSH connection timed out");
+                    error.code = "ETIMEDOUT";
+                    resolve({ success: false, error });
+                });
+                socket.on("error", (err) => {
+                    socket.destroy();
+                    resolve({ success: false, error: err });
+                });
+                socket.on("end", () => {
+                    if (!banner) {
                         resolve({
                             success: false,
-                            error: new Error(`Unexpected response: not an SSH server`),
-                            banner,
+                            error: new Error("Connection closed without receiving SSH banner"),
                         });
                     }
-                }
-            });
-            socket.on("timeout", () => {
-                socket.destroy();
-                const error = new Error("SSH connection timed out");
-                error.code = "ETIMEDOUT";
-                resolve({ success: false, error });
-            });
-            socket.on("error", (err) => {
-                socket.destroy();
-                resolve({ success: false, error: err });
-            });
-            socket.on("end", () => {
-                if (!banner) {
-                    resolve({
-                        success: false,
-                        error: new Error("Connection closed without receiving SSH banner"),
-                    });
-                }
-            });
+                });
+            };
+            if (connectFn) {
+                // Proxied path: connectFn returns an already-connected socket. Guard the
+                // connect itself with a timer since there's no "connect" event to await.
+                let timedOut = false;
+                const connectTimer = setTimeout(() => {
+                    timedOut = true;
+                    const error = new Error("SSH connection timed out");
+                    error.code = "ETIMEDOUT";
+                    resolve({ success: false, error });
+                }, timeout);
+                connectFn(hostname, port)
+                    .then((socket) => {
+                    clearTimeout(connectTimer);
+                    // If the timer already fired, the check has resolved as failed —
+                    // tear down the late socket instead of attaching, so it doesn't leak.
+                    if (timedOut) {
+                        socket.destroy();
+                        return;
+                    }
+                    attachHandlers(socket);
+                })
+                    .catch((err) => {
+                    clearTimeout(connectTimer);
+                    resolve({ success: false, error: err });
+                });
+                return;
+            }
+            const socket = new net.Socket();
+            attachHandlers(socket);
             socket.connect(port, hostname);
         });
         const durationMs = Date.now() - startTime;

package/src/connectivity/checks/ssh-check.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/src/connectivity/checks/ssh-check.spec.js

@@ -0,0 +1,102 @@
+import { describe, it, expect, afterEach, vi } from "vitest";
+import net from "node:net";
+import { sshCheck } from "./ssh-check.js";
+/** Start a throwaway TCP server that writes the given banner on connect. */
+function startServer(banner) {
+    return new Promise((resolve) => {
+        const server = net.createServer((socket) => {
+            socket.write(banner);
+        });
+        server.listen(0, "127.0.0.1", () => resolve(server));
+    });
+}
+function portOf(server) {
+    const addr = server.address();
+    if (addr && typeof addr === "object")
+        return addr.port;
+    throw new Error("no port");
+}
+describe("sshCheck", () => {
+    let server;
+    afterEach(() => {
+        server === null || server === void 0 ? void 0 : server.close();
+        server = undefined;
+    });
+    it("passes against a real SSH banner (direct connection)", async () => {
+        var _a;
+        server = await startServer("SSH-2.0-OpenSSH_9.0\r\n");
+        const result = await sshCheck({
+            hostname: "127.0.0.1",
+            port: portOf(server),
+            source: "local",
+            testId: "git-host:ssh",
+        });
+        expect(result.passed).toBe(true);
+        expect(String((_a = result.metadata) === null || _a === void 0 ? void 0 : _a.banner)).toMatch(/^SSH-/);
+    });
+    it("fails when the server is not an SSH server (direct connection)", async () => {
+        server = await startServer("HTTP/1.1 200 OK\r\n");
+        const result = await sshCheck({
+            hostname: "127.0.0.1",
+            port: portOf(server),
+            source: "local",
+            testId: "git-host:ssh",
+        });
+        expect(result.passed).toBe(false);
+    });
+    it("uses connectFn's pre-connected socket when provided", async () => {
+        var _a;
+        server = await startServer("SSH-2.0-Tunneled\r\n");
+        const port = portOf(server);
+        let called = false;
+        const connectFn = (hostname, p) => {
+            called = true;
+            return new Promise((resolve, reject) => {
+                const socket = net.connect(p, hostname);
+                socket.once("connect", () => resolve(socket));
+                socket.once("error", reject);
+            });
+        };
+        const result = await sshCheck({
+            hostname: "127.0.0.1",
+            port,
+            source: "vpc",
+            testId: "git-host:ssh",
+            connectFn,
+        });
+        expect(called).toBe(true);
+        expect(result.passed).toBe(true);
+        expect(String((_a = result.metadata) === null || _a === void 0 ? void 0 : _a.banner)).toMatch(/^SSH-/);
+    });
+    it("fails (does not throw) when connectFn rejects", async () => {
+        const connectFn = () => Promise.reject(new Error("tunnel refused"));
+        const result = await sshCheck({
+            hostname: "10.0.0.1",
+            port: 22,
+            source: "vpc",
+            testId: "git-host:ssh",
+            connectFn,
+        });
+        expect(result.passed).toBe(false);
+    });
+    it("destroys a connectFn socket that resolves after the timeout (no leak)", async () => {
+        const destroy = vi.fn();
+        // Resolves a fake socket well after the check's connect timeout fires.
+        const connectFn = () => new Promise((resolve) => {
+            setTimeout(() => resolve({ destroy }), 80);
+        });
+        const result = await sshCheck({
+            hostname: "10.0.0.1",
+            port: 22,
+            source: "vpc",
+            testId: "git-host:ssh",
+            timeout: 20,
+            connectFn,
+        });
+        expect(result.passed).toBe(false);
+        expect(result.errorCode).toBe("tcp_connection_timeout");
+        // Wait past the connectFn resolution to confirm the late socket is torn down.
+        await new Promise((r) => setTimeout(r, 100));
+        expect(destroy).toHaveBeenCalled();
+    });
+});

package/src/connectivity/classify.d.ts

@@ -0,0 +1,28 @@
+import type { CheckResult, ConnectivityStatus } from "./types.js";
+export type RowVerdict = "pass" | "informational" | "blocking";
+/**
+ * Classify a single connectivity check row into pass / informational / blocking.
+ *
+ * This is the SINGLE source of truth shared by the verdict math
+ * (`computeDoctorTotals`) and both report renderers (the dev-tools clack
+ * renderer and the builder-code Ink renderer), so the recommendation, exit code,
+ * summary count, outro text, and per-row rendering can never disagree — the
+ * verdict counts exactly the rows the renderers draw red.
+ *
+ * A failed row is INFORMATIONAL (contributes to neither passed nor failed, and
+ * renders as a warning rather than a blocking failure) when:
+ *
+ *  1. it is an SSH probe (`git-host:ssh`) — SSH is informational everywhere; or
+ *  2. it is the VPC DNS probe (`source === "vpc"` && `git-host:dns`) — matching
+ *     `analyzeConnectivity`'s `vpcCoreResults`, which excludes DNS from
+ *     `vpcToGitHost`; or
+ *  3. it is a LOCAL `git-host:*` probe superseded by a PASSING VPC probe
+ *     (`vpcToGitHost === "pass"`) — a private host is expected to be unreachable
+ *     from the local machine, and the VPC proxy is the authoritative path. This
+ *     mirrors `analyzeConnectivity` giving `vpcToGitHost === "pass"` precedence
+ *     over `localToGitHost`. Keyed on `=== "pass"` (not merely "a VPC run was
+ *     requested"), so a FAILED VPC run still surfaces the local failures.
+ */
+export declare function classifyCheckRow(result: CheckResult, ctx: {
+    vpcToGitHost?: ConnectivityStatus;
+}): RowVerdict;

package/src/connectivity/classify.js

@@ -0,0 +1,38 @@
+/**
+ * Classify a single connectivity check row into pass / informational / blocking.
+ *
+ * This is the SINGLE source of truth shared by the verdict math
+ * (`computeDoctorTotals`) and both report renderers (the dev-tools clack
+ * renderer and the builder-code Ink renderer), so the recommendation, exit code,
+ * summary count, outro text, and per-row rendering can never disagree — the
+ * verdict counts exactly the rows the renderers draw red.
+ *
+ * A failed row is INFORMATIONAL (contributes to neither passed nor failed, and
+ * renders as a warning rather than a blocking failure) when:
+ *
+ *  1. it is an SSH probe (`git-host:ssh`) — SSH is informational everywhere; or
+ *  2. it is the VPC DNS probe (`source === "vpc"` && `git-host:dns`) — matching
+ *     `analyzeConnectivity`'s `vpcCoreResults`, which excludes DNS from
+ *     `vpcToGitHost`; or
+ *  3. it is a LOCAL `git-host:*` probe superseded by a PASSING VPC probe
+ *     (`vpcToGitHost === "pass"`) — a private host is expected to be unreachable
+ *     from the local machine, and the VPC proxy is the authoritative path. This
+ *     mirrors `analyzeConnectivity` giving `vpcToGitHost === "pass"` precedence
+ *     over `localToGitHost`. Keyed on `=== "pass"` (not merely "a VPC run was
+ *     requested"), so a FAILED VPC run still surfaces the local failures.
+ */
+export function classifyCheckRow(result, ctx) {
+    if (result.passed)
+        return "pass";
+    if (result.testId === "git-host:ssh")
+        return "informational";
+    if (result.source === "vpc" && result.testId === "git-host:dns") {
+        return "informational";
+    }
+    if (result.source === "local" &&
+        result.testId.startsWith("git-host:") &&
+        ctx.vpcToGitHost === "pass") {
+        return "informational";
+    }
+    return "blocking";
+}

package/src/connectivity/classify.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/src/connectivity/classify.spec.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { classifyCheckRow } from "./classify.js";
+function row(source, testId, passed) {
+    return { source, testId, target: "git", passed, durationMs: 1 };
+}
+describe("classifyCheckRow", () => {
+    it("passing rows are 'pass' regardless of source", () => {
+        expect(classifyCheckRow(row("local", "git-host:tcp", true), {})).toBe("pass");
+        expect(classifyCheckRow(row("vpc", "git-host:dns", true), {})).toBe("pass");
+    });
+    it("a failing SSH probe is informational for any source", () => {
+        expect(classifyCheckRow(row("local", "git-host:ssh", false), {})).toBe("informational");
+        expect(classifyCheckRow(row("vpc", "git-host:ssh", false), {
+            vpcToGitHost: "fail",
+        })).toBe("informational");
+    });
+    it("a failing VPC DNS probe is informational (matches vpcCoreResults)", () => {
+        expect(classifyCheckRow(row("vpc", "git-host:dns", false), {
+            vpcToGitHost: "fail",
+        })).toBe("informational");
+    });
+    it("VPC core failures (tcp/tls/http) are blocking", () => {
+        for (const t of [
+            "git-host:tcp",
+            "git-host:tls",
+            "git-host:http",
+        ]) {
+            expect(classifyCheckRow(row("vpc", t, false), { vpcToGitHost: "fail" })).toBe("blocking");
+        }
+    });
+    it("local git-host failures are superseded (informational) ONLY when VPC passed", () => {
+        const r = row("local", "git-host:tcp", false);
+        expect(classifyCheckRow(r, { vpcToGitHost: "pass" })).toBe("informational");
+        // Not superseded when VPC failed or no VPC run happened.
+        expect(classifyCheckRow(r, { vpcToGitHost: "fail" })).toBe("blocking");
+        expect(classifyCheckRow(r, {})).toBe("blocking");
+    });
+    it("non-git-host local failures are always blocking", () => {
+        expect(classifyCheckRow(row("local", "builder.io", false), {
+            vpcToGitHost: "pass",
+        })).toBe("blocking");
+    });
+});

package/src/connectivity/node.d.ts

@@ -13,3 +13,5 @@ export { tlsCheck } from "./checks/tls-check.js";
 export type { TlsCheckOptions } from "./checks/tls-check.js";
 export { sshCheck } from "./checks/ssh-check.js";
 export type { SshCheckOptions } from "./checks/ssh-check.js";
+export { classifyCheckRow } from "./classify.js";
+export type { RowVerdict } from "./classify.js";

package/src/connectivity/node.js

@@ -7,3 +7,4 @@ export { dnsCheck } from "./checks/dns-check.js";
 export { tcpCheck } from "./checks/tcp-check.js";
 export { tlsCheck } from "./checks/tls-check.js";
 export { sshCheck } from "./checks/ssh-check.js";
+export { classifyCheckRow } from "./classify.js";

package/src/connectivity/run-checks.js

@@ -7,7 +7,7 @@ import { tcpCheck } from "./checks/tcp-check.js";
 import { tlsCheck } from "./checks/tls-check.js";
 import { sshCheck } from "./checks/ssh-check.js";
 export async function runChecks(input) {
-    const { tests, gitHost, onProgress, fetchFn, dispatcher, connectFn } = input;
+    const { tests, gitHost, onProgress, fetchFn, dispatcher, connectFn, sshConnectFn, dnsResolver, } = input;
     const results = [];
     const total = tests.length;
     for (let index = 0; index < tests.length; index++) {
@@ -18,7 +18,7 @@ export async function runChecks(input) {
             index,
             total,
         });
-        const result = await runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn);
+        const result = await runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn, sshConnectFn, dnsResolver);
         results.push(result);
         emitProgress(onProgress, {
             type: "test:complete",
@@ -37,7 +37,7 @@ export async function runChecks(input) {
         results,
     };
 }
-async function runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn) {
+async function runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn, sshConnectFn, dnsResolver) {
     const { source, testId } = test;
     const checkType = getCheckTypeForTestId(testId);
     if (!isCheckAvailable(checkType)) {
@@ -89,6 +89,7 @@ async function runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn) {
                 hostname: extractHostname(target),
                 source,
                 testId,
+                servers: dnsResolver === null || dnsResolver === void 0 ? void 0 : dnsResolver.servers,
             });
         case "tcp":
             return tcpCheck({
@@ -112,6 +113,7 @@ async function runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn) {
                 port: extractExplicitPort(target, 22),
                 source,
                 testId,
+                connectFn: sshConnectFn,
             });
         default:
             return {

package/src/connectivity/run-checks.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/src/connectivity/run-checks.spec.js

@@ -0,0 +1,47 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import dns from "node:dns";
+import { runChecks } from "./run-checks.js";
+const GIT_HOST = "https://git.example.com";
+describe("runChecks — proxy seams are opt-in (never assumed)", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("does NOT use a custom DNS resolver when dnsResolver is absent", async () => {
+        const resolve4 = vi
+            .spyOn(dns.promises, "resolve4")
+            .mockResolvedValue(["1.2.3.4"]);
+        const setServers = vi.spyOn(dns.promises.Resolver.prototype, "setServers");
+        await runChecks({
+            tests: [{ source: "cloud", testId: "git-host:dns" }],
+            gitHost: GIT_HOST,
+        });
+        expect(resolve4).toHaveBeenCalled();
+        expect(setServers).not.toHaveBeenCalled();
+    });
+    it("threads dnsResolver.servers to the DNS check when provided", async () => {
+        const setServers = vi.spyOn(dns.promises.Resolver.prototype, "setServers");
+        vi.spyOn(dns.promises.Resolver.prototype, "resolve4").mockResolvedValue([
+            "10.0.0.5",
+        ]);
+        await runChecks({
+            tests: [{ source: "vpc", testId: "git-host:dns" }],
+            gitHost: GIT_HOST,
+            dnsResolver: { servers: ["10.64.0.10:53"] },
+        });
+        expect(setServers).toHaveBeenCalledWith(["10.64.0.10:53"]);
+    });
+    it("threads sshConnectFn to the SSH check when provided", async () => {
+        var _a;
+        const sshConnectFn = vi
+            .fn()
+            .mockRejectedValue(new Error("tunnel unavailable"));
+        const report = await runChecks({
+            tests: [{ source: "vpc", testId: "git-host:ssh" }],
+            gitHost: GIT_HOST,
+            sshConnectFn,
+        });
+        expect(sshConnectFn).toHaveBeenCalled();
+        // It still returns a (failed) result rather than throwing.
+        expect((_a = report.results[0]) === null || _a === void 0 ? void 0 : _a.passed).toBe(false);
+    });
+});

package/src/connectivity/types.d.ts

@@ -1,4 +1,4 @@
-export type Source = "local" | "cloud" | "static-ip";
+export type Source = "local" | "cloud" | "static-ip" | "vpc";
 export type TestId = "builder.io" | "builder.codes" | "api.builder.io" | "cdn.builder.io" | "builderio.xyz" | "builderio.xyz:ws" | "builderio.dev" | "builderio.dev:ws" | "fly.dev" | "git-host:http" | "git-host:dns" | "git-host:tcp" | "git-host:tls" | "git-host:ssh";
 export interface Test {
     source: Source;
@@ -26,11 +26,25 @@ export interface RunChecksInput {
      */
     dispatcher?: object;
     /**
-     * Returns a connected socket tunneled through a proxy (via HTTP CONNECT).
-     * Used by TCP and TLS checks for static IP routing. The returned socket
-     * is already connected to hostname:port through the proxy.
+     * Returns a connected socket tunneled through a proxy (via HTTP CONNECT
+     * or SOCKS5). Used by TCP and TLS checks for static IP / VPC routing. The
+     * returned socket is already connected to hostname:port through the proxy.
      */
     connectFn?: (hostname: string, port: number) => Promise<unknown>;
+    /**
+     * Like `connectFn`, but used by the SSH check. Kept separate so SSH can be
+     * proxied independently of TCP/TLS (e.g. routed through a VPC SOCKS5 proxy).
+     */
+    sshConnectFn?: (hostname: string, port: number) => Promise<unknown>;
+    /**
+     * DNS servers (e.g. ["10.64.0.10:53"]) the DNS check should resolve against
+     * instead of the system resolver. Used to resolve customer-internal hostnames
+     * via a VPC proxy's DNS forwarder (dnsmasq), which the caller can reach
+     * directly even though SOCKS5 only does remote DNS on connect.
+     */
+    dnsResolver?: {
+        servers: string[];
+    };
 }
 export type ProgressEvent = {
     type: "test:start";
@@ -62,7 +76,7 @@ export interface CheckReport {
 }
 export type ConnectivityErrorCode = "dns_resolution_failed" | "dns_timeout" | "dns_wrong_ip" | "tcp_connection_refused" | "tcp_connection_timeout" | "tcp_connection_reset" | "tcp_host_unreachable" | "tcp_network_unreachable" | "tls_self_signed_cert" | "tls_cert_expired" | "tls_cert_not_yet_valid" | "tls_cert_invalid" | "tls_cert_hostname_mismatch" | "tls_handshake_failed" | "tls_protocol_error" | "proxy_auth_required" | "proxy_connection_failed" | "proxy_tunnel_failed" | "http_unauthorized" | "http_forbidden" | "http_not_found" | "http_server_error" | "http_service_unavailable" | "latency_high" | "check_unavailable" | "unknown_error";
 export type CheckType = "http" | "websocket" | "dns" | "tcp" | "tls" | "ssh";
-export type Recommendation = "ready_for_cloud_dev" | "enable_static_ip_proxy" | "whitelist_static_ip" | "fix_local_dns" | "fix_local_tls_certs" | "fix_local_firewall" | "use_local_development";
+export type Recommendation = "ready_for_cloud_dev" | "enable_static_ip_proxy" | "whitelist_static_ip" | "fix_local_dns" | "fix_local_tls_certs" | "fix_local_firewall" | "fix_vpc_connectivity" | "use_local_development";
 export type LikelyCause = "ip_whitelisting_required" | "vpn_blocking" | "corporate_proxy_required" | "self_signed_certificate" | "dns_misconfiguration" | "firewall_blocking" | "server_unavailable";
 export type ConnectivityStatus = "pass" | "fail" | "unknown";
 export interface AnalysisResult {
@@ -76,6 +90,7 @@ export interface AnalysisResult {
         localToGitHost: ConnectivityStatus;
         cloudToGitHost: ConnectivityStatus;
         staticIpToGitHost: ConnectivityStatus;
+        vpcToGitHost: ConnectivityStatus;
     };
     allResults: CheckResult[];
 }

package/src/index.d.ts

@@ -16,6 +16,7 @@ export * from "./vscode-tunnel.js";
 export * from "./claw.js";
 export * from "./kube-error.js";
 export * from "./connectivity/types.js";
+export * from "./connectivity/classify.js";
 export * from "./single-tenancy.js";
 export * from "./design-systems.js";
 export { connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, } from "./connectivity/error-codes.js";

package/src/index.js

@@ -16,6 +16,7 @@ export * from "./vscode-tunnel.js";
 export * from "./claw.js";
 export * from "./kube-error.js";
 export * from "./connectivity/types.js";
+export * from "./connectivity/classify.js";
 export * from "./single-tenancy.js";
 export * from "./design-systems.js";
 export { connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, } from "./connectivity/error-codes.js";