@builder.io/ai-utils 0.83.0-dev.202607211718.99c5f9cf8 → 0.84.0-dev.202607212345.137e4170f

package/package.json

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

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.",
@@ -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;
@@ -1300,6 +1304,7 @@ export type HostingCustomDomainCertCheckV1 = FusionEventVariant<"hosting.custom-
     domain: string;
     projectId: string;
     certId: string;
+    attemptId: string;
     startedAtMs: number;
     timeoutMs: number;
 }, {

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;