@agent-native/core 0.80.9 → 0.80.11

package/corpus/templates/design/actions/capture-design-state.ts

@@ -0,0 +1,224 @@
+import { defineAction } from "@agent-native/core";
+import {
+  getRequestOrgId,
+  getRequestUserEmail,
+} from "@agent-native/core/server/request-context";
+import { assertAccess } from "@agent-native/core/sharing";
+import { eq } from "drizzle-orm";
+import { nanoid } from "nanoid";
+import { z } from "zod";
+
+import { getDb, schema } from "../server/db/index.js";
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import { hasCapability } from "../shared/design-source-capabilities.js";
+import type { DesignSourceCapabilities } from "../shared/design-source-capabilities.js";
+
+/**
+ * Resolve the capabilities for the design's source type.
+ * Falls back to inline capabilities when not present in stored data.
+ */
+function resolveCapabilities(
+  designData: string | null,
+): DesignSourceCapabilities | null {
+  if (!designData) return null;
+  try {
+    const parsed = JSON.parse(designData) as Record<string, unknown>;
+    if (parsed.capabilities && typeof parsed.capabilities === "object") {
+      return parsed.capabilities as DesignSourceCapabilities;
+    }
+  } catch {
+    // ignore parse errors
+  }
+  return null;
+}
+
+/**
+ * Maximum serialised size of a captured/replayed `captureData` payload.
+ * Captured DOM snapshots are arbitrary caller markup; cap them so a single
+ * capture can't bloat the design row (and the shareable content it feeds).
+ */
+const CAPTURE_DATA_MAX_BYTES = 256 * 1024; // 256KB
+
+/**
+ * Strip stored-XSS vectors out of an HTML/markup string before it is persisted
+ * and later replayed into shareable design content. Mirrors the framework's
+ * text-edit HTML sanitiser: removes script/style/iframe/object/embed/link/meta/
+ * base tags, inline `on*` handlers, and `javascript:` / `vbscript:` / `data:`
+ * URLs in `href` / `src` / `xlink:href`.
+ */
+function sanitizeMarkup(html: string): string {
+  return html
+    .replace(
+      /<\s*(script|style|iframe|object|embed|link|meta|base)\b[\s\S]*?<\s*\/\s*\1\s*>/gi,
+      "",
+    )
+    .replace(
+      /<\s*(script|style|iframe|object|embed|link|meta|base)\b[^>]*\/?\s*>/gi,
+      "",
+    )
+    .replace(/\s+on[A-Za-z]+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/g, "")
+    .replace(
+      /\s+(href|src|xlink:href)\s*=\s*(?:(["'])\s*(?:javascript|vbscript|data):[\s\S]*?\2|(?:javascript|vbscript|data):[^\s>]*)/gi,
+      "",
+    );
+}
+
+/**
+ * A string "looks like markup" — and is therefore worth sanitising — when it
+ * contains an angle-bracket tag opener or an Alpine `x-`/`@`/`:` binding that
+ * could carry script. Plain data strings (route names, ids) are left untouched.
+ */
+function looksLikeMarkup(value: string): boolean {
+  return /<[a-zA-Z!/]/.test(value) || value.includes("</");
+}
+
+/**
+ * Recursively sanitise every string value inside a captured/replayed
+ * `captureData` object (e.g. `domHtml`, `domSnapshot`, `x-data` markup) so no
+ * untrusted DOM is persisted raw. Non-string leaves pass through unchanged.
+ */
+function sanitizeCaptureData(value: unknown): unknown {
+  if (typeof value === "string") {
+    return looksLikeMarkup(value) ? sanitizeMarkup(value) : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => sanitizeCaptureData(entry));
+  }
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      out[k] = sanitizeCaptureData(v);
+    }
+    return out;
+  }
+  return value;
+}
+
+export default defineAction({
+  description:
+    "Capture the running app's current route, props, and API data into a " +
+    "design_state row of kind 'capture'. Requires the design's source to " +
+    "advertise the 'captureState' capability (localhost and fusion tiers). " +
+    "The bridge's captureState operation is called and the result is persisted " +
+    "as a new design state that can be loaded in the States panel. " +
+    "For inline designs without a live bridge, use create-design-state instead.",
+  schema: z.object({
+    designId: z.string().describe("Design project ID"),
+    name: z
+      .string()
+      .min(1)
+      .describe(
+        "Human-readable label for the captured state (e.g. 'Checkout – empty cart', 'Profile – logged in').",
+      ),
+    breakpoint: z
+      .enum(["auto", "desktop", "tablet", "mobile"])
+      .default("auto")
+      .describe("Breakpoint context active at the time of capture."),
+    sourceRef: z
+      .string()
+      .optional()
+      .describe(
+        "Source connection ref (routeId for localhost/fusion). Omit if the design has only one source.",
+      ),
+    route: z
+      .string()
+      .optional()
+      .describe("App route path at capture time (e.g. '/checkout')."),
+    captureData: z
+      .preprocess(
+        (v) => (typeof v === "string" ? JSON.parse(v) : v),
+        z.record(z.string(), z.unknown()),
+      )
+      .describe(
+        "The payload returned by the bridge captureState op — typically " +
+          "{ route, props, queryParams, apiResponses, domSnapshot }. " +
+          "The caller (UI or agent) must have already invoked the bridge and pass the result here.",
+      ),
+    previewRef: z
+      .string()
+      .optional()
+      .describe(
+        "Snapshot image URL or design_version id produced immediately before " +
+          "or after the capture (optional).",
+      ),
+  }),
+  run: async ({
+    designId,
+    name,
+    breakpoint,
+    sourceRef,
+    route,
+    captureData,
+    previewRef,
+  }) => {
+    await assertAccess("design", designId, "editor");
+
+    const db = getDb();
+
+    // Capability gate — captureState must be available for this design source.
+    const [design] = await db
+      .select({ data: schema.designs.data })
+      .from(schema.designs)
+      .where(eq(schema.designs.id, designId))
+      .limit(1);
+
+    if (!design) {
+      throw new Error(`Design '${designId}' not found.`);
+    }
+
+    const caps = resolveCapabilities(design.data);
+    if (caps !== null && !hasCapability(caps, "captureState")) {
+      throw new Error(
+        "The design's source does not support captureState. " +
+          "Connect Builder or a localhost bridge to enable live captures.",
+      );
+    }
+
+    const id = nanoid();
+    const now = new Date().toISOString();
+    const ownerEmail = getRequestUserEmail();
+    if (!ownerEmail) throw new Error("no authenticated user");
+    const orgId = getRequestOrgId();
+
+    // Sanitise captured DOM/markup (stored-XSS guard) and enforce a size cap so
+    // a single capture can't bloat the row / the shareable content it feeds.
+    const sanitizedCaptureData = sanitizeCaptureData(captureData);
+    const captureDataJson = JSON.stringify(sanitizedCaptureData);
+    if (Buffer.byteLength(captureDataJson, "utf8") > CAPTURE_DATA_MAX_BYTES) {
+      throw new Error(
+        `captureData exceeds the ${Math.round(
+          CAPTURE_DATA_MAX_BYTES / 1024,
+        )}KB limit. Capture a smaller DOM snapshot or trim the payload.`,
+      );
+    }
+
+    await db.insert(schema.designState).values({
+      id,
+      designId,
+      sourceRef: sourceRef ?? null,
+      name,
+      kind: "capture",
+      breakpoint,
+      route: route ?? null,
+      fixtureData: null,
+      captureData: captureDataJson,
+      previewRef: previewRef ?? null,
+      createdAt: now,
+      updatedAt: now,
+      ownerEmail,
+      orgId,
+    });
+
+    return {
+      id,
+      designId,
+      name,
+      kind: "capture",
+      breakpoint,
+      route: route ?? null,
+      sourceRef: sourceRef ?? null,
+      previewRef: previewRef ?? null,
+      createdAt: now,
+    };
+  },
+});

