@agent-native/core-corpus 0.214.0 → 0.216.0

package/corpus/templates/slides-2/actions/index-design-system-with-builder.ts

@@ -0,0 +1,181 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import {
+  assertBuilderDesignSystemCodeIndexingAllowed,
+  buildBuilderDesignSystemIndexFiles,
+  FeatureNotConfiguredError,
+  startBuilderDesignSystemIndex,
+} from "@agent-native/core/server";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { z } from "zod";
+
+import { upsertBuilderProxyDesignSystem } from "../server/lib/builder-design-system-proxy.js";
+import { assertDesignSystemWorkflowsEnabled } from "../server/lib/design-system-workflows.js";
+
+const codeFileSchema = z.object({
+  filename: z.string().trim().min(1).describe("File name or relative path"),
+  content: z
+    .string()
+    .describe(
+      "File content. Text files (code, CSS, markdown, JSON, SVG): raw text. " +
+        "Binary files -- most importantly `.fig` (a zip/kiwi binary container, " +
+        'never valid text) -- MUST be base64-encoded with encoding: "base64"; ' +
+        "sending raw/binary-as-string content with the default utf8 encoding " +
+        "corrupts the file before it reaches Builder.",
+    ),
+  mimeType: z.string().trim().optional().describe("Optional MIME type"),
+  encoding: z
+    .enum(["utf8", "base64"])
+    .optional()
+    .describe(
+      "Encoding of `content`. Defaults to utf8. Set to base64 for `.fig` and " +
+        "other binary files.",
+    ),
+});
+
+const githubSourceSchema = z.object({
+  repoUrl: z.string().trim().min(1).describe("GitHub repository URL"),
+  ref: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("Optional branch, tag, or commit"),
+  include: z
+    .array(z.string().trim().min(1))
+    .optional()
+    .describe("Optional repository-relative files or folders to include"),
+  exclude: z
+    .array(z.string().trim().min(1))
+    .optional()
+    .describe("Optional repository-relative files or folders to exclude"),
+  instructions: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("Optional indexing guidance for this repository"),
+});
+
+export default defineAction({
+  description:
+    "Start Builder DSI design-system indexing from connected code, a GitHub repository, code/design files, and optional design.md guidance. " +
+    "Use this instead of legacy local code import when the user wants a reusable brand kit or slide design system. " +
+    "Use Builder.io (free tier available) to index design systems; Builder owns the indexed design-system docs, generated guidance, token/component extraction, and job state.",
+  schema: z.object({
+    projectName: z
+      .string()
+      .optional()
+      .describe("Optional Builder project/design-system name"),
+    description: z
+      .string()
+      .optional()
+      .describe("Additional brand context or instructions for Builder"),
+    githubRepoUrl: z
+      .string()
+      .optional()
+      .describe("Legacy single GitHub repository URL to index with Builder"),
+    githubSources: z
+      .array(githubSourceSchema)
+      .min(1)
+      .max(20)
+      .optional()
+      .describe(
+        "GitHub repositories to index in one design system. Each source may specify a branch/tag/commit and repository-relative files or folders.",
+      ),
+    connectedProjectId: z
+      .string()
+      .optional()
+      .describe("Optional existing Builder project id to attach indexing to"),
+    codeFiles: z
+      .array(codeFileSchema)
+      .optional()
+      .describe("Optional inlined code/design files to upload to Builder"),
+    designMd: z
+      .string()
+      .optional()
+      .describe(
+        "Optional design.md guidance to upload to Builder DSI alongside Figma/code sources",
+      ),
+  }),
+  mcpAnnotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+  },
+  run: async ({
+    projectName,
+    description,
+    githubRepoUrl,
+    githubSources,
+    connectedProjectId,
+    codeFiles,
+    designMd,
+  }) => {
+    await assertDesignSystemWorkflowsEnabled();
+    if (githubRepoUrl || githubSources?.length || codeFiles?.length) {
+      await assertBuilderDesignSystemCodeIndexingAllowed();
+    }
+    const files = buildBuilderDesignSystemIndexFiles({
+      codeFiles,
+      designMd,
+    });
+    let result: Awaited<ReturnType<typeof startBuilderDesignSystemIndex>>;
+    try {
+      result = await startBuilderDesignSystemIndex({
+        projectName,
+        description,
+        githubRepoUrl,
+        githubRepos: githubSources,
+        connectedProjectId,
+        files,
+      });
+    } catch (error) {
+      if (error instanceof FeatureNotConfiguredError) {
+        fail(error.message, {
+          errorCode: "builder_not_configured",
+          statusCode: 412,
+          ...(error.builderConnectUrl
+            ? { details: { builderConnectUrl: error.builderConnectUrl } }
+            : {}),
+        });
+      }
+      throw error;
+    }
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) {
+      fail("no authenticated user", {
+        errorCode: "not_authenticated",
+        statusCode: 401,
+      });
+    }
+
+    const proxy = await upsertBuilderProxyDesignSystem({
+      result,
+      ownerEmail,
+      orgId: getRequestOrgId(),
+      projectName,
+      description,
+      githubSources:
+        githubSources ?? (githubRepoUrl ? [{ repoUrl: githubRepoUrl }] : []),
+      sourceKind:
+        (githubSources?.length || githubRepoUrl) &&
+        (codeFiles?.length || designMd)
+          ? "mixed"
+          : githubSources?.length || githubRepoUrl
+            ? "github"
+            : codeFiles?.length || designMd
+              ? "code"
+              : undefined,
+    });
+
+    return {
+      ...result,
+      ...proxy,
+      uploadedFileCount: files.length,
+      githubSourceCount: githubSources?.length ?? (githubRepoUrl ? 1 : 0),
+    };
+  },
+});

