@builder.io/ai-utils 0.109.1 → 0.110.0

package/package.json

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

package/src/codegen.d.ts

@@ -4424,6 +4424,8 @@ export interface WorkspaceFolder {
      * Optional, so older CLIs/configs that ignore it stay compatible.
      */
     templateRepoUrl?: string;
+    /** Local-cluster testing only: branch or tag of `templateRepoUrl` to clone. Absent means its default branch. */
+    templateRef?: string;
     repoName?: string;
     resetGit?: boolean;
     /**

package/src/projects.d.ts

@@ -1963,6 +1963,8 @@ export interface Project {
     templateId?: string | null;
     /** @internal Read-only source repo cloned to bootstrap the project. Immutable. Absent for non-template projects. Distinct from `repoUrl`, which is always the real push remote. */
     templateRepoUrl?: string;
+    /** @internal Local-cluster testing only: the branch or tag of `templateRepoUrl` to clone instead of its default branch. Ignored once the real remote is seeded. */
+    templateRef?: string;
     /** Local filesystem path for desktop-app projects. */
     localPath?: string | null;
     /** The state of the project. Use `isProjectDeleted()` helper for backwards-compatible checks. */
@@ -2252,6 +2254,8 @@ export interface CreateProjectOptions {
     useInternalHost?: boolean;
     /** @internal Read-only source repo cloned to bootstrap the project. Carried through to Firestore. */
     templateRepoUrl?: string;
+    /** @internal Local-cluster testing only: branch or tag of `templateRepoUrl` to clone. Carried through to Firestore. */
+    templateRef?: string;
     /** @internal First-class hosting config copied from the template. Carried through to Firestore. */
     hosting?: ProjectHosting;
     /** @internal When true, provision the internalHost repo eagerly at creation. Hardcoded true for v0. */
@@ -2275,6 +2279,11 @@ export declare const GetProjectsQuerySchema: z.ZodObject<{
     limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
 export type GetProjectsQuery = z.infer<typeof GetProjectsQuerySchema>;
+/**
+ * A plain branch or tag name. It becomes an argument to `git clone -b`, so
+ * anything that could be read as an option or a path escape is rejected.
+ */
+export declare const TemplateRefSchema: z.ZodString;
 /**
  * Request body for `POST /projects/create`. Identity/credentials come from the
  * authenticated request context, never the body.
@@ -2290,6 +2299,7 @@ export declare const CreateProjectRequestSchema: z.ZodObject<{
     name: z.ZodString;
     initialMessage: z.ZodOptional<z.ZodString>;
     designSystems: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    templateRef: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type CreateProjectRequest = z.infer<typeof CreateProjectRequestSchema>;
 export interface BuilderMyContext {

package/src/projects.js

@@ -1107,6 +1107,20 @@ export const GetProjectsQuerySchema = z.object({
     /** At most this many projects, counted after access, hidden and DSI filtering. */
     limit: z.coerce.number().int().min(1).max(1000).optional(),
 });
+/**
+ * A plain branch or tag name. It becomes an argument to `git clone -b`, so
+ * anything that could be read as an option or a path escape is rejected.
+ */
+export const TemplateRefSchema = z
+    .string()
+    .max(255)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._/-]*$/)
+    .refine((ref) => !ref.includes(".."), {
+    message: "templateRef must not contain '..'",
+})
+    .meta({
+    description: "Local-cluster testing only: branch or tag of the template repo to clone. Rejected unless the service runs against a local cluster.",
+});
 /**
  * Request body for `POST /projects/create`. Identity/credentials come from the
  * authenticated request context, never the body.
@@ -1118,6 +1132,8 @@ export const CreateProjectRequestSchema = z.object({
     initialMessage: z.string().optional(),
     /** Design system ids to seed into project settings at creation. */
     designSystems: z.array(z.string()).optional(),
+    /** Local-cluster testing only: branch or tag of the template repo to clone. Template source only. */
+    templateRef: TemplateRefSchema.optional(),
 });
 export function resolveBranchIsPublic(isPublic, defaultBranchType) {
     if (isPublic !== undefined)

package/src/projects.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { AGENT_NATIVE_STARTER_REPO, getAgentNativeRootPackageJsonWriteError, getManagedDatabasePackageJsonError, getProjectState, GetShapeQuestionnaireOptionsSchema, InitialPromptSchema, isProjectDeleted, matchesAgentNativeStarter, findFigmaFileUrl, mentionsFigmaFileUrl, parseFigmaFileUrl, ProjectHostingExternalSchema, ProjectHostingSchema, ProjectSettingsExternalSchema, ProjectTemplateOverridesSchema, ShapeSessionSchema, SubmitShapeAnswersOptionsSchema, } from "./projects";
+import { AGENT_NATIVE_STARTER_REPO, CreateProjectRequestSchema, TemplateRefSchema, getAgentNativeRootPackageJsonWriteError, getManagedDatabasePackageJsonError, getProjectState, GetShapeQuestionnaireOptionsSchema, InitialPromptSchema, isProjectDeleted, matchesAgentNativeStarter, findFigmaFileUrl, mentionsFigmaFileUrl, parseFigmaFileUrl, ProjectHostingExternalSchema, ProjectHostingSchema, ProjectSettingsExternalSchema, ProjectTemplateOverridesSchema, ShapeSessionSchema, SubmitShapeAnswersOptionsSchema, } from "./projects";
 describe("project hosting schemas", () => {
     it("accepts the canonical published branch route", () => {
         expect(ProjectHostingSchema.parse({ publishedBranchId: "branch-live" })).toEqual({ publishedBranchId: "branch-live" });
@@ -294,3 +294,37 @@ describe("getProjectState", () => {
         expect(isProjectDeleted(project({ deleted: false }))).toBe(false);
     });
 });
+describe("TemplateRefSchema", () => {
+    it.each(["main", "eval/kyle/faster-start", "v1.2.3", "release_2026.10"])("accepts the branch or tag name %s", (ref) => {
+        expect(TemplateRefSchema.safeParse(ref).success).toBe(true);
+    });
+    it.each([
+        "",
+        "-b",
+        "--upload-pack=evil",
+        "../escape",
+        "a/../b",
+        "has space",
+        "semi;colon",
+        "a".repeat(256),
+    ])("rejects %j", (ref) => {
+        expect(TemplateRefSchema.safeParse(ref).success).toBe(false);
+    });
+});
+describe("CreateProjectRequestSchema templateRef", () => {
+    const base = {
+        source: { kind: "template", templateId: "agent-native-starter" },
+        name: "p",
+    };
+    it("is optional", () => {
+        expect(CreateProjectRequestSchema.parse(base).templateRef).toBeUndefined();
+    });
+    it("carries a valid ref through", () => {
+        expect(CreateProjectRequestSchema.parse({ ...base, templateRef: "eval/x" })
+            .templateRef).toBe("eval/x");
+    });
+    it("rejects an invalid ref", () => {
+        expect(CreateProjectRequestSchema.safeParse({ ...base, templateRef: "--x" })
+            .success).toBe(false);
+    });
+});