@agent-native/core 0.80.9 → 0.80.11

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/get-component-details.ts

@@ -0,0 +1,251 @@
+/**
+ * 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,
+  componentNodeIdMatches,
+  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");
+    const canEditProps =
+      sourceType === "inline" || hasCapability(caps, "applyEdit");
+    const ctaRequired = !hasFullIndex || !canEditProps;
+    const ctaMessage = !hasFullIndex
+      ? "Full prop controls (TypeScript prop types, cva variants, Storybook stories) require a connected Builder app. Connect Builder to unlock."
+      : !canEditProps
+        ? "Prop write-back requires the bridge applyEdit capability. Preview controls remain available until source write hardening is enabled."
+        : undefined;
+
+    // ── 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) =>
+      componentNodeIdMatches(n, 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,
+    };
+
+    // ── 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,
+        ctaRequired,
+        ctaMessage,
+      },
+    };
+  },
+});