package/corpus/templates/design/actions/connect-builder-app.ts

@@ -0,0 +1,162 @@
+/**
+ * connect-builder-app — return the Builder connection state / CTA payload for
+ * a design so the UI can render the appropriate inline card.
+ *
+ * This action intentionally does NOT start the OAuth / cli-auth flow; the
+ * existing `connect-builder` agent-chat tool owns that flow and renders the
+ * interactive card in chat.  What this action does instead:
+ *
+ * 1. Check whether Builder is currently configured (credentials + project ID)
+ *    via the shared `resolveBuilderStatus` helper (no credential values leak).
+ * 2. Return a structured payload the UI can use to decide whether to render
+ *    an "already connected" summary, a "connect to unlock" CTA, or a
+ *    "Builder enabled — ready to migrate" state.
+ *
+ * The `connectUrl` field is the pre-built URL that opens the Builder cli-auth
+ * popup from the current app origin (same shape the agent-chat plugin returns
+ * in the `kind: "connect-builder-card"` tool result).  The UI should open this
+ * in a popup and poll `/builder/status` for completion, matching the existing
+ * connect flow.
+ *
+ * Gate: any design the caller can view is sufficient — the action is read-only
+ * and returns only connection-level metadata, not design content.
+ */
+
+import { defineAction } from "@agent-native/core";
+import { getBuilderBranchProjectId } from "@agent-native/core/server";
+import { getRequestContext } from "@agent-native/core/server/request-context";
+import { resolveAccess } from "@agent-native/core/sharing";
+import { z } from "zod";
+
+import "../server/db/index.js"; // ensure registerShareableResource runs
+import { resolveBuilderStatus } from "../shared/builder-app.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** The default Builder app host — mirrors the constant in builder-browser.ts. */
+const DEFAULT_BUILDER_APP_HOST = "https://builder.io";
+
+/** Resolve the Builder app host from env, matching core builder-browser.ts. */
+function resolveBuilderAppHost(): string {
+  return (
+    process.env.BUILDER_APP_HOST ||
+    process.env.BUILDER_PUBLIC_APP_HOST ||
+    DEFAULT_BUILDER_APP_HOST
+  );
+}
+
+/**
+ * Build the connect URL for the current deployment's origin.
+ * Mirrors the shape returned by `getBuilderBrowserConnectUrl` in core, but
+ * without requiring the H3 event — uses the request-context origin instead.
+ */
+function buildConnectUrl(origin: string): string {
+  const base = origin.replace(/\/+$/, "");
+  return `${base}/_agent-native/builder/connect`;
+}
+
+// ---------------------------------------------------------------------------
+// Action
+// ---------------------------------------------------------------------------
+
+export default defineAction({
+  description:
+    "Return the Builder connection state and CTA payload for a design. " +
+    "Use this to check whether Builder is configured before offering the " +
+    "'Make it real' upgrade flow. Returns { connected, builderEnabled, " +
+    "connectUrl, appHost, branchProjectId } so the UI can render the correct " +
+    "inline card without making a separate status fetch. " +
+    "When connected is false, direct the user to the connectUrl to start the " +
+    "Builder OAuth flow. When builderEnabled is true, the Builder cloud agent " +
+    "can accept a migration job via migrate-inline-design-to-app.",
+  schema: z.object({
+    designId: z
+      .string()
+      .describe("Design project ID to check Builder connection for"),
+  }),
+  readOnly: true,
+  http: { method: "GET" },
+  run: async ({ designId }) => {
+    // Require at least viewer access so unauthenticated callers cannot
+    // probe Builder connection state.
+    const access = await resolveAccess("design", designId);
+    if (!access) {
+      throw new Error("Design not found");
+    }
+
+    const status = await resolveBuilderStatus();
+
+    // Resolve the connect URL from the current request origin so it points
+    // to this exact deployment (same origin as the signed connect token the
+    // server mints for cli-auth flows).
+    const origin = getRequestContext()?.requestOrigin ?? "";
+    const connectUrl = buildConnectUrl(origin);
+
+    const appHost = resolveBuilderAppHost();
+
+    // Surface the env-level branch project id for informational use only.
+    // (Credential values are never included.)
+    const branchProjectId =
+      status.branchProjectId || getBuilderBranchProjectId() || undefined;
+
+    if (!status.connected) {
+      return {
+        connected: false,
+        builderEnabled: false,
+        connectUrl,
+        appHost,
+        branchProjectId,
+        cta: {
+          kind: "connect-builder" as const,
+          label: "Make this a real app",
+          description:
+            "Connect Builder.io to unlock React components, live props, " +
+            "data states, branches, and one-click deploys.",
+          primaryAction: "Connect Builder.io",
+          connectUrl,
+        },
+        message:
+          "Builder is not connected. Open connectUrl to start the OAuth flow.",
+      };
+    }
+
+    if (!status.builderEnabled) {
+      return {
+        connected: true,
+        builderEnabled: false,
+        connectUrl,
+        appHost,
+        branchProjectId,
+        cta: {
+          kind: "configure-project" as const,
+          label: "Configure Builder project",
+          description:
+            "Builder credentials are present but no branch project is " +
+            "configured. Set DISPATCH_BUILDER_PROJECT_ID, " +
+            "BUILDER_BRANCH_PROJECT_ID, or BUILDER_PROJECT_ID to enable " +
+            "the cloud agent.",
+          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 cloud agent migration.",
+      };
+    }
+
+    // Fully configured — ready for migration.
+    return {
+      connected: true,
+      builderEnabled: true,
+      connectUrl,
+      appHost,
+      branchProjectId,
+      cta: null,
+      message:
+        "Builder is connected and cloud agents are available. " +
+        "Call migrate-inline-design-to-app to generate a real React app branch.",
+    };
+  },
+});