@builder.io/ai-utils 0.81.3 → 0.83.0

package/package.json

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

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

@@ -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");
+    });
+});

package/src/connectivity/types.d.ts

@@ -1,5 +1,5 @@
 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 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" | "project:dns" | "project:tcp" | "project:tls" | "project:http" | "project-health:dns" | "project-health:tcp" | "project-health:tls" | "project-health:http";
 export interface Test {
     source: Source;
     testId: TestId;
@@ -25,6 +25,12 @@ export interface RunChecksInput {
      * Typically only needed server-side for static IP routing.
      */
     dispatcher?: object;
+    /**
+     * Treat 4xx HTTP responses as failures (not just 5xx). Used by
+     * `doctor --browser` so a proxy block page (e.g. a 403 from Zscaler) counts
+     * as a failure instead of a reachable-server pass.
+     */
+    strictHttpStatus?: boolean;
     /**
      * 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
@@ -45,6 +51,16 @@ export interface RunChecksInput {
     dnsResolver?: {
         servers: string[];
     };
+    /**
+     * Full URL of a specific project (e.g. a project's status-v2 endpoint) that the
+     * `project:*` tests probe. Resolved by resolveTarget for those testIds.
+     */
+    projectUrl?: string;
+    /**
+     * URL of the health.builderio.* domain the project is routed through, probed by
+     * the `project-health:*` tests. Derived from projectUrl's kube domain.
+     */
+    projectHealthUrl?: string;
 }
 export type ProgressEvent = {
     type: "test:start";

package/src/editor-ai.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+export declare const EDITOR_AI_READ_DEFAULT_LIMIT = 250;
+export declare const EDITOR_AI_READ_MAX_LIMIT = 1500;
+export declare const EditorAiReadRequestSchema: z.ZodObject<{
+    contentId: z.ZodString;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    activeLocale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EditorAiReadRequest = z.infer<typeof EditorAiReadRequestSchema>;
+export declare const EditorAiReadResponseSchema: z.ZodObject<{
+    contentId: z.ZodString;
+    totalLines: z.ZodNumber;
+    offset: z.ZodNumber;
+    limit: z.ZodNumber;
+    activeLocale: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+export type EditorAiReadResponse = z.infer<typeof EditorAiReadResponseSchema>;
+export declare const EditorAiEditRequestSchema: z.ZodObject<{
+    contentId: z.ZodString;
+    old_str: z.ZodString;
+    new_str: z.ZodString;
+    activeLocale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EditorAiEditRequest = z.infer<typeof EditorAiEditRequestSchema>;
+export declare const EditorAiEditResponseSchema: z.ZodObject<{
+    contentId: z.ZodString;
+    patch: z.ZodString;
+    modifiedBuilderContent: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type EditorAiEditResponse = z.infer<typeof EditorAiEditResponseSchema>;
+export declare const EditorAiWriteRequestSchema: z.ZodObject<{
+    contentId: z.ZodString;
+    content: z.ZodString;
+    activeLocale: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EditorAiWriteRequest = z.infer<typeof EditorAiWriteRequestSchema>;
+export declare const EditorAiWriteResponseSchema: z.ZodObject<{
+    contentId: z.ZodString;
+    modifiedBuilderContent: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type EditorAiWriteResponse = z.infer<typeof EditorAiWriteResponseSchema>;
+export type EditorAiErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "FORBIDDEN" | "NOT_FOUND" | "NO_MATCH" | "VALIDATION_FAILED" | "INTERNAL";
+export declare const EditorAiErrorBodySchema: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        hint: z.ZodOptional<z.ZodString>;
+        details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type EditorAiErrorBody = z.infer<typeof EditorAiErrorBodySchema>;

package/src/editor-ai.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+// Request/response contracts for the stateless /editor/read|edit|write
+// endpoints. Shared so the Builder CMS MCP server reuses the same shapes.
+export const EDITOR_AI_READ_DEFAULT_LIMIT = 250;
+export const EDITOR_AI_READ_MAX_LIMIT = 1500;
+export const EditorAiReadRequestSchema = z
+    .object({
+    contentId: z.string().min(1),
+    offset: z.number().int().min(0).optional(),
+    limit: z.number().int().min(1).max(EDITOR_AI_READ_MAX_LIMIT).optional(),
+    // Locale to operate on; defaults to "Default" when omitted.
+    activeLocale: z.string().min(1).optional(),
+})
+    .meta({ title: "EditorAiReadRequest" });
+export const EditorAiReadResponseSchema = z
+    .object({
+    contentId: z.string(),
+    totalLines: z.number().int(),
+    offset: z.number().int(),
+    limit: z.number().int(),
+    activeLocale: z.string(),
+    content: z.string(),
+})
+    .meta({ title: "EditorAiReadResponse" });
+export const EditorAiEditRequestSchema = z
+    .object({
+    contentId: z.string().min(1),
+    old_str: z
+        .string()
+        .min(1)
+        .refine((s) => s.trim().length > 0, {
+        message: "old_str must not be only whitespace",
+    }),
+    new_str: z.string(),
+    // Locale to operate on; defaults to "Default" when omitted.
+    activeLocale: z.string().min(1).optional(),
+})
+    .meta({ title: "EditorAiEditRequest" });
+export const EditorAiEditResponseSchema = z
+    .object({
+    contentId: z.string(),
+    patch: z.string(),
+    modifiedBuilderContent: z.record(z.string(), z.unknown()),
+})
+    .meta({ title: "EditorAiEditResponse" });
+export const EditorAiWriteRequestSchema = z
+    .object({
+    contentId: z.string().min(1),
+    content: z.string().min(1),
+    // Locale to operate on; defaults to "Default" when omitted.
+    activeLocale: z.string().min(1).optional(),
+})
+    .meta({ title: "EditorAiWriteRequest" });
+export const EditorAiWriteResponseSchema = z
+    .object({
+    contentId: z.string(),
+    modifiedBuilderContent: z.record(z.string(), z.unknown()),
+})
+    .meta({ title: "EditorAiWriteResponse" });
+export const EditorAiErrorBodySchema = z
+    .object({
+    error: z.object({
+        code: z.string(),
+        message: z.string(),
+        hint: z.string().optional(),
+        details: z.record(z.string(), z.unknown()).optional(),
+    }),
+})
+    .meta({ title: "EditorAiErrorBody" });

package/src/editor-ai.test.d.ts

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

package/src/editor-ai.test.js

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { EditorAiEditRequestSchema } from "./editor-ai.js";
+describe("EditorAiEditRequestSchema", () => {
+    it("accepts an old_str with real content (whitespace preserved)", () => {
+        const parsed = EditorAiEditRequestSchema.parse({
+            contentId: "c1",
+            old_str: '      <Text text="hi" />',
+            new_str: '      <Text text="bye" />',
+        });
+        // Value is not trimmed — exact indentation is preserved for matching.
+        expect(parsed.old_str).toBe('      <Text text="hi" />');
+    });
+    it("rejects an empty old_str", () => {
+        const result = EditorAiEditRequestSchema.safeParse({
+            contentId: "c1",
+            old_str: "",
+            new_str: "x",
+        });
+        expect(result.success).toBe(false);
+    });
+    it("rejects a whitespace-only old_str", () => {
+        const result = EditorAiEditRequestSchema.safeParse({
+            contentId: "c1",
+            old_str: "   \n\t",
+            new_str: "x",
+        });
+        expect(result.success).toBe(false);
+    });
+    it("allows an empty new_str (delete)", () => {
+        const result = EditorAiEditRequestSchema.safeParse({
+            contentId: "c1",
+            old_str: '<Text text="hi" />',
+            new_str: "",
+        });
+        expect(result.success).toBe(true);
+    });
+});