@agent-native/core 0.182.1 → 0.182.2-nightly-20260917225811

package/corpus/templates/design/actions/index-components.ts

@@ -16,7 +16,12 @@
  */
 
 import { defineAction } from "@agent-native/core/action";
-import { getText, hasCollabState } from "@agent-native/core/collab";
+import {
+  applyTextToYDoc,
+  CollabBaseVersionConflictError,
+  withPreparedYDocMutation,
+} from "@agent-native/core/collab";
+import { getDbExec } from "@agent-native/core/db";
 import { getRequestUserEmail } from "@agent-native/core/server/request-context";
 import { accessFilter, assertAccess } from "@agent-native/core/sharing";
 import { and, eq } from "drizzle-orm";
@@ -24,10 +29,16 @@ import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
 import "../server/db/index.js"; // ensure registerShareableResource runs
+import {
+  SourceWorkspaceEditConflictError,
+  designSourceMutationLockKey,
+  withSourceFileWriteLock,
+} from "../server/source-workspace.js";
 import { resolveSourceCapabilities } from "../shared/capability-resolver.js";
 import { buildCodeLayerProjection } from "../shared/code-layer.js";
 import type { CodeLayerSource } from "../shared/code-layer.js";
 import {
+  componentIndexId,
   detectInstances,
   buildDefinitions,
   type ComponentDefinition,
@@ -36,29 +47,6 @@ import {
 import { hasCapability } from "../shared/design-source-capabilities.js";
 import { designSourceTypeFromData } from "../shared/source-mode.js";
 
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-
-async function liveContent(
-  fileId: string,
-  storedContent: string,
-): Promise<string> {
-  try {
-    if (await hasCollabState(fileId)) {
-      const live = await getText(fileId, "content");
-      if (typeof live === "string") return live;
-    }
-  } catch {
-    // Collab reads are best-effort; SQL content is the fallback.
-  }
-  return storedContent;
-}
-
-function componentIndexId(designId: string, name: string): string {
-  // Stable deterministic id — same component name on the same design always
-  // maps to the same row so upsert is safe.
-  return `ci_${designId}_${name.toLowerCase().replace(/[^a-z0-9]/g, "_")}`;
-}
-
 // ─── Action ───────────────────────────────────────────────────────────────────
 
 export default defineAction({
@@ -118,7 +106,9 @@ export default defineAction({
       };
     }
 
-    // ── Fetch the design file ────────────────────────────────────────────────
+    // Resolve the lock target without holding a database lock. The source-file
+    // lock must be acquired before the transaction so index and write paths
+    // enter Yjs and SQL in the same order.
     const conditions = [
       accessFilter(schema.designs, schema.designShares),
       eq(schema.designFiles.designId, designId),
@@ -126,14 +116,8 @@ export default defineAction({
         ? eq(schema.designFiles.id, fileId)
         : eq(schema.designFiles.filename, "index.html"),
     ];
-
-    const [file] = await db
-      .select({
-        id: schema.designFiles.id,
-        designId: schema.designFiles.designId,
-        filename: schema.designFiles.filename,
-        content: schema.designFiles.content,
-      })
+    const [candidate] = await db
+      .select({ id: schema.designFiles.id })
       .from(schema.designFiles)
       .innerJoin(
         schema.designs,
@@ -141,102 +125,233 @@ export default defineAction({
       )
       .where(and(...conditions))
       .limit(1);
+    if (!candidate) throw new Error("Design HTML file not found.");
+
+    let preparedCallbackEntered = false;
+    let result;
+    try {
+      result = await withSourceFileWriteLock(candidate.id, () =>
+        // Holding the core document lock across the SQL snapshot prevents a
+        // local Yjs writer from changing the document between the row locks and
+        // the component projection. Cross-process writers are stopped by the
+        // transaction-scoped _collab_docs row lock below.
+        withPreparedYDocMutation(candidate.id, undefined, async (lease) => {
+          preparedCallbackEntered = true;
+          const [file] = await db
+            .select({
+              id: schema.designFiles.id,
+              designId: schema.designFiles.designId,
+              filename: schema.designFiles.filename,
+              content: schema.designFiles.content,
+            })
+            .from(schema.designFiles)
+            .innerJoin(
+              schema.designs,
+              eq(schema.designFiles.designId, schema.designs.id),
+            )
+            .where(and(...conditions))
+            .limit(1);
+
+          if (!file) throw new Error("Design HTML file not found.");
+
+          const transaction = getDbExec().transaction;
+          if (!transaction) {
+            throw new SourceWorkspaceEditConflictError(
+              "Could not verify a source file's live version. Re-read the design and retry.",
+            );
+          }
+
+          return transaction(async (tx) => {
+            await tx.execute({
+              sql: "SELECT pg_advisory_xact_lock(hashtextextended(?, 0::bigint))",
+              args: [designSourceMutationLockKey(designId)],
+            });
+
+            // Lock only the selected source row and the live collab row. The
+            // latter makes the following text_snapshot a stable cross-process
+            // view instead of a best-effort cache read.
+            const lockedFileResult = await tx.execute({
+              sql: 'SELECT id, design_id AS "designId", filename, content FROM design_files WHERE id = ? AND design_id = ? FOR UPDATE',
+              args: [file.id, designId],
+            });
+            const lockedFileRow = lockedFileResult.rows[0] as
+              | {
+                  id?: unknown;
+                  designId?: unknown;
+                  filename?: unknown;
+                  content?: unknown;
+                }
+              | undefined;
+
+            if (
+              !lockedFileRow ||
+              typeof lockedFileRow.id !== "string" ||
+              typeof lockedFileRow.designId !== "string" ||
+              typeof lockedFileRow.filename !== "string" ||
+              (lockedFileRow.content !== null &&
+                typeof lockedFileRow.content !== "string") ||
+              lockedFileRow.content !== file.content
+            ) {
+              throw new SourceWorkspaceEditConflictError(
+                "The source file changed while its live version was being read. Re-read the design and retry.",
+              );
+            }
+            const lockedFile = {
+              id: lockedFileRow.id,
+              designId: lockedFileRow.designId,
+              filename: lockedFileRow.filename,
+              content: lockedFileRow.content as string | null,
+            };
+
+            let collabResult: { rows: any[] };
+            try {
+              collabResult = (await tx.execute({
+                sql: "SELECT yjs_state, text_snapshot FROM _collab_docs WHERE doc_id = ? FOR SHARE",
+                args: [file.id],
+              })) as { rows: any[] };
+            } catch {
+              throw new SourceWorkspaceEditConflictError(
+                "Could not verify a source file's live version. Re-read the design and retry.",
+              );
+            }
+            const collabRow = collabResult.rows[0] as
+              | { yjs_state?: unknown; text_snapshot?: unknown }
+              | undefined;
+            let html = (lockedFile.content as string | null) ?? "";
+            let needsCollabSeed = !collabRow;
+            if (collabRow) {
+              if (
+                typeof collabRow.yjs_state !== "string" ||
+                typeof collabRow.text_snapshot !== "string"
+              ) {
+                throw new SourceWorkspaceEditConflictError(
+                  "Could not verify a source file's live version. Re-read the design and retry.",
+                );
+              }
+              if (collabRow.yjs_state.length > 0) {
+                html = collabRow.text_snapshot;
+              } else {
+                needsCollabSeed = true;
+              }
+            }
+
+            // A missing or empty row is lazy collab state, not permission to
+            // index an unprotected SQL fallback. Seed the prepared Y.Doc in
+            // this transaction; if another writer wins the insert/CAS, the
+            // lease raises a typed conflict and the index write rolls back.
+            if (needsCollabSeed) {
+              applyTextToYDoc(lease.doc, "content", html, "agent");
+              try {
+                await lease.persist(tx, html);
+              } catch (error) {
+                if (error instanceof CollabBaseVersionConflictError) {
+                  throw new SourceWorkspaceEditConflictError(
+                    "The source file changed while its live version was being initialized. Re-read the design and retry.",
+                  );
+                }
+                throw error;
+              }
+            }
+
+            const codeLayerSource: CodeLayerSource = {
+              kind: "design-file",
+              designId: lockedFile.designId,
+              fileId: lockedFile.id,
+              filename: lockedFile.filename,
+            };
+            const projection = buildCodeLayerProjection(html, {
+              source: codeLayerSource,
+            });
+            const instances = detectInstances(projection.nodes);
+            const definitions = buildDefinitions(instances);
+
+            // ── Persist discovered components ────────────────────────────────────
+            // Write each distinct component name into component_index so that
+            // get-component-details can resolve metadata by node id.
+            const now = new Date().toISOString();
+            const selectorByNodeId = new Map(
+              instances.map((instance) => [instance.nodeId, instance.selector]),
+            );
+            // Derive the owner from the request user, falling back to the design's
+            // owner. Never stamp an empty-string owner (an unowned row): require a real
+            // owner before writing a new component_index row.
+            const designOwner = (access.resource as { ownerEmail?: unknown })
+              .ownerEmail;
+            const ownerEmail =
+              getRequestUserEmail() ??
+              (typeof designOwner === "string" && designOwner
+                ? designOwner
+                : null);
+            if (!ownerEmail) throw new Error("no authenticated user");
+
+            for (const def of definitions) {
+              const id = componentIndexId(designId, def.name);
+              await tx.execute({
+                sql: `INSERT INTO component_index
+                  (id, design_id, name, runtime_selectors, owner_email, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT (id) DO UPDATE SET
+                  runtime_selectors = excluded.runtime_selectors,
+                  updated_at = excluded.updated_at`,
+                args: [
+                  id,
+                  designId,
+                  def.name,
+                  JSON.stringify(
+                    def.instanceNodeIds
+                      .map((nodeId) => selectorByNodeId.get(nodeId))
+                      .filter((selector): selector is string =>
+                        Boolean(selector),
+                      ),
+                  ),
+                  ownerEmail,
+                  now,
+                  now,
+                ],
+              });
+            }
+
+            // Annotate instances with their component_index id.
+            const indexMap = new Map(
+              definitions.map((def) => [
+                def.name,
+                componentIndexId(designId, def.name),
+              ]),
+            );
+            const annotatedInstances = instances.map((inst) => ({
+              ...inst,
+              componentIndexId: indexMap.get(inst.name),
+            }));
 
-    if (!file) throw new Error("Design HTML file not found.");
-
-    const html = await liveContent(file.id, file.content ?? "");
-
-    // ── Projection + detection ───────────────────────────────────────────────
-    const codeLayerSource: CodeLayerSource = {
-      kind: "design-file",
-      designId: file.designId,
-      fileId: file.id,
-      filename: file.filename,
-    };
-
-    const projection = buildCodeLayerProjection(html, {
-      source: codeLayerSource,
-    });
-
-    const instances = detectInstances(projection.nodes);
-    const definitions = buildDefinitions(instances);
-
-    // ── Persist discovered components ────────────────────────────────────────
-    // Write each distinct component name into component_index so that
-    // get-component-details can resolve metadata by node id.
-    const now = new Date().toISOString();
-    // Derive the owner from the request user, falling back to the design's
-    // owner. Never stamp an empty-string owner (an unowned row): require a real
-    // owner before writing a new component_index row.
-    const designOwner = (access.resource as { ownerEmail?: unknown })
-      .ownerEmail;
-    const ownerEmail =
-      getRequestUserEmail() ??
-      (typeof designOwner === "string" && designOwner ? designOwner : null);
-    if (!ownerEmail) throw new Error("no authenticated user");
-
-    for (const def of definitions) {
-      const id = componentIndexId(designId, def.name);
-      const existing = await db
-        .select({ id: schema.componentIndex.id })
-        .from(schema.componentIndex)
-        .where(eq(schema.componentIndex.id, id))
-        .limit(1);
-
-      if (existing.length === 0) {
-        await db.insert(schema.componentIndex).values({
-          id,
-          designId,
-          name: def.name,
-          runtimeSelectors: JSON.stringify(
-            def.instanceNodeIds.map(
-              (nodeId) => `[data-agent-native-node-id="${nodeId}"]`,
-            ),
-          ),
-          ownerEmail,
-          createdAt: now,
-          updatedAt: now,
-        });
-      } else {
-        await db
-          .update(schema.componentIndex)
-          .set({
-            runtimeSelectors: JSON.stringify(
-              def.instanceNodeIds.map(
-                (nodeId) => `[data-agent-native-node-id="${nodeId}"]`,
-              ),
-            ),
-            updatedAt: now,
-          })
-          .where(eq(schema.componentIndex.id, id));
+            return {
+              designId,
+              sourceType,
+              ctaRequired: false,
+              hasFullIndex,
+              components: definitions,
+              instances: annotatedInstances,
+              totalComponents: definitions.length,
+              totalInstances: instances.length,
+              note:
+                sourceType === "inline"
+                  ? "Showing annotated Alpine components from data-agent-native-component attributes. Connect Builder (free tier available) for full TS prop types and cva variants."
+                  : undefined,
+            };
+          });
+        }),
+      );
+    } catch (error) {
+      if (
+        !preparedCallbackEntered &&
+        !(error instanceof SourceWorkspaceEditConflictError)
+      ) {
+        throw new SourceWorkspaceEditConflictError(
+          "Could not verify a source file's live version. Re-read the design and retry.",
+        );
       }
+      throw error;
     }
 
-    // Annotate instances with their component_index id.
-    const indexMap = new Map(
-      definitions.map((def) => [
-        def.name,
-        componentIndexId(designId, def.name),
-      ]),
-    );
-    const annotatedInstances = instances.map((inst) => ({
-      ...inst,
-      componentIndexId: indexMap.get(inst.name),
-    }));
-
-    return {
-      designId,
-      sourceType,
-      ctaRequired: false,
-      hasFullIndex,
-      components: definitions,
-      instances: annotatedInstances,
-      totalComponents: definitions.length,
-      totalInstances: instances.length,
-      note:
-        sourceType === "inline"
-          ? "Showing annotated Alpine components from data-agent-native-component attributes. Connect Builder (free tier available) for full TS prop types and cva variants."
-          : undefined,
-    };
+    return result;
   },
 });

package/corpus/templates/design/actions/migrate-board-objects-to-file.ts

@@ -42,6 +42,7 @@ import { mutateDesignData } from "../server/lib/design-data-mutation.js";
 import { snapshotDesignBeforeAgentEdit } from "../server/lib/design-versions.js";
 import {
   readLiveSourceFile,
+  withDesignSourceMutationTransaction,
   writeInlineSourceFile,
 } from "../server/source-workspace.js";
 import {
@@ -226,15 +227,17 @@ export default defineAction({
       });
     } else {
       try {
-        await db.insert(schema.designFiles).values({
-          id: boardFileId,
-          designId,
-          filename: BOARD_FILENAME,
-          fileType: "html",
-          content: boardHtml,
-          createdAt: now,
-          updatedAt: now,
-        });
+        await withDesignSourceMutationTransaction(designId, (tx) =>
+          tx.insert(schema.designFiles).values({
+            id: boardFileId,
+            designId,
+            filename: BOARD_FILENAME,
+            fileType: "html",
+            content: boardHtml,
+            createdAt: now,
+            updatedAt: now,
+          }),
+        );
       } catch (error) {
         const [concurrentBoardFile] = await db
           .select({ id: schema.designFiles.id })

package/corpus/templates/design/actions/present-design-variants.ts

@@ -15,12 +15,12 @@ import "../server/db/index.js"; // ensure registerShareableResource runs
 import { getDb, schema } from "../server/db/index.js";
 import { mutateDesignData } from "../server/lib/design-data-mutation.js";
 import { snapshotDesignBeforeAgentEdit } from "../server/lib/design-versions.js";
+import { withDesignSourceMutationTransaction } from "../server/source-workspace.js";
 import {
   mergeCanvasFramePlacements,
   nextFreeCanvasRowY,
   type CanvasFramePlacement,
 } from "../shared/canvas-frames.js";
-import { isUniqueConstraintViolation } from "../shared/db-conflict.js";
 import { getOverviewScreenFileIds } from "../shared/design-files.js";
 import { assertDesignHtmlWellFormed } from "../shared/html-integrity.js";
 import { widthToPrefix } from "../shared/responsive-classes.js";
@@ -205,8 +205,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 
-const MAX_FILENAME_INSERT_ATTEMPTS = 5;
-
 /**
  * True only when `rawSet` proves none of its screens has ever been removed by
  * delete-file.ts. This action stamps every variant set it creates with
@@ -496,9 +494,16 @@ async function deleteVariantSetsByIds(
   });
 
   if (removedFileIds.length > 0) {
-    await db
-      .delete(schema.designFiles)
-      .where(inArray(schema.designFiles.id, removedFileIds));
+    await withDesignSourceMutationTransaction(designId, async (tx) => {
+      await tx
+        .delete(schema.designFiles)
+        .where(
+          and(
+            eq(schema.designFiles.designId, designId),
+            inArray(schema.designFiles.id, removedFileIds),
+          ),
+        );
+    });
 
     // Closes the small window between the metadata prune above and the
     // physical row delete: mirrors delete-file.ts's before/delete/after
@@ -992,46 +997,45 @@ export default defineAction({
 
     const db = getDb();
     const now = new Date().toISOString();
-    const existingFiles = await db
-      .select()
-      .from(schema.designFiles)
-      .where(eq(schema.designFiles.designId, designId));
-    const usedFilenames = new Set(existingFiles.map((file) => file.filename));
-    const screenFileIds = getOverviewScreenFileIds(existingFiles);
     const variantSetId = nanoid();
-    const screens: VariantScreen[] = [];
-
-    for (let index = 0; index < variants.length; index += 1) {
-      const variant = variants[index]!;
-      const label = variant.label.trim() || optionName(index);
-      const slug = slugify(label, `option-${index + 1}`);
-      let filename = uniqueFilename(`variant-${slug}.html`, usedFilenames);
-      let fileId = nanoid();
-      const providedContent = variant.content?.trim();
-      const initialSize = inferVariantSize(variant, prompt);
-      const rawContent =
-        providedContent ||
-        fallbackVariantContent(variant, index, prompt, initialSize);
-      const { width, height } = providedContent
-        ? inferVariantSize({ ...variant, content: rawContent })
-        : initialSize;
-      // Stamp missing data-agent-native-node-id attributes before persisting
-      // so each variant screen is fully addressable by id-keyed editor
-      // operations as soon as it lands on the overview board.
-      const content = annotateScreenHtmlForPersist(rawContent, "html");
-
-      // `usedFilenames` is a snapshot taken once at the top of run(), so a
-      // concurrent present-design-variants call (an agent retry after a
-      // timeout is the common trigger) can independently compute the same
-      // (designId, filename) pair and win the insert first. The
-      // `design_files_design_filename_unique_idx` unique index (see
-      // server/plugins/db.ts) turns the loser's insert into a constraint
-      // error instead of a silently duplicated screen; recover by refreshing
-      // the real filename list from the DB, picking a fresh unique name, and
-      // retrying — bounded so a persistent non-race failure still surfaces.
-      for (let attempt = 0; ; attempt += 1) {
-        try {
-          await db.insert(schema.designFiles).values({
+    let screenFileIds: string[] = [];
+    const screenContents = new Map<string, string>();
+    const screens = await withDesignSourceMutationTransaction(
+      designId,
+      async (tx) => {
+        const existingFiles = await tx
+          .select()
+          .from(schema.designFiles)
+          .where(eq(schema.designFiles.designId, designId));
+        const usedFilenames = new Set(
+          existingFiles.map((file) => file.filename),
+        );
+        screenFileIds = getOverviewScreenFileIds(existingFiles);
+        const createdScreens: VariantScreen[] = [];
+
+        for (let index = 0; index < variants.length; index += 1) {
+          const variant = variants[index]!;
+          const label = variant.label.trim() || optionName(index);
+          const slug = slugify(label, `option-${index + 1}`);
+          const filename = uniqueFilename(
+            `variant-${slug}.html`,
+            usedFilenames,
+          );
+          const fileId = nanoid();
+          const providedContent = variant.content?.trim();
+          const initialSize = inferVariantSize(variant, prompt);
+          const rawContent =
+            providedContent ||
+            fallbackVariantContent(variant, index, prompt, initialSize);
+          const { width, height } = providedContent
+            ? inferVariantSize({ ...variant, content: rawContent })
+            : initialSize;
+          // Stamp missing data-agent-native-node-id attributes before
+          // persisting so each variant screen is fully addressable by
+          // id-keyed editor operations as soon as it lands on the board.
+          const content = annotateScreenHtmlForPersist(rawContent, "html");
+
+          await tx.insert(schema.designFiles).values({
             id: fileId,
             designId,
             filename,
@@ -1040,34 +1044,26 @@ export default defineAction({
             createdAt: now,
             updatedAt: now,
           });
-          break;
-        } catch (err) {
-          if (
-            !isUniqueConstraintViolation(err) ||
-            attempt >= MAX_FILENAME_INSERT_ATTEMPTS
-          ) {
-            throw err;
-          }
-          const freshFiles = await db
-            .select({ filename: schema.designFiles.filename })
-            .from(schema.designFiles)
-            .where(eq(schema.designFiles.designId, designId));
-          for (const file of freshFiles) usedFilenames.add(file.filename);
-          filename = uniqueFilename(`variant-${slug}.html`, usedFilenames);
-          fileId = nanoid();
+          usedFilenames.add(filename);
+          screenContents.set(fileId, content);
+
+          createdScreens.push({
+            id: fileId,
+            variantId: variant.id,
+            label,
+            filename,
+            width,
+            height,
+          });
         }
-      }
-      await seedFromText(fileId, content);
-
-      screens.push({
-        id: fileId,
-        variantId: variant.id,
-        label,
-        filename,
-        width,
-        height,
-      });
-    }
+        return createdScreens;
+      },
+    );
+    await Promise.all(
+      screens.map((screen) =>
+        seedFromText(screen.id, screenContents.get(screen.id)!),
+      ),
+    );
 
     // Presenting options should not silently reconfigure the design. When it
     // does, the overview paints an extra preview beside EVERY primary frame