@agent-native/core 0.80.8 → 0.80.10

package/corpus/templates/design/actions/deploy-design-preview.ts

@@ -0,0 +1,275 @@
+/**
+ * deploy-design-preview — trigger a preview deploy when the source supports it
+ * (§6.6 of DESIGN-STUDIO-PLAN.md).
+ *
+ * Behaviour:
+ * - **Capability gate (server-side):** re-checks `deployPreview` capability.
+ *   When `unavailable` (inline/localhost), returns a `ctaRequired` response with a
+ *   "Make it real" CTA — never fakes a deploy call.
+ * - **Builder gate:** if `resolveIsBuilderBranchingEnabled()` returns false,
+ *   returns a `connectRequired` CTA.
+ * - **Branch requirement:** a branch must already exist on the design (created
+ *   via `create-design-branch`).  If no branch is found, returns a clear
+ *   `branchRequired` message rather than silently failing.
+ * - **Deploy trigger:** calls `runBuilderAgent()` with a scoped "deploy preview"
+ *   prompt asking the Builder cloud agent to build and publish a preview URL for
+ *   the named branch.  Builder returns `{ branchName, url, status }`.
+ * - **Persistence:** updates the matching branch entry in the design's `data`
+ *   JSON blob with `previewUrl` and `deployStatus`.
+ *
+ * The preview URL is the Builder-hosted ephemeral preview (not a permanent
+ * production deploy — use the Builder Visual Editor's Publish flow for that).
+ *
+ * Per DESIGN-STUDIO-PLAN.md §5, `deploy` (production) is the separate step;
+ * `deployPreview` is the lighter "preview build" step exposed here.
+ */
+
+import { defineAction } from "@agent-native/core";
+import {
+  runBuilderAgent,
+  resolveBuilderBranchProjectId,
+  resolveIsBuilderBranchingEnabled,
+} from "@agent-native/core/server";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+import { assertAccess, resolveAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import {
+  resolveSourceCapabilities,
+  resolveFusionCapabilities,
+} from "../shared/capability-resolver.js";
+import { hasCapability } from "../shared/design-source-capabilities.js";
+import { normalizeDesignSourceType } from "../shared/source-mode.js";
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function parseDesignData(raw: unknown): Record<string, unknown> {
+  if (typeof raw !== "string") return {};
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (
+      parsed !== null &&
+      typeof parsed === "object" &&
+      !Array.isArray(parsed)
+    ) {
+      return parsed as Record<string, unknown>;
+    }
+  } catch {
+    // Stale JSON — return empty.
+  }
+  return {};
+}
+
+interface StoredBranchEntry {
+  branchName?: string;
+  projectId?: string;
+  url?: string;
+  status?: string;
+  purpose?: string | null;
+  preSnapshotVersionId?: string | null;
+  previewUrl?: string | null;
+  deployStatus?: string | null;
+  createdAt?: string;
+  [key: string]: unknown;
+}
+
+function parseBranches(
+  designData: Record<string, unknown>,
+): StoredBranchEntry[] {
+  const raw = designData["branches"];
+  if (!Array.isArray(raw)) return [];
+  return raw.filter(
+    (b): b is StoredBranchEntry =>
+      b !== null && typeof b === "object" && !Array.isArray(b),
+  );
+}
+
+/** Build a concise deploy-preview prompt for the Builder cloud agent. */
+function buildDeployPrompt(
+  designTitle: string,
+  branchName: string,
+  projectId: string,
+): string {
+  return [
+    `Deploy a preview build for branch "${branchName}" of project "${projectId}".`,
+    `Design: "${designTitle}".`,
+    "Build the branch and publish a preview URL so the design can be reviewed",
+    "in a real browser before merging to production.",
+  ].join("\n");
+}
+
+// ─── Action ───────────────────────────────────────────────────────────────────
+
+export default defineAction({
+  description:
+    "Trigger a preview deploy for a fusion-backed design branch. " +
+    "Requires the design's source to advertise the 'deployPreview' capability " +
+    "(fusion tier) AND Builder.io to be connected. " +
+    "For inline/localhost designs, returns ctaRequired=true with a Make-it-real " +
+    "CTA — never fakes a deploy call. " +
+    "A branch must already exist (created via create-design-branch). " +
+    "On success, persists previewUrl and deployStatus into the design's branch " +
+    "metadata and returns the preview URL. " +
+    "Note: this triggers a *preview* deploy, not a production publish. " +
+    "Use the Builder Visual Editor's Publish flow for production deploys.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID to deploy a preview for"),
+    branchName: z
+      .string()
+      .optional()
+      .describe(
+        "Branch name to deploy. Defaults to the most recently created branch " +
+          "when omitted.",
+      ),
+  }),
+  run: async ({ designId, branchName }) => {
+    const db = getDb();
+
+    // ── Access check (editor level required for deploys) ────────────────────
+    await assertAccess("design", designId, "editor");
+    const access = await resolveAccess("design", designId);
+    if (!access) throw new Error("Design not found");
+
+    const resource = access.resource as {
+      title?: string;
+      data?: unknown;
+    };
+
+    // ── Source type + capability check ──────────────────────────────────────
+    const designData = parseDesignData(resource.data);
+    const sourceType =
+      normalizeDesignSourceType(designData["sourceType"]) ?? "inline";
+
+    // For fusion sources, resolve the Builder connection status first so that
+    // resolveFusionCapabilities returns the CONNECTED map (with deployPreview
+    // available) when Builder is actually wired up.  For inline/localhost the
+    // generic resolver is sufficient — those sources never have deployPreview.
+    const builderEnabled =
+      sourceType === "fusion"
+        ? await resolveIsBuilderBranchingEnabled()
+        : false;
+    const caps =
+      sourceType === "fusion"
+        ? resolveFusionCapabilities(builderEnabled)
+        : resolveSourceCapabilities(sourceType);
+
+    if (!hasCapability(caps, "deployPreview")) {
+      // For a disconnected fusion source the connect-builder CTA applies.
+      const isFusion = sourceType === "fusion";
+      return {
+        designId,
+        sourceType,
+        ctaRequired: true,
+        ctaKind: isFusion
+          ? ("connect-builder" as const)
+          : ("make-it-real" as const),
+        ctaMessage: isFusion
+          ? "Builder is not yet connected. Connect Builder.io to trigger preview deploys."
+          : "Preview deploys require a Builder-hosted app. Use 'Make it real' to upgrade " +
+            "this inline design to a real-app source, then deploy previews.",
+        previewUrl: null,
+        deployStatus: null,
+        branch: null,
+      };
+    }
+
+    // At this point sourceType === "fusion" and builderEnabled === true,
+    // so no separate Builder gate is needed — the capability check above
+    // already required a connected Builder to set deployPreview=available.
+
+    // ── Resolve branch entry ─────────────────────────────────────────────────
+    const branches = parseBranches(designData);
+
+    let branch: StoredBranchEntry | null = null;
+    if (branchName) {
+      branch =
+        branches.find(
+          (b) => b.branchName?.toLowerCase() === branchName.toLowerCase(),
+        ) ?? null;
+    } else {
+      branch = branches.length > 0 ? branches[branches.length - 1]! : null;
+    }
+
+    if (!branch || !branch.branchName) {
+      return {
+        designId,
+        sourceType,
+        ctaRequired: false,
+        ctaKind: null,
+        ctaMessage: null,
+        note:
+          "No branch found for this design. Use create-design-branch to create " +
+          "a branch first, then trigger a preview deploy.",
+        previewUrl: null,
+        deployStatus: null,
+        branch: null,
+      };
+    }
+
+    // ── Trigger the preview deploy via the Builder cloud agent ───────────────
+    const projectId = await resolveBuilderBranchProjectId();
+    const userEmail = getRequestUserEmail();
+    if (!userEmail) throw new Error("No authenticated user");
+
+    const designTitle =
+      typeof resource.title === "string" && resource.title.trim()
+        ? resource.title.trim()
+        : "Design";
+
+    const builderResult = await runBuilderAgent({
+      prompt: buildDeployPrompt(designTitle, branch.branchName, projectId),
+      projectId,
+      branchName: branch.branchName,
+      userEmail,
+    });
+
+    // ── Persist preview URL + deploy status into the branch entry ────────────
+    const now = new Date().toISOString();
+    const updatedBranches = branches.map((b) => {
+      if (b.branchName?.toLowerCase() !== branch!.branchName!.toLowerCase()) {
+        return b;
+      }
+      return {
+        ...b,
+        previewUrl: builderResult.url,
+        deployStatus: builderResult.status,
+        lastDeployedAt: now,
+      };
+    });
+
+    const updatedData = JSON.stringify({
+      ...designData,
+      branches: updatedBranches,
+    });
+
+    await db
+      .update(schema.designs)
+      .set({ data: updatedData, updatedAt: now })
+      .where(eq(schema.designs.id, designId));
+
+    return {
+      designId,
+      sourceType,
+      ctaRequired: false,
+      ctaKind: null,
+      ctaMessage: null,
+      previewUrl: builderResult.url,
+      deployStatus: builderResult.status,
+      branch: {
+        branchName: branch.branchName,
+        projectId: builderResult.projectId,
+        url: branch.url ?? null,
+        previewUrl: builderResult.url,
+        deployStatus: builderResult.status,
+        lastDeployedAt: now,
+      },
+      note:
+        "Preview deploy triggered. The Builder cloud agent is building the branch. " +
+        "Visit the previewUrl once status is 'ready' to review the deployed design. " +
+        "For production deploys, use the Builder Visual Editor's Publish flow.",
+    };
+  },
+});

