@agent-native/core 0.80.9 → 0.80.10

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;
+}