@builder.io/ai-utils 0.81.3 → 0.83.0-dev.202607211718.99c5f9cf8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.81.3",
+  "version": "0.83.0-dev.202607211718.99c5f9cf8",
   "description": "Builder.io AI utils",
   "files": [
     "src"

package/src/acl-schema.d.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+export declare const PermissionSchema: z.ZodEnum<{
+    list: "list";
+    read: "read";
+    write: "write";
+}>;
+export type Permission = z.infer<typeof PermissionSchema>;
+export declare const AclEntrySchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        allow: "allow";
+        deny: "deny";
+    }>;
+    resource: z.ZodString;
+    permissions: z.ZodArray<z.ZodEnum<{
+        list: "list";
+        read: "read";
+        write: "write";
+    }>>;
+    description: z.ZodOptional<z.ZodString>;
+    principals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type AclEntry = z.infer<typeof AclEntrySchema>;
+export declare const AclPolicySchema: z.ZodObject<{
+    secrets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    entries: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        action: z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+        }>;
+        resource: z.ZodString;
+        permissions: z.ZodArray<z.ZodEnum<{
+            list: "list";
+            read: "read";
+            write: "write";
+        }>>;
+        description: z.ZodOptional<z.ZodString>;
+        principals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    denyDescription: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AclPolicy = z.infer<typeof AclPolicySchema>;
+export declare const AclDenialSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "command-allowlist": "command-allowlist";
+        "command-security": "command-security";
+        "file-access": "file-access";
+    }>;
+    reason: z.ZodEnum<{
+        "deny-pattern-matched": "deny-pattern-matched";
+        "no-allow-match": "no-allow-match";
+        "security-policy": "security-policy";
+        "shell-metacharacter": "shell-metacharacter";
+    }>;
+    resource: z.ZodString;
+    command: z.ZodOptional<z.ZodString>;
+    permission: z.ZodOptional<z.ZodEnum<{
+        list: "list";
+        read: "read";
+        write: "write";
+    }>>;
+    policy: z.ZodOptional<z.ZodString>;
+    matchedPattern: z.ZodOptional<z.ZodString>;
+    matchedEntry: z.ZodOptional<z.ZodObject<{
+        action: z.ZodEnum<{
+            allow: "allow";
+            deny: "deny";
+        }>;
+        resource: z.ZodString;
+        permissions: z.ZodArray<z.ZodEnum<{
+            list: "list";
+            read: "read";
+            write: "write";
+        }>>;
+        description: z.ZodOptional<z.ZodString>;
+        principals: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type AclDenial = z.infer<typeof AclDenialSchema>;
+export interface AccessResult {
+    allowed: boolean;
+    message: string;
+    matchedEntry?: AclEntry;
+    matchedPattern?: string;
+    reason?: "deny-pattern-matched" | "no-allow-match";
+    requestedResource?: string;
+    requestedPermission?: Permission;
+}

package/src/acl-schema.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+export const PermissionSchema = z
+    .enum(["read", "write", "list"])
+    .meta({ title: "Permission" });
+// One ACL rule
+export const AclEntrySchema = z
+    .object({
+    action: z
+        .enum(["allow", "deny"])
+        .meta({ description: "whether this rule allows or denies access" }),
+    resource: z
+        .string()
+        .meta({ description: "what — supports glob patterns like /files/*.txt" }),
+    permissions: z
+        .array(PermissionSchema)
+        .meta({ description: "actions this rule applies to" }),
+    description: z.string().optional().meta({
+        description: "custom message, in deny case, this is the error message. This will override denyDescription on AclPolicy if defined.",
+    }),
+    principals: z.array(z.string()).optional().meta({
+        description: "array of teams/roles this rule applies to (e.g., ['developer', 'admin'])",
+    }),
+})
+    .meta({ title: "AclEntry" });
+// A full ACL policy is just a list of rules
+export const AclPolicySchema = z
+    .object({
+    secrets: z.array(z.string()).optional(),
+    entries: z.array(AclEntrySchema).optional(),
+    denyDescription: z.string().optional().meta({
+        description: "Default message to use when a resource is denied access",
+    }),
+})
+    .meta({ title: "AclPolicy" });
+// Structured description of an ACL/policy denial. Travels with the tool result
+// so internal tools can show admins exactly which rule blocked a command/file,
+// and both UIs can render a distinct "blocked, did not run" treatment.
+export const AclDenialSchema = z
+    .object({
+    kind: z
+        .enum(["command-security", "command-allowlist", "file-access"])
+        .meta({ description: "which gate produced the denial" }),
+    reason: z
+        .enum([
+        "security-policy",
+        "deny-pattern-matched",
+        "no-allow-match",
+        "shell-metacharacter",
+    ])
+        .meta({ description: "why the denial happened" }),
+    resource: z.string().meta({
+        description: "the file path or command that was blocked",
+    }),
+    command: z.string().optional().meta({
+        description: "the full command, when the denial is command-related",
+    }),
+    permission: PermissionSchema.optional().meta({
+        description: "the requested permission, for file-access denials",
+    }),
+    policy: z.string().optional().meta({
+        description: "named security policy that matched, when applicable",
+    }),
+    matchedPattern: z.string().optional().meta({
+        description: "the glob/pattern that matched the resource or command",
+    }),
+    matchedEntry: AclEntrySchema.optional().meta({
+        description: "the full ACL entry that matched, for file-access denials",
+    }),
+    message: z.string().meta({ description: "human-readable explanation" }),
+})
+    .meta({ title: "AclDenial" });

package/src/claw.d.ts

@@ -101,6 +101,7 @@ export type ChannelType<P extends KnownPlatform> = (typeof CHANNEL_TYPES)[P][num
 /** Union of every channel sub-type across all platforms. */
 export type AnyChannelType = ChannelType<KnownPlatform>;
 export declare function isChannelType<P extends KnownPlatform>(platform: P, type: string): type is ChannelType<P>;
+export declare function isBuilderBranchChannelId(channelId: string): boolean;
 /** Platform recorded on a logged message; "unknown" when the channelId fails to parse. */
 export type ChannelSource = KnownPlatform | "unknown";
 /** Channel sub-type recorded on a logged message; "unknown" when parsing fails. */

package/src/claw.js

@@ -81,6 +81,15 @@ export const CHANNEL_TYPES = {
 export function isChannelType(platform, type) {
     return CHANNEL_TYPES[platform].includes(type);
 }
+export function isBuilderBranchChannelId(channelId) {
+    try {
+        const channel = parseChannelId(channelId);
+        return channel.platform === "builder" && channel.type === "branch";
+    }
+    catch (_a) {
+        return false;
+    }
+}
 /**
  * Converts a Builder channel_id URI to a clickable URL for the
  * corresponding platform (Slack, Jira, etc.).

package/src/claw.spec.js

@@ -1,5 +1,15 @@
 import { describe, it, expect } from "vitest";
-import { convertChannelIdToUrl, formatIncomingMessage, formatWorkerMessage, formatWorkerReport, } from "./claw";
+import { convertChannelIdToUrl, formatIncomingMessage, formatWorkerMessage, formatWorkerReport, isBuilderBranchChannelId, } from "./claw";
+describe("isBuilderBranchChannelId", () => {
+    it("recognizes Builder branch channel IDs", () => {
+        expect(isBuilderBranchChannelId("builder/branch/proj-id/my-branch")).toBe(true);
+    });
+    it("rejects other and invalid channel IDs", () => {
+        expect(isBuilderBranchChannelId("slack/channel/team/channel")).toBe(false);
+        expect(isBuilderBranchChannelId("builder/project/proj-id")).toBe(false);
+        expect(isBuilderBranchChannelId("invalid")).toBe(false);
+    });
+});
 describe("convertChannelIdToUrl", () => {
     describe("slack/thread format", () => {
         it("converts a thread channel ID to a Slack app_redirect URL", () => {

package/src/codegen/investigation-context.d.ts

@@ -18,5 +18,5 @@ export interface BuildInvestigationSystemPromptInput {
     event: InvestigationEvent;
     completionJson: InvestigationCompletionJSON | undefined;
 }
-export declare function buildInvestigationSystemPrompt({ event, completionJson }: BuildInvestigationSystemPromptInput): string;
+export declare function buildInvestigationSystemPrompt({ event, completionJson, }: BuildInvestigationSystemPromptInput): string;
 export declare const SUGGESTED_QUESTIONS: readonly string[];

package/src/codegen.d.ts

@@ -2890,6 +2890,8 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
     systemReminderPrompt: z.ZodOptional<z.ZodString>;
 }, z.core.$loose>;
 export type CodeGenInputOptions = z.infer<typeof CodeGenInputOptionsSchema> & {
+    /** @internal Derived from BuilderEditorState.components for editor AI. */
+    _allowedComponentNames?: string[];
     /**
      * Optional factory function to wrap the MCP client with custom behavior
      * Used by Editor AI to add permission checks for model operations
@@ -3295,6 +3297,7 @@ export interface GenerateCompletionStepGit {
      */
     diagnostics?: GitStatusDiagnostics;
 }
+export declare const FUSION_GENERATION_APP_PLACEHOLDER_COMMENT = "{/* TODO: FUSION_GENERATION_APP_PLACEHOLDER replace everything here with the actual app! */}";
 /**
  * A typed comment added to the session via the generic `AddComment` tool. The
  * `commentType` mirrors the tool's `type` field (e.g. `"code-review"`) and
@@ -3950,6 +3953,13 @@ export interface MCPAuthRequiredServer {
     authorizationUrl: string;
     scopes: string[];
     isReauth: boolean;
+    /**
+     * Server opted in to the LLM-driven `__authenticate` flow via its Firestore
+     * `useAuthenticateTool` field. Servers opted in this way (or, org-wide, via
+     * the `codegen-tool-mcp-authenticate` LD flag) get a synthetic auth tool
+     * instead of a blocking `mcp-auth-required` event.
+     */
+    useAuthenticateTool?: boolean;
 }
 export interface GenerateCodeEventMCPAuthRequired {
     type: "mcp-auth-required";

package/src/codegen.js

@@ -1229,7 +1229,7 @@ export const SendMessageToolInputSchema = z
         description: "When true, send the response as a voice message using text-to-speech. Only supported for Telegram channels. Only set to true when the user's original message was a voice/audio message (look for '[Voice message transcription]' or '[Audio' markers), the channel is Telegram, and the response is short and conversational with no URLs, code, lists, or other content that doesn't translate to audio. Default to false (text) for all text-originated messages.",
     }),
     from_user_id: z.string().optional().meta({
-        description: "Builder.io user ID this message is from / should be attributed to. Only allowed when channel_id is 'builder/branch/{project_id}/{branch_name}'. When set, the message is delivered to the target branch as coming from this user (role 'user') instead of from the agent. Use whenever the message represents user feedback/intent that should be assigned to someone — even if it was composed, summarized, or merged from multiple people.",
+        description: "Builder.io user ID this message is from / should be attributed to. Only allowed when channel_id is 'builder/branch/{project_id}/{branch_name}'. When set, the message is delivered to the target branch as coming from this user (role 'user') instead of from the agent. Defaults to the current requester when omitted. Set this explicitly when relaying a message on behalf of someone other than the person who sent the current message — even if it was composed, summarized, or merged from multiple people.",
     }),
 })
     .meta({ title: "SendMessageToolInput" });
