@agent-native/core-corpus 0.214.0 → 0.217.0

package/corpus/templates/slides-2/actions/restore-deck-version.ts

@@ -0,0 +1,203 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import { writeAppState } from "@agent-native/core/application-state";
+import { assertAccess, ForbiddenError } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { notifyClients } from "../server/handlers/decks.js";
+import {
+  createDeckVersionSnapshot,
+  deckVersionChangeGroupFromAction,
+  deckVersionChatContextFromAction,
+  deckVersionContentSignature,
+} from "../server/lib/deck-versions.js";
+import { lockSlideAssetReferences } from "../server/lib/slide-asset-references.js";
+import { getDeckUrl } from "./_app-url.js";
+import { assertSlides2DeckData } from "./_deck-app-scope.js";
+import {
+  assertDeckWriteApplied,
+  deckRevisionWhere,
+  nextDeckRevision,
+} from "./_deck-write.js";
+import { assertDeckInlineImagesPersistable } from "./_render-artifacts.js";
+import { isAgentPatchCaller } from "./patch-deck.js";
+
+export default defineAction({
+  description:
+    "Restore a deck to a saved history snapshot. The current deck is snapshotted first, so restore is reversible.",
+  schema: z.object({
+    deckId: z.string().describe("Deck ID"),
+    versionId: z.string().describe("Version snapshot ID to restore"),
+  }),
+  http: { method: "POST" },
+  mcpAnnotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: false,
+    idempotentHint: false,
+  },
+  retrySafe: false,
+  run: async ({ deckId, versionId }, ctx) => {
+    let access;
+    try {
+      access = await assertAccess("deck", deckId, "editor");
+    } catch (error) {
+      if (error instanceof ForbiddenError) {
+        fail("Deck not found.", {
+          errorCode: "deck_not_found",
+          statusCode: 404,
+        });
+      }
+      throw error;
+    }
+    const current = access.resource;
+    const ownerEmail = current.ownerEmail as string;
+    assertSlides2DeckData(current.data);
+    const db = getDb();
+
+    const [version] = await db
+      .select()
+      .from(schema.deckVersions)
+      .where(
+        and(
+          eq(schema.deckVersions.id, versionId),
+          eq(schema.deckVersions.deckId, deckId),
+          eq(schema.deckVersions.ownerEmail, ownerEmail),
+        ),
+      )
+      .limit(1);
+
+    if (!version) {
+      fail("Saved deck version not found.", {
+        errorCode: "deck_version_not_found",
+        statusCode: 404,
+      });
+    }
+
+    assertSlides2DeckData(version.data);
+    const data = JSON.parse(version.data);
+    const now = nextDeckRevision(current.updatedAt);
+    const title = version.title || data?.title || current.title || "Untitled";
+    data.title = title;
+
+    const designSystemId =
+      typeof data.designSystemId === "string" && data.designSystemId
+        ? data.designSystemId
+        : null;
+    if (
+      current.title === title &&
+      current.designSystemId === designSystemId &&
+      deckVersionContentSignature(current.data) ===
+        deckVersionContentSignature(data)
+    ) {
+      if (isAgentPatchCaller(ctx?.caller)) {
+        fail(
+          "Nothing was written: the selected deck version already matches the current deck. Re-read with get-deck before retrying.",
+          {
+            errorCode: "deck_version_already_current",
+            statusCode: 409,
+          },
+        );
+      }
+      return {
+        id: deckId,
+        title,
+        slideCount: Array.isArray(data?.slides) ? data.slides.length : 0,
+        restoredVersionId: versionId,
+        updatedAt: current.updatedAt,
+        url: getDeckUrl(deckId),
+        applied: false,
+      };
+    }
+
+    assertDeckInlineImagesPersistable(null, data);
+    data.updatedAt = now;
+
+    const persisted = await db.transaction(async (tx: any) => {
+      await lockSlideAssetReferences(
+        tx,
+        data,
+        {
+          ownerEmail,
+          orgId: current.orgId,
+        },
+        current.id,
+      );
+      await createDeckVersionSnapshot(
+        {
+          id: current.id,
+          title: current.title,
+          data: current.data,
+          ownerEmail,
+        },
+        {
+          force: true,
+          chatContext: deckVersionChatContextFromAction(ctx),
+          label: "Before restore",
+          db: tx,
+        },
+      );
+      const updateResult = await tx
+        .update(schema.decks)
+        .set({
+          title,
+          data: JSON.stringify(data),
+          designSystemId,
+          updatedAt: now,
+        })
+        .where(deckRevisionWhere(schema.decks, deckId, current.updatedAt));
+      assertDeckWriteApplied(updateResult, deckId, "deck restore");
+
+      const [restored] = await tx
+        .select({
+          id: schema.decks.id,
+          title: schema.decks.title,
+          data: schema.decks.data,
+          designSystemId: schema.decks.designSystemId,
+          updatedAt: schema.decks.updatedAt,
+        })
+        .from(schema.decks)
+        .where(eq(schema.decks.id, deckId))
+        .limit(1);
+      if (
+        !restored ||
+        restored.id !== deckId ||
+        restored.title !== title ||
+        restored.data !== JSON.stringify(data) ||
+        (restored.designSystemId ?? null) !== designSystemId ||
+        restored.updatedAt !== now
+      ) {
+        fail("The restored deck could not be confirmed after writing.", {
+          errorCode: "deck_restore_readback_failed",
+          statusCode: 503,
+        });
+      }
+      return restored;
+    });
+
+    const agentChangeId = deckVersionChangeGroupFromAction(ctx);
+    if (agentChangeId) {
+      await notifyClients(deckId, { agentChangeId });
+    } else {
+      await notifyClients(deckId);
+    }
+    await writeAppState("refresh-signal", {
+      ts: now,
+      source: "restore-deck-version",
+    });
+
+    const persistedData = JSON.parse(persisted.data);
+    return {
+      id: persisted.id,
+      title: persisted.title,
+      slideCount: Array.isArray(persistedData?.slides)
+        ? persistedData.slides.length
+        : 0,
+      restoredVersionId: versionId,
+      updatedAt: persisted.updatedAt,
+      url: getDeckUrl(deckId),
+      appUrl: getDeckUrl(deckId),
+    };
+  },
+});

