@builder.io/ai-utils 0.20.1 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "description": "Builder.io AI utils",
   "type": "module",
   "main": "src/index.js",
@@ -9,6 +9,14 @@
     ".": {
       "import": "./src/index.js",
       "types": "./src/index.d.ts"
+    },
+    "./connectivity/node": {
+      "import": "./src/connectivity/node.js",
+      "types": "./src/connectivity/node.d.ts"
+    },
+    "./connectivity/browser": {
+      "import": "./src/connectivity/browser.js",
+      "types": "./src/connectivity/browser.d.ts"
     }
   },
   "files": [

package/src/connectivity/browser.d.ts

@@ -0,0 +1,7 @@
+export type { Source, TestId, Test, RunChecksInput, ProgressEvent, CheckResult, CheckReport, ConnectivityErrorCode, CheckType, Recommendation, LikelyCause, ConnectivityStatus, AnalysisResult, AnalyzeConnectivityInput, } from "./types.js";
+export { runChecks } from "./run-checks.browser.js";
+export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, SELF_SIGNED_CERT_ERRORS, CERT_EXPIRED_ERRORS, CERT_NOT_YET_VALID_ERRORS, CERT_INVALID_ERRORS, CERT_HOSTNAME_MISMATCH_ERRORS, SSL_PROTOCOL_ERRORS, SSL_HANDSHAKE_ERRORS, NETWORK_UNREACHABLE_ERRORS, TIMEOUT_ERRORS, PROXY_ERRORS, DNS_ERRORS, } from "./error-codes.js";
+export { BUILDER_TARGETS, DEFAULT_PORTS, resolveTarget, extractHostname, extractPort, } from "./targets.js";
+export { isBrowser, isNode, getCheckTypeForTestId, isCheckAvailable, getUnavailabilityReason, } from "./environment.js";
+export { httpCheck } from "./checks/http-check.js";
+export type { HttpCheckOptions } from "./checks/http-check.js";

package/src/connectivity/browser.js

@@ -0,0 +1,5 @@
+export { runChecks } from "./run-checks.browser.js";
+export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, SELF_SIGNED_CERT_ERRORS, CERT_EXPIRED_ERRORS, CERT_NOT_YET_VALID_ERRORS, CERT_INVALID_ERRORS, CERT_HOSTNAME_MISMATCH_ERRORS, SSL_PROTOCOL_ERRORS, SSL_HANDSHAKE_ERRORS, NETWORK_UNREACHABLE_ERRORS, TIMEOUT_ERRORS, PROXY_ERRORS, DNS_ERRORS, } from "./error-codes.js";
+export { BUILDER_TARGETS, DEFAULT_PORTS, resolveTarget, extractHostname, extractPort, } from "./targets.js";
+export { isBrowser, isNode, getCheckTypeForTestId, isCheckAvailable, getUnavailabilityReason, } from "./environment.js";
+export { httpCheck } from "./checks/http-check.js";

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

@@ -0,0 +1,8 @@
+import type { CheckResult, Source, TestId } from "../types.js";
+export interface DnsCheckOptions {
+    hostname: string;
+    source: Source;
+    testId: TestId;
+    timeout?: number;
+}
+export declare function dnsCheck(options: DnsCheckOptions): Promise<CheckResult>;

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

@@ -0,0 +1,96 @@
+import dns from "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 startTime = Date.now();
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new Error("DNS resolution timed out"));
+        }, timeout);
+    });
+    try {
+        let addresses = [];
+        let ipVersion = "IPv4";
+        try {
+            addresses = await Promise.race([resolve4(hostname), timeoutPromise]);
+        }
+        catch (ipv4Error) {
+            // If IPv4 fails with ENODATA/ENOTFOUND, try IPv6 before giving up
+            const err = ipv4Error;
+            if (err.code === "ENODATA" || err.code === "ENOTFOUND") {
+                try {
+                    addresses = await Promise.race([resolve6(hostname), timeoutPromise]);
+                    ipVersion = "IPv6";
+                }
+                catch (_a) {
+                    throw ipv4Error;
+                }
+            }
+            else {
+                throw ipv4Error;
+            }
+        }
+        clearTimeout(timeoutId);
+        const durationMs = Date.now() - startTime;
+        if (addresses.length === 0) {
+            return {
+                source,
+                testId,
+                target: hostname,
+                passed: false,
+                errorCode: "dns_resolution_failed",
+                durationMs,
+                metadata: {
+                    error: "No addresses resolved",
+                },
+            };
+        }
+        return {
+            source,
+            testId,
+            target: hostname,
+            passed: true,
+            durationMs,
+            metadata: {
+                addresses,
+                ipVersion,
+                addressCount: addresses.length,
+            },
+        };
+    }
+    catch (error) {
+        clearTimeout(timeoutId);
+        const durationMs = Date.now() - startTime;
+        const err = error;
+        if (err.message === "DNS resolution timed out") {
+            return {
+                source,
+                testId,
+                target: hostname,
+                passed: false,
+                errorCode: "dns_timeout",
+                durationMs,
+                metadata: {
+                    error: err.message,
+                    timeoutMs: timeout,
+                },
+            };
+        }
+        const errorCode = mapNodeErrorToConnectivityCode(err);
+        return {
+            source,
+            testId,
+            target: hostname,
+            passed: false,
+            errorCode,
+            durationMs,
+            metadata: {
+                error: err.message,
+                nodeErrorCode: err.code,
+            },
+        };
+    }
+}

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