@@ -1918,6 +1918,7 @@ export const CodeGenInputOptionsSchema = z
     systemReminderPrompt: z.string().optional(),
 })
     .meta({ title: "CodeGenInputOptions" });
+export const FUSION_GENERATION_APP_PLACEHOLDER_COMMENT = "{/* TODO: FUSION_GENERATION_APP_PLACEHOLDER replace everything here with the actual app! */}";
 export const AutoPushModeSchema = z
     .enum(["force-push", "merge-push", "ff-push", "safe-push", "none"])
     .meta({ title: "AutoPushMode" });

package/src/completion.d.ts

@@ -99,7 +99,8 @@ export interface BuilderEditorState {
      */
     content?: BuilderContent;
     /**
-     * Builder custom components.
+     * Components available in the Builder editor, including built-ins.
+     * When present, editor AI restricts generated content to this list.
      */
     components?: Component[];
     /**

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

@@ -7,5 +7,12 @@ export interface HttpCheckOptions {
     fetchFn?: ConnectivityFetchFn;
     /** Fetch dispatcher for proxy routing (e.g. undici ProxyAgent). */
     dispatcher?: object;
+    /**
+     * Treat any 4xx as a failure (not just 5xx). Used by `doctor --browser`: a
+     * TLS-inspecting proxy (Zscaler) that blocks browser-shaped traffic typically
+     * answers with a 403/407/451 block page, which a plain reachability check
+     * would otherwise count as a pass.
+     */
+    strictHttpStatus?: boolean;
 }
 export declare function httpCheck(options: HttpCheckOptions): Promise<CheckResult>;

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

