@agent-native/core 0.85.7 → 0.86.1

package/corpus/templates/design/actions/create-fusion-app.ts

@@ -0,0 +1,202 @@
+/**
+ * create-fusion-app — start a brand-new full-app (fusion) design.
+ *
+ * Provisions a Builder Fusion branch (one branch per design) in the
+ * configured Builder branch project and hands the user's prompt to the
+ * Builder cloud agent to scaffold the app. The branch/container is not
+ * necessarily ready immediately — call `sync-fusion-app` to poll the
+ * container and pick up the preview URL once it boots.
+ *
+ * Gated behind `FULL_APP_BUILDING_ENABLED`. When Builder is not configured
+ * (no credentials or no branch project ID), returns the same graceful
+ * `{ status: "not-configured", cta, message }` shape as
+ * `migrate-inline-design-to-app` instead of throwing.
+ */
+
+import { defineAction } from "@agent-native/core";
+import {
+  runBuilderAgent,
+  resolveBuilderBranchProjectId,
+} from "@agent-native/core/server";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+import { assertAccess } 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 { resolveBuilderStatus } from "../shared/builder-app.js";
+import {
+  FULL_APP_BUILDING_ENABLED,
+  parseDesignDataBlob,
+  readFusionApp,
+  writeFusionApp,
+} from "../shared/full-app.js";
+
+const DEFAULT_BUILDER_APP_HOST = "https://builder.io";
+
+function resolveBuilderAppHost(): string {
+  return (
+    process.env.BUILDER_APP_HOST ||
+    process.env.BUILDER_PUBLIC_APP_HOST ||
+    DEFAULT_BUILDER_APP_HOST
+  );
+}
+
+function buildConnectUrl(origin: string): string {
+  const base = origin.replace(/\/+$/, "");
+  return `${base}/_agent-native/builder/connect`;
+}
+
+export default defineAction({
+  description:
+    "Create a brand-new full-app (fusion) design: provisions a Builder Fusion " +
+    "branch and hands the prompt to the Builder cloud agent to scaffold a real " +
+    "running app. Use this when the user wants a real app (not an HTML " +
+    "prototype) built from scratch for a design. Requires Builder.io to be " +
+    "connected with a branch project ID configured; when not configured " +
+    "returns a connect CTA — never throws. If the design already has a " +
+    "fusion app, returns the existing linkage instead of creating a second " +
+    "branch. The branch container may still be booting after this call — " +
+    "call sync-fusion-app to poll for the preview URL.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID to back with a full app."),
+    prompt: z
+      .string()
+      .min(1)
+      .describe(
+        "What app to build, in the user's own words (features, pages, data model, etc.).",
+      ),
+    branchName: z
+      .string()
+      .optional()
+      .describe(
+        "Optional branch name for the Builder agent to use. If omitted, Builder generates one.",
+      ),
+  }),
+  run: async ({ designId, prompt, branchName }) => {
+    if (!FULL_APP_BUILDING_ENABLED) {
+      throw new Error("Full app building is not enabled");
+    }
+
+    const access = await assertAccess("design", designId, "editor");
+    const design = access.resource as typeof schema.designs.$inferSelect;
+
+    // Already app-backed: don't create a second branch.
+    const existingApp = readFusionApp(design.data);
+    if (existingApp) {
+      return {
+        status: existingApp.status,
+        designId,
+        projectId: existingApp.projectId,
+        branchName: existingApp.branchName,
+        editorUrl: existingApp.editorUrl,
+        message:
+          `This design is already backed by fusion branch ` +
+          `"${existingApp.branchName}". Call sync-fusion-app to check its ` +
+          `status, or send-fusion-message to continue building on it.`,
+      };
+    }
+
+    const builderStatus = await resolveBuilderStatus();
+    if (!builderStatus.connected || !builderStatus.builderEnabled) {
+      const connectUrl = buildConnectUrl(
+        process.env.APP_URL ??
+          process.env.VITE_APP_URL ??
+          process.env.BETTER_AUTH_URL ??
+          "",
+      );
+      const appHost = resolveBuilderAppHost();
+
+      if (!builderStatus.connected) {
+        return {
+          status: "not-configured" as const,
+          designId,
+          cta: {
+            kind: "connect-builder" as const,
+            label: "Build a real app",
+            description:
+              "Connect Builder.io to build this design as a real running app " +
+              "with a live container, branches, and deploys.",
+            primaryAction: "Connect Builder.io",
+            connectUrl,
+          },
+          message:
+            "Builder is not connected. Call connect-builder-app to start " +
+            "the OAuth flow, then retry create-fusion-app.",
+        };
+      }
+
+      return {
+        status: "not-configured" as const,
+        designId,
+        cta: {
+          kind: "configure-project" as const,
+          label: "Configure Builder project",
+          description:
+            "Builder credentials are present but no branch project ID is set. " +
+            "Set DISPATCH_BUILDER_PROJECT_ID, BUILDER_BRANCH_PROJECT_ID, or " +
+            "BUILDER_PROJECT_ID to enable full app building.",
+          primaryAction: "Open Builder settings",
+          connectUrl: `${appHost}/account-settings`,
+        },
+        message:
+          "Builder credentials are configured but no branch project ID is set. " +
+          "Set DISPATCH_BUILDER_PROJECT_ID to enable full app building.",
+      };
+    }
+
+    const projectId = await resolveBuilderBranchProjectId();
+    if (!projectId) {
+      throw new Error(
+        "Builder branch project ID is not configured. " +
+          "Set DISPATCH_BUILDER_PROJECT_ID, BUILDER_BRANCH_PROJECT_ID, or " +
+          "BUILDER_PROJECT_ID and try again.",
+      );
+    }
+
+    const ownerEmail = getRequestUserEmail();
+    const preamble =
+      `You are building a brand-new full application for the design project ` +
+      `"${design.title}". This is a fresh app — there is no existing code to ` +
+      `preserve beyond what you generate. Build exactly what the user asks for ` +
+      `below.\n\n## User request\n\n${prompt}`;
+
+    const result = await runBuilderAgent({
+      prompt: preamble,
+      projectId,
+      branchName: branchName?.trim() || undefined,
+      userEmail: ownerEmail ?? undefined,
+    });
+
+    const now = new Date().toISOString();
+    const db = getDb();
+    const nextData = writeFusionApp(parseDesignDataBlob(design.data), {
+      projectId: result.projectId,
+      branchName: result.branchName,
+      editorUrl: result.url,
+      status: "building",
+      statusMessage:
+        "App is being generated. Call sync-fusion-app to check progress.",
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    await db
+      .update(schema.designs)
+      .set({ data: JSON.stringify(nextData), updatedAt: now })
+      .where(eq(schema.designs.id, designId));
+
+    return {
+      status: "building" as const,
+      designId,
+      projectId: result.projectId,
+      branchName: result.branchName,
+      editorUrl: result.url,
+      message:
+        `Started building "${design.title}" as a full app on branch ` +
+        `"${result.branchName}". Call sync-fusion-app to poll for the ` +
+        `preview URL once the container finishes booting.`,
+    };
+  },
+});

