@agent-native/core 0.80.9 → 0.80.11

package/corpus/templates/design/shared/builder-app.ts

@@ -0,0 +1,297 @@
+/**
+ * Builder app helpers for the Design Studio.
+ *
+ * Provides two capabilities:
+ *
+ * 1. **Connection status** — resolve whether Builder is configured for the
+ *    current request (credentials + project ID), without duplicating Builder
+ *    auth logic.  Delegates entirely to the core `resolveBuilderCredentials` /
+ *    `resolveIsBuilderBranchingEnabled` helpers; no credential values are
+ *    surfaced in return types.
+ *
+ * 2. **Migration seed** — build the prompt seed handed to the Builder cloud
+ *    agent when migrating an inline Alpine/HTML design to a real React + Tailwind
+ *    app.  The seed carries:
+ *      - The design's semantic HTML (up to `MAX_HTML_BYTES` per file).
+ *      - The `:root` CSS custom-property block extracted from each file.
+ *      - Any Brand Kit token summary from the linked design system.
+ *      - Human-readable migration instructions for the Builder cloud agent.
+ *
+ * Nothing in this module calls the Builder API directly.  API calls happen in
+ * `migrate-inline-design-to-app.ts` (action) via `runBuilderAgent`.
+ *
+ * Security note: credential values are never included in return types or seed
+ * content.  The `resolveBuilderStatus` function returns only boolean flags and
+ * the pre-built `connectUrl` from the core browser helpers.
+ */
+
+import {
+  resolveBuilderBranchProjectId,
+  resolveIsBuilderBranchingEnabled,
+} from "@agent-native/core/server";
+import { resolveHasCompleteBuilderConnection } from "@agent-native/core/server";
+import { getRequestUserEmail } from "@agent-native/core/server/request-context";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface BuilderConnectionStatus {
+  /** True when Builder credentials are configured and valid. */
+  connected: boolean;
+  /** True when a Builder branch project is also configured (= agents can run). */
+  builderEnabled: boolean;
+  /** The resolved Builder branch project ID, empty string when not configured. */
+  branchProjectId: string;
+  /** The email of the currently authenticated user (for routing the Builder job). */
+  ownerEmail: string | null;
+}
+
+export interface MigrationSeed {
+  /**
+   * The full migration prompt to hand to `runBuilderAgent`.
+   * Contains the design HTML, extracted CSS vars, token summary, and
+   * detailed instructions for the Builder cloud agent.
+   */
+  prompt: string;
+  /**
+   * The number of design files included in the seed (capped at
+   * `MAX_SEED_FILES`).
+   */
+  fileCount: number;
+  /**
+   * Total HTML bytes included in the seed (before any truncation).
+   */
+  totalBytes: number;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Maximum number of files to include in the migration seed.
+ * Inline designs rarely exceed this; the cap keeps the Builder prompt
+ * within a safe token budget.
+ */
+const MAX_SEED_FILES = 10;
+
+/**
+ * Maximum bytes per HTML file included in the migration seed.
+ * Files larger than this are truncated with an ellipsis notice so the
+ * Builder agent still sees the overall structure without exceeding its
+ * prompt limit.
+ */
+const MAX_HTML_BYTES_PER_FILE = 80_000;
+
+// ---------------------------------------------------------------------------
+// Connection status
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the Builder connection status for the current request context.
+ *
+ * Delegates to core helpers (`resolveHasCompleteBuilderConnection`,
+ * `resolveIsBuilderBranchingEnabled`, `resolveBuilderBranchProjectId`) so
+ * credential resolution lives in one place and is never duplicated here.
+ *
+ * Usage:
+ * ```ts
+ * const status = await resolveBuilderStatus();
+ * if (!status.builderEnabled) {
+ *   return { cta: "connect-builder" };
+ * }
+ * ```
+ */
+export async function resolveBuilderStatus(): Promise<BuilderConnectionStatus> {
+  const [connected, builderEnabled, branchProjectId] = await Promise.all([
+    resolveHasCompleteBuilderConnection(),
+    resolveIsBuilderBranchingEnabled(),
+    resolveBuilderBranchProjectId(),
+  ]);
+
+  return {
+    connected,
+    builderEnabled,
+    branchProjectId,
+    ownerEmail: getRequestUserEmail() ?? null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CSS-var extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the `:root` block(s) from a raw HTML/CSS string.
+ *
+ * Returns only the lines inside `:root { … }` declarations to keep the
+ * migration seed focused on custom-property tokens rather than the full
+ * stylesheet.  Falls back to the empty string when no `:root` block is found.
+ */
+function extractRootCssVars(html: string): string {
+  // Match one or more :root { … } blocks (non-greedy, handles multi-block files).
+  const matches = [...html.matchAll(/:root\s*\{([^}]*)\}/g)];
+  if (matches.length === 0) return "";
+
+  const lines: string[] = [];
+  for (const match of matches) {
+    const block = match[1] ?? "";
+    for (const line of block.split("\n")) {
+      const trimmed = line.trim();
+      // Only include CSS custom property declarations (--var: value;).
+      if (trimmed.startsWith("--") && trimmed.includes(":")) {
+        lines.push(`  ${trimmed}`);
+      }
+    }
+  }
+  return lines.length > 0 ? `:root {\n${lines.join("\n")}\n}` : "";
+}
+
+// ---------------------------------------------------------------------------
+// Migration seed builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the migration seed prompt for the Builder cloud agent.
+ *
+ * @param params.title - Human-readable design title (used in the prompt header).
+ * @param params.files - Current design files (id + filename + content + fileType).
+ * @param params.resolvedCssVars - Resolved CSS-var → value map from tweak selections.
+ * @param params.brandKitSummary - Optional human-readable token summary from the
+ *   linked design system (e.g. from `index-design-tokens`).
+ *
+ * The caller is responsible for fetching the design snapshot first.  This
+ * function is pure (no DB or network calls) so it is easy to test and reuse.
+ */
+export function buildMigrationSeed(params: {
+  title: string;
+  files: Array<{
+    filename: string;
+    content: string;
+    fileType: string;
+  }>;
+  resolvedCssVars?: Record<string, string>;
+  brandKitSummary?: string;
+}): MigrationSeed {
+  const { title, files, resolvedCssVars, brandKitSummary } = params;
+
+  // Limit file count.
+  const seedFiles = files.slice(0, MAX_SEED_FILES);
+  let totalBytes = 0;
+
+  // Build per-file sections.
+  const fileSections: string[] = [];
+  for (const file of seedFiles) {
+    const rawBytes = new TextEncoder().encode(file.content).length;
+    totalBytes += rawBytes;
+
+    let content = file.content;
+    let truncationNote = "";
+    if (rawBytes > MAX_HTML_BYTES_PER_FILE) {
+      content = file.content.slice(0, MAX_HTML_BYTES_PER_FILE);
+      truncationNote = `\n<!-- [TRUNCATED: original file was ${rawBytes} bytes; only the first ${MAX_HTML_BYTES_PER_FILE} bytes are shown] -->`;
+    }
+
+    // Extract :root CSS vars from each file for the token block.
+    const cssVars = extractRootCssVars(content);
+
+    const section = [
+      `### File: ${file.filename}`,
+      "```html",
+      content,
+      truncationNote,
+      "```",
+      ...(cssVars
+        ? [
+            "",
+            "**Extracted CSS custom properties (design tokens):**",
+            "```css",
+            cssVars,
+            "```",
+          ]
+        : []),
+    ]
+      .filter((l) => l !== "")
+      .join("\n");
+
+    fileSections.push(section);
+  }
+
+  // Build the resolved CSS vars block (from tweak selections).
+  let resolvedVarsBlock = "";
+  if (resolvedCssVars && Object.keys(resolvedCssVars).length > 0) {
+    const lines = Object.entries(resolvedCssVars)
+      .map(([k, v]) => `  ${k}: ${v};`)
+      .join("\n");
+    resolvedVarsBlock = [
+      "",
+      "## User-tuned token overrides (apply these values in the real app)",
+      "```css",
+      `:root {\n${lines}\n}`,
+      "```",
+    ].join("\n");
+  }
+
+  // Brand Kit summary block.
+  const brandKitBlock =
+    brandKitSummary && brandKitSummary.trim()
+      ? [
+          "",
+          "## Brand Kit / Design System tokens",
+          brandKitSummary.trim(),
+        ].join("\n")
+      : "";
+
+  // Build the full prompt.
+  const omittedFilesNote =
+    files.length > MAX_SEED_FILES
+      ? `\n> Note: ${files.length - MAX_SEED_FILES} additional file(s) were omitted to stay within the prompt limit.\n`
+      : "";
+
+  const prompt = [
+    `# Migrate inline design to React app: "${title}"`,
+    "",
+    "You are a Builder cloud agent. The user has an inline Alpine.js / Tailwind HTML prototype",
+    "that they want to migrate to a real React + TypeScript + Tailwind app.",
+    "",
+    "## Your task",
+    "1. Convert the HTML prototype below into a production-quality React + TypeScript + Tailwind",
+    "   application, preserving the visual design and UX faithfully.",
+    "2. Map Alpine.js `x-data` / `x-show` / `x-bind` patterns to React state, conditional",
+    "   rendering, and event handlers.",
+    "3. Extract inline styles and repeated patterns into reusable React components with",
+    "   Tailwind classes.  Preserve the `:root` CSS custom properties as a `globals.css` file",
+    "   and wire them into the Tailwind theme config.",
+    "4. Carry all design tokens (color, typography, spacing, radius) from the `:root` block",
+    "   into the generated `globals.css` and `tailwind.config.ts` so the visual identity is",
+    "   identical to the original prototype.",
+    "5. Do not introduce placeholder data or lorem ipsum.  Keep the structural content",
+    "   from the original design.",
+    "6. Use shadcn/ui primitives (Button, Card, Dialog, Input, etc.) where the HTML uses",
+    "   semantically equivalent patterns.",
+    "7. The app must compile and render without errors.",
+    "",
+    "## Source design files",
+    omittedFilesNote,
+    ...fileSections,
+    resolvedVarsBlock,
+    brandKitBlock,
+    "",
+    "## Output expectations",
+    "- A fully working React app in the current project branch.",
+    "- `src/app/globals.css` containing all `:root` CSS custom properties from above.",
+    "- `tailwind.config.ts` wiring those vars into the Tailwind theme.",
+    "- At least one page component that renders the migrated design.",
+    "- All Alpine `x-data` patterns converted to React hooks / state.",
+    "- All Tailwind CDN classes preserved as-is in JSX.",
+  ]
+    .filter((l) => l !== undefined && l !== null)
+    .join("\n");
+
+  return {
+    prompt,
+    fileCount: seedFiles.length,
+    totalBytes,
+  };
+}

package/corpus/templates/design/shared/capability-resolver.ts

@@ -0,0 +1,123 @@
+/**
+ * Source capability resolver — pure, no DB, no side effects.
+ *
+ * Maps a `DesignSourceType` (inline | localhost | fusion) to the concrete
+ * `DesignSourceCapabilities` map.  Callers that have already proven a richer
+ * capability set (e.g. a localhost bridge that has verified `readFile`) should
+ * override the defaults after calling this function.
+ *
+ * The canonical tier semantics live in `DESIGN-STUDIO-PLAN.md` §5:
+ *
+ * - **inline** — HTML/CSS preview + controlled writes via the deterministic
+ *   `replace-document-content` / `apply-tweaks` path; `previewMotion` + Tier-A
+ *   `writeMotion` (managed `<style data-agent-native-motion>` block) and CSS-var
+ *   token edits are available without a file-write bridge.
+ * - **localhost** — starts read-only/preview-only; `readFile` / `applyEdit` /
+ *   `writeFile` and real-app capabilities (`indexComponents`, `writeTokens`)
+ *   become `available` only after bridge hardening.
+ * - **fusion (Builder)** — starts preview-only; unlocks the full set
+ *   (`indexComponents`, `writeTokens`, `writeMotion`, `branch`, `deploy`) once
+ *   the bridge proves capabilities.
+ *
+ * The UI must never infer write ability from `sourceType` alone; it must always
+ * read the capability map returned here (or an overridden variant).
+ */
+
+import {
+  available,
+  planned,
+  unavailable,
+  INLINE_DEFAULT_CAPABILITIES,
+  LOCALHOST_DEFAULT_CAPABILITIES,
+  FUSION_DISCONNECTED_CAPABILITIES,
+  FUSION_CONNECTED_CAPABILITIES,
+  type DesignSourceCapabilities,
+} from "./design-source-capabilities";
+import type { DesignSourceType } from "./source-mode";
+
+/**
+ * Return the default `DesignSourceCapabilities` for the given `sourceType`.
+ *
+ * These are **defaults** — they represent the conservative starting point for
+ * a freshly connected source.  Callers that have runtime evidence of a richer
+ * capability set (e.g. a bridge handshake that confirmed `readFile` works)
+ * should spread/override specific entries rather than calling this function
+ * again.
+ *
+ * ```ts
+ * const caps = resolveSourceCapabilities(design.sourceType);
+ * // Override after bridge handshake:
+ * const proven: DesignSourceCapabilities = {
+ *   ...caps,
+ *   readFile: available("Bridge verified"),
+ * };
+ * ```
+ *
+ * @param sourceType - The source type from `DesignSourceType`.
+ * @returns A read-only snapshot of the default capability map.
+ */
+export function resolveSourceCapabilities(
+  sourceType: DesignSourceType,
+): DesignSourceCapabilities {
+  switch (sourceType) {
+    case "inline":
+      return INLINE_DEFAULT_CAPABILITIES;
+    case "localhost":
+      return LOCALHOST_DEFAULT_CAPABILITIES;
+    case "fusion":
+      // Conservative default for fusion when connection status is unknown.
+      // Use resolveFusionCapabilities(connected) when Builder connection status
+      // is known, or resolveDescriptorCapabilities() which honours the
+      // descriptor's proven capabilities map.
+      return FUSION_DISCONNECTED_CAPABILITIES;
+    default: {
+      // Exhaustive check — TypeScript will catch unhandled variants.
+      const _exhaustive: never = sourceType;
+      void _exhaustive;
+      // Fallback: safest option is inline (no file writes, no real-app ops).
+      return INLINE_DEFAULT_CAPABILITIES;
+    }
+  }
+}
+
+/**
+ * Return the correct `DesignSourceCapabilities` for a **fusion** source based
+ * on the current Builder connection status.
+ *
+ * Per DESIGN-STUDIO-PLAN.md §5:
+ * - **Not connected** (`connected = false`): preview-only.  No real-app write
+ *   operations (`indexComponents`, `branch`, `deployPreview`, `deploy`,
+ *   `writeFile`, `writeTokens`, `writeMotion`) are available.
+ * - **Connected** (`connected = true`): `indexComponents`, `branch`,
+ *   `deployPreview`, and `deploy` are **available**.  Source writes
+ *   (`writeFile`, `writeTokens`, `writeMotion`) remain **planned** until
+ *   bridge hardening is complete.
+ *
+ * Usage (in an action that already resolved Builder status):
+ * ```ts
+ * import { resolveFusionCapabilities } from "../shared/capability-resolver.js";
+ * import { resolveIsBuilderBranchingEnabled } from "@agent-native/core/server";
+ *
+ * const connected = await resolveIsBuilderBranchingEnabled();
+ * const caps = resolveFusionCapabilities(connected);
+ * if (hasCapability(caps, "branch")) { ... }
+ * ```
+ *
+ * @param connected - `true` when Builder credentials are configured AND a
+ *   branch project is set (i.e. `resolveIsBuilderBranchingEnabled()` returns
+ *   `true`).
+ */
+export function resolveFusionCapabilities(
+  connected: boolean,
+): DesignSourceCapabilities {
+  return connected
+    ? FUSION_CONNECTED_CAPABILITIES
+    : FUSION_DISCONNECTED_CAPABILITIES;
+}
+
+// Re-export factory helpers so callers only need this module to build
+// capability maps with override entries.
+export { available, planned, unavailable };
+export type { DesignSourceCapabilities };
+// Re-export the fusion constants for callers that prefer direct access.
+export { FUSION_CONNECTED_CAPABILITIES, FUSION_DISCONNECTED_CAPABILITIES };

package/corpus/templates/design/shared/capture-sanitize.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared sanitization helpers for design state capture payloads.
+ *
+ * Used by both create-design-state and capture-design-state to enforce a
+ * consistent stored-XSS guard and size cap before persisting arbitrary
+ * caller-supplied markup / DOM snapshots into `design_state` rows.
+ */
+
+/**
+ * Maximum serialised size of a captured/replayed `captureData` or
+ * `fixtureData` payload. Caps single-row size to protect the DB and the
+ * shareable content each row feeds.
+ */
+export const CAPTURE_DATA_MAX_BYTES = 256 * 1024; // 256 KB
+
+/**
+ * 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`.
+ */
+export 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.
+ */
+export function looksLikeMarkup(value: string): boolean {
+  return /<[a-zA-Z!/]/.test(value) || value.includes("</");
+}
+
+/**
+ * Recursively sanitise every string value inside a captured/replayed
+ * `captureData` or `fixtureData` object (e.g. `domHtml`, `domSnapshot`,
+ * `x-data` markup) so no untrusted DOM is persisted raw. Non-string leaves
+ * pass through unchanged.
+ */
+export 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;
+}