package/corpus/templates/slides-2/actions/run.ts

@@ -0,0 +1,2 @@
+import { runScript } from "@agent-native/core/scripts";
+void runScript();

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

@@ -0,0 +1,313 @@
+import { defineAction } from "@agent-native/core/action";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { resolveAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import { notifyClients } from "../server/handlers/decks.js";
+import {
+  createDeckVersionSnapshot,
+  deckVersionContentSignature,
+} from "../server/lib/deck-versions.js";
+import {
+  lockSlideAssetReferences,
+  withSlideAssetReferencesLocked,
+} from "../server/lib/slide-asset-references.js";
+import {
+  assertHumanReadableDeckTitle,
+  repairGeneratedDeckTitle,
+} from "../shared/deck-title.js";
+import {
+  createLayoutFitRevision,
+  deckFitRenderFieldsChanged,
+  slideFitRenderFieldsChanged,
+} from "../shared/slide-fit.js";
+import {
+  ensureUniqueSlideIds,
+  repairDeckSlideReferences,
+} from "../shared/slide-ids.js";
+import { getDeckUrl } from "./_app-url.js";
+import {
+  assertSlides2CreatePayload,
+  assertSlides2DeckData,
+} from "./_deck-app-scope.js";
+import {
+  trackDeckCreationStarted,
+  trackSlideContentEdited,
+} from "./_deck-tracking.js";
+import {
+  assertDesignSystemReadable,
+  assertValidAspectRatio,
+  assertDeckWriteApplied,
+  assertDeckClientWriteCurrent,
+  deckClientWriteFields,
+  deckClientWriteSchema,
+  deckDesignSystemId,
+  deckHttpError,
+  deckTitle,
+  deckRevisionWhere,
+  nextDeckRevision,
+  type DeckPayload,
+} from "./_deck-write.js";
+import { assertNoDeckRenderArtifacts } from "./_render-artifacts.js";
+import { assertSourceBackedSlidesUnchanged } from "./_slide-source.js";
+import { withDeckLock } from "./patch-deck.js";
+
+function shouldSnapshotDeckWrite(
+  current: { title?: string | null; data?: string | null },
+  nextTitle: string,
+  nextDeck: DeckPayload,
+): boolean {
+  return (
+    (current.title ?? "Untitled") !== nextTitle ||
+    deckVersionContentSignature(current.data ?? "") !==
+      deckVersionContentSignature(nextDeck)
+  );
+}
+
+export default defineAction({
+  description:
+    "Create or replace a deck's full JSON payload (title, slides, deck-level fields).",
+  schema: z.object({
+    deckId: z.string().min(1).describe("Deck ID"),
+    deck: z.record(z.string(), z.unknown()).describe("Full deck JSON payload"),
+    clientWrite: deckClientWriteSchema.optional(),
+  }),
+  http: { method: "PUT" },
+  agentTool: false,
+  run: async ({ deckId, deck: inputDeck, clientWrite }, ctx) =>
+    withDeckLock(deckId, async () => {
+      const deck = inputDeck as DeckPayload;
+      assertSlides2CreatePayload(deck);
+      if (Array.isArray(deck.slides)) {
+        const normalized = ensureUniqueSlideIds(
+          deck.slides as Array<{ id?: unknown }>,
+        );
+        deck.slides = normalized.slides;
+        if (normalized.changed) {
+          Object.assign(
+            deck,
+            repairDeckSlideReferences(
+              deck,
+              normalized.slides,
+              normalized.originalIds,
+            ),
+          );
+        }
+      }
+      assertValidAspectRatio(deck);
+
+      const db = getDb();
+      const now = new Date().toISOString();
+
+      deck.id = deckId;
+      deck.updatedAt = now;
+      const requestedTitle = deckTitle(deck);
+
+      const access = await resolveAccess("deck", deckId);
+      if (access) {
+        assertSlides2DeckData(access.resource.data);
+        const writeDisposition = assertDeckClientWriteCurrent(
+          access.resource,
+          deckId,
+          clientWrite,
+        );
+        if (writeDisposition === "already-applied") {
+          return {
+            ...(JSON.parse(access.resource.data) as DeckPayload),
+            updatedAt: access.resource.updatedAt,
+            appUrl: getDeckUrl(deckId),
+          };
+        }
+      }
+      const previous = stampChangedSlideRevisions(access?.resource.data, deck);
+      assertSourceBackedSlidesUnchanged(access?.resource.data, deck);
+
+      if (!access) {
+        const ownerEmail = getRequestUserEmail();
+        if (!ownerEmail) {
+          throw deckHttpError(403, "Sign in to create a deck");
+        }
+        const title =
+          repairGeneratedDeckTitle(requestedTitle, firstSlideContent(deck)) ??
+          requestedTitle;
+        assertHumanReadableDeckTitle(title);
+        deck.title = title;
+        deck.appId = "slides-2";
+        await assertDesignSystemReadable(deckDesignSystemId(deck));
+        assertNoDeckRenderArtifacts(null, deck);
+        const orgId = getRequestOrgId() ?? null;
+        await withSlideAssetReferencesLocked(
+          db,
+          deck,
+          { ownerEmail, orgId },
+          async (tx) => {
+            await tx.insert(schema.decks).values({
+              id: deckId,
+              title,
+              data: JSON.stringify(deck),
+              designSystemId: deckDesignSystemId(deck),
+              ...deckClientWriteFields(clientWrite, now),
+              ownerEmail,
+              orgId,
+              createdAt: now,
+              updatedAt: now,
+            });
+          },
+        );
+      } else if (
+        access.role === "owner" ||
+        access.role === "admin" ||
+        access.role === "editor"
+      ) {
+        deck.appId = "slides-2";
+        const title =
+          repairGeneratedDeckTitle(
+            requestedTitle,
+            firstSlideContent(deck),
+            access.resource.title,
+          ) ?? requestedTitle;
+        assertHumanReadableDeckTitle(title);
+        deck.title = title;
+        const updatedAt = nextDeckRevision(access.resource.updatedAt);
+        deck.updatedAt = updatedAt;
+        const nextDesignSystemId = Object.hasOwn(deck, "designSystemId")
+          ? deckDesignSystemId(deck)
+          : (access.resource.designSystemId ?? null);
+        await assertDesignSystemReadable(nextDesignSystemId);
+        assertNoDeckRenderArtifacts(access.resource.data, deck);
+        if (!shouldSnapshotDeckWrite(access.resource, title, deck)) {
+          if (clientWrite) {
+            const updateResult = await db
+              .update(schema.decks)
+              .set(
+                deckClientWriteFields(clientWrite, access.resource.updatedAt),
+              )
+              .where(
+                deckRevisionWhere(
+                  schema.decks,
+                  deckId,
+                  access.resource.updatedAt,
+                ),
+              );
+            assertDeckWriteApplied(updateResult, deckId, "deck save replay");
+          }
+          return { ...deck, updatedAt: access.resource.updatedAt };
+        }
+        await db.transaction(async (tx: any) => {
+          await lockSlideAssetReferences(
+            tx,
+            deck,
+            {
+              ownerEmail: access.resource.ownerEmail as string,
+              orgId: access.resource.orgId,
+            },
+            deckId,
+          );
+          if (shouldSnapshotDeckWrite(access.resource, title, deck)) {
+            await createDeckVersionSnapshot(
+              {
+                id: access.resource.id,
+                title: access.resource.title,
+                data: access.resource.data,
+                ownerEmail: access.resource.ownerEmail as string,
+              },
+              { label: "Before editor save", db: tx },
+            );
+          }
+          const updateResult = await tx
+            .update(schema.decks)
+            .set({
+              title,
+              data: JSON.stringify(deck),
+              designSystemId: nextDesignSystemId,
+              updatedAt,
+              ...deckClientWriteFields(clientWrite, updatedAt),
+            })
+            .where(
+              deckRevisionWhere(
+                schema.decks,
+                deckId,
+                access.resource.updatedAt,
+              ),
+            );
+          assertDeckWriteApplied(updateResult, deckId, "deck save");
+        });
+      } else {
+        throw deckHttpError(404, "Deck not found");
+      }
+
+      // An insert here is an undo/restore of a deleted deck (or a save racing
+      // add-deck), not a new deck; only add-deck records creations.
+      if (access) {
+        trackSlideContentEdited(
+          "save_deck",
+          deckId,
+          previous.slides,
+          deck,
+          ctx,
+        );
+        trackDeckCreationStarted(
+          deckId,
+          previous.generationContext,
+          deck.generationContext,
+          ctx,
+        );
+      }
+
+      await notifyClients(deckId);
+      return { ...deck, appUrl: getDeckUrl(deckId) };
+    }),
+});
+
+function firstSlideContent(deck: DeckPayload): string | null {
+  const slides = Array.isArray(deck.slides) ? deck.slides : [];
+  const content = slides[0] && (slides[0] as Record<string, unknown>).content;
+  return typeof content === "string" ? content : null;
+}
+
+/** Returns the parsed stored deck so callers don't parse it a second time. */
+export function stampChangedSlideRevisions(
+  previousData: string | null | undefined,
+  nextDeck: DeckPayload,
+): {
+  aspectRatio?: unknown;
+  designSystemId?: unknown;
+  slides?: unknown;
+  generationContext?: unknown;
+} {
+  const previous = previousData
+    ? (JSON.parse(previousData) as {
+        aspectRatio?: unknown;
+        designSystemId?: unknown;
+        slides?: unknown;
+        generationContext?: unknown;
+      })
+    : {};
+  const deckFitFieldsChanged = deckFitRenderFieldsChanged(previous, nextDeck);
+  const previousSlides = (
+    Array.isArray(previous.slides) ? previous.slides : []
+  ) as Array<Record<string, unknown>>;
+  const nextSlides = Array.isArray(nextDeck.slides)
+    ? (nextDeck.slides as Array<Record<string, unknown>>)
+    : [];
+
+  for (const slide of nextSlides) {
+    const prior = previousSlides.find((candidate) => candidate.id === slide.id);
+    if (
+      deckFitFieldsChanged ||
+      !prior ||
+      slideFitRenderFieldsChanged(prior, slide)
+    ) {
+      slide.layoutFitRevision = createLayoutFitRevision();
+    } else if (typeof prior.layoutFitRevision === "string") {
+      slide.layoutFitRevision = prior.layoutFitRevision;
+    } else {
+      delete slide.layoutFitRevision;
+    }
+  }
+  return previous;
+}

package/corpus/templates/slides-2/actions/search-google-fonts.ts

@@ -0,0 +1,61 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+import { z } from "zod";
+
+import {
+  GoogleFontError,
+  MAX_GOOGLE_FONT_RESULTS,
+  searchGoogleFonts,
+} from "../server/lib/google-fonts.js";
+
+export default defineAction({
+  title: "Search Google Fonts",
+  description:
+    "Search the public Google Fonts catalog and return bounded family metadata and available variants. Font files are imported separately before they can be applied to a deck.",
+  schema: z.object({
+    q: z
+      .string()
+      .trim()
+      .min(1)
+      .max(120)
+      .describe("Font family search text, up to 120 characters."),
+    limit: z
+      .number()
+      .int()
+      .min(1)
+      .max(MAX_GOOGLE_FONT_RESULTS)
+      .default(MAX_GOOGLE_FONT_RESULTS)
+      .describe("Maximum results to return, up to 24."),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  requiresAuth: true,
+  retrySafe: true,
+  mcpAnnotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  run: async ({ q, limit }) => {
+    if (!getRequestUserEmail()) {
+      fail("Sign in to search fonts.", {
+        errorCode: "google_font_auth_required",
+        statusCode: 401,
+      });
+    }
+    try {
+      return (await searchGoogleFonts(q)).slice(0, limit);
+    } catch (error) {
+      if (error instanceof GoogleFontError) {
+        fail(error.message, {
+          errorCode: error.errorCode,
+          statusCode: error.statusCode,
+        });
+      }
+      fail("Google Fonts search could not be completed.", {
+        errorCode: "google_font_search_failed",
+        statusCode: 502,
+      });
+    }
+  },
+});

package/corpus/templates/slides-2/actions/search-images.ts

@@ -0,0 +1,30 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { searchProviderImages } from "../server/lib/media-search-providers.js";
+
+export default defineAction({
+  description: "Search for images using Google Custom Search API.",
+  schema: z.object({
+    q: z.string().optional().describe("Search query (required)"),
+    count: z.coerce
+      .number()
+      .int()
+      .min(1)
+      .max(10)
+      .default(10)
+      .describe("Maximum number of image results to return."),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args) => {
+    const q = args.q;
+    if (!q) {
+      fail("Missing query parameter 'q'", {
+        errorCode: "search_query_required",
+        statusCode: 400,
+      });
+    }
+    return searchProviderImages(q, args.count);
+  },
+});

package/corpus/templates/slides-2/actions/search-logos.ts

@@ -0,0 +1,23 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { searchProviderLogos } from "../server/lib/media-search-providers.js";
+
+export default defineAction({
+  description: "Search for company logos by name or domain.",
+  schema: z.object({
+    q: z.string().optional().describe("Company name or domain to search"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async (args) => {
+    const q = (args.q || "").trim();
+    if (!q) {
+      fail("Missing ?q= parameter", {
+        errorCode: "search_query_required",
+        statusCode: 400,
+      });
+    }
+    return searchProviderLogos(q);
+  },
+});

package/corpus/templates/slides-2/actions/search-svgl-logos.ts

@@ -0,0 +1,42 @@
+import { defineAction, fail } from "@agent-native/core/action";
+import { z } from "zod";
+
+import { searchSvglLogos, SvglError } from "../server/lib/svgl.js";
+
+export default defineAction({
+  title: "Search SVGL logos",
+  description:
+    "Search the public SVGL logo catalog by title and return bounded, validated HTTPS SVG routes for preview or import.",
+  schema: z.object({
+    q: z
+      .string()
+      .trim()
+      .min(1)
+      .max(120)
+      .describe("Logo title or brand name to search, up to 120 characters."),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  retrySafe: true,
+  mcpAnnotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  run: async ({ q }) => {
+    try {
+      return await searchSvglLogos(q);
+    } catch (error) {
+      if (error instanceof SvglError) {
+        fail(error.message, {
+          errorCode: error.errorCode,
+          statusCode: error.statusCode,
+        });
+      }
+      fail("SVGL logo search could not be completed.", {
+        errorCode: "svgl_search_failed",
+        statusCode: 502,
+      });
+    }
+  },
+});