@agent-native/core-corpus 0.214.0 → 0.216.0

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

@@ -0,0 +1,562 @@
+import { defineAction, embedApp, fail } from "@agent-native/core";
+import {
+  buildDeepLink,
+  currentRequestUserIsOrgAdmin,
+  getAppConfig,
+} from "@agent-native/core/server";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { loadAgentDesignSystemContext } from "@agent-native/core/shared";
+import {
+  accessFilter,
+  resolveAccess,
+  type ShareRole,
+} from "@agent-native/core/sharing";
+import { and, eq, isNull } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { notifyClients } from "../server/handlers/decks.js";
+import { formatSlideHtml } from "../server/lib/slide-content-patch.js";
+import {
+  sourceImportCoverage,
+  sourceImportForDeck,
+} from "../server/lib/source-import.js";
+import { summarizeSlideAnimationTargets } from "../server/lib/validate-slide-animations.js";
+import { isRealSlide, stripHtml } from "../shared/blank-slide.js";
+import { resolveDeckDesignSystemId } from "../shared/deck-content.js";
+import { normalizeOwnerEmail } from "../shared/ownership.js";
+import { summarizeDeckStyle } from "../shared/representative-slide.js";
+import { hashSlideContent } from "../shared/slide-fit.js";
+import {
+  ensureUniqueSlideIds,
+  repairDeckSlideReferences,
+} from "../shared/slide-ids.js";
+import { normalizeSlideTransition } from "../shared/slide-transitions.js";
+import { getDeckUrl } from "./_app-url.js";
+import { assertSlides2DeckData } from "./_deck-app-scope.js";
+import {
+  canReadPresenterNotes,
+  redactPresenterNotes,
+} from "./_presenter-notes.js";
+import getDesignSystem from "./get-design-system.js";
+import { withDeckLock } from "./patch-deck.js";
+
+const MAX_REPAIR_ATTEMPTS = 3;
+
+async function readDeck(
+  deckId: string,
+  reviewPreview = false,
+  reviewOrgId?: string,
+) {
+  let row;
+  let accessRole: "owner" | ShareRole;
+  if (reviewPreview) {
+    const orgId = getRequestOrgId();
+    if (!orgId || !(await currentRequestUserIsOrgAdmin(orgId))) {
+      fail("Only organization owners and admins can preview reviewed decks.", {
+        statusCode: 403,
+      });
+    }
+    const isSuperOrg = getAppConfig().observability.superOrgId === orgId;
+    const targetOrgId = isSuperOrg ? reviewOrgId : orgId;
+    if (!targetOrgId) {
+      fail("A customer organization is required for this deck preview.", {
+        statusCode: 400,
+      });
+    }
+    const [scope] = await getDb()
+      .select({
+        ownerEmail: schema.decks.ownerEmail,
+        orgId: schema.decks.orgId,
+      })
+      .from(schema.decks)
+      .where(
+        and(eq(schema.decks.id, deckId), eq(schema.decks.orgId, targetOrgId)),
+      )
+      .limit(1);
+    if (!scope) fail("Deck not found.", { statusCode: 404 });
+    const access = await resolveAccess("deck", deckId, {
+      userEmail: scope.ownerEmail,
+      orgId: targetOrgId,
+    });
+    if (!access || access.resource.orgId !== targetOrgId) {
+      fail("Deck not found.", { statusCode: 404 });
+    }
+    row = access.resource;
+    accessRole = access.role;
+  } else {
+    const access = await resolveAccess("deck", deckId);
+    if (!access) {
+      throw Object.assign(new Error("Deck not found"), { statusCode: 404 });
+    }
+    row = access.resource;
+    accessRole = access.role;
+  }
+  const data = JSON.parse(row.data);
+  assertSlides2DeckData(data);
+  const normalized = ensureUniqueSlideIds(
+    Array.isArray(data?.slides) ? data.slides : [],
+  );
+  return { row, data, accessRole, ...normalized };
+}
+
+function canPersistSlideIdRepair(accessRole: "owner" | ShareRole): boolean {
+  return (
+    accessRole === "owner" || accessRole === "admin" || accessRole === "editor"
+  );
+}
+
+function normalizeDeckReadInMemory(
+  snapshot: Awaited<ReturnType<typeof readDeck>>,
+) {
+  return {
+    ...snapshot,
+    data: snapshot.changed
+      ? repairDeckSlideReferences(
+          snapshot.data,
+          snapshot.slides,
+          snapshot.originalIds,
+        )
+      : snapshot.data,
+    repaired: false,
+  };
+}
+
+async function loadDeckWithUniqueSlideIds(
+  deckId: string,
+  reviewPreview = false,
+  reviewOrgId?: string,
+) {
+  if (reviewPreview) {
+    return normalizeDeckReadInMemory(await readDeck(deckId, true, reviewOrgId));
+  }
+
+  for (let attempt = 0; attempt < MAX_REPAIR_ATTEMPTS; attempt += 1) {
+    const snapshot = await readDeck(deckId);
+    if (!snapshot.changed) return { ...snapshot, repaired: false };
+    if (!canPersistSlideIdRepair(snapshot.accessRole)) {
+      return normalizeDeckReadInMemory(snapshot);
+    }
+
+    const repaired = await withDeckLock(deckId, async () => {
+      const lockedSnapshot = await readDeck(deckId);
+      if (!lockedSnapshot.changed) {
+        return { ...lockedSnapshot, repaired: false };
+      }
+      if (!canPersistSlideIdRepair(lockedSnapshot.accessRole)) {
+        return normalizeDeckReadInMemory(lockedSnapshot);
+      }
+
+      const repairedData = {
+        ...repairDeckSlideReferences(
+          lockedSnapshot.data,
+          lockedSnapshot.slides,
+          lockedSnapshot.originalIds,
+        ),
+        updatedAt: new Date().toISOString(),
+      };
+      const versionCondition =
+        typeof lockedSnapshot.row.updatedAt !== "string"
+          ? isNull(schema.decks.updatedAt)
+          : eq(schema.decks.updatedAt, lockedSnapshot.row.updatedAt);
+      await getDb()
+        .update(schema.decks)
+        .set({
+          data: JSON.stringify(repairedData),
+          updatedAt: repairedData.updatedAt,
+        })
+        .where(
+          and(
+            eq(schema.decks.id, lockedSnapshot.row.id),
+            versionCondition,
+            eq(schema.decks.data, lockedSnapshot.row.data),
+            accessFilter(schema.decks, schema.deckShares, undefined, "editor"),
+          ),
+        );
+
+      const confirmed = await readDeck(deckId);
+      return confirmed.changed ? null : { ...confirmed, repaired: true };
+    });
+
+    if (repaired) {
+      if (repaired.repaired) await notifyClients(deckId);
+      return repaired;
+    }
+  }
+
+  fail(`Could not repair duplicate slide IDs for deck ${deckId}.`, {
+    errorCode: "slide_id_repair_conflict",
+    statusCode: 409,
+  });
+}
+
+// Rows can hold legacy transition strings (slide, zoom, instant) and slides
+// saved before transitionSpeed existed. Unset transition reads as null.
+function canonicalReadSlide(slide: {
+  id?: unknown;
+  transition?: unknown;
+  transitionSpeed?: unknown;
+}) {
+  return {
+    ...slide,
+    transition:
+      slide.transition === undefined || slide.transition === null
+        ? null
+        : normalizeSlideTransition(slide.transition),
+    transitionSpeed: slide.transitionSpeed ?? null,
+  };
+}
+
+function compactAnimationSummary(value: unknown, content: string) {
+  if (!Array.isArray(value)) return null;
+  const targetSummaries = summarizeSlideAnimationTargets(content, value);
+  return {
+    count: value.length,
+    steps: value.map((entry, index) => {
+      if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return { order: index + 1, valid: false };
+      }
+      const animation = entry as Record<string, unknown>;
+      const targetSummary = targetSummaries[index];
+      return {
+        order: index + 1,
+        id: typeof animation.id === "string" ? animation.id : null,
+        elementIndex:
+          typeof animation.elementIndex === "number"
+            ? animation.elementIndex
+            : null,
+        elementPath: Array.isArray(animation.elementPath)
+          ? animation.elementPath
+          : null,
+        byParagraph:
+          typeof animation.byParagraph === "boolean"
+            ? animation.byParagraph
+            : false,
+        trigger:
+          animation.trigger === "with-previous" ? "with-previous" : "on-click",
+        type: typeof animation.type === "string" ? animation.type : null,
+        targetPreview: targetSummary?.targetPreview ?? null,
+        resolvedPath: targetSummary?.resolvedPath ?? null,
+        targetValid: targetSummary?.targetValid ?? false,
+        targetIssue: targetSummary
+          ? targetSummary.targetIssue
+          : "target-not-found",
+      };
+    }),
+  };
+}
+
+function deckDeepLink(deckId: string): string {
+  return buildDeepLink({
+    app: "slides-2",
+    view: "editor",
+    params: { deckId },
+  });
+}
+
+export default defineAction({
+  title: "Read Slides deck",
+  description:
+    "Read a Slides deck or selected slides. Pass the deck ID as `id` or `deckId` (either name works); pass `slideId` for one targeted read or `slideIds` with compact=false for one full read of several slides, including each slide's HTML and contentHash. Compact summaries include every slide in order and `isBlank` marks slides with no text or visible media; a blank slide still occupies its numbered position and is not missing. The result includes linked `designSystem.agentContext` when the deck has a readable design system; treat it as authoritative before authoring or restyling. For focused edits on legacy/imported HTML slides, use an exact selectedText range or stable objectId with update-slide and the matching content hash. For source-backed React slides, do not route selected text or objectId through update-slide: call get-slide-source, then update-slide-source with a unique locator grounded in the current source; if the selection cannot be mapped uniquely, ask the user to reselect or clarify. An edit that changes HTML markup or layout needs a targeted read before HTML mutation. Use compact=true for a lightweight targeted check, or compact=false and format=true when markup or layout requires source inspection. Source imports expose provenance and sourceCoverage for verification; structural edits remain supported and clear source-import metadata. When sourceCoverage is present, do not claim completion until sourceCoverage.complete is true and its expectedSlideIds and actualSlideIds match in order. User-visible slide numbers are 1-based and match the UI. Use slideId for edits. Returns deckStyle (backgrounds, text and accent colors, fonts, heading sizes across slides, with deviating slides named) and representativeSlideId; before a structural or layout change, read that slide with slideId and compact='false' and mirror its structure and values.",
+  timeoutMs: 60_000,
+  schema: z
+    .object({
+      id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "Deck ID. `deckId` is accepted as an alias; pass either one.",
+        ),
+      deckId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "Deck ID. Alias of `id`, matching create-deck / add-slide / update-slide / patch-deck.",
+        ),
+      slideId: z
+        .string()
+        .optional()
+        .describe(
+          "Optional stable slide ID. When set, return only that slide for a targeted read.",
+        ),
+      slideIds: z
+        .array(z.string().min(1))
+        .min(1)
+        .optional()
+        .describe(
+          "Optional ordered stable slide IDs. With compact=false, return the full source for only these slides in one read.",
+        ),
+      compact: z
+        .enum(["true", "false"])
+        .optional()
+        .describe(
+          "Set to 'true' for compact slide summaries, or 'false' for full slide HTML. In-app agent calls without slideId or slideIds default to compact output.",
+        ),
+      format: z
+        .enum(["true", "false"])
+        .optional()
+        .describe(
+          "Set to 'true' to return full slide HTML formatted with Prettier for code-style patches. The contentHash still identifies the persisted source.",
+        ),
+      reviewPreview: z
+        .boolean()
+        .optional()
+        .describe(
+          "Human Review only: read a saved deck for an organization owner/admin. Cross-organization reads are limited to the single organization configured as this app's observability super organization.",
+        ),
+      reviewOrgId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("The customer organization shown in this Human Review row."),
+    })
+    .superRefine((args, context) => {
+      if (args.slideId !== undefined && args.slideIds !== undefined) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["slideIds"],
+          message: "Pass slideId or slideIds, not both",
+        });
+      }
+      if (
+        args.slideIds &&
+        new Set(args.slideIds).size !== args.slideIds.length
+      ) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["slideIds"],
+          message: "slideIds must not contain duplicates",
+        });
+      }
+    }),
+  readOnly: false, // GET repairs duplicate slide IDs.
+  // The only write is that repair, and a replay finds no duplicates left to fix.
+  retrySafe: true,
+  http: { method: "GET" },
+  mcpApp: {
+    compactCatalog: true,
+    resource: embedApp({
+      title: "Deck preview",
+      description: "Open the deck in the Slides 2 editor.",
+      iframeTitle: "Agent-Native Slides 2",
+      openLabel: "Open deck",
+      height: 680,
+    }),
+  },
+  mcpAnnotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: false,
+  },
+  run: async (args, ctx) => {
+    const isWidgetCaller =
+      ctx?.caller === "mcp-widget" || ctx?.caller === "mcp-widget-write";
+    const deckId = args.deckId ?? args.id;
+    if (!deckId) {
+      fail("Pass the deck id as `id` or `deckId`.", {
+        errorCode: "deck_id_missing",
+        statusCode: 400,
+      });
+    }
+    const {
+      row,
+      data,
+      slides: storedSlides,
+      accessRole,
+    } = ctx?.caller === "mcp-widget"
+      ? normalizeDeckReadInMemory(await readDeck(deckId))
+      : await loadDeckWithUniqueSlideIds(
+          deckId,
+          args.reviewPreview,
+          args.reviewOrgId,
+        );
+    // Both the compact and full branches read these; normalize once, here.
+    const slides = storedSlides.map(canonicalReadSlide);
+    const ownerEmail = getRequestUserEmail();
+    const normalizedOwnerEmail = normalizeOwnerEmail(ownerEmail);
+    const selectedSlideIndex =
+      args.slideId === undefined
+        ? -1
+        : slides.findIndex((slide: any) => slide?.id === args.slideId);
+
+    if (args.slideId !== undefined && selectedSlideIndex < 0) {
+      throw Object.assign(new Error(`Slide not found: ${args.slideId}`), {
+        statusCode: 404,
+      });
+    }
+
+    const selectedSlide =
+      selectedSlideIndex >= 0 ? slides[selectedSlideIndex] : null;
+    const slideIndexesById = new Map(
+      slides.map((slide: any, index: number) => [slide?.id, index] as const),
+    );
+    const selectedSlideIndices = (args.slideIds ?? []).map((slideId) => {
+      const index = slideIndexesById.get(slideId);
+      if (index === undefined) {
+        throw Object.assign(new Error(`Slide not found: ${slideId}`), {
+          statusCode: 404,
+        });
+      }
+      return index;
+    });
+    const slideEntries: Array<{ slide: any; index: number }> =
+      selectedSlideIndex >= 0
+        ? [{ slide: selectedSlide, index: selectedSlideIndex }]
+        : selectedSlideIndices.length > 0
+          ? selectedSlideIndices.map((index) => ({
+              slide: slides[index],
+              index,
+            }))
+          : slides.map((slide: any, index: number) => ({ slide, index }));
+
+    const compact =
+      args.compact === "true" ||
+      (args.compact === undefined &&
+        ctx?.caller === "tool" &&
+        selectedSlideIndex < 0 &&
+        selectedSlideIndices.length === 0);
+    const sourceImport = sourceImportForDeck(data?.sourceImport);
+    const sourceCoverage = sourceImportCoverage(
+      sourceImport,
+      slides.map((slide: any) => slide.id),
+    );
+    const linkedDesignSystemId = resolveDeckDesignSystemId(row, data);
+    const designSystemReader =
+      ctx?.caller === "mcp-widget"
+        ? {
+            run: (args: { id: string; compact?: "true" | "false" }) =>
+              getDesignSystem.run(args, ctx),
+          }
+        : getDesignSystem;
+    const designSystem = await loadAgentDesignSystemContext(
+      linkedDesignSystemId,
+      designSystemReader,
+    );
+    const { deckStyle, representativeSlideId } = summarizeDeckStyle(
+      slides as any,
+      selectedSlideIndex,
+    );
+
+    if (compact) {
+      return {
+        id: row.id,
+        title: row.title || data?.title,
+        visibility: row.visibility,
+        ...(isWidgetCaller ? { widgetAccessRole: accessRole } : {}),
+        designSystemId: linkedDesignSystemId,
+        designSystem,
+        ...(slides.length > 0 ? { deckStyle, representativeSlideId } : {}),
+        generationContext: data?.generationContext ?? null,
+        sourceImport: data?.sourceImport
+          ? {
+              mode: data.sourceImport.mode,
+              format: data.sourceImport.format,
+              fidelity: data.sourceImport.fidelity,
+              slideCount: data.sourceImport.slideCount,
+              slideIds: data.sourceImport.slideIds,
+              ...(typeof data.sourceImport.imagesSkipped === "number"
+                ? { imagesSkipped: data.sourceImport.imagesSkipped }
+                : {}),
+            }
+          : null,
+        sourceCoverage,
+        slideCount: slides.length,
+        appUrl: getDeckUrl(row.id),
+        slideNumbering:
+          'User-visible slide numbers are 1-based and match the UI. "Slide 1" means slideNumber 1 / zeroBasedIndex 0. Use slideId for edits.',
+        deepLink: deckDeepLink(row.id),
+        ...(selectedSlide ? { selectedSlideId: selectedSlide.id } : {}),
+        ...(args.slideIds ? { selectedSlideIds: args.slideIds } : {}),
+        slides: slideEntries.map(({ slide: s, index: i }) => ({
+          slideNumber: i + 1,
+          zeroBasedIndex: i,
+          id: s.id,
+          layout: s.layout ?? null,
+          transition: s.transition,
+          transitionSpeed: s.transitionSpeed,
+          isBlank: !isRealSlide(s),
+          animations: compactAnimationSummary(
+            s.animations,
+            typeof s.content === "string" ? s.content : "",
+          ),
+          textPreview: stripHtml(s.content || "").slice(0, 120),
+        })),
+      };
+    }
+
+    const deckMetadata = { ...data };
+    delete deckMetadata.slides;
+
+    const formatHtml = args.format === "true";
+    const canReadNotes = canReadPresenterNotes(accessRole);
+    const fullSlides = await Promise.all(
+      slideEntries.map(async ({ slide: s, index: i }) => {
+        const slideWithoutNotes = redactPresenterNotes(s) as Record<
+          string,
+          unknown
+        >;
+        return {
+          ...(canReadNotes ? s : slideWithoutNotes),
+          slideNumber: i + 1,
+          zeroBasedIndex: i,
+          id: s.id,
+          layout: s.layout ?? null,
+          content: formatHtml
+            ? await formatSlideHtml(String(s.content ?? ""))
+            : s.content,
+          contentHash: hashSlideContent(String(s.content ?? "")),
+          ...(canReadNotes ? { notes: s.notes ?? null } : {}),
+        };
+      }),
+    );
+
+    return {
+      ...deckMetadata,
+      id: row.id,
+      title: row.title || data?.title,
+      visibility: row.visibility,
+      createdByMe:
+        normalizedOwnerEmail !== null &&
+        normalizeOwnerEmail(row.ownerEmail) === normalizedOwnerEmail,
+      ...(isWidgetCaller ? { widgetAccessRole: accessRole } : {}),
+      designSystemId: linkedDesignSystemId,
+      designSystem,
+      ...(slides.length > 0 ? { deckStyle, representativeSlideId } : {}),
+      sourceCoverage,
+      slideCount: slides.length,
+      appUrl: getDeckUrl(row.id),
+      slideNumbering:
+        'User-visible slide numbers are 1-based and match the UI. "Slide 1" means slideNumber 1 / zeroBasedIndex 0. Use slideId for edits.',
+      createdAt:
+        typeof data.createdAt === "string" ? data.createdAt : row.createdAt,
+      updatedAt: row.updatedAt,
+      deepLink: deckDeepLink(row.id),
+      ...(selectedSlide ? { selectedSlideId: selectedSlide.id } : {}),
+      ...(args.slideIds ? { selectedSlideIds: args.slideIds } : {}),
+      slides: fullSlides,
+    };
+  },
+  link: ({ result, args }) => {
+    const argId =
+      typeof args.deckId === "string"
+        ? args.deckId
+        : typeof args.id === "string"
+          ? args.id
+          : undefined;
+    const id =
+      result && typeof result === "object"
+        ? (result as { id?: string }).id
+        : argId;
+    if (!id) return null;
+    return {
+      url: deckDeepLink(id),
+      label: "Open deck in Slides 2",
+      view: "editor",
+    };
+  },
+});