@@ -0,0 +1,8 @@
+import type { CheckResult, Source, TestId } from "../types.js";
+export interface HttpCheckOptions {
+    target: string;
+    source: Source;
+    testId: TestId;
+    timeout?: number;
+}
+export declare function httpCheck(options: HttpCheckOptions): Promise<CheckResult>;

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

@@ -0,0 +1,81 @@
+import { mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, } from "../error-codes.js";
+const DEFAULT_TIMEOUT_MS = 30000;
+const LATENCY_THRESHOLD_MS = 5000;
+export async function httpCheck(options) {
+    const { target, source, testId, timeout = DEFAULT_TIMEOUT_MS } = options;
+    const startTime = Date.now();
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+        const response = await fetch(target, {
+            method: "HEAD",
+            signal: controller.signal,
+            redirect: "follow",
+        });
+        clearTimeout(timeoutId);
+        const durationMs = Date.now() - startTime;
+        const errorCode = mapHttpStatusToErrorCode(response.status);
+        const hasHighLatency = durationMs > LATENCY_THRESHOLD_MS;
+        if (errorCode) {
+            return {
+                source,
+                testId,
+                target,
+                passed: false,
+                errorCode,
+                durationMs,
+                metadata: {
+                    statusCode: response.status,
+                    statusText: response.statusText,
+                },
+            };
+        }
+        return {
+            source,
+            testId,
+            target,
+            passed: true,
+            durationMs,
+            errorCode: hasHighLatency ? "latency_high" : undefined,
+            metadata: {
+                statusCode: response.status,
+                statusText: response.statusText,
+                latencyHigh: hasHighLatency,
+            },
+        };
+    }
+    catch (error) {
+        clearTimeout(timeoutId);
+        const durationMs = Date.now() - startTime;
+        const err = error;
+        if (err.name === "AbortError") {
+            return {
+                source,
+                testId,
+                target,
+                passed: false,
+                errorCode: "tcp_connection_timeout",
+                durationMs,
+                metadata: {
+                    error: "Request timed out",
+                    timeoutMs: timeout,
+                },
+            };
+        }
+        const errorCode = mapFetchErrorToConnectivityCode(err);
+        return {
+            source,
+            testId,
+            target,
+            passed: false,
+            errorCode,
+            durationMs,
+            metadata: {
+                error: err.message,
+                ...(err.cause && {
+                    causeCode: err.cause.code,
+                }),
+            },
+        };
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { CheckResult, Source, TestId } from "../types.js";
+export interface SshCheckOptions {
+    hostname: string;
+    port?: number;
+    source: Source;
+    testId: TestId;
+    timeout?: number;
+}
+export declare function sshCheck(options: SshCheckOptions): Promise<CheckResult>;

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

@@ -0,0 +1,108 @@
+import net from "net";
+import { mapNodeErrorToConnectivityCode } from "../error-codes.js";
+const DEFAULT_PORT = 22;
+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 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 });
+                    }
+                    else {
+                        resolve({
+                            success: false,
+                            error: new Error(`Unexpected response: not an SSH server`),
+                            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"),
+                    });
+                }
+            });
+            socket.connect(port, hostname);
+        });
+        const durationMs = Date.now() - startTime;
+        if (result.success) {
+            return {
+                source,
+                testId,
+                target,
+                passed: true,
+                durationMs,
+                metadata: {
+                    hostname,
+                    port,
+                    banner: result.banner,
+                },
+            };
+        }
+        const errorCode = result.error
+            ? mapNodeErrorToConnectivityCode(result.error)
+            : "tcp_connection_refused";
+        return {
+            source,
+            testId,
+            target,
+            passed: false,
+            errorCode,
+            durationMs,
+            metadata: {
+                hostname,
+                port,
+                error: (_a = result.error) === null || _a === void 0 ? void 0 : _a.message,
+                nodeErrorCode: (_b = result.error) === null || _b === void 0 ? void 0 : _b.code,
+                banner: result.banner,
+            },
+        };
+    }
+    catch (error) {
+        const durationMs = Date.now() - startTime;
+        const err = error;
+        return {
+            source,
+            testId,
+            target,
+            passed: false,
+            errorCode: mapNodeErrorToConnectivityCode(err),
+            durationMs,
+            metadata: {
+                hostname,
+                port,
+                error: err.message,
+                nodeErrorCode: err.code,
+            },
+        };
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { CheckResult, Source, TestId } from "../types.js";
+export interface TcpCheckOptions {
+    hostname: string;
+    port?: number;
+    source: Source;
+    testId: TestId;
+    timeout?: number;
+}
+export declare function tcpCheck(options: TcpCheckOptions): Promise<CheckResult>;

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

@@ -0,0 +1,80 @@
+import net from "net";
+import { mapNodeErrorToConnectivityCode } from "../error-codes.js";
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_PORT = 443;
+export async function tcpCheck(options) {
+    var _a, _b;
+    const { hostname, port = DEFAULT_PORT, source, testId, timeout = DEFAULT_TIMEOUT_MS, } = options;
+    const target = `${hostname}:${port}`;
+    const startTime = Date.now();
+    try {
+        const result = await new Promise((resolve) => {
+            const socket = new net.Socket();
+            socket.setTimeout(timeout);
+            socket.on("connect", () => {
+                socket.destroy();
+                resolve({ success: true });
+            });
+            socket.on("timeout", () => {
+                socket.destroy();
+                const error = new Error("Connection timed out");
+                error.code = "ETIMEDOUT";
+                resolve({ success: false, error });
+            });
+            socket.on("error", (err) => {
+                socket.destroy();
+                resolve({ success: false, error: err });
+            });
+            socket.connect(port, hostname);
+        });
+        const durationMs = Date.now() - startTime;
+        if (result.success) {
+            return {
+                source,
+                testId,
+                target,
+                passed: true,
+                durationMs,
+                metadata: {
+                    hostname,
+                    port,
+                },
+            };
+        }
+        const errorCode = result.error
+            ? mapNodeErrorToConnectivityCode(result.error)
+            : "tcp_connection_timeout";
+        return {
+            source,
+            testId,
+            target,
+            passed: false,
+            errorCode,
+            durationMs,
+            metadata: {
+                hostname,
+                port,
+                error: (_a = result.error) === null || _a === void 0 ? void 0 : _a.message,
+                nodeErrorCode: (_b = result.error) === null || _b === void 0 ? void 0 : _b.code,
+            },
+        };
+    }
+    catch (error) {
+        const durationMs = Date.now() - startTime;
+        const err = error;
+        return {
+            source,
+            testId,
+            target,
+            passed: false,
+            errorCode: mapNodeErrorToConnectivityCode(err),
+            durationMs,
+            metadata: {
+                hostname,
+                port,
+                error: err.message,
+                nodeErrorCode: err.code,
+            },
+        };
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { CheckResult, Source, TestId } from "../types.js";
+export interface TlsCheckOptions {
+    hostname: string;
+    port?: number;
+    source: Source;
+    testId: TestId;
+    timeout?: number;
+}
+export declare function tlsCheck(options: TlsCheckOptions): Promise<CheckResult>;

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

@@ -0,0 +1,113 @@
+import tls from "tls";
+import { mapNodeErrorToConnectivityCode } from "../error-codes.js";
+const DEFAULT_TIMEOUT_MS = 10000;
+const DEFAULT_PORT = 443;
+export async function tlsCheck(options) {
+    var _a, _b;
+    const { hostname, port = DEFAULT_PORT, source, testId, timeout = DEFAULT_TIMEOUT_MS, } = options;
+    const target = `${hostname}:${port}`;
+    const startTime = Date.now();
+    try {
+        const result = await new Promise((resolve) => {
+            const socket = tls.connect({
+                host: hostname,
+                port,
+                servername: hostname, // SNI required for virtual hosts
+                rejectUnauthorized: true,
+                timeout,
+            }, () => {
+                const cert = socket.getPeerCertificate();
+                let certInfo;
+                if (cert && Object.keys(cert).length > 0) {
+                    certInfo = {
+                        subject: formatCertName(cert.subject),
+                        issuer: formatCertName(cert.issuer),
+                        validFrom: cert.valid_from,
+                        validTo: cert.valid_to,
+                        fingerprint: cert.fingerprint,
+                        serialNumber: cert.serialNumber,
+                        subjectAltNames: cert.subjectaltname
+                            ? cert.subjectaltname.split(", ")
+                            : undefined,
+                    };
+                }
+                socket.end();
+                resolve({ success: true, certInfo });
+            });
+            socket.on("timeout", () => {
+                socket.destroy();
+                const error = new Error("TLS connection timed out");
+                error.code = "ETIMEDOUT";
+                resolve({ success: false, error });
+            });
+            socket.on("error", (err) => {
+                socket.destroy();
+                resolve({ success: false, error: err });
+            });
+        });
+        const durationMs = Date.now() - startTime;
+        if (result.success) {
+            return {
+                source,
+                testId,
+                target,
+                passed: true,
+                durationMs,
+                metadata: {
+                    hostname,
+                    port,
+                    certificate: result.certInfo,
+                },
+            };
+        }
+        const errorCode = result.error
+            ? mapNodeErrorToConnectivityCode(result.error)
+            : "tls_handshake_failed";
+        return {
+            source,
+            testId,
+            target,
+            passed: false,
+            errorCode,
+            durationMs,
+            metadata: {
+                hostname,
+                port,
+                error: (_a = result.error) === null || _a === void 0 ? void 0 : _a.message,
+                nodeErrorCode: (_b = result.error) === null || _b === void 0 ? void 0 : _b.code,
+            },
+        };
+    }
+    catch (error) {
+        const durationMs = Date.now() - startTime;
+        const err = error;
+        return {
+            source,
+            testId,
+            target,
+            passed: false,
+            errorCode: mapNodeErrorToConnectivityCode(err),
+            durationMs,
+            metadata: {
+                hostname,
+                port,
+                error: err.message,
+                nodeErrorCode: err.code,
+            },
+        };
+    }
+}
+function formatCertName(name) {
+    if (!name) {
+        return "";
+    }
+    const parts = [];
+    const fields = ["CN", "O", "OU", "L", "ST", "C"];
+    for (const field of fields) {
+        const value = name[field];
+        if (value) {
+            parts.push(`${field}=${value}`);
+        }
+    }
+    return parts.join(", ");
+}

package/src/connectivity/environment.d.ts

@@ -0,0 +1,6 @@
+import type { TestId, CheckType } from "./types.js";
+export declare function isBrowser(): boolean;
+export declare function isNode(): boolean;
+export declare function getCheckTypeForTestId(testId: TestId): CheckType;
+export declare function isCheckAvailable(checkType: CheckType): boolean;
+export declare function getUnavailabilityReason(checkType: CheckType): string;

package/src/connectivity/environment.js

@@ -0,0 +1,27 @@
+export function isBrowser() {
+    return (typeof window !== "undefined" && typeof window.document !== "undefined");
+}
+export function isNode() {
+    return (typeof process !== "undefined" &&
+        process.versions != null &&
+        process.versions.node != null);
+}
+export function getCheckTypeForTestId(testId) {
+    if (testId.startsWith("git-host:")) {
+        return testId.replace("git-host:", "");
+    }
+    return "http";
+}
+export function isCheckAvailable(checkType) {
+    if (checkType === "http") {
+        return true;
+    }
+    // DNS, TCP, TLS, and SSH checks require Node.js modules
+    return isNode();
+}
+export function getUnavailabilityReason(checkType) {
+    if (isBrowser()) {
+        return `${checkType.toUpperCase()} checks are not available in browser environments. Only HTTP checks can be performed from the browser.`;
+    }
+    return `${checkType.toUpperCase()} checks are not available in this environment.`;
+}

package/src/connectivity/error-codes.d.ts

@@ -0,0 +1,21 @@
+import type { ConnectivityErrorCode } from "./types.js";
+export declare const SELF_SIGNED_CERT_ERRORS: Set<string>;
+export declare const CERT_EXPIRED_ERRORS: Set<string>;
+export declare const CERT_NOT_YET_VALID_ERRORS: Set<string>;
+export declare const CERT_INVALID_ERRORS: Set<string>;
+export declare const CERT_HOSTNAME_MISMATCH_ERRORS: Set<string>;
+export declare const SSL_PROTOCOL_ERRORS: Set<string>;
+export declare const SSL_HANDSHAKE_ERRORS: Set<string>;
+export declare const NETWORK_UNREACHABLE_ERRORS: Set<string>;
+export declare const TIMEOUT_ERRORS: Set<string>;
+export declare const PROXY_ERRORS: Set<string>;
+export declare const DNS_ERRORS: Set<string>;
+export declare function mapNodeErrorToConnectivityCode(error: Error & {
+    code?: string;
+}): ConnectivityErrorCode;
+export declare function mapHttpStatusToErrorCode(status: number): ConnectivityErrorCode | undefined;
+export declare function mapFetchErrorToConnectivityCode(error: Error & {
+    cause?: Error & {
+        code?: string;
+    };
+}): ConnectivityErrorCode;

package/src/connectivity/error-codes.js

@@ -0,0 +1,167 @@
+export const SELF_SIGNED_CERT_ERRORS = new Set([
+    "DEPTH_ZERO_SELF_SIGNED_CERT",
+    "SELF_SIGNED_CERT_IN_CHAIN",
+]);
+export const CERT_EXPIRED_ERRORS = new Set([
+    "CERT_HAS_EXPIRED",
+    "ERROR_IN_CERT_NOT_AFTER_FIELD",
+]);
+// Most commonly caused by incorrect system clock settings
+export const CERT_NOT_YET_VALID_ERRORS = new Set([
+    "CERT_NOT_YET_VALID",
+    "ERROR_IN_CERT_NOT_BEFORE_FIELD",
+]);
+export const CERT_INVALID_ERRORS = new Set([
+    "UNABLE_TO_GET_ISSUER_CERT",
+    "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+    "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+    "INVALID_CA",
+    "CERT_SIGNATURE_FAILURE",
+    "CERT_REVOKED",
+    "CERT_REJECTED",
+    "CERT_UNTRUSTED",
+    "CERT_CHAIN_TOO_LONG",
+    "PATH_LENGTH_EXCEEDED",
+    "INVALID_PURPOSE",
+    "UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY",
+    "UNABLE_TO_DECRYPT_CERT_SIGNATURE",
+]);
+export const CERT_HOSTNAME_MISMATCH_ERRORS = new Set([
+    "HOSTNAME_MISMATCH",
+    "ERR_TLS_CERT_ALTNAME_INVALID",
+]);
+export const SSL_PROTOCOL_ERRORS = new Set([
+    "ERR_TLS_INVALID_PROTOCOL_VERSION",
+    "ERR_TLS_INVALID_PROTOCOL_METHOD",
+    "ERR_TLS_PROTOCOL_VERSION_CONFLICT",
+    "ERR_TLS_INVALID_STATE",
+    "ERR_TLS_INVALID_CONTEXT",
+    "ERR_TLS_RENEGOTIATION_DISABLED",
+    "ERR_TLS_REQUIRED_SERVER_NAME",
+    "ERR_TLS_SESSION_ATTACK",
+    "ERR_TLS_SNI_FROM_SERVER",
+    "ERR_TLS_DH_PARAM_SIZE",
+    "ERR_SSL_WRONG_VERSION_NUMBER",
+    "EPROTO",
+]);
+export const SSL_HANDSHAKE_ERRORS = new Set([
+    "ERR_TLS_HANDSHAKE_TIMEOUT",
+    "ERR_SSL_HANDSHAKE_FAILURE",
+]);
+export const NETWORK_UNREACHABLE_ERRORS = new Set([
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+    "ENETDOWN",
+    "ENONET",
+]);
+export const TIMEOUT_ERRORS = new Set([
+    "ETIMEDOUT",
+    "ESOCKETTIMEDOUT",
+    "ERR_SOCKET_CONNECTION_TIMEOUT",
+    "ERR_HTTP_REQUEST_TIMEOUT",
+]);
+export const PROXY_ERRORS = new Set([
+    "ERR_PROXY_INVALID_CONFIG",
+    "ERR_PROXY_TUNNEL",
+    "ERR_TUNNEL_CONNECTION_FAILED",
+]);
+export const DNS_ERRORS = new Set(["ENOTFOUND", "EAI_AGAIN", "ENODATA"]);
+export function mapNodeErrorToConnectivityCode(error) {
+    const errorCode = error.code;
+    if (!errorCode) {
+        return "unknown_error";
+    }
+    if (DNS_ERRORS.has(errorCode)) {
+        return "dns_resolution_failed";
+    }
+    if (errorCode === "ECONNREFUSED") {
+        return "tcp_connection_refused";
+    }
+    if (errorCode === "ECONNRESET" || errorCode === "EPIPE") {
+        return "tcp_connection_reset";
+    }
+    if (TIMEOUT_ERRORS.has(errorCode)) {
+        return "tcp_connection_timeout";
+    }
+    if (errorCode === "ENETUNREACH" || errorCode === "ENETDOWN") {
+        return "tcp_network_unreachable";
+    }
+    if (errorCode === "EHOSTUNREACH") {
+        return "tcp_host_unreachable";
+    }
+    if (SELF_SIGNED_CERT_ERRORS.has(errorCode)) {
+        return "tls_self_signed_cert";
+    }
+    if (CERT_EXPIRED_ERRORS.has(errorCode)) {
+        return "tls_cert_expired";
+    }
+    if (CERT_NOT_YET_VALID_ERRORS.has(errorCode)) {
+        return "tls_cert_not_yet_valid";
+    }
+    if (CERT_HOSTNAME_MISMATCH_ERRORS.has(errorCode)) {
+        return "tls_cert_hostname_mismatch";
+    }
+    if (CERT_INVALID_ERRORS.has(errorCode)) {
+        return "tls_cert_invalid";
+    }
+    if (SSL_HANDSHAKE_ERRORS.has(errorCode)) {
+        return "tls_handshake_failed";
+    }
+    if (SSL_PROTOCOL_ERRORS.has(errorCode)) {
+        return "tls_protocol_error";
+    }
+    if (PROXY_ERRORS.has(errorCode)) {
+        return "proxy_tunnel_failed";
+    }
+    return "unknown_error";
+}
+export function mapHttpStatusToErrorCode(status) {
+    if (status >= 200 && status < 400) {
+        return undefined;
+    }
+    if (status === 407) {
+        return "proxy_auth_required";
+    }
+    if (status === 401) {
+        return "http_unauthorized";
+    }
+    if (status === 403) {
+        return "http_forbidden";
+    }
+    if (status === 404) {
+        return "http_not_found";
+    }
+    if (status === 503) {
+        return "http_service_unavailable";
+    }
+    if (status >= 500) {
+        return "http_server_error";
+    }
+    return "unknown_error";
+}
+// Fetch errors don't have Node.js-style error codes, so we inspect the message
+export function mapFetchErrorToConnectivityCode(error) {
+    if (error.cause && "code" in error.cause) {
+        return mapNodeErrorToConnectivityCode(error.cause);
+    }
+    const message = error.message.toLowerCase();
+    if (message.includes("failed to fetch") || message.includes("network")) {
+        return "tcp_connection_refused";
+    }
+    if (message.includes("timeout") || message.includes("timed out")) {
+        return "tcp_connection_timeout";
+    }
+    if (message.includes("dns") || message.includes("not found")) {
+        return "dns_resolution_failed";
+    }
+    if (message.includes("certificate") || message.includes("ssl")) {
+        if (message.includes("expired")) {
+            return "tls_cert_expired";
+        }
+        if (message.includes("self-signed") || message.includes("self signed")) {
+            return "tls_self_signed_cert";
+        }
+        return "tls_cert_invalid";
+    }
+    return "unknown_error";
+}

package/src/connectivity/node.d.ts

@@ -0,0 +1,15 @@
+export type { Source, TestId, Test, RunChecksInput, ProgressEvent, CheckResult, CheckReport, ConnectivityErrorCode, CheckType, Recommendation, LikelyCause, ConnectivityStatus, AnalysisResult, AnalyzeConnectivityInput, } from "./types.js";
+export { runChecks } from "./run-checks.js";
+export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, SELF_SIGNED_CERT_ERRORS, CERT_EXPIRED_ERRORS, CERT_NOT_YET_VALID_ERRORS, CERT_INVALID_ERRORS, CERT_HOSTNAME_MISMATCH_ERRORS, SSL_PROTOCOL_ERRORS, SSL_HANDSHAKE_ERRORS, NETWORK_UNREACHABLE_ERRORS, TIMEOUT_ERRORS, PROXY_ERRORS, DNS_ERRORS, } from "./error-codes.js";
+export { BUILDER_TARGETS, DEFAULT_PORTS, resolveTarget, extractHostname, extractPort, } from "./targets.js";
+export { isBrowser, isNode, getCheckTypeForTestId, isCheckAvailable, getUnavailabilityReason, } from "./environment.js";
+export { httpCheck } from "./checks/http-check.js";
+export type { HttpCheckOptions } from "./checks/http-check.js";
+export { dnsCheck } from "./checks/dns-check.js";
+export type { DnsCheckOptions } from "./checks/dns-check.js";
+export { tcpCheck } from "./checks/tcp-check.js";
+export type { TcpCheckOptions } from "./checks/tcp-check.js";
+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";

package/src/connectivity/node.js

@@ -0,0 +1,9 @@
+export { runChecks } from "./run-checks.js";
+export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, SELF_SIGNED_CERT_ERRORS, CERT_EXPIRED_ERRORS, CERT_NOT_YET_VALID_ERRORS, CERT_INVALID_ERRORS, CERT_HOSTNAME_MISMATCH_ERRORS, SSL_PROTOCOL_ERRORS, SSL_HANDSHAKE_ERRORS, NETWORK_UNREACHABLE_ERRORS, TIMEOUT_ERRORS, PROXY_ERRORS, DNS_ERRORS, } from "./error-codes.js";
+export { BUILDER_TARGETS, DEFAULT_PORTS, resolveTarget, extractHostname, extractPort, } from "./targets.js";
+export { isBrowser, isNode, getCheckTypeForTestId, isCheckAvailable, getUnavailabilityReason, } from "./environment.js";
+export { httpCheck } from "./checks/http-check.js";
+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";

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

@@ -0,0 +1,2 @@
+import type { RunChecksInput, CheckReport } from "./types.js";
+export declare function runChecks(input: RunChecksInput): Promise<CheckReport>;

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

@@ -0,0 +1,103 @@
+import { resolveTarget } from "./targets.js";
+import { getCheckTypeForTestId, isCheckAvailable, getUnavailabilityReason, } from "./environment.js";
+import { httpCheck } from "./checks/http-check.js";
+export async function runChecks(input) {
+    const { tests, gitHost, onProgress } = input;
+    const results = [];
+    const total = tests.length;
+    for (let index = 0; index < tests.length; index++) {
+        const test = tests[index];
+        emitProgress(onProgress, {
+            type: "test:start",
+            test,
+            index,
+            total,
+        });
+        const result = await runSingleCheck(test, gitHost);
+        results.push(result);
+        emitProgress(onProgress, {
+            type: "test:complete",
+            result,
+            index,
+            total,
+        });
+    }
+    emitProgress(onProgress, {
+        type: "batch:complete",
+        results,
+    });
+    return {
+        timestamp: new Date().toISOString(),
+        gitHost,
+        results,
+    };
+}
+async function runSingleCheck(test, gitHost) {
+    const { source, testId } = test;
+    const checkType = getCheckTypeForTestId(testId);
+    if (!isCheckAvailable(checkType)) {
+        const startTime = Date.now();
+        let target;
+        try {
+            target = resolveTarget(testId, gitHost);
+        }
+        catch (_a) {
+            target = gitHost || testId;
+        }
+        return {
+            source,
+            testId,
+            target,
+            passed: false,
+            errorCode: "check_unavailable",
+            durationMs: Date.now() - startTime,
+            metadata: {
+                reason: getUnavailabilityReason(checkType),
+                checkType,
+            },
+        };
+    }
+    let target;
+    try {
+        target = resolveTarget(testId, gitHost);
+    }
+    catch (error) {
+        return {
+            source,
+            testId,
+            target: gitHost || testId,
+            passed: false,
+            errorCode: "unknown_error",
+            durationMs: 0,
+            metadata: {
+                error: error.message,
+            },
+        };
+    }
+    switch (checkType) {
+        case "http":
+            return httpCheck({ target, source, testId });
+        default:
+            return {
+                source,
+                testId,
+                target,
+                passed: false,
+                errorCode: "check_unavailable",
+                durationMs: 0,
+                metadata: {
+                    reason: `Check type "${checkType}" is not available in browser environments`,
+                },
+            };
+    }
+}
+function emitProgress(onProgress, event) {
+    if (onProgress) {
+        try {
+            onProgress(event);
+        }
+        catch (_a) {
+            // Ignore errors in progress callback to prevent breaking the check flow
+        }
+    }
+}

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

@@ -0,0 +1,2 @@
+import type { RunChecksInput, CheckReport } from "./types.js";
+export declare function runChecks(input: RunChecksInput): Promise<CheckReport>;

package/src/connectivity/run-checks.js

@@ -0,0 +1,134 @@
+import { resolveTarget, extractHostname, extractPort } from "./targets.js";
+import { getCheckTypeForTestId, isCheckAvailable, getUnavailabilityReason, } from "./environment.js";
+import { httpCheck } from "./checks/http-check.js";
+import { dnsCheck } from "./checks/dns-check.js";
+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 } = input;
+    const results = [];
+    const total = tests.length;
+    for (let index = 0; index < tests.length; index++) {
+        const test = tests[index];
+        emitProgress(onProgress, {
+            type: "test:start",
+            test,
+            index,
+            total,
+        });
+        const result = await runSingleCheck(test, gitHost);
+        results.push(result);
+        emitProgress(onProgress, {
+            type: "test:complete",
+            result,
+            index,
+            total,
+        });
+    }
+    emitProgress(onProgress, {
+        type: "batch:complete",
+        results,
+    });
+    return {
+        timestamp: new Date().toISOString(),
+        gitHost,
+        results,
+    };
+}
+async function runSingleCheck(test, gitHost) {
+    const { source, testId } = test;
+    const checkType = getCheckTypeForTestId(testId);
+    if (!isCheckAvailable(checkType)) {
+        const startTime = Date.now();
+        let target;
+        try {
+            target = resolveTarget(testId, gitHost);
+        }
+        catch (_a) {
+            target = gitHost || testId;
+        }
+        return {
+            source,
+            testId,
+            target,
+            passed: false,
+            errorCode: "check_unavailable",
+            durationMs: Date.now() - startTime,
+            metadata: {
+                reason: getUnavailabilityReason(checkType),
+                checkType,
+            },
+        };
+    }
+    let target;
+    try {
+        target = resolveTarget(testId, gitHost);
+    }
+    catch (error) {
+        return {
+            source,
+            testId,
+            target: gitHost || testId,
+            passed: false,
+            errorCode: "unknown_error",
+            durationMs: 0,
+            metadata: {
+                error: error.message,
+            },
+        };
+    }
+    switch (checkType) {
+        case "http":
+            return httpCheck({ target, source, testId });
+        case "dns":
+            return dnsCheck({
+                hostname: extractHostname(target),
+                source,
+                testId,
+            });
+        case "tcp":
+            return tcpCheck({
+                hostname: extractHostname(target),
+                port: extractPort(target, 443),
+                source,
+                testId,
+            });
+        case "tls":
+            return tlsCheck({
+                hostname: extractHostname(target),
+                port: extractPort(target, 443),
+                source,
+                testId,
+            });
+        case "ssh":
+            return sshCheck({
+                hostname: extractHostname(target),
+                port: 22,
+                source,
+                testId,
+            });
+        default:
+            return {
+                source,
+                testId,
+                target,
+                passed: false,
+                errorCode: "unknown_error",
+                durationMs: 0,
+                metadata: {
+                    error: `Unknown check type: ${checkType}`,
+                },
+            };
+    }
+}
+function emitProgress(onProgress, event) {
+    if (onProgress) {
+        try {
+            onProgress(event);
+        }
+        catch (_a) {
+            // Ignore errors in progress callback to prevent breaking the check flow
+        }
+    }
+}