@@ -1,9 +1,10 @@
-import { mapFetchErrorToConnectivityCode } from "../error-codes.js";
+import { mapFetchErrorToConnectivityCode, mapHttpStatusToErrorCode, } from "../error-codes.js";
 import { isBrowser } from "../environment.js";
 const DEFAULT_TIMEOUT_MS = 30000;
 const LATENCY_THRESHOLD_MS = 5000;
 export async function httpCheck(options) {
-    const { target, source, testId, timeout = DEFAULT_TIMEOUT_MS, fetchFn = fetch, dispatcher, } = options;
+    var _a;
+    const { target, source, testId, timeout = DEFAULT_TIMEOUT_MS, fetchFn = fetch, dispatcher, strictHttpStatus = false, } = options;
     const startTime = Date.now();
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
@@ -46,14 +47,21 @@ export async function httpCheck(options) {
         clearTimeout(timeoutId);
         const durationMs = Date.now() - startTime;
         const hasHighLatency = durationMs > LATENCY_THRESHOLD_MS;
-        const isServerError = response.status >= 500;
-        if (isServerError) {
+        // Standard mode only fails on 5xx (server reachable is what matters).
+        // Browser (strict) mode also fails on 4xx to surface proxy block pages.
+        const isFailingStatus = strictHttpStatus
+            ? response.status >= 400
+            : response.status >= 500;
+        if (isFailingStatus) {
             return {
                 source,
                 testId,
                 target,
                 passed: false,
-                errorCode: "http_server_error",
+                // Canonical status->code mapping: 401/403/404/407/503/5xx get specific
+                // codes; other 4xx (400/405/429/...) map to "unknown_error" instead of
+                // being mislabeled as a specific auth failure.
+                errorCode: (_a = mapHttpStatusToErrorCode(response.status)) !== null && _a !== void 0 ? _a : "unknown_error",
                 durationMs,
                 metadata: {
                     statusCode: response.status,

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

@@ -24,3 +24,61 @@ describe("httpCheck", () => {
         expect(result.metadata).toMatchObject({ reachabilityOnly: true });
     });
 });
+describe("httpCheck strictHttpStatus", () => {
+    const target = "https://api.builder.io/codegen/health";
+    it("treats 403 as a pass by default (server reachable)", async () => {
+        const fetchFn = vi
+            .fn()
+            .mockResolvedValue({ ok: false, status: 403, statusText: "Forbidden" });
+        const result = await httpCheck({
+            target,
+            source: "local",
+            testId: "api.builder.io",
+            fetchFn,
+        });
+        expect(result.passed).toBe(true);
+        expect(result.metadata).toMatchObject({ statusCode: 403 });
+    });
+    it("treats 403 as a failure in strict mode (proxy block page)", async () => {
+        const fetchFn = vi
+            .fn()
+            .mockResolvedValue({ ok: false, status: 403, statusText: "Forbidden" });
+        const result = await httpCheck({
+            target,
+            source: "local",
+            testId: "api.builder.io",
+            fetchFn,
+            strictHttpStatus: true,
+        });
+        expect(result.passed).toBe(false);
+        expect(result.errorCode).toBe("http_forbidden");
+        expect(result.metadata).toMatchObject({ statusCode: 403 });
+    });
+    it("maps an unhandled 4xx (429) to unknown_error, not http_forbidden", async () => {
+        const fetchFn = vi
+            .fn()
+            .mockResolvedValue({ ok: false, status: 429, statusText: "Too Many" });
+        const result = await httpCheck({
+            target,
+            source: "local",
+            testId: "api.builder.io",
+            fetchFn,
+            strictHttpStatus: true,
+        });
+        expect(result.passed).toBe(false);
+        expect(result.errorCode).toBe("unknown_error");
+    });
+    it("still passes on 200 in strict mode", async () => {
+        const fetchFn = vi
+            .fn()
+            .mockResolvedValue({ ok: true, status: 200, statusText: "OK" });
+        const result = await httpCheck({
+            target,
+            source: "local",
+            testId: "api.builder.io",
+            fetchFn,
+            strictHttpStatus: true,
+        });
+        expect(result.passed).toBe(true);
+    });
+});

package/src/connectivity/environment.js

@@ -13,6 +13,12 @@ export function getCheckTypeForTestId(testId) {
     if (testId.startsWith("git-host:")) {
         return testId.replace("git-host:", "");
     }
+    if (testId.startsWith("project-health:")) {
+        return testId.replace("project-health:", "");
+    }
+    if (testId.startsWith("project:")) {
+        return testId.replace("project:", "");
+    }
     return "http";
 }
 export function isCheckAvailable(checkType) {

package/src/connectivity/node.d.ts

@@ -1,7 +1,7 @@
 export type { Source, TestId, Test, RunChecksInput, ProgressEvent, CheckResult, CheckReport, ConnectivityErrorCode, CheckType, Recommendation, LikelyCause, ConnectivityStatus, AnalysisResult, AnalyzeConnectivityInput, ConnectivityFetchFn, } from "./types.js";
 export { runChecks } from "./run-checks.js";
 export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, 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, DEFAULT_LOCAL_BUILDER_TESTS, BUILDER_TEST_DISPLAY_NAMES, resolveTarget, extractHostname, extractPort, } from "./targets.js";
+export { BUILDER_TARGETS, DEFAULT_PORTS, DEFAULT_LOCAL_BUILDER_TESTS, BUILDER_TEST_DISPLAY_NAMES, resolveTarget, getProjectHealthUrl, 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/node.js

@@ -1,6 +1,6 @@
 export { runChecks } from "./run-checks.js";
 export { mapNodeErrorToConnectivityCode, mapHttpStatusToErrorCode, mapFetchErrorToConnectivityCode, connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, 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, DEFAULT_LOCAL_BUILDER_TESTS, BUILDER_TEST_DISPLAY_NAMES, resolveTarget, extractHostname, extractPort, } from "./targets.js";
+export { BUILDER_TARGETS, DEFAULT_PORTS, DEFAULT_LOCAL_BUILDER_TESTS, BUILDER_TEST_DISPLAY_NAMES, resolveTarget, getProjectHealthUrl, 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";

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, sshConnectFn, dnsResolver, } = input;
+    const { tests, gitHost, onProgress, fetchFn, dispatcher, connectFn, sshConnectFn, dnsResolver, projectUrl, projectHealthUrl, strictHttpStatus, } = 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, sshConnectFn, dnsResolver);
+        const result = await runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn, sshConnectFn, dnsResolver, { projectUrl, projectHealthUrl, strictHttpStatus });
         results.push(result);
         emitProgress(onProgress, {
             type: "test:complete",
@@ -37,14 +37,14 @@ export async function runChecks(input) {
         results,
     };
 }
-async function runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn, sshConnectFn, dnsResolver) {
+async function runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn, sshConnectFn, dnsResolver, extras) {
     const { source, testId } = test;
     const checkType = getCheckTypeForTestId(testId);
     if (!isCheckAvailable(checkType)) {
         const startTime = Date.now();
         let target;
         try {
-            target = resolveTarget(testId, gitHost);
+            target = resolveTarget(testId, gitHost, extras);
         }
         catch (_a) {
             target = gitHost || testId;
@@ -64,7 +64,7 @@ async function runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn, ssh
     }
     let target;
     try {
-        target = resolveTarget(testId, gitHost);
+        target = resolveTarget(testId, gitHost, extras);
     }
     catch (error) {
         return {
@@ -81,7 +81,14 @@ async function runSingleCheck(test, gitHost, fetchFn, dispatcher, connectFn, ssh
     }
     switch (checkType) {
         case "http":
-            return httpCheck({ target, source, testId, fetchFn, dispatcher });
+            return httpCheck({
+                target,
+                source,
+                testId,
+                fetchFn,
+                dispatcher,
+                strictHttpStatus: extras === null || extras === void 0 ? void 0 : extras.strictHttpStatus,
+            });
         case "websocket":
             return websocketCheck({ target, source, testId });
         case "dns":

package/src/connectivity/targets.d.ts

@@ -12,8 +12,18 @@ export declare const DEFAULT_LOCAL_BUILDER_TESTS: Test[];
  * UI surfaces to show friendly labels instead of raw testId strings.
  */
 export declare const BUILDER_TEST_DISPLAY_NAMES: Partial<Record<TestId, string>>;
+/**
+ * Given a full project URL (e.g. https://<id>-<branch>.builderio.dev/... ), return
+ * the matching health.builderio.* URL the project is routed through, or null when
+ * the host is not a known Builder kube domain.
+ */
+export declare function getProjectHealthUrl(projectUrl: string): string | null;
 export declare const DEFAULT_PORTS: Record<string, number>;
-export declare function resolveTarget(testId: TestId, gitHost?: string): string;
+export interface ResolveTargetExtras {
+    projectUrl?: string;
+    projectHealthUrl?: string;
+}
+export declare function resolveTarget(testId: TestId, gitHost?: string, extras?: ResolveTargetExtras): string;
 export declare function extractHostname(target: string): string;
 /**
  * Extract only an explicitly specified port from a URL, ignoring protocol-specific defaults.

package/src/connectivity/targets.js

@@ -37,7 +37,28 @@ export const BUILDER_TEST_DISPLAY_NAMES = {
     "builderio.xyz:ws": "*.builderio.xyz (WebSocket)",
     "builderio.dev": "*.builderio.dev",
     "builderio.dev:ws": "*.builderio.dev (WebSocket)",
+    "project:dns": "Project URL (DNS)",
+    "project:tcp": "Project URL (TCP)",
+    "project:tls": "Project URL (TLS)",
+    "project:http": "Project URL (HTTP)",
+    "project-health:dns": "Health domain (DNS)",
+    "project-health:tcp": "Health domain (TCP)",
+    "project-health:tls": "Health domain (TLS)",
+    "project-health:http": "Health domain (HTTP)",
 };
+/**
+ * Given a full project URL (e.g. https://<id>-<branch>.builderio.dev/... ), return
+ * the matching health.builderio.* URL the project is routed through, or null when
+ * the host is not a known Builder kube domain.
+ */
+export function getProjectHealthUrl(projectUrl) {
+    const host = extractHostname(projectUrl);
+    if (host.endsWith("builderio.xyz"))
+        return BUILDER_TARGETS["builderio.xyz"];
+    if (host.endsWith("builderio.dev"))
+        return BUILDER_TARGETS["builderio.dev"];
+    return null;
+}
 export const DEFAULT_PORTS = {
     http: 443,
     https: 443,
@@ -45,13 +66,25 @@ export const DEFAULT_PORTS = {
     tcp: 443,
     tls: 443,
 };
-export function resolveTarget(testId, gitHost) {
+export function resolveTarget(testId, gitHost, extras) {
     if (testId.startsWith("git-host:")) {
         if (!gitHost) {
             throw new Error(`gitHost parameter is required for test "${testId}"`);
         }
         return gitHost;
     }
+    if (testId.startsWith("project-health:")) {
+        if (!(extras === null || extras === void 0 ? void 0 : extras.projectHealthUrl)) {
+            throw new Error(`projectHealthUrl is required for test "${testId}"`);
+        }
+        return extras.projectHealthUrl;
+    }
+    if (testId.startsWith("project:")) {
+        if (!(extras === null || extras === void 0 ? void 0 : extras.projectUrl)) {
+            throw new Error(`projectUrl is required for test "${testId}"`);
+        }
+        return extras.projectUrl;
+    }
     const target = BUILDER_TARGETS[testId];
     if (!target) {
         throw new Error(`Unknown testId: ${testId}`);

package/src/connectivity/targets.spec.js

@@ -1,5 +1,6 @@
 import { describe, it, expect } from "vitest";
-import { extractPort, extractExplicitPort, BUILDER_TARGETS, DEFAULT_LOCAL_BUILDER_TESTS, BUILDER_TEST_DISPLAY_NAMES, } from "./targets";
+import { extractPort, extractExplicitPort, BUILDER_TARGETS, DEFAULT_LOCAL_BUILDER_TESTS, BUILDER_TEST_DISPLAY_NAMES, resolveTarget, getProjectHealthUrl, } from "./targets";
+import { getCheckTypeForTestId } from "./environment";
 describe("extractPort", () => {
     it("returns explicit port from URL", () => {
         expect(extractPort("https://git.amazon.com:2222", 443)).toBe(2222);
@@ -76,3 +77,52 @@ describe("BUILDER_TEST_DISPLAY_NAMES", () => {
         expect(BUILDER_TEST_DISPLAY_NAMES["builderio.dev:ws"]).toBe("*.builderio.dev (WebSocket)");
     });
 });
+describe("resolveTarget — per-project tests", () => {
+    const PROJECT_URL = "https://9739e085f64844e09c9918ce06fa57f5-main.builderio.dev/_builder.io/api/status-v2";
+    const HEALTH_URL = "https://health.builderio.dev/health";
+    it("resolves project:* testIds to the provided projectUrl", () => {
+        for (const id of [
+            "project:dns",
+            "project:tcp",
+            "project:tls",
+            "project:http",
+        ]) {
+            expect(resolveTarget(id, undefined, { projectUrl: PROJECT_URL })).toBe(PROJECT_URL);
+        }
+    });
+    it("resolves project-health:* testIds to the provided projectHealthUrl", () => {
+        for (const id of [
+            "project-health:dns",
+            "project-health:tcp",
+            "project-health:tls",
+            "project-health:http",
+        ]) {
+            expect(resolveTarget(id, undefined, { projectHealthUrl: HEALTH_URL })).toBe(HEALTH_URL);
+        }
+    });
+    it("throws when the required project URL is missing", () => {
+        expect(() => resolveTarget("project:dns")).toThrow();
+        expect(() => resolveTarget("project-health:dns")).toThrow();
+    });
+});
+describe("getProjectHealthUrl", () => {
+    it("maps a .dev project URL to the .dev health endpoint", () => {
+        expect(getProjectHealthUrl("https://abc-main.builderio.dev/_builder.io/api/status-v2")).toBe("https://health.builderio.dev/health");
+    });
+    it("maps a .xyz project URL to the .xyz health endpoint", () => {
+        expect(getProjectHealthUrl("https://abc-main.builderio.xyz")).toBe("https://health.builderio.xyz/health");
+    });
+    it("returns null for a non-kube domain", () => {
+        expect(getProjectHealthUrl("https://example.com/foo")).toBeNull();
+    });
+});
+describe("getCheckTypeForTestId — per-project tests", () => {
+    it("derives the check type from the project testId suffix", () => {
+        expect(getCheckTypeForTestId("project:dns")).toBe("dns");
+        expect(getCheckTypeForTestId("project:tcp")).toBe("tcp");
+        expect(getCheckTypeForTestId("project:tls")).toBe("tls");
+        expect(getCheckTypeForTestId("project:http")).toBe("http");
+        expect(getCheckTypeForTestId("project-health:dns")).toBe("dns");
+        expect(getCheckTypeForTestId("project-health:tls")).toBe("tls");
+    });
+});