package/corpus/templates/slides-2/actions/index-uploaded-design-system-files.ts

@@ -0,0 +1,77 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import {
+  FeatureNotConfiguredError,
+  indexBuilderDesignSystem,
+} from "@agent-native/core/server";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { z } from "zod";
+
+import { upsertBuilderProxyDesignSystem } from "../server/lib/builder-design-system-proxy.js";
+import { assertDesignSystemWorkflowsEnabled } from "../server/lib/design-system-workflows.js";
+
+export default defineAction({
+  title: "Index uploaded design system files",
+  description:
+    "Finish Builder DSI indexing for files uploaded through the design-system upload flow. Pass the upload tokens returned for those files and an optional design-system name.",
+  schema: z.object({
+    projectName: z
+      .string()
+      .trim()
+      .optional()
+      .describe("Optional name for the design system being indexed"),
+    uploadTokens: z
+      .array(z.string().trim().min(1))
+      .min(1)
+      .describe("Upload tokens returned by the authenticated file-upload flow"),
+  }),
+  agentTool: false,
+  retrySafe: false,
+  run: async ({ projectName, uploadTokens }) => {
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) {
+      fail("Sign in before indexing uploaded design-system files.", {
+        errorCode: "unauthorized",
+        statusCode: 401,
+      });
+    }
+    await assertDesignSystemWorkflowsEnabled();
+
+    let result: Awaited<ReturnType<typeof indexBuilderDesignSystem>>;
+    try {
+      result = await indexBuilderDesignSystem({
+        sources: uploadTokens.map((uploadToken) => ({
+          kind: "file" as const,
+          uploadToken,
+        })),
+        projectName,
+      });
+    } catch (error) {
+      if (error instanceof FeatureNotConfiguredError) {
+        fail(error.message, {
+          errorCode: "builder_not_configured",
+          statusCode: 412,
+          ...(error.builderConnectUrl
+            ? { details: { builderConnectUrl: error.builderConnectUrl } }
+            : {}),
+        });
+      }
+      throw error;
+    }
+    const proxy = await upsertBuilderProxyDesignSystem({
+      result,
+      ownerEmail,
+      orgId: getRequestOrgId(),
+      projectName,
+      sourceKind: "figma",
+    });
+
+    return {
+      ...result,
+      ...proxy,
+      uploadedFileCount: uploadTokens.length,
+    };
+  },
+});

