@builder.io/ai-utils 0.58.1 → 0.60.0

package/src/messages.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 export function getContentText(message) {
     if (typeof message === "string") {
         return message;
@@ -14,3 +15,160 @@ export function getContentAttachments(message) {
         .filter((item) => item.type === "image")
         .map((item) => item.source);
 }
+export const URLSchema = z
+    .object({ type: z.literal("url"), value: z.string() })
+    .meta({ title: "URL" });
+export const FileUploadSchema = z
+    .object({
+    type: z.literal("upload"),
+    contentType: z.enum([
+        "image/webp",
+        "image/png",
+        "image/jpeg",
+        "image/gif",
+        "application/pdf",
+        "application/json",
+        "text/plain",
+    ]),
+    name: z.string(),
+    dataUrl: z.string(),
+    text: z.string().optional(),
+    size: z.number(),
+    id: z.string(),
+    originalUrl: z.string().optional(),
+    ephemeral: z.boolean().optional(),
+})
+    .meta({ title: "FileUpload" });
+export const TemplateSchema = z
+    .object({ type: z.literal("template"), name: z.string(), id: z.number() })
+    .meta({ title: "Template" });
+export const BuilderContentAttachmentSchema = z
+    .object({ type: z.literal("builder"), html: z.string() })
+    .meta({ title: "BuilderContentAttachment" });
+export const FigmaContentAttachmentSchema = z
+    .object({ type: z.literal("figma"), html: z.string() })
+    .meta({ title: "FigmaContentAttachment" });
+export const AttachmentSchema = z
+    .discriminatedUnion("type", [
+    FileUploadSchema,
+    TemplateSchema,
+    URLSchema,
+    BuilderContentAttachmentSchema,
+    FigmaContentAttachmentSchema,
+])
+    .meta({ title: "Attachment" });
+export const CitationCharLocationParamSchema = z
+    .object({
+    cited_text: z.string(),
+    document_index: z.number(),
+    document_title: z.string().nullable(),
+    end_char_index: z.number(),
+    start_char_index: z.number(),
+    type: z.literal("char_location"),
+})
+    .meta({ title: "CitationCharLocationParam" });
+export const CitationContentBlockLocationParamSchema = z
+    .object({
+    cited_text: z.string(),
+    document_index: z.number(),
+    document_title: z.string().nullable(),
+    end_block_index: z.number(),
+    start_block_index: z.number(),
+    type: z.literal("content_block_location"),
+})
+    .meta({ title: "CitationContentBlockLocationParam" });
+export const CitationPageLocationParamSchema = z
+    .object({
+    cited_text: z.string(),
+    document_index: z.number(),
+    document_title: z.string().nullable(),
+    end_page_number: z.number(),
+    start_page_number: z.number(),
+    type: z.literal("page_location"),
+})
+    .meta({ title: "CitationPageLocationParam" });
+export const CitationWebSearchResultLocationParamSchema = z
+    .object({
+    cited_text: z.string(),
+    encrypted_index: z.string(),
+    title: z.string().nullable(),
+    type: z.literal("web_search_result_location"),
+    url: z.string(),
+})
+    .meta({ title: "CitationWebSearchResultLocationParam" });
+export const TextCitationParamSchema = z
+    .discriminatedUnion("type", [
+    CitationCharLocationParamSchema,
+    CitationPageLocationParamSchema,
+    CitationContentBlockLocationParamSchema,
+    CitationWebSearchResultLocationParamSchema,
+])
+    .meta({ title: "TextCitationParam" });
+export const ImageBase64SourceSchema = z
+    .object({
+    type: z.literal("base64"),
+    media_type: z.enum(["image/webp", "image/png", "image/jpeg", "image/gif"]),
+    data: z.string(),
+    original_url: z.string().optional(),
+})
+    .meta({ title: "ImageBase64Source" });
+export const ImageUrlSourceSchema = z
+    .object({
+    type: z.literal("url"),
+    url: z.string(),
+})
+    .meta({ title: "ImageUrlSource" });
+export const ContentMessageItemTextSchema = z
+    .object({
+    type: z.literal("text"),
+    text: z.string(),
+    cache: z.boolean().optional(),
+    citations: z.array(TextCitationParamSchema).nullish(),
+    ephemeral: z.boolean().optional(),
+    thoughtSignature: z.string().optional(),
+    tag: z.string().optional(),
+})
+    .meta({ title: "ContentMessageItemText" });
+export const ContentMessageItemImageSchema = z
+    .object({
+    type: z.literal("image"),
+    source: z.discriminatedUnion("type", [
+        ImageBase64SourceSchema,
+        ImageUrlSourceSchema,
+    ]),
+    cache: z.boolean().optional(),
+    ephemeral: z.boolean().optional(),
+})
+    .meta({ title: "ContentMessageItemImage" });
+export const ContentMessageItemResourceSchema = z
+    .object({
+    type: z.literal("resource"),
+    resource: z.object({
+        uri: z.string(),
+        mimeType: z.string().optional(),
+        text: z.string().optional(),
+        blob: z.string().optional(),
+    }),
+})
+    .meta({ title: "ContentMessageItemResource" });
+export const ContentMessageItemToolResultSchema = z
+    .object({
+    type: z.literal("tool_result"),
+    tool_use_id: z.string(),
+    tool_name: z.string().optional(),
+    tool_input: z.string().optional(),
+    title: z.string().optional(),
+    content: z.union([
+        z.string(),
+        z.array(z.discriminatedUnion("type", [
+            ContentMessageItemTextSchema,
+            ContentMessageItemImageSchema,
+            ContentMessageItemResourceSchema,
+        ])),
+    ]),
+    is_error: z.boolean().optional(),
+    cache: z.boolean().optional(),
+    ephemeral: z.boolean().optional(),
+    structured_result: z.record(z.string(), z.any()).optional(),
+})
+    .meta({ title: "ContentMessageItemToolResult" });

package/src/projects.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import type { ConnectivityErrorCode, CheckType, LikelyCause } from "./connectivity/types.js";
 import type { FileOverride, EnvironmentVariable, LaunchServerState, LaunchServerStatus, BranchBackup, CommitMode, CustomInstruction, CustomAgentDefinition, GitSnapshot, AutoPushMode, GenerateUserMessage, CodeGenToolMap, GenerateCompletionStep, ReviewEffort } from "./codegen";
 import type { FallbackTokensPrivate } from "./organization";
@@ -224,6 +225,7 @@ export interface GitConfig {
 export type GitConfigs = Record<string, GitConfig>;
 export declare const EXAMPLE_REPOS: string[];
 export declare const STARTER_REPO = "BuilderIO/fusion-starter";
+export declare const DSI_PREVIEW_REPO = "BuilderIO/dsi-starter";
 export declare const EXAMPLE_OR_STARTER_REPOS: string[];
 export declare const EXAMPLE_OR_STARTER_REPOS_URLS: string[];
 export interface GitBackupUploadUrlResult {
@@ -326,21 +328,34 @@ export type ShutdownResponse = {
 export type ShutdownResponseSerialized = Omit<ShutdownResponse, "error"> & {
     error?: string;
 };
-export type SetupDependency = SetupMiseDependency | SetupScriptDependency;
-export interface SetupMiseDependency {
-    key: string;
-    type: "mise";
-    tool: string;
-    version?: string;
-}
-export interface SetupScriptDependency {
-    key: string;
-    type: "script";
-    name: string;
-    script: string;
-}
+export declare const SetupMiseDependencySchema: z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"mise">;
+    tool: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SetupMiseDependency = z.infer<typeof SetupMiseDependencySchema>;
+export declare const SetupScriptDependencySchema: z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"script">;
+    name: z.ZodString;
+    script: z.ZodString;
+}, z.core.$strip>;
+export type SetupScriptDependency = z.infer<typeof SetupScriptDependencySchema>;
+export declare const SetupDependencySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"mise">;
+    tool: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    type: z.ZodLiteral<"script">;
+    name: z.ZodString;
+    script: z.ZodString;
+}, z.core.$strip>], "type">;
+export type SetupDependency = z.infer<typeof SetupDependencySchema>;
 export type FusionExecutionEnvironment = "containerized" | "container-less" | "cloud" | "cloud-v2";
-export type AgentType = "setup-project" | "project-configuration" | "org-agent" | "code-review-orchestrator";
+export type AgentType = "setup-project" | "project-configuration" | "org-agent" | "code-review-orchestrator" | "design-system-indexer" | "builder-publish-integration";
 export interface PartialBranchData {
     name?: string;
     createdBy: string;
@@ -445,7 +460,7 @@ export interface OrgAgentConfig {
     enabledTools: string[];
     longLived: boolean;
 }
-export type BranchType = "code-review" | "setup-project" | "org-agent" | "default";
+export type BranchType = "code-review" | "setup-project" | "org-agent" | "design-system-indexing" | "default";
 /** Category of work a branch represents, auto-assigned during prompt analysis. */
 export type BranchCategory = "feature" | "fix" | "research" | "other";
 export interface BranchSharedData {
@@ -598,15 +613,25 @@ export interface PreviewPasswordProtection {
     password?: string;
 }
 export interface Project {
+    /** Unique project identifier. */
     id: string;
+    /** Display name of the project. */
     name: string;
+    /** ID of the space (organization) that owns this project. */
     ownerId: string;
+    /** Full repo name in the form "owner/repo", e.g. "acme/frontend". */
     repoFullName: string | undefined;
+    /** Git hosting provider: "github", "gitlab", "azure", "bitbucket", etc. */
     repoProvider: string;
+    /** Clone protocol: "https" or "ssh". */
     repoProtocol: string | undefined;
+    /** Optional human-readable description of the project. */
     description?: string;
+    /** Description pulled from the connected git repository's metadata. */
     repoDescription?: string;
+    /** Whether the connected repository is private. */
     repoPrivate: boolean;
+    /** Full clone URL of the repository. */
     repoUrl: string | undefined;
     /** 8-character SHA-256 hash of normalized repoUrl for cross-project matching */
     repoHash?: string;
@@ -614,103 +639,195 @@ export interface Project {
     createdDate: InMigrationDate;
     /** MIGRATION: accepts both string and number during migration period */
     updatedAt: InMigrationDate;
+    /** When true, the project appears at the top of the project list. */
     pinned?: boolean;
+    /** Sort order among pinned projects. */
     pinOrder?: number;
+    /** When true, the project is archived and hidden from the default view. */
     archived?: boolean;
+    /** User ID of the person who created the project. */
     createdBy: string;
+    /** User ID of the last person to update the project. */
     lastUpdateBy?: string;
+    /** Internal counter tracking CI check run outcomes per status. */
     checkRunCounts?: Record<string, number>;
+    /** User ID of whoever added the repository connection. */
     repoAddedBy?: string;
+    /** Internal counter tracking pipeline run outcomes per status. */
     pipelineCounts?: Record<string, number>;
+    /** When true, the project has not completed initial setup. */
     needSetup?: boolean;
+    /** Project purpose: general app or design-system indexing target. */
     projectType?: "app" | "repo-indexing";
+    /** Custom domains associated with this project. */
     domains?: string[];
+    /** Whether the project is publicly accessible. */
     accessMode?: "public" | "private";
+    /** Fine-grained access control configuration for the project. */
     projectAccess?: ProjectAccessControl;
     settings: {
+        /** When true, this is a native (mobile/desktop) app with no web dev server. */
         isNativeApp?: boolean;
+        /** When true, automatically detect the dev server URL from command output (Desktop app only). */
         autoDetectDevServer?: boolean;
+        /** Regex patterns matched against dev command output to detect the server URL. */
         autoDetectDevServerPatterns?: string[];
+        /** Execution environment for the Fusion runtime (cloud, containerized, container-less). */
         fusionEnvironment?: FusionExecutionEnvironment;
+        /** Port the dev server listens on inside the container. Use 0 for auto-assign. Default: 3000. */
         devServerPort?: number;
+        /** @internal Explicit dev server URL; overrides auto-detection. Set by the system, not user-configurable. */
         devServerUrl?: string;
+        /** @internal Whether to reload the preview when files change. Managed by the app UI. */
         refreshPreview?: boolean;
+        /** Commands to install dependencies before starting the dev server (e.g. "npm install"). */
         installCommand?: string;
+        /** @internal Command to run validation checks. Used internally by the setup agent. */
         validateCommand?: string;
+        /** @internal URL origin used for the dev server proxy. Related to Electron proxy configuration. Exposed via specific UI; not a free-text field. */
         proxyOrigin?: string;
+        /** @internal Default proxy origin, resolved at runtime. */
         proxyDefaultOrigin?: string;
+        /** @internal Mode for automatically pushing AI commits. Managed by the app. */
         defaultAutoPush?: AutoPushMode;
+        /** How branch names are generated: ai-session ID, descriptive name, or a custom pattern. */
         gitBranchNamingStrategy?: "ai-session" | "branch-name" | "custom";
+        /** @internal Mise tools and custom scripts run before the setup command. Managed via builder.config.json. */
         setupDependencies?: SetupDependency[];
+        /** Custom branch name pattern used when gitBranchNamingStrategy is "custom". */
         gitBranchNamingCustom?: string;
+        /** When true, the user is prompted to provide a branch name before a new branch is created. */
         askUserForBranchName?: boolean;
+        /** Command to start the dev server (e.g. "npm run dev"). */
         devServerCommand?: string;
+        /** CPU tier for the container: "performance", "standard", or "shared". */
         cpuKind?: CpuKind;
+        /** Number of vCPUs allocated to the container: 1, 2, or 4. */
         cpus?: 1 | 2 | 4;
+        /** RAM allocated to the container in MB. Higher values (8192/16384) are enterprise-only. Default: 4096. */
         memory?: 2048 | 4096 | 8192 | 16384;
-        /** @deprecated */
+        /** @deprecated Use {@link memory} instead. */
         memoryLimit?: 1024 | 2048 | 4096 | 8192 | 16384;
+        /** Idle behavior for the container: stop, suspend, or stay on. Default: "suspend". */
         autoStop?: MachineAutoStop;
+        /** Base branch used when cloning and creating new branches. Default: "main". */
         mainBranchName?: string;
+        /** Minimum number of machines kept alive at all times. Default: 0. */
         minMachinesRunning?: number;
+        /** Persistent disk size in GB. Default: 5. */
         volumeSize?: 5 | 10 | 12 | 15 | 20 | 25 | 30 | 50;
+        /** @internal Subpath within the repository to use as the working root. */
         includePath?: string;
+        /** Glob patterns limiting which paths are included when cloning or processing. */
         includePatterns?: string[];
+        /** Environment variables injected into the dev container. */
         environmentVariables?: EnvironmentVariable[];
+        /** Files injected into the container during setup, written before installCommand runs. */
         fileOverrides?: FileOverride[];
+        /** Structured instruction rules applied to AI sessions (name, content, scope, tool allowlists). */
         customInstructions?: CustomInstruction[];
+        /** Definitions for specialized sub-agents with custom system prompts, tools, and model overrides. */
         customAgents?: CustomAgentDefinition[];
+        /** How the AI commits changes: direct commits, draft PRs, or ready-for-review PRs. Default: "draft-prs". */
         commitMode?: CommitMode;
+        /** Default visibility for new branches: shared (team-visible) or private. Default: "private". */
         defaultBranchType?: "shared" | "private";
+        /** Custom container image path (e.g. ghcr.io/org/image:tag). Overrides nodeVersion when set. */
         dockerImagePath?: string;
+        /** Node.js version to use in the container (e.g. "22"). Ignored when dockerImagePath is set. */
         nodeVersion?: string;
+        /** Named design systems to expose for AI assistance. */
         designSystems?: string[];
+        /** @internal Use @antfu/ni for package management instead of direct npm/yarn/pnpm commands. */
         useNI?: boolean;
+        /** Additional repositories cloned alongside the main repo for extra AI context. */
         folders?: Array<{
+            /** Identifier for this workspace folder (kebab/snake case recommended). */
             name: string;
+            /** Full clone URL of the repository (must end in .git for GitHub/GitLab). */
             remoteUrl: string;
+            /** Base branch to clone. Default: "main". */
             mainBranchName?: string;
+            /** Subpath within this repo to use as the working root. */
             includePath?: string;
+            /** User ID of whoever added this folder. */
             addedBy?: string;
+            /** Detected or specified git provider. */
             repoProvider?: string;
+            /** Clone protocol: "https" or "ssh". */
             repoProtocol?: string;
+            /** Whether to track git history for this folder. */
             enableGit?: boolean;
         }>;
+        /** Freeform workspace-level AI instructions, equivalent to an AGENTS.md file. */
         agentsMD?: string;
+        /** One-time command run after the repo is first cloned, before installCommand. */
         initializationCommand?: string;
+        /** @internal Subpath within the repo recommended by auto-detection as the project root. */
         repoSubpath?: string;
+        /** @internal Workspace root recommended by auto-setup analysis; not user-configurable. */
         recommendedRoot?: string;
+        /** Enable HTTPS for the dev server proxy. Default: false. */
         https?: boolean;
+        /** Custom local domain for HTTPS (e.g. "myapp.local"). */
         localHttpsDomain?: string;
+        /** Browser automation configuration for AI-driven end-to-end testing and visual verification. */
         browserAutomation?: {
+            /** Run browser automation tasks as background agents. */
             backgroundAgents?: boolean;
+            /** Custom instructions for the browser agent. */
             instructions?: string;
+            /** Username for sites requiring authentication. */
             authUser?: string;
+            /** Password for sites requiring authentication. */
             authPassword?: string;
         };
+        /** Automated PR reviewer configuration. */
         prReviewer?: {
+            /** Whether the automated reviewer is enabled. */
             enabled: boolean;
+            /** Custom review guidelines for the reviewer. */
             instructions?: string;
+            /** How deeply to review: "low", "medium" (default), or "high". */
             reviewEffort?: ReviewEffort;
         };
+        /** Enable volume snapshots so session state can be saved and restored. */
         enableSnapshots?: boolean;
+        /** When true, the AI captures memories after a branch is merged for use in future sessions. */
         postMergeMemories?: boolean;
+        /** @internal Custom instructions for AI-generated commit messages. */
         commitInstructions?: string;
+        /** Maximum number of AI completions allowed per agent session. */
         maxAgentCompletions?: number;
+        /** @internal Bypass command security restrictions. Admin use only. */
         skipCommandSecurity?: boolean;
+        /** File path to the HTTPS private key. */
         httpsServerKeyPath?: string;
+        /** File path to the HTTPS certificate. */
         httpsServerCertPath?: string;
+        /** File path to the HTTPS CA certificate. */
         httpsServerCaPath?: string;
+        /** HTTPS private key content as a string (alternative to httpsServerKeyPath). */
         httpsServerKeyContent?: string;
+        /** HTTPS certificate content as a string (alternative to httpsServerCertPath). */
         httpsServerCertContent?: string;
+        /** HTTPS CA certificate content as a string (alternative to httpsServerCaPath). */
         httpsServerCaContent?: string;
+        /** PFX/PKCS12 bundle for HTTPS. */
         httpsServerPfx?: string;
+        /** Passphrase for an encrypted HTTPS private key or PFX. */
         httpsServerPassphrase?: string;
+        /** Secure protocol string passed to Node.js https.createServer (e.g. "TLSv1_2_method"). */
         httpsServerSecureProtocol?: string;
+        /** Numeric TLS options bitmask passed to Node.js https.createServer. */
         httpsServerSecureOptions?: number;
+        /** Cipher suite string (OpenSSL format) for the HTTPS server. */
         httpsServerCiphers?: string;
+        /** When true, the server's cipher order takes precedence over the client's. */
         httpsServerHonorCipherOrder?: boolean;
+        /** When true, the server requests a client certificate. */
         httpsServerRequestCert?: boolean;
+        /** When false, self-signed or untrusted client certificates are accepted. */
         httpsServerRejectUnauthorized?: boolean;
         /**
          * When true, this project is the preferred project for its connected repository.
@@ -720,23 +837,35 @@ export interface Project {
         /** Single tenancy config ID for this project. Overrides the space-level defaultSingleTenancyConfig.
          *  References a document in the singleTenancyConfigurations collection. */
         singleTenancyConfig?: string;
+        /** Password-protect the preview URL. */
         previewPasswordProtection?: PreviewPasswordProtection;
     };
+    /** URL of the project's screenshot thumbnail, or null if none has been captured. */
     screenshot: string | null;
+    /** When true, this project is a built-in example shown to new users. */
     isExample?: boolean;
+    /** When true, the project is publicly accessible without authentication. */
     isPublic?: boolean;
+    /** Volume snapshot metadata for restoring container state. */
     snapshotVolume?: {
+        /** Fly.io volume identifier. */
         volumeId: string;
+        /** Fly.io app name associated with the snapshot. */
         appName: string;
+        /** Unix timestamp (ms) when the snapshot was created. */
         createdAt: number;
     };
+    /** When true, this project was created from a user-defined template. */
     isFromUserTemplate?: boolean;
+    /** ID of the template used to create this project, if any. */
     templateId?: string | null;
+    /** Local filesystem path for desktop-app projects. */
     localPath?: string | null;
     /** The state of the project. Use `isProjectDeleted()` helper for backwards-compatible checks. */
     state?: EntityState;
     /** MIGRATION: accepts both string and number during migration period */
     deletedAt?: InMigrationDateNullable;
+    /** User ID of whoever deleted the project. */
     deletedBy?: string;
     /**
      * When true, branches are stored in the standalone `branches` collection

package/src/projects.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 /**
  * Detect git provider from a repository URL (HTTPS or SSH).
  * Used by both error diagnostics and connectivity checks for consistent provider labeling.
@@ -33,8 +34,31 @@ export const EXAMPLE_REPOS = [
     "BuilderIO/org-agent-starter",
 ];
 export const STARTER_REPO = "BuilderIO/fusion-starter";
+export const DSI_PREVIEW_REPO = "BuilderIO/dsi-starter";
 export const EXAMPLE_OR_STARTER_REPOS = [...EXAMPLE_REPOS, STARTER_REPO];
 export const EXAMPLE_OR_STARTER_REPOS_URLS = EXAMPLE_OR_STARTER_REPOS.map((repo) => `https://github.com/${repo}`);
+export const SetupMiseDependencySchema = z
+    .object({
+    key: z.string(),
+    type: z.literal("mise"),
+    tool: z.string(),
+    version: z.string().optional(),
+})
+    .meta({ title: "SetupMiseDependency" });
+export const SetupScriptDependencySchema = z
+    .object({
+    key: z.string(),
+    type: z.literal("script"),
+    name: z.string(),
+    script: z.string(),
+})
+    .meta({ title: "SetupScriptDependency" });
+export const SetupDependencySchema = z
+    .discriminatedUnion("type", [
+    SetupMiseDependencySchema,
+    SetupScriptDependencySchema,
+])
+    .meta({ title: "SetupDependency" });
 export const checkIsNewBranch = (branch) => {
     return "projectId" in branch;
 };