package/src/connectivity/targets.d.ts

@@ -0,0 +1,6 @@
+import type { TestId } from "./types.js";
+export declare const BUILDER_TARGETS: Record<string, string>;
+export declare const DEFAULT_PORTS: Record<string, number>;
+export declare function resolveTarget(testId: TestId, gitHost?: string): string;
+export declare function extractHostname(target: string): string;
+export declare function extractPort(target: string, defaultPort?: number): number;

package/src/connectivity/targets.js

@@ -0,0 +1,52 @@
+export const BUILDER_TARGETS = {
+    "builder.io": "https://www.builder.io",
+    "builder.codes": "https://test.projects.builder.codes/proxy-health",
+    "api.builder.io": "https://api.builder.io/codegen/health",
+    "cdn.builder.io": "https://cdn.builder.io/api/v1/image/assets/TEMP/75a212ab82b6175c9862b125e0e23db8d369a58a?width=100",
+    "builderio.xyz": "https://builderio.xyz/health",
+    "fly.dev": "https://fly.dev",
+};
+export const DEFAULT_PORTS = {
+    http: 443,
+    https: 443,
+    ssh: 22,
+    tcp: 443,
+    tls: 443,
+};
+export function resolveTarget(testId, gitHost) {
+    if (testId.startsWith("git-host:")) {
+        if (!gitHost) {
+            throw new Error(`gitHost parameter is required for test "${testId}"`);
+        }
+        return gitHost;
+    }
+    const target = BUILDER_TARGETS[testId];
+    if (!target) {
+        throw new Error(`Unknown testId: ${testId}`);
+    }
+    return target;
+}
+export function extractHostname(target) {
+    try {
+        const url = new URL(target);
+        return url.hostname;
+    }
+    catch (_a) {
+        return target;
+    }
+}
+export function extractPort(target, defaultPort = 443) {
+    try {
+        const url = new URL(target);
+        if (url.port) {
+            return parseInt(url.port, 10);
+        }
+        if (url.protocol === "http:") {
+            return 80;
+        }
+        return defaultPort;
+    }
+    catch (_a) {
+        return defaultPort;
+    }
+}