package/corpus/templates/slides-2/actions/list-assets.ts

@@ -0,0 +1,286 @@
+import { defineAction } from "@agent-native/core";
+import { fail } from "@agent-native/core/action";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { assertAccess } from "@agent-native/core/sharing";
+import { and, desc, eq, inArray, isNull, like, or } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { collectSlideAssetIds } from "../server/lib/slide-source.js";
+import { assertSlides2DeckData } from "./_deck-app-scope.js";
+import { readStoredSlideSource } from "./_slide-source.js";
+
+const assetListSchema = z
+  .preprocess(
+    (value) => (value === undefined ? {} : value),
+    z.object({
+      scope: z
+        .enum(["slide", "deck", "global"])
+        .default("global")
+        .describe(
+          'Asset collection: "slide" for assets referenced by one slide, "deck" for its full catalog, or "global"; defaults to "global"',
+        ),
+      media: z
+        .enum(["image", "video", "all"])
+        .default("image")
+        .describe(
+          'Media type: "image", supported "video" (MP4 or WebM), or "all"; defaults to "image" for existing image-library callers',
+        ),
+      deckId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          'Deck ID, required when scope is "slide" or "deck"; optional with "global" to limit results to assets that deck can resolve',
+        ),
+      slideId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Slide ID, required when scope is "slide"'),
+    }),
+  )
+  .superRefine(({ scope, deckId, slideId }, context) => {
+    if ((scope === "deck" || scope === "slide") && !deckId) {
+      context.addIssue({
+        code: "custom",
+        message: "Deck and slide scopes require deckId.",
+      });
+    }
+    if (scope === "slide" && !slideId) {
+      context.addIssue({
+        code: "custom",
+        message: "Slide scope requires slideId.",
+      });
+    }
+    if (scope !== "slide" && slideId !== undefined) {
+      context.addIssue({
+        code: "custom",
+        message: "Only slide scope accepts slideId.",
+      });
+    }
+  });
+
+function imageAssetWorkspaceScope(orgId: string | null | undefined) {
+  if (!orgId) return isNull(schema.uploadedAssets.orgId);
+  return eq(schema.uploadedAssets.orgId, orgId);
+}
+
+function assetScopeForDeck(ownerEmail: string, orgId: string | null) {
+  const ownerScope = and(
+    eq(schema.uploadedAssets.ownerEmail, ownerEmail),
+    orgId
+      ? eq(schema.uploadedAssets.orgId, orgId)
+      : isNull(schema.uploadedAssets.orgId),
+  );
+  return orgId
+    ? or(ownerScope, eq(schema.uploadedAssets.orgId, orgId))
+    : ownerScope;
+}
+
+function requireSlideId(slideId: string | undefined): string {
+  if (!slideId) {
+    fail("Slide scope requires slideId.", {
+      errorCode: "asset_deck_scope_invalid",
+      statusCode: 400,
+    });
+  }
+  return slideId;
+}
+
+export default defineAction({
+  title: "List uploaded media",
+  description:
+    "List uploaded images or supported MP4/WebM videos referenced by one accessible slide, from its full deck catalog, or from the global collection. Pass deckId with global scope when selecting for a deck to limit results to the current user's assets that deck can resolve. Global results without a deck are limited to the current workspace. Slide scope requires deckId and slideId. Defaults to images for existing image-library callers.",
+  schema: assetListSchema,
+  readOnly: true,
+  retrySafe: true,
+  http: { method: "GET" },
+  mcpAnnotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: false,
+  },
+  run: async ({ scope, media, deckId, slideId }) => {
+    const slideScope =
+      scope === "slide" ? { slideId: requireSlideId(slideId) } : null;
+    let db: ReturnType<typeof getDb>;
+    try {
+      db = getDb();
+    } catch {
+      fail("Could not load uploaded images.", {
+        errorCode: "asset_list_failed",
+        statusCode: 500,
+      });
+    }
+    const requestedMedia = media ?? "image";
+    const mediaFilter =
+      requestedMedia === "image"
+        ? like(schema.uploadedAssets.type, "image/%")
+        : requestedMedia === "video"
+          ? or(
+              eq(schema.uploadedAssets.type, "video/mp4"),
+              eq(schema.uploadedAssets.type, "video/webm"),
+            )
+          : or(
+              like(schema.uploadedAssets.type, "image/%"),
+              eq(schema.uploadedAssets.type, "video/mp4"),
+              eq(schema.uploadedAssets.type, "video/webm"),
+            );
+    const filters = [mediaFilter];
+
+    const deckScoped = scope === "deck" || scope === "slide" || Boolean(deckId);
+    if (deckScoped) {
+      if (!deckId) {
+        fail("Deck scope requires deckId.", {
+          errorCode: "asset_deck_scope_invalid",
+          statusCode: 400,
+        });
+      }
+      if (scope === "deck") {
+        filters.push(eq(schema.uploadedAssets.deckId, deckId));
+      } else if (scope === "global") {
+        const ownerEmail = getRequestUserEmail();
+        if (!ownerEmail) {
+          fail("Sign in to view uploaded images.", {
+            errorCode: "asset_list_auth_required",
+            statusCode: 401,
+          });
+        }
+        filters.push(isNull(schema.uploadedAssets.deckId));
+        filters.push(eq(schema.uploadedAssets.ownerEmail, ownerEmail));
+      }
+      try {
+        await assertAccess("deck", deckId, "editor");
+      } catch (error) {
+        if ((error as { statusCode?: unknown })?.statusCode === 403) {
+          fail("You don't have access to this presentation's images.", {
+            errorCode: "asset_deck_access_denied",
+            statusCode: 403,
+          });
+        }
+        if ((error as { statusCode?: unknown })?.statusCode === 404) {
+          fail("Deck not found.", {
+            errorCode: "deck_not_found",
+            statusCode: 404,
+          });
+        }
+        fail("Could not verify access to this presentation.", {
+          errorCode: "asset_list_failed",
+          statusCode: 500,
+        });
+      }
+      let deckRows: Array<{
+        data: string;
+        ownerEmail: string;
+        orgId: string | null;
+      }>;
+      try {
+        deckRows = await db
+          .select({
+            data: schema.decks.data,
+            ownerEmail: schema.decks.ownerEmail,
+            orgId: schema.decks.orgId,
+          })
+          .from(schema.decks)
+          .where(eq(schema.decks.id, deckId))
+          .limit(1);
+      } catch {
+        fail("Could not load uploaded images.", {
+          errorCode: "asset_list_failed",
+          statusCode: 500,
+        });
+      }
+      const [deckRow] = deckRows;
+      if (!deckRow) {
+        fail("Deck not found.", {
+          errorCode: "deck_not_found",
+          statusCode: 404,
+        });
+      }
+
+      let deck: unknown;
+      let slideSource: string | undefined;
+      if (slideScope) {
+        const snapshot = readStoredSlideSource(
+          deckRow.data,
+          slideScope.slideId,
+        );
+        deck = snapshot.data;
+        slideSource = snapshot.slide.sourceTsx;
+      } else {
+        try {
+          deck = JSON.parse(deckRow.data);
+        } catch {
+          fail("Deck data is invalid.", {
+            errorCode: "invalid_deck_data",
+            statusCode: 500,
+          });
+        }
+      }
+      assertSlides2DeckData(deck);
+      if (!deck || typeof deck !== "object" || Array.isArray(deck)) {
+        fail("Deck data is invalid.", {
+          errorCode: "invalid_deck_data",
+          statusCode: 500,
+        });
+      }
+      if (slideScope) {
+        if (typeof slideSource !== "string") {
+          fail("Could not load uploaded images.", {
+            errorCode: "asset_list_failed",
+            statusCode: 500,
+          });
+        }
+        let referencedAssetIds: string[];
+        try {
+          referencedAssetIds = collectSlideAssetIds(slideSource);
+        } catch {
+          fail("Could not load uploaded images.", {
+            errorCode: "asset_list_failed",
+            statusCode: 500,
+          });
+        }
+        if (referencedAssetIds.length === 0) return [];
+        filters.push(inArray(schema.uploadedAssets.id, referencedAssetIds));
+      }
+      filters.push(assetScopeForDeck(deckRow.ownerEmail, deckRow.orgId));
+    } else {
+      filters.push(isNull(schema.uploadedAssets.deckId));
+      const ownerEmail = getRequestUserEmail();
+      if (!ownerEmail) {
+        fail("Sign in to view uploaded images.", {
+          errorCode: "asset_list_auth_required",
+          statusCode: 401,
+        });
+      }
+      filters.push(
+        eq(schema.uploadedAssets.ownerEmail, ownerEmail),
+        imageAssetWorkspaceScope(getRequestOrgId()),
+      );
+    }
+
+    try {
+      return await db
+        .select({
+          id: schema.uploadedAssets.id,
+          url: schema.uploadedAssets.url,
+          filename: schema.uploadedAssets.filename,
+          type: schema.uploadedAssets.type,
+          size: schema.uploadedAssets.size,
+          createdAt: schema.uploadedAssets.createdAt,
+        })
+        .from(schema.uploadedAssets)
+        .where(and(...filters))
+        .orderBy(desc(schema.uploadedAssets.createdAt));
+    } catch {
+      fail("Could not load uploaded images.", {
+        errorCode: "asset_list_failed",
+        statusCode: 500,
+      });
+    }
+  },
+});