package/corpus/templates/slides-2/actions/get-design-system-decode-job-status.ts

@@ -0,0 +1,57 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import {
+  FeatureNotConfiguredError,
+  fetchBuilderDesignSystemDecodeJobStatus,
+  parseBuilderDesignSystemProxyReference,
+} from "@agent-native/core/server";
+import { assertAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+export default defineAction({
+  title: "Get design-system decode status",
+  description:
+    "Read Builder decode-job progress for a design system the current user can view.",
+  schema: z.object({
+    designSystemId: z
+      .string()
+      .min(1)
+      .describe("Local design-system id returned by Builder indexing"),
+  }),
+  readOnly: true,
+  retrySafe: true,
+  http: { method: "GET" },
+  agentTool: false,
+  run: async ({ designSystemId }) => {
+    const access = await assertAccess(
+      "design-system",
+      designSystemId,
+      "viewer",
+    );
+    const reference = parseBuilderDesignSystemProxyReference(
+      access.resource.data,
+    );
+    if (!reference) {
+      fail("This design system is not backed by Builder indexing.", {
+        errorCode: "not_builder_design_system",
+        statusCode: 404,
+      });
+    }
+
+    try {
+      return await fetchBuilderDesignSystemDecodeJobStatus(
+        reference.builderJobId,
+      );
+    } catch (error) {
+      if (error instanceof FeatureNotConfiguredError) {
+        fail(error.message, {
+          errorCode: "builder_not_configured",
+          statusCode: 412,
+          ...(error.builderConnectUrl
+            ? { details: { builderConnectUrl: error.builderConnectUrl } }
+            : {}),
+        });
+      }
+      throw error;
+    }
+  },
+});

package/corpus/templates/slides-2/actions/get-design-system-tier-limit.ts

@@ -0,0 +1,12 @@
+import { defineAction } from "@agent-native/core/action";
+import { fetchBuilderDesignSystemTierLimit } from "@agent-native/core/server";
+import { z } from "zod";
+
+export default defineAction({
+  description:
+    "Read the DSI plan/tier limit (current design-system count vs. the plan max, and whether code/GitHub indexing is allowed). Use before offering to create a design system, so a user already at their plan's cap sees the limit and an upgrade link instead of a generic failure after they try.",
+  schema: z.object({}),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async () => fetchBuilderDesignSystemTierLimit(),
+});