package/corpus/templates/design/actions/export-coding-handoff.ts

@@ -11,6 +11,7 @@ import { z } from "zod";
 import { schema } from "../server/db/index.js";
 import {
   buildCodingHandoffPrompt,
+  buildHandoffZipUrl,
   buildRawHandoffUrl,
   normalizeHandoffFormat,
 } from "../server/lib/coding-handoff.js";
@@ -30,9 +31,9 @@ function designDeepLink(designId: string): string {
 
 export default defineAction({
   description:
-    "Turn a design into code: create a coding-tool handoff for a design " +
-    "project. Returns a tokenized raw-code URL external agents can fetch, " +
-    "plus a ready-to-copy prompt. The bundle reflects the design's CURRENT " +
+    "Turn a design into code: create an agent handoff for a design project. " +
+    "Returns tokenized raw and ZIP URLs external agents can fetch, plus a " +
+    "ready-to-copy prompt. The bundle reflects the design's CURRENT " +
     "state — live editor (collab) content plus the user's applied visual " +
     "tweaks resolved into the HTML :root — so the generated code matches the " +
     "tuned design, not the original generated tokens. This is the canonical " +
@@ -56,7 +57,7 @@ export default defineAction({
   mcpApp: {
     compactCatalog: true,
     resource: embedApp({
-      title: "Design coding handoff",
+      title: "Design agent handoff",
       description: "Open the design in the real Design editor.",
       iframeTitle: "Agent-Native Design",
       openLabel: "Open design",
@@ -97,8 +98,14 @@ export default defineAction({
       origin: resolvedOrigin,
       format: handoffFormat,
     });
+    const zipUrl = buildHandoffZipUrl({
+      id,
+      token,
+      origin: resolvedOrigin,
+    });
     const prompt = buildCodingHandoffPrompt({
       rawUrl,
+      zipUrl,
       title: design.title,
       fileCount: snapshot.files.length,
     });
@@ -106,6 +113,7 @@ export default defineAction({
     return {
       designId: id,
       rawUrl,
+      zipUrl,
       prompt,
       clipboardText: prompt,
       format: handoffFormat,

package/corpus/templates/design/actions/generate-design.ts

@@ -1,6 +1,5 @@
 import { defineAction, embedApp } from "@agent-native/core";
 import {
-  deleteAppState,
   readAppState,
   writeAppState,
 } from "@agent-native/core/application-state";
@@ -26,6 +25,7 @@ import {
 import {
   designGenerationSessionKey,
   type DesignGenerationSession,
+  updateGenerationSessionWithSavedFiles,
 } from "../shared/generation-session.js";
 
 /** Editor deep link so external agents can surface "Open design". */
@@ -57,28 +57,13 @@ async function updateGenerationSessionForSavedFiles(
   const session = rawSession as unknown as DesignGenerationSession;
   if (session.designId !== designId || !Array.isArray(session.frames)) return;
 
-  const saved = new Set(savedFilenames);
-  const frames = session.frames.map((frame) =>
-    frame.filename && saved.has(frame.filename)
-      ? {
-          ...frame,
-          status: "done" as const,
-          step: "Saved",
-          progress: 1,
-        }
-      : frame,
+  const nextSession = updateGenerationSessionWithSavedFiles(
+    session,
+    savedFilenames,
   );
-  const allDone = frames.every((frame) => frame.status === "done");
-  if (allDone) {
-    await deleteAppState(key);
-    return;
-  }
+  if (nextSession === session) return;
 
-  await writeAppState(key, {
-    ...session,
-    status: "generating",
-    frames,
-  } as unknown as Record<string, unknown>);
+  await writeAppState(key, nextSession as unknown as Record<string, unknown>);
 }
 
 export default defineAction({

package/corpus/templates/design/actions/generate-screens.ts

@@ -51,7 +51,7 @@ const requestedScreenSchema = z
       .optional()
       .describe("Target filename for this screen, such as onboarding.html"),
     role: z.enum(["screen", "variant"]).optional().default("screen"),
-    variantOf: z.string().optional(),
+    variantOf: z.string().trim().min(1).optional(),
   })
   .superRefine((screen, ctx) => {
     if (screen.role === "variant" && !screen.variantOf) {
@@ -80,7 +80,48 @@ export default defineAction({
     screens: z
       .preprocess(
         (value) => (typeof value === "string" ? JSON.parse(value) : value),
-        z.array(requestedScreenSchema).min(1).max(8),
+        z
+          .array(requestedScreenSchema)
+          .min(1)
+          .max(8)
+          .superRefine((screens, ctx) => {
+            const requestAnchors = new Map<
+              string,
+              { index: number; role: DesignGenerationFrame["role"] }
+            >();
+            screens.forEach((screen, index) => {
+              const anchors = [screen.frameId, screen.filename, screen.title];
+              for (const anchor of anchors) {
+                if (!anchor || requestAnchors.has(anchor)) continue;
+                requestAnchors.set(anchor, {
+                  index,
+                  role: screen.role,
+                });
+              }
+            });
+
+            screens.forEach((screen, index) => {
+              if (screen.role !== "variant" || !screen.variantOf) return;
+              const anchor = requestAnchors.get(screen.variantOf);
+              if (!anchor) return;
+              if (anchor.index === index) {
+                ctx.addIssue({
+                  code: z.ZodIssueCode.custom,
+                  path: [index, "variantOf"],
+                  message: "variant screens cannot point to themselves",
+                });
+                return;
+              }
+              if (anchor.role === "variant") {
+                ctx.addIssue({
+                  code: z.ZodIssueCode.custom,
+                  path: [index, "variantOf"],
+                  message:
+                    "variant screens must anchor to a base screen, not another variant",
+                });
+              }
+            });
+          }),
       )
       .describe("Screens or variants that should be generated on the canvas"),
     designSystemId: z

package/corpus/templates/design/actions/get-component-details.ts

@@ -0,0 +1,242 @@
+/**
+ * get-component-details — read action.
+ *
+ * For a selected component instance, returns the component name, source file
+ * (via resolveNodeToFile when the capability is available), props / variants,
+ * and the persistent component_index row when one exists.
+ *
+ * Works across both tiers:
+ * - **Alpine / inline** — returns name + observed props from attributes, plus
+ *   a CTA flag for features that require a real-app source.
+ * - **Real app (localhost / fusion)** — returns the full component_index row
+ *   including parsed TS prop types, cva variants, Storybook stories, and the
+ *   source file path.  The `resolveNodeToFile` capability unlocks the source
+ *   deep-link returned in `sourceLocation`.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { getText, hasCollabState } from "@agent-native/core/collab";
+import { accessFilter, resolveAccess } from "@agent-native/core/sharing";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import { resolveSourceCapabilities } from "../shared/capability-resolver.js";
+import { buildCodeLayerProjection } from "../shared/code-layer.js";
+import type { CodeLayerSource } from "../shared/code-layer.js";
+import {
+  componentNameFor,
+  extractProps,
+  type ComponentInstance,
+} from "../shared/component-model.js";
+import { hasCapability } from "../shared/design-source-capabilities.js";
+import { normalizeDesignSourceType } 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 parseJson<T>(raw: string | null | undefined, fallback: T): T {
+  if (!raw) return fallback;
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+// ─── Action ───────────────────────────────────────────────────────────────────
+
+export default defineAction({
+  description:
+    "Return details for a selected component instance: component name, " +
+    "source file (when resolveNodeToFile capability is available), props, " +
+    "variants, and the persisted component_index row. " +
+    "Provide the design id and node id (data-agent-native-node-id) of the " +
+    "selected component root. For Alpine designs the response includes " +
+    "lightweight attribute-based props and a CTA flag for full prop controls.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    nodeId: z
+      .string()
+      .describe(
+        "The data-agent-native-node-id of the selected component instance root element.",
+      ),
+    fileId: z
+      .string()
+      .optional()
+      .describe("Design file id. Defaults to index.html."),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId, nodeId, fileId }) => {
+    const db = getDb();
+
+    // ── Access check ────────────────────────────────────────────────────────
+    const access = await resolveAccess("design", designId);
+    if (!access) throw new Error("Design not found");
+
+    // ── Source type + capabilities ───────────────────────────────────────────
+    let rawSourceType: unknown = "inline";
+    const rawData = (access.resource as { data?: unknown }).data;
+    if (typeof rawData === "string") {
+      try {
+        const parsed: unknown = JSON.parse(rawData);
+        if (
+          parsed !== null &&
+          typeof parsed === "object" &&
+          "sourceType" in (parsed as object)
+        ) {
+          rawSourceType = (parsed as { sourceType: unknown }).sourceType;
+        }
+      } catch {
+        // Default to inline.
+      }
+    }
+
+    const sourceType = normalizeDesignSourceType(rawSourceType) ?? "inline";
+    const caps = resolveSourceCapabilities(sourceType);
+    const canResolveToFile = hasCapability(caps, "resolveNodeToFile");
+    const hasFullIndex = hasCapability(caps, "indexComponents");
+
+    // ── Fetch design file ────────────────────────────────────────────────────
+    const conditions = [
+      accessFilter(schema.designs, schema.designShares),
+      eq(schema.designFiles.designId, designId),
+      fileId
+        ? 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,
+      })
+      .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 html = await liveContent(file.id, file.content ?? "");
+
+    // ── Projection lookup ────────────────────────────────────────────────────
+    const codeLayerSource: CodeLayerSource = {
+      kind: "design-file",
+      designId: file.designId,
+      fileId: file.id,
+      filename: file.filename,
+    };
+
+    const projection = buildCodeLayerProjection(html, {
+      source: codeLayerSource,
+    });
+
+    const node = projection.nodes.find((n) => n.id === nodeId);
+    if (!node) {
+      throw new Error(
+        `Node "${nodeId}" not found in projection. Run get-code-layer-projection to list current node ids.`,
+      );
+    }
+
+    const name = componentNameFor(node);
+    if (!name) {
+      throw new Error(
+        `Node "${nodeId}" does not carry a data-agent-native-component attribute and is not a component root.`,
+      );
+    }
+
+    // ── Simple props from attributes ─────────────────────────────────────────
+    const observedProps = extractProps(node);
+    const alpineData =
+      typeof node.attributes["x-data"] === "string"
+        ? node.attributes["x-data"]
+        : undefined;
+
+    const instance: ComponentInstance = {
+      instanceId: node.id,
+      name,
+      props: observedProps,
+      alpineData,
+      selector: node.selector,
+      nodeId: node.id,
+    };
+
+    // ── Lookup persisted component_index row ─────────────────────────────────
+    const [indexRow] = await db
+      .select()
+      .from(schema.componentIndex)
+      .where(
+        and(
+          eq(schema.componentIndex.designId, designId),
+          eq(schema.componentIndex.name, name),
+        ),
+      )
+      .limit(1);
+
+    const persistedProps = parseJson<unknown[]>(indexRow?.props, []);
+    const persistedVariants = parseJson<Record<string, string[]>>(
+      indexRow?.variants,
+      {},
+    );
+    const persistedStories = parseJson<unknown[]>(indexRow?.stories, []);
+
+    // ── Source location (real-app only) ──────────────────────────────────────
+    // The bridge `resolveNodeToFile` op maps a node id to a source file + span.
+    // For inline designs the capability is `available` but resolves to the
+    // design file itself (no external source file).  We surface whatever we
+    // have from the index row.
+    const sourceLocation =
+      canResolveToFile && indexRow?.filePath
+        ? {
+            filePath: indexRow.filePath,
+            exportName: indexRow.exportName ?? undefined,
+          }
+        : undefined;
+
+    return {
+      designId,
+      nodeId,
+      sourceType,
+      instance,
+      name,
+      // Props: merge observed attribute props with richer persisted prop types
+      // when available.  Real-app callers get the full TS/cva prop table.
+      observedProps,
+      persistedProps,
+      persistedVariants,
+      persistedStories,
+      sourceLocation,
+      capabilities: {
+        canResolveToFile,
+        hasFullIndex,
+        canEditProps: true, // preview-only on inline; persists on real-app
+        ctaRequired: !hasFullIndex,
+        ctaMessage: !hasFullIndex
+          ? "Full prop controls (TypeScript prop types, cva variants, Storybook stories) require a connected Builder app. Connect Builder to unlock."
+          : undefined,
+      },
+    };
+  },
+});