package/corpus/templates/design/actions/deploy-fusion-app.ts

@@ -0,0 +1,123 @@
+/**
+ * deploy-fusion-app — reserve a hosting slug (if needed) and trigger a hosted
+ * deploy of a fusion app's branch.
+ *
+ * On first deploy, derives a default `<slug>.builder.cloud` hosting slug from
+ * the design title unless the caller passes one explicitly. Reservation
+ * failures (slug already taken) surface clearly so the caller can retry with
+ * a different slug. Persists the reserved slug, deployed URL, and last deploy
+ * id/status on the fusion app linkage so get-fusion-deploy-status can poll
+ * without re-resolving them.
+ */
+
+import { defineAction } from "@agent-native/core";
+import {
+  deployFusionProject,
+  getFusionHostingUrl,
+  reserveFusionHostingSlug,
+} from "@agent-native/core/server";
+import { assertAccess } 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 {
+  FULL_APP_BUILDING_ENABLED,
+  parseDesignDataBlob,
+  readFusionApp,
+  writeFusionApp,
+} from "../shared/full-app.js";
+
+const MAX_SLUG_LENGTH = 40;
+
+function defaultSlugFromTitle(title: string, designId: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, MAX_SLUG_LENGTH)
+    .replace(/-+$/g, "");
+  return slug || `app-${designId.slice(0, 8)}`;
+}
+
+export default defineAction({
+  description:
+    "Deploy a fusion (full-app) design to a public hosted URL. Reserves a " +
+    "<slug>.builder.cloud hosting slug (derived from the design title if not " +
+    "already reserved and no slug is given) and triggers a hosted deploy of " +
+    "the branch. If the slug is already taken, the error will say so — retry " +
+    "with a different slug. Poll get-fusion-deploy-status for progress " +
+    "(queued -> building -> uploading -> deploying -> live | failed).",
+  schema: z.object({
+    designId: z.string().describe("Design project ID backed by a fusion app."),
+    slug: z
+      .string()
+      .optional()
+      .describe(
+        "Hosting slug to reserve (results in <slug>.builder.cloud). Omit to " +
+          "use the design's already-reserved slug, or derive one from the title.",
+      ),
+  }),
+  run: async ({ designId, slug }) => {
+    if (!FULL_APP_BUILDING_ENABLED) {
+      throw new Error("Full app building is not enabled");
+    }
+
+    const access = await assertAccess("design", designId, "editor");
+    const design = access.resource as typeof schema.designs.$inferSelect;
+    const fusionApp = readFusionApp(design.data);
+    if (!fusionApp) {
+      throw new Error(
+        "This design has no fusion app linkage. Call create-fusion-app first.",
+      );
+    }
+
+    const requestedSlug =
+      slug?.trim() ||
+      fusionApp.hostingSlug ||
+      defaultSlugFromTitle(design.title, designId);
+
+    let reservedSlug: string;
+    try {
+      const reservation = await reserveFusionHostingSlug({
+        projectId: fusionApp.projectId,
+        slug: requestedSlug,
+      });
+      reservedSlug = reservation.slug;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Could not reserve hosting slug "${requestedSlug}": ${message}. ` +
+          "Pass a different slug and try again.",
+      );
+    }
+
+    const deploy = await deployFusionProject({
+      projectId: fusionApp.projectId,
+      checkoutBranch: fusionApp.branchName,
+    });
+
+    const deployedUrl = getFusionHostingUrl(reservedSlug);
+    const now = new Date().toISOString();
+    const db = getDb();
+    const nextData = writeFusionApp(parseDesignDataBlob(design.data), {
+      ...fusionApp,
+      hostingSlug: reservedSlug,
+      deployedUrl,
+      lastDeployId: deploy.deployId,
+      lastDeployStatus: deploy.status,
+      updatedAt: now,
+    });
+    await db
+      .update(schema.designs)
+      .set({ data: JSON.stringify(nextData), updatedAt: now })
+      .where(eq(schema.designs.id, designId));
+
+    return {
+      deployId: deploy.deployId,
+      status: deploy.status,
+      url: deployedUrl,
+    };
+  },
+});

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

@@ -290,23 +290,20 @@ export default defineAction({
     if (changed) {
       // Mark agent presence + selection so live viewers can see where the
       // agent is working before the update arrives via collab.
+      //
+      // No resolvable DOM selector is available here (search-replace targets
+      // source text, not a stamped node), so we publish `selection: null`
+      // rather than a fabricated `[data-edit-target=...]` selector that could
+      // never resolve against the rendered iframe. Region attribution instead
+      // rides on the `{ kind: "text", quote }` recentEdits descriptor that
+      // `applyText(..., "agent")` auto-publishes from the content diff below —
+      // clients render a lingering highlight over the changed text.
       agentEnterDocument(file.id);
-      if (resolvedMode === "search-replace" && applied > 0) {
-        const firstSearch = edits?.[0]?.search;
-        agentUpdateSelection(file.id, {
-          selection: firstSearch
-            ? `[data-edit-target="${firstSearch.slice(0, 40)}"]`
-            : null,
-          editingFile: file.filename,
-          designId,
-        });
-      } else {
-        agentUpdateSelection(file.id, {
-          selection: null,
-          editingFile: file.filename,
-          designId,
-        });
-      }
+      agentUpdateSelection(file.id, {
+        selection: null,
+        editingFile: file.filename,
+        designId,
+      });
 
       try {
         await db

package/corpus/templates/design/actions/get-design-system.ts

@@ -1,4 +1,8 @@
 import { defineAction } from "@agent-native/core";
+import {
+  hydrateBuilderDesignSystemReference,
+  parseBuilderDesignSystemProxyReference,
+} from "@agent-native/core/server";
 import { resolveAccess } from "@agent-native/core/sharing";
 import { z } from "zod";
 
@@ -19,6 +23,22 @@ export default defineAction({
     }
 
     const row = access.resource;
+    const builderReference = parseBuilderDesignSystemProxyReference(row.data);
+    const builder = builderReference
+      ? await hydrateBuilderDesignSystemReference(builderReference).catch(
+          (error) => ({
+            ...builderReference,
+            docs: [],
+            tokenValues: {},
+            docCount: 0,
+            warning:
+              error instanceof Error
+                ? error.message
+                : "Builder design-system docs could not be loaded.",
+          }),
+        )
+      : null;
+
     return {
       id: row.id,
       title: row.title,
@@ -30,6 +50,7 @@ export default defineAction({
       visibility: row.visibility,
       createdAt: row.createdAt,
       updatedAt: row.updatedAt,
+      builder,
     };
   },
 });

package/corpus/templates/design/actions/get-fusion-deploy-status.ts

@@ -0,0 +1,86 @@
+/**
+ * get-fusion-deploy-status — read-only poll of a fusion app's last deploy.
+ *
+ * No DB writes: reads the persisted lastDeployId/deployedUrl off the fusion
+ * app linkage and asks Builder for the current deploy status.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { getFusionDeploys } from "@agent-native/core/server";
+import { accessFilter } 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 {
+  FULL_APP_BUILDING_ENABLED,
+  readFusionApp,
+} from "../shared/full-app.js";
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export default defineAction({
+  description:
+    "Read-only: check the status of a fusion (full-app) design's last hosted " +
+    "deploy (queued|building|migrating|uploading|deploying|live|failed|" +
+    "canceled). Call after deploy-fusion-app to poll for completion. Makes no " +
+    "database writes.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID backed by a fusion app."),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId }) => {
+    if (!FULL_APP_BUILDING_ENABLED) {
+      throw new Error("Full app building is not enabled");
+    }
+
+    const db = getDb();
+    const [design] = await db
+      .select({ data: schema.designs.data })
+      .from(schema.designs)
+      .where(
+        and(
+          accessFilter(schema.designs, schema.designShares),
+          eq(schema.designs.id, designId),
+        ),
+      )
+      .limit(1);
+    if (!design) {
+      const err = new Error("Design not found") as Error & {
+        statusCode: number;
+      };
+      err.statusCode = 404;
+      throw err;
+    }
+
+    const fusionApp = readFusionApp(design.data);
+    if (!fusionApp) {
+      throw new Error(
+        "This design has no fusion app linkage. Call create-fusion-app first.",
+      );
+    }
+    if (!fusionApp.lastDeployId) {
+      throw new Error(
+        "This fusion app has not been deployed yet. Call deploy-fusion-app first.",
+      );
+    }
+
+    const deploys = await getFusionDeploys({
+      projectId: fusionApp.projectId,
+      deployId: fusionApp.lastDeployId,
+    });
+    const deploy = deploys[0];
+    const status =
+      asString(deploy?.status) ?? fusionApp.lastDeployStatus ?? "unknown";
+
+    return {
+      deployId: fusionApp.lastDeployId,
+      status,
+      url: fusionApp.deployedUrl ?? null,
+    };
+  },
+});

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

@@ -1,7 +1,7 @@
 import { defineAction } from "@agent-native/core";
 import {
+  buildBuilderDesignSystemIndexFiles,
   startBuilderDesignSystemIndex,
-  type BuilderDesignSystemIndexFile,
 } from "@agent-native/core/server";
 import {
   getRequestOrgId,
@@ -11,50 +11,17 @@ import { z } from "zod";
 
 import { upsertBuilderProxyDesignSystem } from "../server/lib/builder-design-system-proxy.js";
 
-const MAX_CODE_FILES = 50;
-const MAX_TOTAL_CODE_BYTES = 2 * 1024 * 1024;
-
 const codeFileSchema = z.object({
   filename: z.string().trim().min(1).describe("File name or relative path"),
   content: z.string().describe("Raw text content of the code/design file"),
   mimeType: z.string().trim().optional().describe("Optional MIME type"),
 });
 
-function mimeTypeForFilename(filename: string, explicit?: string): string {
-  if (explicit?.trim()) return explicit.trim();
-  const lower = filename.toLowerCase();
-  if (lower.endsWith(".css")) return "text/css";
-  if (lower.endsWith(".json")) return "application/json";
-  if (lower.endsWith(".md") || lower.endsWith(".mdx")) return "text/markdown";
-  if (lower.endsWith(".html")) return "text/html";
-  if (lower.endsWith(".svg")) return "image/svg+xml";
-  return "text/plain";
-}
-
-function makeFiles(
-  codeFiles: Array<z.infer<typeof codeFileSchema>> | undefined,
-): BuilderDesignSystemIndexFile[] {
-  const encoder = new TextEncoder();
-  const files: BuilderDesignSystemIndexFile[] = [];
-  let totalBytes = 0;
-  for (const file of (codeFiles ?? []).slice(0, MAX_CODE_FILES)) {
-    const data = encoder.encode(file.content);
-    if (totalBytes + data.byteLength > MAX_TOTAL_CODE_BYTES) break;
-    totalBytes += data.byteLength;
-    files.push({
-      name: file.filename.replace(/^\/+/, "") || "code.txt",
-      data,
-      mimeType: mimeTypeForFilename(file.filename, file.mimeType),
-    });
-  }
-  return files;
-}
-
 export default defineAction({
   description:
-    "Start Builder design-system indexing from a GitHub repository and/or code files. " +
+    "Start Builder DSI design-system indexing from connected code, a GitHub repository, code/design files, and optional design.md guidance. " +
     "Use this instead of local import-code/import-github when the user wants a reusable brand kit or design system. " +
-    "Requires Builder.io to be connected; Builder owns the indexed design-system docs, generated guidance, and job state.",
+    "Requires Builder.io to be connected; Builder owns the indexed design-system docs, generated guidance, token/component extraction, and job state.",
   schema: z.object({
     projectName: z
       .string()
@@ -76,6 +43,12 @@ export default defineAction({
       .array(codeFileSchema)
       .optional()
       .describe("Optional inlined code/design files to upload to Builder"),
+    designMd: z
+      .string()
+      .optional()
+      .describe(
+        "Optional design.md guidance to upload to Builder DSI alongside Figma/code sources",
+      ),
   }),
   run: async ({
     projectName,
@@ -83,8 +56,12 @@ export default defineAction({
     githubRepoUrl,
     connectedProjectId,
     codeFiles,
+    designMd,
   }) => {
-    const files = makeFiles(codeFiles);
+    const files = buildBuilderDesignSystemIndexFiles({
+      codeFiles,
+      designMd,
+    });
     const result = await startBuilderDesignSystemIndex({
       projectName,
       description,

package/corpus/templates/design/actions/list-fusion-edits.ts

@@ -0,0 +1,96 @@
+/**
+ * list-fusion-edits — read-only list of queued fusion edit instructions for a
+ * design.
+ *
+ * Viewer access is sufficient since this is a read. Returns edits ordered
+ * oldest-first (the order apply-fusion-edits will present them to the app
+ * agent) plus a pendingCount convenience field.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { accessFilter } from "@agent-native/core/sharing";
+import { and, asc, 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 { FULL_APP_BUILDING_ENABLED } from "../shared/full-app.js";
+
+function parseTarget(raw: string | null): Record<string, unknown> | null {
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export default defineAction({
+  description:
+    "List queued fusion (full-app) visual edit instructions for a design, " +
+    "oldest first. Optionally filter by status (pending|sent|error). Use to " +
+    "review what's queued before calling apply-fusion-edits, or to check the " +
+    "outcome of a previous batch.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID backed by a fusion app."),
+    status: z
+      .enum(["pending", "sent", "error"])
+      .optional()
+      .describe("Filter to edits with this status. Omit to return all."),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId, status }) => {
+    if (!FULL_APP_BUILDING_ENABLED) {
+      throw new Error("Full app building is not enabled");
+    }
+
+    const db = getDb();
+
+    const [design] = await db
+      .select({ id: schema.designs.id })
+      .from(schema.designs)
+      .where(
+        and(
+          accessFilter(schema.designs, schema.designShares),
+          eq(schema.designs.id, designId),
+        ),
+      )
+      .limit(1);
+    if (!design) {
+      const err = new Error("Design not found") as Error & {
+        statusCode: number;
+      };
+      err.statusCode = 404;
+      throw err;
+    }
+
+    const conditions = [eq(schema.designFusionEdits.designId, designId)];
+    if (status) conditions.push(eq(schema.designFusionEdits.status, status));
+
+    const rows = await db
+      .select()
+      .from(schema.designFusionEdits)
+      .where(and(...conditions))
+      .orderBy(asc(schema.designFusionEdits.createdAt));
+
+    const edits = rows.map((row) => ({
+      id: row.id,
+      instruction: row.instruction,
+      target: parseTarget(row.target),
+      status: row.status,
+      screenFileId: row.screenFileId,
+      batchId: row.batchId,
+      error: row.error,
+      sentAt: row.sentAt,
+      createdAt: row.createdAt,
+    }));
+
+    const pendingCount = rows.filter((row) => row.status === "pending").length;
+
+    return { edits, pendingCount };
+  },
+});