package/src/connectivity/types.d.ts

@@ -0,0 +1,66 @@
+export type Source = "local" | "cloud" | "static-ip";
+export type TestId = "builder.io" | "builder.codes" | "api.builder.io" | "cdn.builder.io" | "builderio.xyz" | "fly.dev" | "git-host:http" | "git-host:dns" | "git-host:tcp" | "git-host:tls" | "git-host:ssh";
+export interface Test {
+    source: Source;
+    testId: TestId;
+}
+export interface RunChecksInput {
+    tests: Test[];
+    gitHost?: string;
+    onProgress?: (event: ProgressEvent) => void;
+}
+export type ProgressEvent = {
+    type: "test:start";
+    test: Test;
+    index: number;
+    total: number;
+} | {
+    type: "test:complete";
+    result: CheckResult;
+    index: number;
+    total: number;
+} | {
+    type: "batch:complete";
+    results: CheckResult[];
+};
+export interface CheckResult {
+    source: Source;
+    testId: TestId;
+    target: string;
+    passed: boolean;
+    errorCode?: ConnectivityErrorCode;
+    durationMs: number;
+    metadata?: Record<string, unknown>;
+}
+export interface CheckReport {
+    timestamp: string;
+    gitHost?: string;
+    results: CheckResult[];
+}
+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" | "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 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 {
+    recommendation: Recommendation;
+    reason: string;
+    steps: string[];
+    fallback?: Recommendation;
+    likelyCause?: LikelyCause;
+    summary: {
+        localToBuilder: ConnectivityStatus;
+        localToGitHost: ConnectivityStatus;
+        cloudToGitHost: ConnectivityStatus;
+        staticIpToGitHost: ConnectivityStatus;
+    };
+    allResults: CheckResult[];
+}
+export interface AnalyzeConnectivityInput {
+    localResults: CheckResult[];
+    serverResults: CheckResult[];
+    spaceSettings: {
+        staticProxyEnabled: boolean;
+    };
+    gitHost: string;
+}

package/src/connectivity/types.js

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

package/src/index.d.ts

@@ -9,3 +9,4 @@ export * from "./repo-indexing.js";
 export * from "./organization.js";
 export * from "./features.js";
 export * from "./vscode-tunnel.js";
+export * from "./connectivity/types.js";

package/src/index.js

@@ -9,3 +9,4 @@ export * from "./repo-indexing.js";
 export * from "./organization.js";
 export * from "./features.js";
 export * from "./vscode-tunnel.js";
+export * from "./connectivity/types.js";