@builder.io/ai-utils 0.58.0 → 0.59.0

package/package.json

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

package/src/claw.d.ts

@@ -78,6 +78,8 @@ export interface WorkerReportOptions {
     originChannelId?: string;
     /** Clickable URL for the origin channel, if the integration already has one. */
     channelUrl?: string;
+    /** Human-readable name for the origin channel, if the integration has one. */
+    channelName?: string;
     /** The report content. */
     content: string;
     /** Agent/tool ID (for sub-agent reports). */
@@ -88,6 +90,8 @@ export interface WorkerMessageOptions {
     originChannelId?: string;
     /** Clickable URL for the origin channel, if the integration already has one. */
     channelUrl?: string;
+    /** Human-readable name for the origin channel, if the integration has one. */
+    channelName?: string;
     /** The report content. */
     content: string;
     /** Project ID (for branch reports). */
@@ -128,6 +132,8 @@ export interface IncomingMessageOptions {
     channelId: string;
     /** Clickable URL for channelId, if the integration already has one. */
     channelUrl?: string;
+    /** Human-readable channel name, if the integration has one. */
+    channelName?: string;
     /** DM channel ID, if the message was a direct message. */
     dmId?: string;
     /** Display name of the sender. */

package/src/claw.js

@@ -101,6 +101,9 @@ export function formatWorkerReport(opts) {
         if (url) {
             xml += `<origin_channel_url>${url}</origin_channel_url>\n`;
         }
+        if (opts.channelName) {
+            xml += `<origin_channel_name>${opts.channelName}</origin_channel_name>\n`;
+        }
     }
     xml += `<agent_id>${opts.agentId}</agent_id>\n`;
     xml += `<content>\n${opts.content.trim()}\n</content>\n`;
@@ -117,6 +120,9 @@ export function formatWorkerMessage(opts) {
         if (url) {
             xml += `<origin_channel_url>${url}</origin_channel_url>\n`;
         }
+        if (opts.channelName) {
+            xml += `<origin_channel_name>${opts.channelName}</origin_channel_name>\n`;
+        }
     }
     if (opts.senderDisplayName) {
         xml += `<sender>${opts.senderDisplayName}</sender>\n`;
@@ -166,6 +172,9 @@ export function formatIncomingMessage(opts) {
     if (channelUrl) {
         result += `<channel_url>${channelUrl}</channel_url>\n`;
     }
+    if (opts.channelName) {
+        result += `<channel_name>${opts.channelName}</channel_name>\n`;
+    }
     if (opts.dmId) {
         result += `<dm_id>${opts.dmId}</dm_id>\n`;
     }

package/src/claw.spec.js

@@ -103,6 +103,16 @@ describe("formatIncomingMessage", () => {
         });
         expect(result).toContain("<channel_url>https://test.atlassian.net/browse/PROJ-123</channel_url>");
     });
+    it("includes channel_name when provided by the integration", () => {
+        const result = formatIncomingMessage({
+            channelId: "slack/thread/TTEAM/CCHAN/1234567890.000100",
+            channelName: "#engineering",
+            sender: "Charlie",
+            timestamp: "Wednesday, January 3, 2024 at 12:00 PM PST",
+            content: "Slack message",
+        });
+        expect(result).toContain("<channel_name>#engineering</channel_name>");
+    });
     it("does not include channel_url for unsupported platforms", () => {
         const result = formatIncomingMessage({
             channelId: "telegram/chat/123456",
@@ -154,6 +164,14 @@ describe("formatWorkerMessage", () => {
         });
         expect(result).toContain("<origin_channel_url>https://test.atlassian.net/browse/PROJ-456</origin_channel_url>");
     });
+    it("includes origin_channel_name when provided by the integration", () => {
+        const result = formatWorkerMessage({
+            originChannelId: "slack/thread/TTEAM/CCHAN/1234567890.000100",
+            channelName: "#engineering",
+            content: "Worker result",
+        });
+        expect(result).toContain("<origin_channel_name>#engineering</origin_channel_name>");
+    });
     it("does not include origin_channel_url for unsupported platforms", () => {
         const result = formatWorkerMessage({
             originChannelId: "builder/branch/proj-id/my-branch",
@@ -195,6 +213,15 @@ describe("formatWorkerReport", () => {
         });
         expect(result).toContain("<origin_channel_url>https://test.atlassian.net/browse/PROJ-789</origin_channel_url>");
     });
+    it("includes origin_channel_name when provided by the integration", () => {
+        const result = formatWorkerReport({
+            originChannelId: "slack/channel/TTEAM/CCHAN",
+            channelName: "#engineering",
+            content: "Report content",
+            agentId: "agent-xyz",
+        });
+        expect(result).toContain("<origin_channel_name>#engineering</origin_channel_name>");
+    });
     it("does not include origin_channel_url for unsupported platforms", () => {
         const result = formatWorkerReport({
             originChannelId: "telegram/chat/123456",

package/src/codegen.d.ts

@@ -110,6 +110,15 @@ export interface CustomAgentDefinition {
     maxCompletions?: number;
     /** Default reasoning effort level for this agent type. Overrides the session default. */
     reasoning?: ReasoningEffort;
+    /**
+     * Default {@link SyncChangesFromRemote} policy applied to messages received
+     * by this agent when the message itself does not specify `syncChanges`.
+     * Only consulted at the session/sub-agent level (i.e. when the session was
+     * spawned with `agentType` equal to this agent's name). Use cases include
+     * always resetting the working branch to its base before each new message
+     * (e.g. the setup-project agent).
+     */
+    defaultSyncChanges?: SyncChangesFromRemote;
     /**
      * Where this agent was discovered. Drives precedence on name collision:
      * `project` > `user` > `plugin`. Set by the discovery loader, not by the
@@ -540,6 +549,9 @@ export interface ExitToolInput {
     devServerNeedsCredentials?: boolean;
     needsVPN?: boolean;
     autoReload?: boolean;
+    usesBuilderCms?: boolean;
+    /** Technologies used by the connected application (e.g. ["React", "Next.js", "Postgres", "Drizzle"]) */
+    stack?: string[];
     /** A human-readable description of what the project is about (not tech specs), used by fusion to route requests to the right project */
     projectDescription?: string;
 }
@@ -638,6 +650,8 @@ export interface ProposedConfig {
     durationMs?: number;
     needsVPN?: boolean;
     autoReload?: boolean;
+    usesBuilderCms?: boolean;
+    stack?: string[];
 }
 /**
  * Parameters for proposing a configuration to the backend
@@ -671,6 +685,8 @@ export interface ProposeConfigParams {
     needsVPN?: boolean;
     projectDescription?: string;
     autoReload?: boolean;
+    usesBuilderCms?: boolean;
+    stack?: string[];
 }
 export interface VerifySetupCommandToolInput {
     command: string;
@@ -705,6 +721,26 @@ export interface SetEnvVariableToolInput {
     placeholder?: boolean;
     explanation?: string;
 }
+export interface SetFileOverrideToolInput {
+    /**
+     * Path where the file should be written. Supports absolute paths
+     * ("/app/.npmrc"), tilde ("~/.npmrc") and paths relative to the project
+     * working directory ("./.npmrc"). Use this tool ONLY for configuration-only
+     * files that should NOT be committed to the repo (e.g. `.npmrc` with auth
+     * tokens, machine-local env files) — never to patch source code or fix
+     * software issues.
+     */
+    path: string;
+    /**
+     * Plain text content to write to the file. Mutually exclusive with `base64`.
+     */
+    content?: string;
+    /**
+     * Base64-encoded binary content to write to the file. Mutually exclusive
+     * with `content`. Use only when the file is genuinely binary.
+     */
+    base64?: string;
+}
 export interface SendMessageToolInput {
     channel_id: string;
     markdown: string;
@@ -858,6 +894,7 @@ export interface CodeGenToolMap {
     VerifyValidateCommand: VerifyValidateCommandToolInput;
     ProposeEnvVariable: ProposeEnvVariableToolInput;
     SetEnvVariable: SetEnvVariableToolInput;
+    SetFileOverride: SetFileOverrideToolInput;
     SendMessage: SendMessageToolInput;
     SpawnBranch: SpawnBranchToolInput;
     CreateProject: CreateProjectToolInput;
@@ -874,6 +911,10 @@ export interface CodeGenToolMap {
 export interface EnsurePRToolInput {
     project_id: string;
     branch_name: string;
+    /** Builder.io user ID to attribute the PR to. Must be a member of the org. */
+    builder_user_id?: string;
+    /** Whether to create the PR as a draft. Defaults to false. */
+    draft?: boolean;
 }
 export interface EscalateToPlanner {
     /** What's blocking execution */
@@ -961,7 +1002,7 @@ export declare const DEFAULT_QUEUE_BEHAVIOR: QueueBehavior;
 /** True for any schedule that aborts the in-flight run on enqueue. */
 export declare function isInterruptSchedule(schedule: QueueSchedule): boolean;
 export declare function normalizeQueueMode(mode: QueueMode | undefined): QueueBehavior;
-export declare const BASE_CODEGEN_POSITIONS: readonly ["fusion", "editor-ai", "repo-indexing", "cli", "create-app-firebase", "create-app-lovable", "builder-code-panel", "setup-project", "code-review-orchestrator", "project-configuration", "org-agent", "org-worker", "browser-testing", "projects-scheduler-memory-extraction", "builder-code", "unknown", "dsi-mcp"];
+export declare const BASE_CODEGEN_POSITIONS: readonly ["fusion", "editor-ai", "repo-indexing", "cli", "create-app-firebase", "create-app-lovable", "builder-code-panel", "setup-project", "code-review-orchestrator", "project-configuration", "org-agent", "org-worker", "browser-testing", "projects-scheduler-memory-extraction", "builder-code", "unknown", "dsi-mcp", "design-system-indexer", "builder-publish-integration"];
 export type BaseCodeGenPosition = (typeof BASE_CODEGEN_POSITIONS)[number];
 export type CodeGenPosition = BaseCodeGenPosition | `${BaseCodeGenPosition}-agent`;
 export interface RepoIndexingConfig {
@@ -1082,7 +1123,7 @@ export interface CodeGenInputOptions {
     /** @deprecated */
     systemReminderPrompt?: string;
 }
-export type CodeGenErrorCodes = "credits-limit-daily" | "credits-limit-monthly" | "credits-limit-other" | "cli-genetic-error" | "git-update-error" | "prompt-too-long" | "context-too-long" | "abrupt-end" | "unknown" | "failed-recover-state" | "completion-expired" | "ask-to-continue" | "bad-initial-url" | "bad-smart-export-payload" | "invalid-last-message" | "corrupted-session" | "privacy-mode-key-required" | "privacy-mode-key-invalid" | "cli-network-error" | "assertion" | "rate-limit" | "unknown-design-system";
+export type CodeGenErrorCodes = "credits-limit-daily" | "credits-limit-monthly" | "credits-limit-user" | "credits-limit-other" | "cli-genetic-error" | "git-update-error" | "prompt-too-long" | "context-too-long" | "abrupt-end" | "unknown" | "failed-recover-state" | "completion-expired" | "ask-to-continue" | "bad-initial-url" | "bad-smart-export-payload" | "invalid-last-message" | "corrupted-session" | "privacy-mode-key-required" | "privacy-mode-key-invalid" | "cli-network-error" | "assertion" | "rate-limit" | "unknown-design-system";
 export interface CodegenUsage {
     total: number;
     fast: number;
@@ -1255,6 +1296,7 @@ export interface GenerateCompletionStepDone {
     usage: CodegenUsage | undefined;
     url?: string;
     promptVersion: string | undefined;
+    planPath: string | undefined;
     stopReason: CompletionStopReason;
     hasChanges: boolean;
 }
@@ -1709,6 +1751,7 @@ export interface GenerateCodeEventDone {
     actionTitle: string;
     content?: string;
     needsPagination: boolean;
+    planPath: string | undefined;
     actions?: ActionItem[];
     suggestions: PromptSuggestion[];
     creditsUsed: number;

package/src/codegen.js

@@ -44,4 +44,6 @@ export const BASE_CODEGEN_POSITIONS = [
     "builder-code",
     "unknown",
     "dsi-mcp",
+    "design-system-indexer",
+    "builder-publish-integration",
 ];

package/src/design-systems.d.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+export type GenerateDesignSystemAttachmentKind = "fig" | "image" | "pdf" | "text";
+export interface GenerateDesignSystemFormFields {
+    /**
+     * Human-friendly project name. If omitted, the server generates one from
+     * the uploaded `.fig` filenames.
+     */
+    projectName?: string;
+}
+export interface GenerateDesignSystemRequest extends GenerateDesignSystemFormFields {
+    /**
+     * Mixed list of uploaded files in any order. Sent as repeated
+     * `attachments` fields in the multipart body.
+     */
+    attachments: File[];
+}
+export interface GenerateDesignSystemResponse {
+    projectId: string;
+    branchName: string;
+    branchUrl: string;
+}
+export interface GenerateDesignSystemErrorResponse {
+    error: string | Record<string, unknown>;
+}
+export declare const GENERATE_DESIGN_SYSTEM_MAX_FILE_BYTES: number;
+export declare const GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS = 50;
+export declare const GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS = 1;
+/**
+ * Validation for non-file fields posted alongside the multipart upload.
+ * Files are parsed out of the body by multer before this schema runs.
+ *
+ * The inferred type matches `GenerateDesignSystemFormFields` so the wire
+ * contract stays in lockstep with the shared type.
+ */
+export declare const generateDesignSystemBodySchema: z.ZodObject<{
+    projectName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GenerateDesignSystemBody = z.infer<typeof generateDesignSystemBodySchema>;

package/src/design-systems.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export const GENERATE_DESIGN_SYSTEM_MAX_FILE_BYTES = 100 * 1024 * 1024;
+export const GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS = 50;
+export const GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS = 1;
+/**
+ * Validation for non-file fields posted alongside the multipart upload.
+ * Files are parsed out of the body by multer before this schema runs.
+ *
+ * The inferred type matches `GenerateDesignSystemFormFields` so the wire
+ * contract stays in lockstep with the shared type.
+ */
+export const generateDesignSystemBodySchema = z.object({
+    projectName: z.string().trim().min(1).max(200).optional(),
+});

package/src/events.d.ts

@@ -625,6 +625,7 @@ export type ClawMessageSentV1 = FusionEventVariant<"claw.message.sent", {
     channelId?: string;
     /** Optional clickable URL for channelId. */
     channelUrl?: string;
+    channelName?: string;
     dmId?: string;
     senderDisplayName?: string;
     agentBranchName?: string;
@@ -785,6 +786,7 @@ export interface SendMessageToOrgAgentInput {
     channelId?: string;
     /** Optional clickable URL for channelId. */
     channelUrl?: string;
+    channelName?: string;
     senderDisplayName?: string;
     messageContext?: string;
     senderId?: string;

package/src/index.d.ts

@@ -14,4 +14,5 @@ export * from "./claw.js";
 export * from "./kube-error.js";
 export * from "./connectivity/types.js";
 export * from "./single-tenancy.js";
+export * from "./design-systems.js";
 export { connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, } from "./connectivity/error-codes.js";

package/src/index.js

@@ -14,4 +14,5 @@ export * from "./claw.js";
 export * from "./kube-error.js";
 export * from "./connectivity/types.js";
 export * from "./single-tenancy.js";
+export * from "./design-systems.js";
 export { connectivityErrorCodeToLikelyCause, mapConnectivityErrorMessage, } from "./connectivity/error-codes.js";

package/src/projects.d.ts

@@ -224,6 +224,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 {
@@ -340,7 +341,7 @@ export interface SetupScriptDependency {
     script: string;
 }
 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 +446,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 +599,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 +625,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 +823,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

@@ -33,6 +33,7 @@ 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 checkIsNewBranch = (branch) => {