@builder.io/ai-utils 0.83.0 → 0.84.0

package/package.json

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

package/src/claw.d.ts

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

package/src/claw.js

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

package/src/claw.spec.js

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

package/src/codegen.d.ts

@@ -6,6 +6,7 @@ import { type EnvironmentVariable, type SetupDependency } from "./common-schemas
 import type { ForcedBackup, GitDiagnostics, ProjectSkill } from "./projects";
 import type { Feature } from "./features";
 import type { CpuKind, BranchType } from "./projects";
+import type { FullLibrarySourceInput } from "./design-systems";
 export declare const GitSnapshotSchema: z.ZodString;
 export type GitSnapshot = z.infer<typeof GitSnapshotSchema>;
 export declare const ImportTypeSchema: z.ZodEnum<{
@@ -229,6 +230,10 @@ export declare const DevServerLogsInputSchema: z.ZodObject<{}, z.core.$strip>;
 export type DevServerLogsInput = z.infer<typeof DevServerLogsInputSchema>;
 export declare const GenerateDesignSystemAgentMdInputSchema: z.ZodObject<{}, z.core.$strip>;
 export type GenerateDesignSystemAgentMdInput = z.infer<typeof GenerateDesignSystemAgentMdInputSchema>;
+export declare const ComputeDocHashInputSchema: z.ZodObject<{
+    relevantFiles: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ComputeDocHashInput = z.infer<typeof ComputeDocHashInputSchema>;
 export declare const DevServerRestartInputSchema: z.ZodObject<{}, z.core.$strip>;
 export type DevServerRestartInput = z.infer<typeof DevServerRestartInputSchema>;
 export declare const BashToolInputSchema: z.ZodObject<{
@@ -1974,6 +1979,9 @@ export declare const CodeGenToolMapSchema: z.ZodObject<{
         purpose: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     GenerateDesignSystemAgentMd: z.ZodObject<{}, z.core.$strip>;
+    ComputeDocHash: z.ZodObject<{
+        relevantFiles: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
 }, z.core.$strip>;
 export type CodeGenToolMap = z.infer<typeof CodeGenToolMapSchema>;
 export declare const CodeGenToolsSchema: z.ZodEnum<{
@@ -1984,6 +1992,7 @@ export declare const CodeGenToolsSchema: z.ZodEnum<{
     AskUserQuestion: "AskUserQuestion";
     Bash: "Bash";
     BuilderEdit: "BuilderEdit";
+    ComputeDocHash: "ComputeDocHash";
     ConnectMCP: "ConnectMCP";
     CreateProject: "CreateProject";
     DevServerControl: "DevServerControl";
@@ -2708,6 +2717,7 @@ export declare const CodeGenInputOptionsSchema: z.ZodObject<{
         AskUserQuestion: "AskUserQuestion";
         Bash: "Bash";
         BuilderEdit: "BuilderEdit";
+        ComputeDocHash: "ComputeDocHash";
         ConnectMCP: "ConnectMCP";
         CreateProject: "CreateProject";
         DevServerControl: "DevServerControl";
@@ -4235,6 +4245,7 @@ export interface FusionConfig {
      * `branchType === "design-system-indexing"` branches.
      */
     figmaDecodeJobId?: string;
+    designSystemIndexSources?: FullLibrarySourceInput[];
     featureBranch?: string;
     /** When set, init checks out this exact git commit after cloning featureBranch. */
     checkoutCommit?: string;

package/src/codegen.js

@@ -211,6 +211,25 @@ export const GenerateDesignSystemAgentMdInputSchema = z.object({}).meta({
         " globs `.builder/output/tokens/components/*.css` for component slugs." +
         " Call this as the final step after all CSS files have been written.",
 });
+export const ComputeDocHashInputSchema = z
+    .object({
+    relevantFiles: z
+        .array(z.string())
+        .min(1)
+        .meta({
+        description: "Workspace-relative paths of the source files that define this doc" +
+            " (the same `relevantFiles` recorded in the doc's meta.json). The" +
+            " hash is computed deterministically from these files' contents.",
+    }),
+})
+    .meta({
+    title: "ComputeDocHashInput",
+    description: "Deterministically computes the content hash for an indexed design-system" +
+        " doc from its `relevantFiles`, using the exact algorithm the repo-indexing" +
+        " CLI uses (sorted files, BOM-stripped contents joined with newlines," +
+        " SHA-256). Use this to fill the `hash` field of a component/token/icon" +
+        " meta.json — never invent a hash yourself.",
+});
 export const DevServerRestartInputSchema = z.object({}).meta({
     title: "DevServerRestartInput",
     description: "Restarts the dev server with current configuration.",
@@ -1229,7 +1248,7 @@ export const SendMessageToolInputSchema = z
         description: "When true, send the response as a voice message using text-to-speech. Only supported for Telegram channels. Only set to true when the user's original message was a voice/audio message (look for '[Voice message transcription]' or '[Audio' markers), the channel is Telegram, and the response is short and conversational with no URLs, code, lists, or other content that doesn't translate to audio. Default to false (text) for all text-originated messages.",
     }),
     from_user_id: z.string().optional().meta({
-        description: "Builder.io user ID this message is from / should be attributed to. Only allowed when channel_id is 'builder/branch/{project_id}/{branch_name}'. When set, the message is delivered to the target branch as coming from this user (role 'user') instead of from the agent. Use whenever the message represents user feedback/intent that should be assigned to someone — even if it was composed, summarized, or merged from multiple people.",
+        description: "Builder.io user ID this message is from / should be attributed to. Only allowed when channel_id is 'builder/branch/{project_id}/{branch_name}'. When set, the message is delivered to the target branch as coming from this user (role 'user') instead of from the agent. Defaults to the current requester when omitted. Set this explicitly when relaying a message on behalf of someone other than the person who sent the current message — even if it was composed, summarized, or merged from multiple people.",
     }),
 })
     .meta({ title: "SendMessageToolInput" });
@@ -1587,6 +1606,7 @@ export const CodeGenToolMapSchema = z.object({
     EnsurePR: EnsurePRToolInputSchema,
     EnableDatabase: EnableDatabaseToolInputSchema,
     GenerateDesignSystemAgentMd: GenerateDesignSystemAgentMdInputSchema,
+    ComputeDocHash: ComputeDocHashInputSchema,
 });
 export const CodeGenToolsSchema = CodeGenToolMapSchema.keyof().meta({
     title: "CodeGenTools",

package/src/design-systems.d.ts

@@ -11,64 +11,21 @@ export interface FigmaHydrationResponse {
     manifest: import("./events.js").FigmaFrameManifest | null;
     files: FigmaHydrationFile[];
 }
-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;
-    devToolsVersion?: string;
-    /**
-     * Optional map of filename → page/frame GUIDs to restrict indexing.
-     * GUIDs are file-local, so they must be scoped per attachment.
-     */
-    selection?: Record<string, string[]>;
-    githubRepoUrl?: string;
-    /** Id of a connected Fusion project whose repo is cloned as supplementary context. Takes precedence over `githubRepoUrl`. */
-    connectedProjectId?: string;
-}
 /**
  * Accepts `https://github.com/<owner>/<repo>` (optionally with a trailing
- * `.git` or path segments). Used to gate the public-repo input on the
- * `/design-systems/v1/generate` endpoint.
+ * `.git` or path segments). Used to gate public-repo inputs before cloning.
  */
 export declare const GITHUB_REPO_URL_REGEX: RegExp;
-export interface GenerateDesignSystemRequest extends GenerateDesignSystemFormFields {
-    attachments: File[];
-}
-export interface GenerateDesignSystemResponse {
-    projectId: string;
-    /**
-     * Decode job id. Attachments are processed asynchronously in the
-     * `ai-queue-subscribers` worker. Clients should listen on the
-     * `figmaDecodeJobs/{jobId}` Firestore document for progress and the
-     * resolved `branchName` / `branchUrl`.
-     */
-    jobId: string;
-    designSystemId: 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 = 0;
-export declare const generateDesignSystemBodySchema: z.ZodObject<{
-    projectName: z.ZodOptional<z.ZodString>;
-    devToolsVersion: z.ZodOptional<z.ZodString>;
-    selection: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
-    githubRepoUrl: z.ZodOptional<z.ZodString>;
-    connectedProjectId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type GenerateDesignSystemBody = z.infer<typeof generateDesignSystemBodySchema>;
 /**
  * Signed-URL upload flow.
  *
  * Clients no longer post `.fig` bytes through the service (Cloud Run caps
  * request bodies at 32 MiB). Instead they call `upload/start` to get a
  * temporary signed resumable-upload URL per attachment, stream the bytes
- * directly to GCS, then call `/generate` with the returned upload tokens.
+ * directly to GCS, then call `/index` with the returned upload tokens.
  * See `tech-specs/signed-url-figma-upload`.
  */
 /** A single attachment the client declares when starting an upload. */
@@ -89,7 +46,7 @@ export declare const uploadStartBodySchema: z.ZodObject<{
 export type UploadStartBody = z.infer<typeof uploadStartBodySchema>;
 /**
  * Claims encoded inside a signed `uploadToken`. Bound to the GCS object at
- * `upload/start` and verified at `/generate`, so a client cannot point the
+ * `upload/start` and verified at `/index`, so a client cannot point the
  * decode worker at an object it did not upload.
  */
 export declare const uploadTokenPayloadSchema: z.ZodObject<{
@@ -106,24 +63,167 @@ export interface UploadStartResponseItem {
     idx: number;
     /** Signed URL the client POSTs to (with `x-goog-resumable: start`) to begin the resumable upload. */
     uploadUrl: string;
-    /** Opaque signed token the client passes back to `/generate`. */
+    /** Opaque signed token the client passes back to `/index`. */
     uploadToken: string;
 }
 export interface UploadStartResponse {
     jobId: string;
     uploads: UploadStartResponseItem[];
 }
-/**
- * Request body for the signed-URL variant of `POST /design-systems/v1/generate`.
- * Same non-file fields as the legacy multipart form, plus the `uploads`
- * tokens returned by `upload/start` (one per attachment).
- */
-export declare const generateDesignSystemRequestSchema: z.ZodObject<{
-    projectName: z.ZodOptional<z.ZodString>;
-    devToolsVersion: z.ZodOptional<z.ZodString>;
-    selection: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
-    githubRepoUrl: z.ZodOptional<z.ZodString>;
-    connectedProjectId: z.ZodOptional<z.ZodString>;
-    uploads: z.ZodArray<z.ZodString>;
+export declare const indexDesignSystemScopeSchema: z.ZodEnum<{
+    global: "global";
+    organization: "organization";
+    space: "space";
+}>;
+export type IndexDesignSystemScope = z.infer<typeof indexDesignSystemScopeSchema>;
+export declare const fullLibrarySourceKindSchema: z.ZodEnum<{
+    "connected-repo": "connected-repo";
+    package: "package";
+    "public-repo": "public-repo";
+}>;
+export type FullLibrarySourceKind = z.infer<typeof fullLibrarySourceKindSchema>;
+export declare const fullLibrarySourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"connected-repo">;
+    fusionProjectId: z.ZodString;
+    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    instructions: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"public-repo">;
+    repoUrl: z.ZodString;
+    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    instructions: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"package">;
+    package: z.ZodString;
+    registry: z.ZodOptional<z.ZodString>;
+    token: z.ZodOptional<z.ZodString>;
+    instructions: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "kind">;
+export type FullLibrarySourceInput = z.infer<typeof fullLibrarySourceSchema>;
+export type ConnectedRepoSourceInput = Extract<FullLibrarySourceInput, {
+    kind: "connected-repo";
+}>;
+export type PublicRepoSourceInput = Extract<FullLibrarySourceInput, {
+    kind: "public-repo";
+}>;
+export type PackageSourceInput = Extract<FullLibrarySourceInput, {
+    kind: "package";
+}>;
+export declare const fileSourceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"file">;
+    uploadToken: z.ZodOptional<z.ZodString>;
+    uploadGcsPath: z.ZodOptional<z.ZodString>;
+    selection: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    instructions: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type FileSourceInput = z.infer<typeof fileSourceSchema>;
+export declare const designSystemSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"connected-repo">;
+    fusionProjectId: z.ZodString;
+    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    instructions: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"public-repo">;
+    repoUrl: z.ZodString;
+    include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    instructions: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"package">;
+    package: z.ZodString;
+    registry: z.ZodOptional<z.ZodString>;
+    token: z.ZodOptional<z.ZodString>;
+    instructions: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"file">;
+    uploadToken: z.ZodOptional<z.ZodString>;
+    uploadGcsPath: z.ZodOptional<z.ZodString>;
+    selection: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    instructions: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "kind">;
+export type DesignSystemSourceInput = z.infer<typeof designSystemSourceSchema>;
+export declare const resolvePackageOptionsSchema: z.ZodObject<{
+    package: z.ZodString;
+    registry: z.ZodOptional<z.ZodString>;
+    token: z.ZodOptional<z.ZodString>;
+    specifier: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ResolvePackageOptions = z.infer<typeof resolvePackageOptionsSchema>;
+export interface ResolvePackageResult {
+    /** Whether the package resolved successfully from the registry. */
+    ok: boolean;
+    package: string;
+    /** Registry actually queried (defaults to the public npm registry). */
+    registry: string;
+    /** Specifier requested (defaults to "latest"). */
+    specifier: string;
+    /** Concrete version the specifier resolved to, when ok. */
+    version?: string;
+    /** Tarball URL for the resolved version, when ok. */
+    tarball?: string;
+    /** Human-readable failure reason, when not ok. */
+    error?: string;
+}
+export declare const indexDesignSystemBodySchema: z.ZodObject<{
+    designSystemName: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodEnum<{
+        global: "global";
+        organization: "organization";
+        space: "space";
+    }>>;
+    sources: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"connected-repo">;
+        fusionProjectId: z.ZodString;
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        instructions: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"public-repo">;
+        repoUrl: z.ZodString;
+        include: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        instructions: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"package">;
+        package: z.ZodString;
+        registry: z.ZodOptional<z.ZodString>;
+        token: z.ZodOptional<z.ZodString>;
+        instructions: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"file">;
+        uploadToken: z.ZodOptional<z.ZodString>;
+        uploadGcsPath: z.ZodOptional<z.ZodString>;
+        selection: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+        instructions: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>;
+export type IndexDesignSystemBody = z.infer<typeof indexDesignSystemBodySchema>;
+export declare const sourceFileEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+    type: z.ZodEnum<{
+        dir: "dir";
+        file: "file";
+    }>;
+}, z.core.$strip>;
+export type SourceFileEntry = z.infer<typeof sourceFileEntrySchema>;
+export declare const listSourceFilesQuerySchema: z.ZodObject<{
+    projectId: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ListSourceFilesQuery = z.infer<typeof listSourceFilesQuerySchema>;
+export interface ListSourceFilesResponse {
+    /** The directory that was listed (repo-relative; "" for root). */
+    path: string;
+    entries: SourceFileEntry[];
+}
+export declare const listPublicSourceFilesQuerySchema: z.ZodObject<{
+    repoUrl: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
-export type GenerateDesignSystemRequestBody = z.infer<typeof generateDesignSystemRequestSchema>;
+export type ListPublicSourceFilesQuery = z.infer<typeof listPublicSourceFilesQuerySchema>;

package/src/design-systems.js

@@ -1,45 +1,19 @@
 import { z } from "zod";
 /**
  * Accepts `https://github.com/<owner>/<repo>` (optionally with a trailing
- * `.git` or path segments). Used to gate the public-repo input on the
- * `/design-systems/v1/generate` endpoint.
+ * `.git` or path segments). Used to gate public-repo inputs before cloning.
  */
 export const GITHUB_REPO_URL_REGEX = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+(?:\.git)?\/?$/;
 export const GENERATE_DESIGN_SYSTEM_MAX_FILE_BYTES = 2 * 1024 * 1024 * 1024;
 export const GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS = 50;
 export const GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS = 0;
-export const generateDesignSystemBodySchema = z.object({
-    projectName: z.string().trim().min(1).max(200).optional(),
-    devToolsVersion: z.string().trim().min(1).max(64).optional(),
-    selection: z
-        .preprocess((v) => {
-        if (typeof v !== "string")
-            return v;
-        const trimmed = v.trim();
-        if (!trimmed)
-            return undefined;
-        try {
-            return JSON.parse(trimmed);
-        }
-        catch (_a) {
-            return v;
-        }
-    }, z.record(z.string(), z.array(z.string().min(1)).max(10000)))
-        .optional(),
-    githubRepoUrl: z
-        .string()
-        .trim()
-        .regex(GITHUB_REPO_URL_REGEX, "must be a public github.com repo URL")
-        .optional(),
-    connectedProjectId: z.string().trim().min(1).max(128).optional(),
-});
 /**
  * Signed-URL upload flow.
  *
  * Clients no longer post `.fig` bytes through the service (Cloud Run caps
  * request bodies at 32 MiB). Instead they call `upload/start` to get a
  * temporary signed resumable-upload URL per attachment, stream the bytes
- * directly to GCS, then call `/generate` with the returned upload tokens.
+ * directly to GCS, then call `/index` with the returned upload tokens.
  * See `tech-specs/signed-url-figma-upload`.
  */
 /** A single attachment the client declares when starting an upload. */
@@ -61,7 +35,7 @@ export const uploadStartBodySchema = z.object({
 });
 /**
  * Claims encoded inside a signed `uploadToken`. Bound to the GCS object at
- * `upload/start` and verified at `/generate`, so a client cannot point the
+ * `upload/start` and verified at `/index`, so a client cannot point the
  * decode worker at an object it did not upload.
  */
 export const uploadTokenPayloadSchema = z.object({
@@ -73,15 +47,93 @@ export const uploadTokenPayloadSchema = z.object({
     idx: z.number().int().nonnegative(),
     declaredSize: z.number().int().nonnegative().optional(),
 });
-/**
- * Request body for the signed-URL variant of `POST /design-systems/v1/generate`.
- * Same non-file fields as the legacy multipart form, plus the `uploads`
- * tokens returned by `upload/start` (one per attachment).
- */
-export const generateDesignSystemRequestSchema = z.object({
-    ...generateDesignSystemBodySchema.shape,
-    uploads: z
-        .array(z.string().min(1))
-        .min(GENERATE_DESIGN_SYSTEM_MIN_ATTACHMENTS)
+export const indexDesignSystemScopeSchema = z.enum([
+    "space",
+    "organization",
+    "global",
+]);
+export const fullLibrarySourceKindSchema = z.enum([
+    "connected-repo",
+    "public-repo",
+    "package",
+]);
+const connectedRepoSourceSchema = z.object({
+    kind: z.literal("connected-repo"),
+    fusionProjectId: z.string().min(1),
+    include: z.array(z.string()).optional(),
+    exclude: z.array(z.string()).optional(),
+    instructions: z.string().optional(),
+});
+const publicRepoSourceSchema = z.object({
+    kind: z.literal("public-repo"),
+    repoUrl: z.string().url(),
+    include: z.array(z.string()).optional(),
+    exclude: z.array(z.string()).optional(),
+    instructions: z.string().optional(),
+});
+const packageSourceSchema = z.object({
+    kind: z.literal("package"),
+    package: z.string().min(1),
+    registry: z.string().optional(),
+    token: z.string().optional(),
+    instructions: z.string().optional(),
+});
+export const fullLibrarySourceSchema = z.discriminatedUnion("kind", [
+    connectedRepoSourceSchema,
+    publicRepoSourceSchema,
+    packageSourceSchema,
+]);
+export const fileSourceSchema = z.object({
+    kind: z.literal("file"),
+    uploadToken: z.string().min(1).optional(),
+    uploadGcsPath: z.string().min(1).optional(),
+    /** Optional map of filename → page/frame GUIDs to restrict Figma indexing. */
+    selection: z.record(z.string(), z.array(z.string().min(1))).optional(),
+    instructions: z.string().optional(),
+});
+export const designSystemSourceSchema = z
+    .discriminatedUnion("kind", [
+    connectedRepoSourceSchema,
+    publicRepoSourceSchema,
+    packageSourceSchema,
+    fileSourceSchema,
+])
+    .refine((s) => s.kind !== "file" || !!s.uploadToken || !!s.uploadGcsPath, {
+    message: "File sources require either uploadToken or uploadGcsPath.",
+});
+export const resolvePackageOptionsSchema = z.object({
+    /** Package name, optionally with an embedded version ("@ionic/core@7.0.0"). */
+    package: z.string().min(1),
+    registry: z.string().optional(),
+    token: z.string().optional(),
+    specifier: z.string().optional(),
+});
+export const indexDesignSystemBodySchema = z.object({
+    designSystemName: z.string().optional(),
+    scope: indexDesignSystemScopeSchema.optional(),
+    sources: z
+        .array(designSystemSourceSchema)
+        .min(1)
         .max(GENERATE_DESIGN_SYSTEM_MAX_ATTACHMENTS),
 });
+export const sourceFileEntrySchema = z.object({
+    name: z.string(),
+    /** Repo-relative path (POSIX separators). */
+    path: z.string(),
+    type: z.enum(["dir", "file"]),
+});
+export const listSourceFilesQuerySchema = z.object({
+    projectId: z.string().min(1),
+    /** Directory to list, repo-relative. Empty/omitted → repo root. */
+    path: z.string().optional(),
+    /** Git ref (branch or sha). Omitted → the repo's default branch. */
+    ref: z.string().optional(),
+});
+export const listPublicSourceFilesQuerySchema = z.object({
+    /** Full repo URL (e.g. https://github.com/owner/repo). GitHub only. */
+    repoUrl: z.string().url(),
+    /** Directory to list, repo-relative. Empty/omitted → repo root. */
+    path: z.string().optional(),
+    /** Git ref (branch or sha). Omitted → the repo's default branch. */
+    ref: z.string().optional(),
+});

package/src/events.d.ts

@@ -1071,6 +1071,8 @@ export type FigmaDecodeJobV1 = FusionEventVariant<"figma.decode.job", {
      * file-local, so they must be scoped per attachment.
      */
     selection?: Record<string, string[]>;
+    /** Freeform notes to guide indexing, forwarded to the indexer agent. */
+    instructions?: string;
 }, {}, 1>;
 export declare const FigmaDecodeJobV1: {
     eventName: "figma.decode.job";
@@ -1157,6 +1159,8 @@ export interface FigmaFrameManifest {
     githubRepo?: FigmaGithubRepoSource;
     /** True if one or more frame chunk uploads failed; some frames may be missing. */
     partialFailure?: boolean;
+    /** Freeform notes from the caller to guide indexing. */
+    instructions?: string;
 }
 export type PrReviewRequestedV1 = FusionEventVariant<"pr.review.requested", {
     repoFullName: string;

package/src/projects.d.ts

@@ -229,6 +229,7 @@ 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 DSI_PLACEHOLDER_REPO = "BuilderIO/dsi-placeholder";
 export declare const AGENT_NATIVE_STARTER_REPO = "BuilderIO/builder-agent-native-starter";
 export declare const EXAMPLE_OR_STARTER_REPOS: string[];
 export declare const EXAMPLE_OR_STARTER_REPOS_URLS: string[];
@@ -378,7 +379,7 @@ export interface ProjectSkillUrl extends ProjectSkillBase {
 }
 export type ProjectSkill = ProjectSkillSource | ProjectSkillNpm | ProjectSkillGithub | ProjectSkillUrl;
 export type FusionExecutionEnvironment = "containerized" | "container-less" | "cloud" | "cloud-v2";
-export type AgentType = "setup-project" | "project-configuration" | "org-agent" | "code-review-orchestrator" | "design-system-indexer" | "builder-publish-integration";
+export type AgentType = "setup-project" | "project-configuration" | "org-agent" | "code-review-orchestrator" | "design-system-indexer" | "repo-indexer" | "builder-publish-integration";
 export interface PartialBranchData {
     name?: string;
     createdBy: string;
@@ -489,7 +490,7 @@ export interface OrgAgentConfig {
 }
 export type BranchType = "code-review" | "setup-project"
 /** Hidden branch the webapp creates when the user picks manual setup. */
- | "manual-setup" | "org-agent" | "snapshot-build" | "design-system-indexing" | "deploy" | "default";
+ | "manual-setup" | "org-agent" | "snapshot-build" | "design-system-indexing" | "repo-indexing" | "deploy" | "default";
 /** Category of work a branch represents, auto-assigned during prompt analysis. */
 export type BranchCategory = "feature" | "fix" | "research" | "other";
 export interface BranchSharedData {

package/src/projects.js

@@ -36,11 +36,13 @@ export const EXAMPLE_REPOS = [
 ];
 export const STARTER_REPO = "BuilderIO/fusion-starter";
 export const DSI_PREVIEW_REPO = "BuilderIO/dsi-starter";
+export const DSI_PLACEHOLDER_REPO = "BuilderIO/dsi-placeholder";
 export const AGENT_NATIVE_STARTER_REPO = "BuilderIO/builder-agent-native-starter";
 export const EXAMPLE_OR_STARTER_REPOS = [
     ...EXAMPLE_REPOS,
     STARTER_REPO,
     DSI_PREVIEW_REPO,
+    DSI_PLACEHOLDER_REPO,
     AGENT_NATIVE_STARTER_REPO,
 ];
 export const EXAMPLE_OR_STARTER_REPOS_URLS = EXAMPLE_OR_STARTER_REPOS.map((repo) => `https://github.com/${repo}`);

package/src/repo-indexing.d.ts

@@ -1,4 +1,6 @@
+import type { FullLibrarySourceInput } from "./design-systems.js";
 export type StoreComponentDocsInput = StoreComponentDocsInputV1 | StoreComponentDocsInputV2 | IndexDocumentV1;
+export type ComponentDocSource = "full" | "approximation";
 export interface ManualDocumentV1 {
     document: IndexDocumentV1;
     filePath: string;
@@ -46,6 +48,7 @@ export interface DocumentBase {
     designSystemVersion?: string;
     tokens?: number;
     sessionId?: string;
+    source?: ComponentDocSource;
 }
 export declare const isAgentDocument: (doc: IndexDocumentV1) => doc is AgentDocument;
 export declare const isIconDocument: (doc: IndexDocumentV1) => doc is IconDocument;
@@ -117,6 +120,13 @@ export interface UpdateDesignSystemInput {
     status?: "in-progress" | "completed" | "failed";
     source?: "auto" | "custom";
 }
+export type LastIndexInput = {
+    mode: "full-library";
+    sources: FullLibrarySourceInput[];
+} | {
+    mode: "designs-only";
+    uploadGcsPaths: string[];
+};
 export interface DesignSystem {
     id: string;
     spaceId: string;
@@ -137,6 +147,8 @@ export interface DesignSystem {
     source: "custom" | "auto";
     projectId?: string;
     branchName?: string;
+    lastIndexInput?: LastIndexInput;
+    lastIndexedAt?: string;
 }
 export interface DisplayDesignSystem extends DesignSystem {
     docCount: number;