package/corpus/templates/slides-2/actions/list-deck-templates.ts

@@ -0,0 +1,83 @@
+import { defineAction } from "@agent-native/core/action";
+import { buildDeepLink } from "@agent-native/core/server";
+import { z } from "zod";
+
+import {
+  DECK_TEMPLATE_CATEGORIES,
+  listBuiltInDeckTemplateSummaries,
+} from "../server/lib/deck-templates.js";
+
+export default defineAction({
+  description:
+    "Browse built-in editable deck templates without a provider or generation. Search titles, descriptions, and categories; previews include only the first slide. Use get-deck-template to inspect all slides, then create-deck-from-template to copy one.",
+  schema: z.object({
+    search: z
+      .string()
+      .trim()
+      .max(200)
+      .optional()
+      .describe("Case-insensitive title, description, or category search"),
+    category: z
+      .enum(DECK_TEMPLATE_CATEGORIES)
+      .optional()
+      .describe(
+        "Limit to one starter category; omitted returns all categories",
+      ),
+    page: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(1000)
+      .default(1)
+      .describe("One-based page; defaults to 1"),
+    pageSize: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(24)
+      .default(6)
+      .describe("Results per page, 1–24; defaults to 6"),
+    includePreview: z
+      .enum(["true", "false"])
+      .default("false")
+      .describe("Include first-slide HTML when true; defaults to false"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  link: ({ args }) => ({
+    url: buildDeepLink({
+      app: "slides-2",
+      view: "templates",
+      params: { search: args.search?.trim() },
+    }),
+    label: "Browse templates in Slides 2",
+    view: "templates",
+  }),
+  run: async ({
+    search,
+    category,
+    page = 1,
+    pageSize = 6,
+    includePreview = "false",
+  }) => {
+    const query = search?.trim().toLowerCase();
+    const matches = listBuiltInDeckTemplateSummaries(
+      includePreview === "true",
+    ).filter(
+      (item) =>
+        (!category || item.category === category) &&
+        (!query ||
+          `${item.title} ${item.description} ${item.category}`
+            .toLowerCase()
+            .includes(query)),
+    );
+    const offset = (page - 1) * pageSize;
+    return {
+      templates: matches.slice(offset, offset + pageSize),
+      total: matches.length,
+      page,
+      pageSize,
+      hasMore: offset + pageSize < matches.length,
+    };
+  },
+});